This demo shows use of QTableWidget with custom handling for" +" individual cells.

Using a customized table item we make it possible to have dynamic" +" output in different cells. The content that is implemented for this" +" particular demo is:" +"

" +"
• Adding two cells.
" +"
• Subtracting one cell from another.
" +"
• Multiplying two cells.
" +"
• Dividing one cell with another.
" +"
• Summing the contents of an arbitrary number of cells.
" +""; + +void SpreadSheet::showAbout() +{ + QMessageBox::about(this, "About Spreadsheet", htmlText); +} + +void decode_pos(const QString &pos, int *row, int *col) +{ + if (pos.isEmpty()) { + *col = -1; + *row = -1; + } else { + *col = pos.at(0).toLatin1() - 'A'; + *row = pos.right(pos.size() - 1).toInt() - 1; + } +} + +QString encode_pos(int row, int col) +{ + return QString(col + 'A') + QString::number(row + 1); +} + + +void SpreadSheet::print() +{ +#ifndef QT_NO_PRINTER + QPrinter printer(QPrinter::ScreenResolution); + QPrintPreviewDialog dlg(&printer); + PrintView view; + view.setModel(table->model()); + connect(&dlg, SIGNAL(paintRequested(QPrinter *)), + &view, SLOT(print(QPrinter *))); + dlg.exec(); +#endif +} + diff --git a/demos/spreadsheet/spreadsheet.h b/demos/spreadsheet/spreadsheet.h new file mode 100644 index 0000000..944433d --- /dev/null +++ b/demos/spreadsheet/spreadsheet.h @@ -0,0 +1,124 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef SPREADSHEET_H +#define SPREADSHEET_H + +#include + +QT_BEGIN_NAMESPACE +class QAction; +class QLabel; +class QLineEdit; +class QToolBar; +class QTableWidgetItem; +class QTableWidget; +QT_END_NAMESPACE + +class SpreadSheet : public QMainWindow +{ + Q_OBJECT + +public: + + SpreadSheet(int rows, int cols, QWidget *parent = 0); + +public slots: + void updateStatus(QTableWidgetItem *item); + void updateColor(QTableWidgetItem *item); + void updateLineEdit(QTableWidgetItem *item); + void returnPressed(); + void selectColor(); + void selectFont(); + void clear(); + void showAbout(); + + void print(); + + void actionSum(); + void actionSubtract(); + void actionAdd(); + void actionMultiply(); + void actionDivide(); + +protected: + void setupContextMenu(); + void setupContents(); + + void setupMenuBar(); + void createActions(); + + void actionMath_helper(const QString &title, const QString &op); + bool runInputDialog(const QString &title, + const QString &c1Text, + const QString &c2Text, + const QString &opText, + const QString &outText, + QString *cell1, QString *cell2, QString *outCell); +private: + QToolBar *toolBar; + QAction *colorAction; + QAction *fontAction; + QAction *firstSeparator; + QAction *cell_sumAction; + QAction *cell_addAction; + QAction *cell_subAction; + QAction *cell_mulAction; + QAction *cell_divAction; + QAction *secondSeparator; + QAction *clearAction; + QAction *aboutSpreadSheet; + QAction *exitAction; + + QAction *printAction; + + QLabel *cellLabel; + QTableWidget *table; + QLineEdit *formulaInput; + +}; + +void decode_pos(const QString &pos, int *row, int *col); +QString encode_pos(int row, int col); + + +#endif // SPREADSHEET_H + diff --git a/demos/spreadsheet/spreadsheet.pro b/demos/spreadsheet/spreadsheet.pro new file mode 100644 index 0000000..39c76da --- /dev/null +++ b/demos/spreadsheet/spreadsheet.pro @@ -0,0 +1,35 @@ +###################################################################### +# Automatically generated by qmake (2.01a) Thu Mar 5 14:39:33 2009 +###################################################################### + +TEMPLATE = app +TARGET = +DEPENDPATH += . +INCLUDEPATH += . + +CONFIG += qt warn_on +#unix:contains(QT_CONFIG, dbus):QT += dbus + +# Input +HEADERS += printview.h spreadsheet.h spreadsheetdelegate.h spreadsheetitem.h +SOURCES += main.cpp \ + printview.cpp \ + spreadsheet.cpp \ + spreadsheetdelegate.cpp \ + spreadsheetitem.cpp +RESOURCES += spreadsheet.qrc + + +build_all:!build_pass { + CONFIG -= build_all + CONFIG += release +} + +# install +target.path = $$[QT_INSTALL_DEMOS]/spreadsheet +sources.files = $$SOURCES $$RESOURCES *.pro images +sources.path = $$[QT_INSTALL_DEMOS]/spreadsheet +INSTALLS += target sources + +include($$QT_SOURCE_TREE/demos/demobase.pri) + diff --git a/demos/spreadsheet/spreadsheet.qrc b/demos/spreadsheet/spreadsheet.qrc new file mode 100644 index 0000000..13f496d --- /dev/null +++ b/demos/spreadsheet/spreadsheet.qrc @@ -0,0 +1,5 @@ + + + images/interview.png + + diff --git a/demos/spreadsheet/spreadsheetdelegate.cpp b/demos/spreadsheet/spreadsheetdelegate.cpp new file mode 100644 index 0000000..465c92f --- /dev/null +++ b/demos/spreadsheet/spreadsheetdelegate.cpp @@ -0,0 +1,114 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "spreadsheetdelegate.h" +#include + +SpreadSheetDelegate::SpreadSheetDelegate(QObject *parent) + : QItemDelegate(parent) {} + +QWidget *SpreadSheetDelegate::createEditor(QWidget *parent, + const QStyleOptionViewItem &, + const QModelIndex &index) const +{ + if (index.column() == 1) { + QDateTimeEdit *editor = new QDateTimeEdit(parent); + editor->setDisplayFormat("dd/M/yyy"); + editor->setCalendarPopup(true); + return editor; + } + + QLineEdit *editor = new QLineEdit(parent); + + // create a completer with the strings in the column as model + QStringList allStrings; + for (int i = 1; irowCount(); i++) { + QString strItem(index.model()->data(index.sibling(i, index.column()), + Qt::EditRole).toString()); + + if (!allStrings.contains(strItem)) + allStrings.append(strItem); + } + + QCompleter *autoComplete = new QCompleter(allStrings); + editor->setCompleter(autoComplete); + connect(editor, SIGNAL(editingFinished()), + this, SLOT(commitAndCloseEditor())); + return editor; +} + +void SpreadSheetDelegate::commitAndCloseEditor() +{ + QLineEdit *editor = qobject_cast(sender()); + emit commitData(editor); + emit closeEditor(editor); +} + +void SpreadSheetDelegate::setEditorData(QWidget *editor, + const QModelIndex &index) const +{ + QLineEdit *edit = qobject_cast(editor); + if (edit) { + edit->setText(index.model()->data(index, Qt::EditRole).toString()); + } else { + QDateTimeEdit *dateEditor = qobject_cast(editor); + if (dateEditor) { + dateEditor->setDate(QDate::fromString( + index.model()->data(index, Qt::EditRole).toString(), + "d/M/yy")); + } + } +} + +void SpreadSheetDelegate::setModelData(QWidget *editor, + QAbstractItemModel *model, const QModelIndex &index) const +{ + QLineEdit *edit = qobject_cast(editor); + if (edit) { + model->setData(index, edit->text()); + } else { + QDateTimeEdit *dateEditor = qobject_cast(editor); + if (dateEditor) { + model->setData(index, dateEditor->date().toString("dd/M/yyy")); + } + } +} + diff --git a/demos/spreadsheet/spreadsheetdelegate.h b/demos/spreadsheet/spreadsheetdelegate.h new file mode 100644 index 0000000..3b7b9ac --- /dev/null +++ b/demos/spreadsheet/spreadsheetdelegate.h @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef SPREADSHEETDELEGATE_H +#define SPREADSHEETDELEGATE_H + +#include +#include "spreadsheet.h" + +class SpreadSheetDelegate : public QItemDelegate +{ + Q_OBJECT + +public: + SpreadSheetDelegate(QObject *parent = 0); + QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &, + const QModelIndex &index) const; + void setEditorData(QWidget *editor, const QModelIndex &index) const; + void setModelData(QWidget *editor, QAbstractItemModel *model, + const QModelIndex &index) const; + +private slots: + void commitAndCloseEditor(); +}; + +#endif // SPREADSHEETDELEGATE_H + diff --git a/demos/spreadsheet/spreadsheetitem.cpp b/demos/spreadsheet/spreadsheetitem.cpp new file mode 100644 index 0000000..8f94b87 --- /dev/null +++ b/demos/spreadsheet/spreadsheetitem.cpp @@ -0,0 +1,167 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "spreadsheetitem.h" + +SpreadSheetItem::SpreadSheetItem() + : QTableWidgetItem(), isResolving(false) +{ +} + +SpreadSheetItem::SpreadSheetItem(const QString &text) + : QTableWidgetItem(text), isResolving(false) +{ +} + +QTableWidgetItem *SpreadSheetItem::clone() const +{ + SpreadSheetItem *item = new SpreadSheetItem(); + *item = *this; + return item; +} + +QVariant SpreadSheetItem::data(int role) const +{ + if (role == Qt::EditRole || role == Qt::StatusTipRole) + return formula(); + + if (role == Qt::DisplayRole) + return display(); + + QString t = display().toString(); + bool isNumber = false; + int number = t.toInt(&isNumber); + + if (role == Qt::TextColorRole) { + if (!isNumber) + return qVariantFromValue(QColor(Qt::black)); + else if (number < 0) + return qVariantFromValue(QColor(Qt::red)); + return qVariantFromValue(QColor(Qt::blue)); + } + + if (role == Qt::TextAlignmentRole) + if (!t.isEmpty() && (t.at(0).isNumber() || t.at(0) == '-')) + return (int)(Qt::AlignRight | Qt::AlignVCenter); + + return QTableWidgetItem::data(role); + } + +void SpreadSheetItem::setData(int role, const QVariant &value) +{ + QTableWidgetItem::setData(role, value); + if (tableWidget()) + tableWidget()->viewport()->update(); +} + +QVariant SpreadSheetItem::display() const +{ + // avoid circular dependencies + if (isResolving) + return QVariant(); + + isResolving = true; + QVariant result = computeFormula(formula(), tableWidget(), this); + isResolving = false; + return result; +} + +QVariant SpreadSheetItem::computeFormula(const QString &formula, + const QTableWidget *widget, + const QTableWidgetItem *self) +{ + // check if the s tring is actually a formula or not + QStringList list = formula.split(' '); + if (list.isEmpty() || !widget) + return formula; // it is a normal string + + QString op = list.value(0).toLower(); + + int firstRow = -1; + int firstCol = -1; + int secondRow = -1; + int secondCol = -1; + + if (list.count() > 1) + decode_pos(list.value(1), &firstRow, &firstCol); + + if (list.count() > 2) + decode_pos(list.value(2), &secondRow, &secondCol); + + const QTableWidgetItem *start = widget->item(firstRow, firstCol); + const QTableWidgetItem *end = widget->item(secondRow, secondCol); + + int firstVal = start ? start->text().toInt() : 0; + int secondVal = end ? end->text().toInt() : 0; + + QVariant result; + if (op == "sum") { + int sum = 0; + for (int r = firstRow; r <= secondRow; ++r) { + for (int c = firstCol; c <= secondCol; ++c) { + const QTableWidgetItem *tableItem = widget->item(r, c); + if (tableItem && tableItem != self) + sum += tableItem->text().toInt(); + } + } + + result = sum; + } else if (op == "+") { + result = (firstVal + secondVal); + } else if (op == "-") { + result = (firstVal - secondVal); + } else if (op == "*") { + result = (firstVal * secondVal); + } else if (op == "/") { + if (secondVal == 0) + result = QString("nan"); + else + result = (firstVal / secondVal); + } else if (op == "=") { + if (start) + result = start->text(); + } else { + result = formula; + } + + return result; +} + diff --git a/demos/spreadsheet/spreadsheetitem.h b/demos/spreadsheet/spreadsheetitem.h new file mode 100644 index 0000000..5996d73 --- /dev/null +++ b/demos/spreadsheet/spreadsheetitem.h @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef SPREADSHEETITEM_H +#define SPREADSHEETITEM_H + +#include +#include +#include "spreadsheet.h" + +class SpreadSheetItem : public QTableWidgetItem +{ +public: + SpreadSheetItem(); + SpreadSheetItem(const QString &text); + + QTableWidgetItem *clone() const; + + QVariant data(int role) const; + void setData(int role, const QVariant &value); + QVariant display() const; + + inline QString formula() const + { return QTableWidgetItem::data(Qt::DisplayRole).toString(); } + + static QVariant computeFormula(const QString &formula, + const QTableWidget *widget, + const QTableWidgetItem *self = 0); + +private: + mutable bool isResolving; +}; + +#endif // SPREADSHEETITEM_H + diff --git a/demos/sqlbrowser/browser.cpp b/demos/sqlbrowser/browser.cpp new file mode 100644 index 0000000..f7b24db --- /dev/null +++ b/demos/sqlbrowser/browser.cpp @@ -0,0 +1,247 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "browser.h" +#include "qsqlconnectiondialog.h" + +#include +#include + +Browser::Browser(QWidget *parent) + : QWidget(parent) +{ + setupUi(this); + + table->addAction(insertRowAction); + table->addAction(deleteRowAction); + + if (QSqlDatabase::drivers().isEmpty()) + QMessageBox::information(this, tr("No database drivers found"), + tr("This demo requires at least one Qt database driver. " + "Please check the documentation how to build the " + "Qt SQL plugins.")); + + emit statusMessage(tr("Ready.")); +} + +Browser::~Browser() +{ +} + +void Browser::exec() +{ + QSqlQueryModel *model = new QSqlQueryModel(table); + model->setQuery(QSqlQuery(sqlEdit->toPlainText(), connectionWidget->currentDatabase())); + table->setModel(model); + + if (model->lastError().type() != QSqlError::NoError) + emit statusMessage(model->lastError().text()); + else if (model->query().isSelect()) + emit statusMessage(tr("Query OK.")); + else + emit statusMessage(tr("Query OK, number of affected rows: %1").arg( + model->query().numRowsAffected())); + + updateActions(); +} + +QSqlError Browser::addConnection(const QString &driver, const QString &dbName, const QString &host, + const QString &user, const QString &passwd, int port) +{ + static int cCount = 0; + + QSqlError err; + QSqlDatabase db = QSqlDatabase::addDatabase(driver, QString("Browser%1").arg(++cCount)); + db.setDatabaseName(dbName); + db.setHostName(host); + db.setPort(port); + if (!db.open(user, passwd)) { + err = db.lastError(); + db = QSqlDatabase(); + QSqlDatabase::removeDatabase(QString("Browser%1").arg(cCount)); + } + connectionWidget->refresh(); + + return err; +} + +void Browser::addConnection() +{ + QSqlConnectionDialog dialog(this); + if (dialog.exec() != QDialog::Accepted) + return; + + if (dialog.useInMemoryDatabase()) { + QSqlDatabase::database("in_mem_db", false).close(); + QSqlDatabase::removeDatabase("in_mem_db"); + QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE", "in_mem_db"); + db.setDatabaseName(":memory:"); + if (!db.open()) + QMessageBox::warning(this, tr("Unable to open database"), tr("An error occurred while " + "opening the connection: ") + db.lastError().text()); + QSqlQuery q("", db); + q.exec("drop table Movies"); + q.exec("drop table Names"); + q.exec("create table Movies (id integer primary key, Title varchar, Director varchar, Rating number)"); + q.exec("insert into Movies values (0, 'Metropolis', 'Fritz Lang', '8.4')"); + q.exec("insert into Movies values (1, 'Nosferatu, eine Symphonie des Grauens', 'F.W. Murnau', '8.1')"); + q.exec("insert into Movies values (2, 'Bis ans Ende der Welt', 'Wim Wenders', '6.5')"); + q.exec("insert into Movies values (3, 'Hardware', 'Richard Stanley', '5.2')"); + q.exec("insert into Movies values (4, 'Mitchell', 'Andrew V. McLaglen', '2.1')"); + q.exec("create table Names (id integer primary key, Firstname varchar, Lastname varchar, City varchar)"); + q.exec("insert into Names values (0, 'Sala', 'Palmer', 'Morristown')"); + q.exec("insert into Names values (1, 'Christopher', 'Walker', 'Morristown')"); + q.exec("insert into Names values (2, 'Donald', 'Duck', 'Andeby')"); + q.exec("insert into Names values (3, 'Buck', 'Rogers', 'Paris')"); + q.exec("insert into Names values (4, 'Sherlock', 'Holmes', 'London')"); + connectionWidget->refresh(); + } else { + QSqlError err = addConnection(dialog.driverName(), dialog.databaseName(), dialog.hostName(), + dialog.userName(), dialog.password(), dialog.port()); + if (err.type() != QSqlError::NoError) + QMessageBox::warning(this, tr("Unable to open database"), tr("An error occurred while " + "opening the connection: ") + err.text()); + } +} + +void Browser::showTable(const QString &t) +{ + QSqlTableModel *model = new QSqlTableModel(table, connectionWidget->currentDatabase()); + model->setEditStrategy(QSqlTableModel::OnRowChange); + model->setTable(t); + model->select(); + if (model->lastError().type() != QSqlError::NoError) + emit statusMessage(model->lastError().text()); + table->setModel(model); + table->setEditTriggers(QAbstractItemView::DoubleClicked|QAbstractItemView::EditKeyPressed); + + connect(table->selectionModel(), SIGNAL(currentRowChanged(QModelIndex,QModelIndex)), + this, SLOT(currentChanged())); + updateActions(); +} + +void Browser::showMetaData(const QString &t) +{ + QSqlRecord rec = connectionWidget->currentDatabase().record(t); + QStandardItemModel *model = new QStandardItemModel(table); + + model->insertRows(0, rec.count()); + model->insertColumns(0, 7); + + model->setHeaderData(0, Qt::Horizontal, "Fieldname"); + model->setHeaderData(1, Qt::Horizontal, "Type"); + model->setHeaderData(2, Qt::Horizontal, "Length"); + model->setHeaderData(3, Qt::Horizontal, "Precision"); + model->setHeaderData(4, Qt::Horizontal, "Required"); + model->setHeaderData(5, Qt::Horizontal, "AutoValue"); + model->setHeaderData(6, Qt::Horizontal, "DefaultValue"); + + + for (int i = 0; i < rec.count(); ++i) { + QSqlField fld = rec.field(i); + model->setData(model->index(i, 0), fld.name()); + model->setData(model->index(i, 1), fld.typeID() == -1 + ? QString(QVariant::typeToName(fld.type())) + : QString("%1 (%2)").arg(QVariant::typeToName(fld.type())).arg(fld.typeID())); + model->setData(model->index(i, 2), fld.length()); + model->setData(model->index(i, 3), fld.precision()); + model->setData(model->index(i, 4), fld.requiredStatus() == -1 ? QVariant("?") + : QVariant(bool(fld.requiredStatus()))); + model->setData(model->index(i, 5), fld.isAutoValue()); + model->setData(model->index(i, 6), fld.defaultValue()); + } + + table->setModel(model); + table->setEditTriggers(QAbstractItemView::NoEditTriggers); + + updateActions(); +} + +void Browser::insertRow() +{ + QSqlTableModel *model = qobject_cast(table->model()); + if (!model) + return; + + QModelIndex insertIndex = table->currentIndex(); + int row = insertIndex.row() == -1 ? 0 : insertIndex.row(); + model->insertRow(row); + insertIndex = model->index(row, 0); + table->setCurrentIndex(insertIndex); + table->edit(insertIndex); +} + +void Browser::deleteRow() +{ + QSqlTableModel *model = qobject_cast(table->model()); + if (!model) + return; + + model->setEditStrategy(QSqlTableModel::OnManualSubmit); + + QModelIndexList currentSelection = table->selectionModel()->selectedIndexes(); + for (int i = 0; i < currentSelection.count(); ++i) { + if (currentSelection.at(i).column() != 0) + continue; + model->removeRow(currentSelection.at(i).row()); + } + + model->submitAll(); + model->setEditStrategy(QSqlTableModel::OnRowChange); + + updateActions(); +} + +void Browser::updateActions() +{ + bool enableIns = qobject_cast(table->model()); + bool enableDel = enableIns && table->currentIndex().isValid(); + + insertRowAction->setEnabled(enableIns); + deleteRowAction->setEnabled(enableDel); +} + +void Browser::about() +{ + QMessageBox::about(this, tr("About"), tr("The SQL Browser demonstration " + "show how a data browser can be used to visualize the results of SQL" + "statements on a live database")); +} diff --git a/demos/sqlbrowser/browser.h b/demos/sqlbrowser/browser.h new file mode 100644 index 0000000..787675b --- /dev/null +++ b/demos/sqlbrowser/browser.h @@ -0,0 +1,99 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef BROWSER_H +#define BROWSER_H + +#include +#include "ui_browserwidget.h" + +class ConnectionWidget; +QT_FORWARD_DECLARE_CLASS(QTableView) +QT_FORWARD_DECLARE_CLASS(QPushButton) +QT_FORWARD_DECLARE_CLASS(QTextEdit) +QT_FORWARD_DECLARE_CLASS(QSqlError) + +class Browser: public QWidget, private Ui::Browser +{ + Q_OBJECT +public: + Browser(QWidget *parent = 0); + virtual ~Browser(); + + QSqlError addConnection(const QString &driver, const QString &dbName, const QString &host, + const QString &user, const QString &passwd, int port = -1); + + void insertRow(); + void deleteRow(); + void updateActions(); + +public slots: + void exec(); + void showTable(const QString &table); + void showMetaData(const QString &table); + void addConnection(); + void currentChanged() { updateActions(); } + void about(); + + void on_insertRowAction_triggered() + { insertRow(); } + void on_deleteRowAction_triggered() + { deleteRow(); } + void on_connectionWidget_tableActivated(const QString &table) + { showTable(table); } + void on_connectionWidget_metaDataRequested(const QString &table) + { showMetaData(table); } + void on_submitButton_clicked() + { + exec(); + sqlEdit->setFocus(); + } + void on_clearButton_clicked() + { + sqlEdit->clear(); + sqlEdit->setFocus(); + } + +signals: + void statusMessage(const QString &message); +}; + +#endif diff --git a/demos/sqlbrowser/browserwidget.ui b/demos/sqlbrowser/browserwidget.ui new file mode 100644 index 0000000..20946f0 --- /dev/null +++ b/demos/sqlbrowser/browserwidget.ui @@ -0,0 +1,199 @@ + + + + + Browser + + + + 0 + 0 + 765 + 515 + + + + Qt SQL Browser + + + + 8 + + + 6 + + + + + + 7 + 7 + 0 + 0 + + + + Qt::Horizontal + + + + + 13 + 7 + 1 + 0 + + + + + + + 7 + 7 + 2 + 0 + + + + Qt::ActionsContextMenu + + + QAbstractItemView::SelectRows + + + + + + + + + 5 + 3 + 0 + 0 + + + + + 16777215 + 180 + + + + SQL Query + + + + 9 + + + 6 + + + + + + 7 + 3 + 0 + 0 + + + + + 0 + 18 + + + + + 0 + 120 + + + + + + + + 1 + + + 6 + + + + + Qt::Horizontal + + + + 40 + 20 + + + + + + + + &Clear + + + + + + + &Submit + + + + + + + + + + + + false + + + &Insert Row + + + Inserts a new Row + + + + + false + + + &Delete Row + + + Deletes the current Row + + + + + + + ConnectionWidget + QTreeView +
connectionwidget.h
+ 0 + + + + + sqlEdit + clearButton + submitButton + connectionWidget + table + + + + diff --git a/demos/sqlbrowser/connectionwidget.cpp b/demos/sqlbrowser/connectionwidget.cpp new file mode 100644 index 0000000..7df28ac --- /dev/null +++ b/demos/sqlbrowser/connectionwidget.cpp @@ -0,0 +1,165 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "connectionwidget.h" + +#include +#include + +ConnectionWidget::ConnectionWidget(QWidget *parent) + : QWidget(parent) +{ + QVBoxLayout *layout = new QVBoxLayout(this); + tree = new QTreeWidget(this); + tree->setObjectName(QLatin1String("tree")); + tree->setHeaderLabels(QStringList(tr("database"))); + tree->header()->setResizeMode(QHeaderView::Stretch); + QAction *refreshAction = new QAction(tr("Refresh"), tree); + metaDataAction = new QAction(tr("Show Schema"), tree); + connect(refreshAction, SIGNAL(triggered()), SLOT(refresh())); + connect(metaDataAction, SIGNAL(triggered()), SLOT(showMetaData())); + tree->addAction(refreshAction); + tree->addAction(metaDataAction); + tree->setContextMenuPolicy(Qt::ActionsContextMenu); + + layout->addWidget(tree); + + QMetaObject::connectSlotsByName(this); +} + +ConnectionWidget::~ConnectionWidget() +{ +} + +static QString qDBCaption(const QSqlDatabase &db) +{ + QString nm = db.driverName(); + nm.append(QLatin1Char(':')); + if (!db.userName().isEmpty()) + nm.append(db.userName()).append(QLatin1Char('@')); + nm.append(db.databaseName()); + return nm; +} + +void ConnectionWidget::refresh() +{ + tree->clear(); + QStringList connectionNames = QSqlDatabase::connectionNames(); + + bool gotActiveDb = false; + for (int i = 0; i < connectionNames.count(); ++i) { + QTreeWidgetItem *root = new QTreeWidgetItem(tree); + QSqlDatabase db = QSqlDatabase::database(connectionNames.at(i), false); + root->setText(0, qDBCaption(db)); + if (connectionNames.at(i) == activeDb) { + gotActiveDb = true; + setActive(root); + } + if (db.isOpen()) { + QStringList tables = db.tables(); + for (int t = 0; t < tables.count(); ++t) { + QTreeWidgetItem *table = new QTreeWidgetItem(root); + table->setText(0, tables.at(t)); + } + } + } + if (!gotActiveDb) { + activeDb = connectionNames.value(0); + setActive(tree->topLevelItem(0)); + } + + tree->doItemsLayout(); // HACK +} + +QSqlDatabase ConnectionWidget::currentDatabase() const +{ + return QSqlDatabase::database(activeDb); +} + +static void qSetBold(QTreeWidgetItem *item, bool bold) +{ + QFont font = item->font(0); + font.setBold(bold); + item->setFont(0, font); +} + +void ConnectionWidget::setActive(QTreeWidgetItem *item) +{ + for (int i = 0; i < tree->topLevelItemCount(); ++i) { + if (tree->topLevelItem(i)->font(0).bold()) + qSetBold(tree->topLevelItem(i), false); + } + + if (!item) + return; + + qSetBold(item, true); + activeDb = QSqlDatabase::connectionNames().value(tree->indexOfTopLevelItem(item)); +} + +void ConnectionWidget::on_tree_itemActivated(QTreeWidgetItem *item, int /* column */) +{ + + if (!item) + return; + + if (!item->parent()) { + setActive(item); + } else { + setActive(item->parent()); + emit tableActivated(item->text(0)); + } +} + +void ConnectionWidget::showMetaData() +{ + QTreeWidgetItem *cItem = tree->currentItem(); + if (!cItem || !cItem->parent()) + return; + setActive(cItem->parent()); + emit metaDataRequested(cItem->text(0)); +} + +void ConnectionWidget::on_tree_currentItemChanged(QTreeWidgetItem *current, QTreeWidgetItem *) +{ + metaDataAction->setEnabled(current && current->parent()); +} + diff --git a/demos/sqlbrowser/connectionwidget.h b/demos/sqlbrowser/connectionwidget.h new file mode 100644 index 0000000..5c48414 --- /dev/null +++ b/demos/sqlbrowser/connectionwidget.h @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef CONNECTIONWIDGET_H +#define CONNECTIONWIDGET_H + +#include + +QT_FORWARD_DECLARE_CLASS(QTreeWidget) +QT_FORWARD_DECLARE_CLASS(QTreeWidgetItem) +QT_FORWARD_DECLARE_CLASS(QSqlDatabase) +QT_FORWARD_DECLARE_CLASS(QMenu) + +class ConnectionWidget: public QWidget +{ + Q_OBJECT +public: + ConnectionWidget(QWidget *parent = 0); + virtual ~ConnectionWidget(); + + QSqlDatabase currentDatabase() const; + +signals: + void tableActivated(const QString &table); + void metaDataRequested(const QString &tableName); + +public slots: + void refresh(); + void showMetaData(); + void on_tree_itemActivated(QTreeWidgetItem *item, int column); + void on_tree_currentItemChanged(QTreeWidgetItem *current, QTreeWidgetItem *previous); + +private: + void setActive(QTreeWidgetItem *); + + QTreeWidget *tree; + QAction *metaDataAction; + QString activeDb; +}; + +#endif diff --git a/demos/sqlbrowser/main.cpp b/demos/sqlbrowser/main.cpp new file mode 100644 index 0000000..b7b7fe5 --- /dev/null +++ b/demos/sqlbrowser/main.cpp @@ -0,0 +1,91 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "browser.h" + +#include +#include +#include + +void addConnectionsFromCommandline(const QStringList &args, Browser *browser) +{ + for (int i = 1; i < args.count(); ++i) { + QUrl url(args.at(i), QUrl::TolerantMode); + if (!url.isValid()) { + qWarning("Invalid URL: %s", qPrintable(args.at(i))); + continue; + } + QSqlError err = browser->addConnection(url.scheme(), url.path().mid(1), url.host(), + url.userName(), url.password(), url.port(-1)); + if (err.type() != QSqlError::NoError) + qDebug() << "Unable to open connection:" << err; + } +} + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + QMainWindow mainWin; + mainWin.setWindowTitle(QObject::tr("Qt SQL Browser")); + + Browser browser(&mainWin); + mainWin.setCentralWidget(&browser); + + QMenu *fileMenu = mainWin.menuBar()->addMenu(QObject::tr("&File")); + fileMenu->addAction(QObject::tr("Add &Connection..."), &browser, SLOT(addConnection())); + fileMenu->addSeparator(); + fileMenu->addAction(QObject::tr("&Quit"), &app, SLOT(quit())); + + QMenu *helpMenu = mainWin.menuBar()->addMenu(QObject::tr("&Help")); + helpMenu->addAction(QObject::tr("About"), &browser, SLOT(about())); + helpMenu->addAction(QObject::tr("About Qt"), qApp, SLOT(aboutQt())); + + QObject::connect(&browser, SIGNAL(statusMessage(QString)), + mainWin.statusBar(), SLOT(showMessage(QString))); + + addConnectionsFromCommandline(app.arguments(), &browser); + mainWin.show(); + if (QSqlDatabase::connectionNames().isEmpty()) + QMetaObject::invokeMethod(&browser, "addConnection", Qt::QueuedConnection); + + return app.exec(); +} diff --git a/demos/sqlbrowser/qsqlconnectiondialog.cpp b/demos/sqlbrowser/qsqlconnectiondialog.cpp new file mode 100644 index 0000000..a2e3c89 --- /dev/null +++ b/demos/sqlbrowser/qsqlconnectiondialog.cpp @@ -0,0 +1,115 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "qsqlconnectiondialog.h" +#include "ui_qsqlconnectiondialog.h" + +#include + +QSqlConnectionDialog::QSqlConnectionDialog(QWidget *parent) + : QDialog(parent) +{ + ui.setupUi(this); + + QStringList drivers = QSqlDatabase::drivers(); + + // remove compat names + drivers.removeAll("QMYSQL3"); + drivers.removeAll("QOCI8"); + drivers.removeAll("QODBC3"); + drivers.removeAll("QPSQL7"); + drivers.removeAll("QTDS7"); + + if (!drivers.contains("QSQLITE")) + ui.dbCheckBox->setEnabled(false); + + ui.comboDriver->addItems(drivers); +} + +QSqlConnectionDialog::~QSqlConnectionDialog() +{ +} + +QString QSqlConnectionDialog::driverName() const +{ + return ui.comboDriver->currentText(); +} + +QString QSqlConnectionDialog::databaseName() const +{ + return ui.editDatabase->text(); +} + +QString QSqlConnectionDialog::userName() const +{ + return ui.editUsername->text(); +} + +QString QSqlConnectionDialog::password() const +{ + return ui.editPassword->text(); +} + +QString QSqlConnectionDialog::hostName() const +{ + return ui.editHostname->text(); +} + +int QSqlConnectionDialog::port() const +{ + return ui.portSpinBox->value(); +} + +bool QSqlConnectionDialog::useInMemoryDatabase() const +{ + return ui.dbCheckBox->isChecked(); +} + +void QSqlConnectionDialog::on_okButton_clicked() +{ + if (ui.comboDriver->currentText().isEmpty()) { + QMessageBox::information(this, tr("No database driver selected"), + tr("Please select a database driver")); + ui.comboDriver->setFocus(); + } else { + accept(); + } +} diff --git a/demos/sqlbrowser/qsqlconnectiondialog.h b/demos/sqlbrowser/qsqlconnectiondialog.h new file mode 100644 index 0000000..d5f3456 --- /dev/null +++ b/demos/sqlbrowser/qsqlconnectiondialog.h @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef QSQLCONNECTIONDIALOG_H +#define QSQLCONNECTIONDIALOG_H + +#include +#include + +#include "ui_qsqlconnectiondialog.h" + +class QSqlConnectionDialog: public QDialog +{ + Q_OBJECT +public: + QSqlConnectionDialog(QWidget *parent = 0); + ~QSqlConnectionDialog(); + + QString driverName() const; + QString databaseName() const; + QString userName() const; + QString password() const; + QString hostName() const; + int port() const; + bool useInMemoryDatabase() const; + +private slots: + void on_okButton_clicked(); + void on_cancelButton_clicked() { reject(); } + void on_dbCheckBox_clicked() { ui.connGroupBox->setEnabled(!ui.dbCheckBox->isChecked()); } + +private: + Ui::QSqlConnectionDialogUi ui; +}; + +#endif diff --git a/demos/sqlbrowser/qsqlconnectiondialog.ui b/demos/sqlbrowser/qsqlconnectiondialog.ui new file mode 100644 index 0000000..91a8700 --- /dev/null +++ b/demos/sqlbrowser/qsqlconnectiondialog.ui @@ -0,0 +1,224 @@ + + + + + QSqlConnectionDialogUi + + + + 0 + 0 + 315 + 302 + + + + Connect... + + + + 8 + + + 6 + + + + + Connection settings + + + + 8 + + + 6 + + + + + + + + &Username: + + + editUsername + + + + + + + D&river + + + comboDriver + + + + + + + + + + Default + + + 65535 + + + -1 + + + -1 + + + + + + + Database Name: + + + editDatabase + + + + + + + QLineEdit::Password + + + + + + + + + + + + + &Hostname: + + + editHostname + + + + + + + P&ort: + + + portSpinBox + + + + + + + &Password: + + + editPassword + + + + + + + + + + 0 + + + 6 + + + + + Qt::Horizontal + + + + 40 + 20 + + + + + + + + Us&e predefined in-memory database + + + + + + + + + 0 + + + 6 + + + + + Qt::Horizontal + + + QSizePolicy::Expanding + + + + 20 + 20 + + + + + + + + &OK + + + true + + + + + + + &Cancel + + + + + + + + + + comboDriver + editDatabase + editUsername + editPassword + editHostname + portSpinBox + dbCheckBox + okButton + cancelButton + + + + diff --git a/demos/sqlbrowser/sqlbrowser.pro b/demos/sqlbrowser/sqlbrowser.pro new file mode 100644 index 0000000..1334bc1 --- /dev/null +++ b/demos/sqlbrowser/sqlbrowser.pro @@ -0,0 +1,25 @@ +TEMPLATE = app +TARGET = sqlbrowser + +QT += sql + +HEADERS = browser.h connectionwidget.h qsqlconnectiondialog.h +SOURCES = main.cpp browser.cpp connectionwidget.cpp qsqlconnectiondialog.cpp + +FORMS = browserwidget.ui qsqlconnectiondialog.ui +build_all:!build_pass { + CONFIG -= build_all + CONFIG += release +} + +# install +target.path = $$[QT_INSTALL_DEMOS]/sqlbrowser +sources.files = $$SOURCES $$HEADERS $$FORMS *.pro +sources.path = $$[QT_INSTALL_DEMOS]/sqlbrowser +INSTALLS += target sources + +include($$QT_SOURCE_TREE/demos/demobase.pri) + +wince*: { + DEPLOYMENT_PLUGIN += qsqlite +} diff --git a/demos/textedit/example.html b/demos/textedit/example.html new file mode 100644 index 0000000..19b5520 --- /dev/null +++ b/demos/textedit/example.html @@ -0,0 +1,79 @@ + +

QTextEdit

+

The QTextEdit widget is an advanced editor that supports formatted rich text. It can be used to display HTML and other rich document formats. Internally, QTextEdit uses the QTextDocument class to describe both the high-level structure of each document and the low-level formatting of paragraphs.

+

If you are viewing this document in the textedit demo, you can edit this document to explore Qt's rich text editing features. We have included some comments in each of the following sections to encourage you to experiment.

+

Font and Paragraph Styles

+

QTextEdit supports bold, italic, and underlined font styles, and can display multicolored text. Font families such as Times New Roman and Courier can also be used directly. If you place the cursor in a region of styled text, the controls in the tool bars will change to reflect the current style.

+

Paragraphs can be formatted so that the text is left-aligned, right-aligned, centered, or fully justified.

+

Try changing the alignment of some text and resize the editor to see how the text layout changes.

+

Lists

+

Different kinds of lists can be included in rich text documents. Standard bullet lists can be nested, using different symbols for each level of the list:

+
• Disc symbols are typically used for top-level list items.
+
• Circle symbols can be used to distinguish between items in lower-level lists.
+
• Square symbols provide a reasonable alternative to discs and circles.
+

Ordered lists can be created that can be used for tables of contents. Different characters can be used to enumerate items, and we can use both Roman and Arabic numerals in the same list structure:

+
1. Introduction
+
2. Qt Tools
+
1. Qt Assistant
+
2. Qt Designer
+
1. Form Editor
+
2. Component Architecture
+
3. Qt Linguist
+
+

The list will automatically be renumbered if you add or remove items. Try adding new sections to the above list or removing existing item to see the numbers change.

+
+

Images

+

Inline images are treated like ordinary ranges of characters in the text editor, so they flow with the surrounding text. Images can also be selected in the same way as text, making it easy to cut, copy, and paste them.

+

Try to select this image by clicking and dragging over it with the mouse, or use the text cursor to select it by holding down Shift and using the arrow keys. You can then cut or copy it, and pasting it into different parts of this document.

+

Tables

+

QTextEdit can arrange and format tables, supporting features such as row and column spans, text formatting within cells, and size constraints for columns.

+
+
+ + + + + + + + + + + + + + + + + + + + + + +

+	+ Development Tools	+ Programming Techniques	+ Graphical User Interfaces
+ 9:00 - 11:00	+ Introduction to Qt
+ 11:00 - 13:00	+ Using qmake	+ Object-oriented Programming	+ Layouts in Qt
+ 13:00 - 15:00	+ Qt Designer Tutorial	+ Extreme Programming	+ Writing Custom Styles
+ 15:00 - 17:00	+ Qt Linguist and Internationalization

+
+

Try adding text to the cells in the table and experiment with the alignment of the paragraphs.

+

Hyperlinks

+

QTextEdit is designed to support hyperlinks between documents, and this feature is used extensively in Qt Assistant. Hyperlinks are automatically created when an HTML file is imported into an editor. Since the rich text framework supports hyperlinks natively, they can also be created programatically.

+

Undo and Redo

+

Full support for undo and redo operations is built into QTextEdit and the underlying rich text framework. Operations on a document can be packaged together to make editing a more comfortable experience for the user.

+

Try making changes to this document and press Ctrl+Z to undo them. You can always recover the original contents of the document.

diff --git a/demos/textedit/images/logo32.png b/demos/textedit/images/logo32.png new file mode 100644 index 0000000..5f91e98 Binary files /dev/null and b/demos/textedit/images/logo32.png differ diff --git a/demos/textedit/images/mac/editcopy.png b/demos/textedit/images/mac/editcopy.png new file mode 100644 index 0000000..f551364 Binary files /dev/null and b/demos/textedit/images/mac/editcopy.png differ diff --git a/demos/textedit/images/mac/editcut.png b/demos/textedit/images/mac/editcut.png new file mode 100644 index 0000000..a784fd5 Binary files /dev/null and b/demos/textedit/images/mac/editcut.png differ diff --git a/demos/textedit/images/mac/editpaste.png b/demos/textedit/images/mac/editpaste.png new file mode 100644 index 0000000..64c0b2d Binary files /dev/null and b/demos/textedit/images/mac/editpaste.png differ diff --git a/demos/textedit/images/mac/editredo.png b/demos/textedit/images/mac/editredo.png new file mode 100644 index 0000000..8875bf2 Binary files /dev/null and b/demos/textedit/images/mac/editredo.png differ diff --git a/demos/textedit/images/mac/editundo.png b/demos/textedit/images/mac/editundo.png new file mode 100644 index 0000000..a3bd5e0 Binary files /dev/null and b/demos/textedit/images/mac/editundo.png differ diff --git a/demos/textedit/images/mac/exportpdf.png b/demos/textedit/images/mac/exportpdf.png new file mode 100644 index 0000000..ebb44e6 Binary files /dev/null and b/demos/textedit/images/mac/exportpdf.png differ diff --git a/demos/textedit/images/mac/filenew.png b/demos/textedit/images/mac/filenew.png new file mode 100644 index 0000000..d3882c7 Binary files /dev/null and b/demos/textedit/images/mac/filenew.png differ diff --git a/demos/textedit/images/mac/fileopen.png b/demos/textedit/images/mac/fileopen.png new file mode 100644 index 0000000..fc06c5e Binary files /dev/null and b/demos/textedit/images/mac/fileopen.png differ diff --git a/demos/textedit/images/mac/fileprint.png b/demos/textedit/images/mac/fileprint.png new file mode 100644 index 0000000..10ca56c Binary files /dev/null and b/demos/textedit/images/mac/fileprint.png differ diff --git a/demos/textedit/images/mac/filesave.png b/demos/textedit/images/mac/filesave.png new file mode 100644 index 0000000..b41ecf5 Binary files /dev/null and b/demos/textedit/images/mac/filesave.png differ diff --git a/demos/textedit/images/mac/textbold.png b/demos/textedit/images/mac/textbold.png new file mode 100644 index 0000000..38400bd Binary files /dev/null and b/demos/textedit/images/mac/textbold.png differ diff --git a/demos/textedit/images/mac/textcenter.png b/demos/textedit/images/mac/textcenter.png new file mode 100644 index 0000000..2ef5b2e Binary files /dev/null and b/demos/textedit/images/mac/textcenter.png differ diff --git a/demos/textedit/images/mac/textitalic.png b/demos/textedit/images/mac/textitalic.png new file mode 100644 index 0000000..0170ee2 Binary files /dev/null and b/demos/textedit/images/mac/textitalic.png differ diff --git a/demos/textedit/images/mac/textjustify.png b/demos/textedit/images/mac/textjustify.png new file mode 100644 index 0000000..39cd6c1 Binary files /dev/null and b/demos/textedit/images/mac/textjustify.png differ diff --git a/demos/textedit/images/mac/textleft.png b/demos/textedit/images/mac/textleft.png new file mode 100644 index 0000000..83a66d5 Binary files /dev/null and b/demos/textedit/images/mac/textleft.png differ diff --git a/demos/textedit/images/mac/textright.png b/demos/textedit/images/mac/textright.png new file mode 100644 index 0000000..e7c0464 Binary files /dev/null and b/demos/textedit/images/mac/textright.png differ diff --git a/demos/textedit/images/mac/textunder.png b/demos/textedit/images/mac/textunder.png new file mode 100644 index 0000000..968bac5 Binary files /dev/null and b/demos/textedit/images/mac/textunder.png differ diff --git a/demos/textedit/images/mac/zoomin.png b/demos/textedit/images/mac/zoomin.png new file mode 100644 index 0000000..d46f5af Binary files /dev/null and b/demos/textedit/images/mac/zoomin.png differ diff --git a/demos/textedit/images/mac/zoomout.png b/demos/textedit/images/mac/zoomout.png new file mode 100644 index 0000000..4632656 Binary files /dev/null and b/demos/textedit/images/mac/zoomout.png differ diff --git a/demos/textedit/images/win/editcopy.png b/demos/textedit/images/win/editcopy.png new file mode 100644 index 0000000..1121b47 Binary files /dev/null and b/demos/textedit/images/win/editcopy.png differ diff --git a/demos/textedit/images/win/editcut.png b/demos/textedit/images/win/editcut.png new file mode 100644 index 0000000..38e55f7 Binary files /dev/null and b/demos/textedit/images/win/editcut.png differ diff --git a/demos/textedit/images/win/editpaste.png b/demos/textedit/images/win/editpaste.png new file mode 100644 index 0000000..ffab15a Binary files /dev/null and b/demos/textedit/images/win/editpaste.png differ diff --git a/demos/textedit/images/win/editredo.png b/demos/textedit/images/win/editredo.png new file mode 100644 index 0000000..9d679fe Binary files /dev/null and b/demos/textedit/images/win/editredo.png differ diff --git a/demos/textedit/images/win/editundo.png b/demos/textedit/images/win/editundo.png new file mode 100644 index 0000000..eee23d2 Binary files /dev/null and b/demos/textedit/images/win/editundo.png differ diff --git a/demos/textedit/images/win/exportpdf.png b/demos/textedit/images/win/exportpdf.png new file mode 100644 index 0000000..eef5132 Binary files /dev/null and b/demos/textedit/images/win/exportpdf.png differ diff --git a/demos/textedit/images/win/filenew.png b/demos/textedit/images/win/filenew.png new file mode 100644 index 0000000..af5d122 Binary files /dev/null and b/demos/textedit/images/win/filenew.png differ diff --git a/demos/textedit/images/win/fileopen.png b/demos/textedit/images/win/fileopen.png new file mode 100644 index 0000000..fc6f17e Binary files /dev/null and b/demos/textedit/images/win/fileopen.png differ diff --git a/demos/textedit/images/win/fileprint.png b/demos/textedit/images/win/fileprint.png new file mode 100644 index 0000000..ba7c02d Binary files /dev/null and b/demos/textedit/images/win/fileprint.png differ diff --git a/demos/textedit/images/win/filesave.png b/demos/textedit/images/win/filesave.png new file mode 100644 index 0000000..8feec99 Binary files /dev/null and b/demos/textedit/images/win/filesave.png differ diff --git a/demos/textedit/images/win/textbold.png b/demos/textedit/images/win/textbold.png new file mode 100644 index 0000000..9cbc713 Binary files /dev/null and b/demos/textedit/images/win/textbold.png differ diff --git a/demos/textedit/images/win/textcenter.png b/demos/textedit/images/win/textcenter.png new file mode 100644 index 0000000..11efb4b Binary files /dev/null and b/demos/textedit/images/win/textcenter.png differ diff --git a/demos/textedit/images/win/textitalic.png b/demos/textedit/images/win/textitalic.png new file mode 100644 index 0000000..b30ce14 Binary files /dev/null and b/demos/textedit/images/win/textitalic.png differ diff --git a/demos/textedit/images/win/textjustify.png b/demos/textedit/images/win/textjustify.png new file mode 100644 index 0000000..9de0c88 Binary files /dev/null and b/demos/textedit/images/win/textjustify.png differ diff --git a/demos/textedit/images/win/textleft.png b/demos/textedit/images/win/textleft.png new file mode 100644 index 0000000..16f80bc Binary files /dev/null and b/demos/textedit/images/win/textleft.png differ diff --git a/demos/textedit/images/win/textright.png b/demos/textedit/images/win/textright.png new file mode 100644 index 0000000..16872df Binary files /dev/null and b/demos/textedit/images/win/textright.png differ diff --git a/demos/textedit/images/win/textunder.png b/demos/textedit/images/win/textunder.png new file mode 100644 index 0000000..c72eff5 Binary files /dev/null and b/demos/textedit/images/win/textunder.png differ diff --git a/demos/textedit/images/win/zoomin.png b/demos/textedit/images/win/zoomin.png new file mode 100644 index 0000000..2e586fc Binary files /dev/null and b/demos/textedit/images/win/zoomin.png differ diff --git a/demos/textedit/images/win/zoomout.png b/demos/textedit/images/win/zoomout.png new file mode 100644 index 0000000..a736d39 Binary files /dev/null and b/demos/textedit/images/win/zoomout.png differ diff --git a/demos/textedit/main.cpp b/demos/textedit/main.cpp new file mode 100644 index 0000000..fa38ecb --- /dev/null +++ b/demos/textedit/main.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "textedit.h" +#include + +int main( int argc, char ** argv ) +{ + Q_INIT_RESOURCE(textedit); + + QApplication a( argc, argv ); + TextEdit mw; + mw.resize( 700, 800 ); + mw.show(); + return a.exec(); +} diff --git a/demos/textedit/textedit.cpp b/demos/textedit/textedit.cpp new file mode 100644 index 0000000..7350a42 --- /dev/null +++ b/demos/textedit/textedit.cpp @@ -0,0 +1,694 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "textedit.h" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#ifdef Q_WS_MAC +const QString rsrcPath = ":/images/mac"; +#else +const QString rsrcPath = ":/images/win"; +#endif + +TextEdit::TextEdit(QWidget *parent) + : QMainWindow(parent) +{ + setupFileActions(); + setupEditActions(); + setupTextActions(); + + { + QMenu *helpMenu = new QMenu(tr("Help"), this); + menuBar()->addMenu(helpMenu); + helpMenu->addAction(tr("About"), this, SLOT(about())); + helpMenu->addAction(tr("About &Qt"), qApp, SLOT(aboutQt())); + } + + textEdit = new QTextEdit(this); + connect(textEdit, SIGNAL(currentCharFormatChanged(const QTextCharFormat &)), + this, SLOT(currentCharFormatChanged(const QTextCharFormat &))); + connect(textEdit, SIGNAL(cursorPositionChanged()), + this, SLOT(cursorPositionChanged())); + + setCentralWidget(textEdit); + textEdit->setFocus(); + setCurrentFileName(QString()); + + fontChanged(textEdit->font()); + colorChanged(textEdit->textColor()); + alignmentChanged(textEdit->alignment()); + + connect(textEdit->document(), SIGNAL(modificationChanged(bool)), + actionSave, SLOT(setEnabled(bool))); + connect(textEdit->document(), SIGNAL(modificationChanged(bool)), + this, SLOT(setWindowModified(bool))); + connect(textEdit->document(), SIGNAL(undoAvailable(bool)), + actionUndo, SLOT(setEnabled(bool))); + connect(textEdit->document(), SIGNAL(redoAvailable(bool)), + actionRedo, SLOT(setEnabled(bool))); + + setWindowModified(textEdit->document()->isModified()); + actionSave->setEnabled(textEdit->document()->isModified()); + actionUndo->setEnabled(textEdit->document()->isUndoAvailable()); + actionRedo->setEnabled(textEdit->document()->isRedoAvailable()); + + connect(actionUndo, SIGNAL(triggered()), textEdit, SLOT(undo())); + connect(actionRedo, SIGNAL(triggered()), textEdit, SLOT(redo())); + + actionCut->setEnabled(false); + actionCopy->setEnabled(false); + + connect(actionCut, SIGNAL(triggered()), textEdit, SLOT(cut())); + connect(actionCopy, SIGNAL(triggered()), textEdit, SLOT(copy())); + connect(actionPaste, SIGNAL(triggered()), textEdit, SLOT(paste())); + + connect(textEdit, SIGNAL(copyAvailable(bool)), actionCut, SLOT(setEnabled(bool))); + connect(textEdit, SIGNAL(copyAvailable(bool)), actionCopy, SLOT(setEnabled(bool))); + +#ifndef QT_NO_CLIPBOARD + connect(QApplication::clipboard(), SIGNAL(dataChanged()), this, SLOT(clipboardDataChanged())); +#endif + + QString initialFile = ":/example.html"; + const QStringList args = QCoreApplication::arguments(); + if (args.count() == 2) + initialFile = args.at(1); + + if (!load(initialFile)) + fileNew(); +} + +void TextEdit::closeEvent(QCloseEvent *e) +{ + if (maybeSave()) + e->accept(); + else + e->ignore(); +} + +void TextEdit::setupFileActions() +{ + QToolBar *tb = new QToolBar(this); + tb->setWindowTitle(tr("File Actions")); + addToolBar(tb); + + QMenu *menu = new QMenu(tr("&File"), this); + menuBar()->addMenu(menu); + + QAction *a; + + a = new QAction(QIcon(rsrcPath + "/filenew.png"), tr("&New"), this); + a->setShortcut(QKeySequence::New); + connect(a, SIGNAL(triggered()), this, SLOT(fileNew())); + tb->addAction(a); + menu->addAction(a); + + a = new QAction(QIcon(rsrcPath + "/fileopen.png"), tr("&Open..."), this); + a->setShortcut(QKeySequence::Open); + connect(a, SIGNAL(triggered()), this, SLOT(fileOpen())); + tb->addAction(a); + menu->addAction(a); + + menu->addSeparator(); + + actionSave = a = new QAction(QIcon(rsrcPath + "/filesave.png"), tr("&Save"), this); + a->setShortcut(QKeySequence::Save); + connect(a, SIGNAL(triggered()), this, SLOT(fileSave())); + a->setEnabled(false); + tb->addAction(a); + menu->addAction(a); + + a = new QAction(tr("Save &As..."), this); + connect(a, SIGNAL(triggered()), this, SLOT(fileSaveAs())); + menu->addAction(a); + menu->addSeparator(); + +#ifndef QT_NO_PRINTER + a = new QAction(QIcon(rsrcPath + "/fileprint.png"), tr("&Print..."), this); + a->setShortcut(QKeySequence::Print); + connect(a, SIGNAL(triggered()), this, SLOT(filePrint())); + tb->addAction(a); + menu->addAction(a); + + a = new QAction(QIcon(rsrcPath + "/fileprint.png"), tr("Print Preview..."), this); + connect(a, SIGNAL(triggered()), this, SLOT(filePrintPreview())); + menu->addAction(a); + + a = new QAction(QIcon(rsrcPath + "/exportpdf.png"), tr("&Export PDF..."), this); + a->setShortcut(Qt::CTRL + Qt::Key_D); + connect(a, SIGNAL(triggered()), this, SLOT(filePrintPdf())); + tb->addAction(a); + menu->addAction(a); + + menu->addSeparator(); +#endif + + a = new QAction(tr("&Quit"), this); + a->setShortcut(Qt::CTRL + Qt::Key_Q); + connect(a, SIGNAL(triggered()), this, SLOT(close())); + menu->addAction(a); +} + +void TextEdit::setupEditActions() +{ + QToolBar *tb = new QToolBar(this); + tb->setWindowTitle(tr("Edit Actions")); + addToolBar(tb); + + QMenu *menu = new QMenu(tr("&Edit"), this); + menuBar()->addMenu(menu); + + QAction *a; + a = actionUndo = new QAction(QIcon(rsrcPath + "/editundo.png"), tr("&Undo"), this); + a->setShortcut(QKeySequence::Undo); + tb->addAction(a); + menu->addAction(a); + a = actionRedo = new QAction(QIcon(rsrcPath + "/editredo.png"), tr("&Redo"), this); + a->setShortcut(QKeySequence::Redo); + tb->addAction(a); + menu->addAction(a); + menu->addSeparator(); + a = actionCut = new QAction(QIcon(rsrcPath + "/editcut.png"), tr("Cu&t"), this); + a->setShortcut(QKeySequence::Cut); + tb->addAction(a); + menu->addAction(a); + a = actionCopy = new QAction(QIcon(rsrcPath + "/editcopy.png"), tr("&Copy"), this); + a->setShortcut(QKeySequence::Copy); + tb->addAction(a); + menu->addAction(a); + a = actionPaste = new QAction(QIcon(rsrcPath + "/editpaste.png"), tr("&Paste"), this); + a->setShortcut(QKeySequence::Paste); + tb->addAction(a); + menu->addAction(a); +#ifndef QT_NO_CLIPBOARD + actionPaste->setEnabled(!QApplication::clipboard()->text().isEmpty()); +#endif +} + +void TextEdit::setupTextActions() +{ + QToolBar *tb = new QToolBar(this); + tb->setWindowTitle(tr("Format Actions")); + addToolBar(tb); + + QMenu *menu = new QMenu(tr("F&ormat"), this); + menuBar()->addMenu(menu); + + actionTextBold = new QAction(QIcon(rsrcPath + "/textbold.png"), tr("&Bold"), this); + actionTextBold->setShortcut(Qt::CTRL + Qt::Key_B); + QFont bold; + bold.setBold(true); + actionTextBold->setFont(bold); + connect(actionTextBold, SIGNAL(triggered()), this, SLOT(textBold())); + tb->addAction(actionTextBold); + menu->addAction(actionTextBold); + actionTextBold->setCheckable(true); + + actionTextItalic = new QAction(QIcon(rsrcPath + "/textitalic.png"), tr("&Italic"), this); + actionTextItalic->setShortcut(Qt::CTRL + Qt::Key_I); + QFont italic; + italic.setItalic(true); + actionTextItalic->setFont(italic); + connect(actionTextItalic, SIGNAL(triggered()), this, SLOT(textItalic())); + tb->addAction(actionTextItalic); + menu->addAction(actionTextItalic); + actionTextItalic->setCheckable(true); + + actionTextUnderline = new QAction(QIcon(rsrcPath + "/textunder.png"), tr("&Underline"), this); + actionTextUnderline->setShortcut(Qt::CTRL + Qt::Key_U); + QFont underline; + underline.setUnderline(true); + actionTextUnderline->setFont(underline); + connect(actionTextUnderline, SIGNAL(triggered()), this, SLOT(textUnderline())); + tb->addAction(actionTextUnderline); + menu->addAction(actionTextUnderline); + actionTextUnderline->setCheckable(true); + + menu->addSeparator(); + + QActionGroup *grp = new QActionGroup(this); + connect(grp, SIGNAL(triggered(QAction *)), this, SLOT(textAlign(QAction *))); + + // Make sure the alignLeft is always left of the alignRight + if (QApplication::isLeftToRight()) { + actionAlignLeft = new QAction(QIcon(rsrcPath + "/textleft.png"), tr("&Left"), grp); + actionAlignCenter = new QAction(QIcon(rsrcPath + "/textcenter.png"), tr("C&enter"), grp); + actionAlignRight = new QAction(QIcon(rsrcPath + "/textright.png"), tr("&Right"), grp); + } else { + actionAlignRight = new QAction(QIcon(rsrcPath + "/textright.png"), tr("&Right"), grp); + actionAlignCenter = new QAction(QIcon(rsrcPath + "/textcenter.png"), tr("C&enter"), grp); + actionAlignLeft = new QAction(QIcon(rsrcPath + "/textleft.png"), tr("&Left"), grp); + } + actionAlignJustify = new QAction(QIcon(rsrcPath + "/textjustify.png"), tr("&Justify"), grp); + + actionAlignLeft->setShortcut(Qt::CTRL + Qt::Key_L); + actionAlignLeft->setCheckable(true); + actionAlignCenter->setShortcut(Qt::CTRL + Qt::Key_E); + actionAlignCenter->setCheckable(true); + actionAlignRight->setShortcut(Qt::CTRL + Qt::Key_R); + actionAlignRight->setCheckable(true); + actionAlignJustify->setShortcut(Qt::CTRL + Qt::Key_J); + actionAlignJustify->setCheckable(true); + + tb->addActions(grp->actions()); + menu->addActions(grp->actions()); + + menu->addSeparator(); + + QPixmap pix(16, 16); + pix.fill(Qt::black); + actionTextColor = new QAction(pix, tr("&Color..."), this); + connect(actionTextColor, SIGNAL(triggered()), this, SLOT(textColor())); + tb->addAction(actionTextColor); + menu->addAction(actionTextColor); + + + tb = new QToolBar(this); + tb->setAllowedAreas(Qt::TopToolBarArea | Qt::BottomToolBarArea); + tb->setWindowTitle(tr("Format Actions")); + addToolBarBreak(Qt::TopToolBarArea); + addToolBar(tb); + + comboStyle = new QComboBox(tb); + tb->addWidget(comboStyle); + comboStyle->addItem("Standard"); + comboStyle->addItem("Bullet List (Disc)"); + comboStyle->addItem("Bullet List (Circle)"); + comboStyle->addItem("Bullet List (Square)"); + comboStyle->addItem("Ordered List (Decimal)"); + comboStyle->addItem("Ordered List (Alpha lower)"); + comboStyle->addItem("Ordered List (Alpha upper)"); + connect(comboStyle, SIGNAL(activated(int)), + this, SLOT(textStyle(int))); + + comboFont = new QFontComboBox(tb); + tb->addWidget(comboFont); + connect(comboFont, SIGNAL(activated(const QString &)), + this, SLOT(textFamily(const QString &))); + + comboSize = new QComboBox(tb); + comboSize->setObjectName("comboSize"); + tb->addWidget(comboSize); + comboSize->setEditable(true); + + QFontDatabase db; + foreach(int size, db.standardSizes()) + comboSize->addItem(QString::number(size)); + + connect(comboSize, SIGNAL(activated(const QString &)), + this, SLOT(textSize(const QString &))); + comboSize->setCurrentIndex(comboSize->findText(QString::number(QApplication::font() + .pointSize()))); +} + +bool TextEdit::load(const QString &f) +{ + if (!QFile::exists(f)) + return false; + QFile file(f); + if (!file.open(QFile::ReadOnly)) + return false; + + QByteArray data = file.readAll(); + QTextCodec *codec = Qt::codecForHtml(data); + QString str = codec->toUnicode(data); + if (Qt::mightBeRichText(str)) { + textEdit->setHtml(str); + } else { + str = QString::fromLocal8Bit(data); + textEdit->setPlainText(str); + } + + setCurrentFileName(f); + return true; +} + +bool TextEdit::maybeSave() +{ + if (!textEdit->document()->isModified()) + return true; + if (fileName.startsWith(QLatin1String(":/"))) + return true; + QMessageBox::StandardButton ret; + ret = QMessageBox::warning(this, tr("Application"), + tr("The document has been modified.\n" + "Do you want to save your changes?"), + QMessageBox::Save | QMessageBox::Discard + | QMessageBox::Cancel); + if (ret == QMessageBox::Save) + return fileSave(); + else if (ret == QMessageBox::Cancel) + return false; + return true; +} + +void TextEdit::setCurrentFileName(const QString &fileName) +{ + this->fileName = fileName; + textEdit->document()->setModified(false); + + QString shownName; + if (fileName.isEmpty()) + shownName = "untitled.txt"; + else + shownName = QFileInfo(fileName).fileName(); + + setWindowTitle(tr("%1[*] - %2").arg(shownName).arg(tr("Rich Text"))); + setWindowModified(false); +} + +void TextEdit::fileNew() +{ + if (maybeSave()) { + textEdit->clear(); + setCurrentFileName(QString()); + } +} + +void TextEdit::fileOpen() +{ + QString fn = QFileDialog::getOpenFileName(this, tr("Open File..."), + QString(), tr("HTML-Files (*.htm *.html);;All Files (*)")); + if (!fn.isEmpty()) + load(fn); +} + +bool TextEdit::fileSave() +{ + if (fileName.isEmpty()) + return fileSaveAs(); + + QTextDocumentWriter writer(fileName); + bool success = writer.write(textEdit->document()); + if (success) + textEdit->document()->setModified(false); + return success; +} + +bool TextEdit::fileSaveAs() +{ + QString fn = QFileDialog::getSaveFileName(this, tr("Save as..."), + QString(), tr("ODF files (*.odt);;HTML-Files (*.htm *.html);;All Files (*)")); + if (fn.isEmpty()) + return false; + if (! (fn.endsWith(".odt", Qt::CaseInsensitive) || fn.endsWith(".htm", Qt::CaseInsensitive) || fn.endsWith(".html", Qt::CaseInsensitive)) ) + fn += ".odt"; // default + setCurrentFileName(fn); + return fileSave(); +} + +void TextEdit::filePrint() +{ +#ifndef QT_NO_PRINTER + QPrinter printer(QPrinter::HighResolution); + QPrintDialog *dlg = new QPrintDialog(&printer, this); + if (textEdit->textCursor().hasSelection()) + dlg->addEnabledOption(QAbstractPrintDialog::PrintSelection); + dlg->setWindowTitle(tr("Print Document")); + if (dlg->exec() == QDialog::Accepted) { + textEdit->print(&printer); + } + delete dlg; +#endif +} + +void TextEdit::filePrintPreview() +{ +#ifndef QT_NO_PRINTER + QPrinter printer(QPrinter::HighResolution); + QPrintPreviewDialog preview(&printer, this); + connect(&preview, SIGNAL(paintRequested(QPrinter *)), SLOT(printPreview(QPrinter *))); + preview.exec(); +#endif +} + +void TextEdit::printPreview(QPrinter *printer) +{ +#ifdef QT_NO_PRINTER + Q_UNUSED(printer); +#else + textEdit->print(printer); +#endif +} + + +void TextEdit::filePrintPdf() +{ +#ifndef QT_NO_PRINTER +//! [0] + QString fileName = QFileDialog::getSaveFileName(this, "Export PDF", + QString(), "*.pdf"); + if (!fileName.isEmpty()) { + if (QFileInfo(fileName).suffix().isEmpty()) + fileName.append(".pdf"); + QPrinter printer(QPrinter::HighResolution); + printer.setOutputFormat(QPrinter::PdfFormat); + printer.setOutputFileName(fileName); + textEdit->document()->print(&printer); + } +//! [0] +#endif +} + +void TextEdit::textBold() +{ + QTextCharFormat fmt; + fmt.setFontWeight(actionTextBold->isChecked() ? QFont::Bold : QFont::Normal); + mergeFormatOnWordOrSelection(fmt); +} + +void TextEdit::textUnderline() +{ + QTextCharFormat fmt; + fmt.setFontUnderline(actionTextUnderline->isChecked()); + mergeFormatOnWordOrSelection(fmt); +} + +void TextEdit::textItalic() +{ + QTextCharFormat fmt; + fmt.setFontItalic(actionTextItalic->isChecked()); + mergeFormatOnWordOrSelection(fmt); +} + +void TextEdit::textFamily(const QString &f) +{ + QTextCharFormat fmt; + fmt.setFontFamily(f); + mergeFormatOnWordOrSelection(fmt); +} + +void TextEdit::textSize(const QString &p) +{ + qreal pointSize = p.toFloat(); + if (p.toFloat() > 0) { + QTextCharFormat fmt; + fmt.setFontPointSize(pointSize); + mergeFormatOnWordOrSelection(fmt); + } +} + +void TextEdit::textStyle(int styleIndex) +{ + QTextCursor cursor = textEdit->textCursor(); + + if (styleIndex != 0) { + QTextListFormat::Style style = QTextListFormat::ListDisc; + + switch (styleIndex) { + default: + case 1: + style = QTextListFormat::ListDisc; + break; + case 2: + style = QTextListFormat::ListCircle; + break; + case 3: + style = QTextListFormat::ListSquare; + break; + case 4: + style = QTextListFormat::ListDecimal; + break; + case 5: + style = QTextListFormat::ListLowerAlpha; + break; + case 6: + style = QTextListFormat::ListUpperAlpha; + break; + } + + cursor.beginEditBlock(); + + QTextBlockFormat blockFmt = cursor.blockFormat(); + + QTextListFormat listFmt; + + if (cursor.currentList()) { + listFmt = cursor.currentList()->format(); + } else { + listFmt.setIndent(blockFmt.indent() + 1); + blockFmt.setIndent(0); + cursor.setBlockFormat(blockFmt); + } + + listFmt.setStyle(style); + + cursor.createList(listFmt); + + cursor.endEditBlock(); + } else { + // #### + QTextBlockFormat bfmt; + bfmt.setObjectIndex(-1); + cursor.mergeBlockFormat(bfmt); + } +} + +void TextEdit::textColor() +{ + QColor col = QColorDialog::getColor(textEdit->textColor(), this); + if (!col.isValid()) + return; + QTextCharFormat fmt; + fmt.setForeground(col); + mergeFormatOnWordOrSelection(fmt); + colorChanged(col); +} + +void TextEdit::textAlign(QAction *a) +{ + if (a == actionAlignLeft) + textEdit->setAlignment(Qt::AlignLeft | Qt::AlignAbsolute); + else if (a == actionAlignCenter) + textEdit->setAlignment(Qt::AlignHCenter); + else if (a == actionAlignRight) + textEdit->setAlignment(Qt::AlignRight | Qt::AlignAbsolute); + else if (a == actionAlignJustify) + textEdit->setAlignment(Qt::AlignJustify); +} + +void TextEdit::currentCharFormatChanged(const QTextCharFormat &format) +{ + fontChanged(format.font()); + colorChanged(format.foreground().color()); +} + +void TextEdit::cursorPositionChanged() +{ + alignmentChanged(textEdit->alignment()); +} + +void TextEdit::clipboardDataChanged() +{ +#ifndef QT_NO_CLIPBOARD + actionPaste->setEnabled(!QApplication::clipboard()->text().isEmpty()); +#endif +} + +void TextEdit::about() +{ + QMessageBox::about(this, tr("About"), tr("This example demonstrates Qt's " + "rich text editing facilities in action, providing an example " + "document for you to experiment with.")); +} + +void TextEdit::mergeFormatOnWordOrSelection(const QTextCharFormat &format) +{ + QTextCursor cursor = textEdit->textCursor(); + if (!cursor.hasSelection()) + cursor.select(QTextCursor::WordUnderCursor); + cursor.mergeCharFormat(format); + textEdit->mergeCurrentCharFormat(format); +} + +void TextEdit::fontChanged(const QFont &f) +{ + comboFont->setCurrentIndex(comboFont->findText(QFontInfo(f).family())); + comboSize->setCurrentIndex(comboSize->findText(QString::number(f.pointSize()))); + actionTextBold->setChecked(f.bold()); + actionTextItalic->setChecked(f.italic()); + actionTextUnderline->setChecked(f.underline()); +} + +void TextEdit::colorChanged(const QColor &c) +{ + QPixmap pix(16, 16); + pix.fill(c); + actionTextColor->setIcon(pix); +} + +void TextEdit::alignmentChanged(Qt::Alignment a) +{ + if (a & Qt::AlignLeft) { + actionAlignLeft->setChecked(true); + } else if (a & Qt::AlignHCenter) { + actionAlignCenter->setChecked(true); + } else if (a & Qt::AlignRight) { + actionAlignRight->setChecked(true); + } else if (a & Qt::AlignJustify) { + actionAlignJustify->setChecked(true); + } +} + diff --git a/demos/textedit/textedit.doc b/demos/textedit/textedit.doc new file mode 100644 index 0000000..53279b9 --- /dev/null +++ b/demos/textedit/textedit.doc @@ -0,0 +1,18 @@ +/*! \page textedit-example.html + + \ingroup examples + \title Text Edit Example + + This example displays a text editor with the user interface written + in pure C++. + + A similar example which uses \link designer-manual.book Qt + Designer\endlink to produce the user interface is in the \link + designer-manual.book Qt Designer manual\endlink. + + + See \c{$QTDIR/examples/textedit} for the source code. + +*/ + + diff --git a/demos/textedit/textedit.h b/demos/textedit/textedit.h new file mode 100644 index 0000000..1fb09f9 --- /dev/null +++ b/demos/textedit/textedit.h @@ -0,0 +1,129 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef TEXTEDIT_H +#define TEXTEDIT_H + +#include +#include +#include + +QT_FORWARD_DECLARE_CLASS(QAction) +QT_FORWARD_DECLARE_CLASS(QComboBox) +QT_FORWARD_DECLARE_CLASS(QFontComboBox) +QT_FORWARD_DECLARE_CLASS(QTextEdit) +QT_FORWARD_DECLARE_CLASS(QTextCharFormat) +QT_FORWARD_DECLARE_CLASS(QMenu) + +class TextEdit : public QMainWindow +{ + Q_OBJECT + +public: + TextEdit(QWidget *parent = 0); + +protected: + virtual void closeEvent(QCloseEvent *e); + +private: + void setupFileActions(); + void setupEditActions(); + void setupTextActions(); + bool load(const QString &f); + bool maybeSave(); + void setCurrentFileName(const QString &fileName); + +private slots: + void fileNew(); + void fileOpen(); + bool fileSave(); + bool fileSaveAs(); + void filePrint(); + void filePrintPreview(); + void filePrintPdf(); + + void textBold(); + void textUnderline(); + void textItalic(); + void textFamily(const QString &f); + void textSize(const QString &p); + void textStyle(int styleIndex); + void textColor(); + void textAlign(QAction *a); + + void currentCharFormatChanged(const QTextCharFormat &format); + void cursorPositionChanged(); + + void clipboardDataChanged(); + void about(); + void printPreview(QPrinter *); + +private: + void mergeFormatOnWordOrSelection(const QTextCharFormat &format); + void fontChanged(const QFont &f); + void colorChanged(const QColor &c); + void alignmentChanged(Qt::Alignment a); + + QAction *actionSave, + *actionTextBold, + *actionTextUnderline, + *actionTextItalic, + *actionTextColor, + *actionAlignLeft, + *actionAlignCenter, + *actionAlignRight, + *actionAlignJustify, + *actionUndo, + *actionRedo, + *actionCut, + *actionCopy, + *actionPaste; + + QComboBox *comboStyle; + QFontComboBox *comboFont; + QComboBox *comboSize; + + QToolBar *tb; + QString fileName; + QTextEdit *textEdit; +}; + +#endif diff --git a/demos/textedit/textedit.pro b/demos/textedit/textedit.pro new file mode 100644 index 0000000..6f15e70 --- /dev/null +++ b/demos/textedit/textedit.pro @@ -0,0 +1,23 @@ +TEMPLATE = app +TARGET = textedit + +CONFIG += qt warn_on + +HEADERS = textedit.h +SOURCES = textedit.cpp \ + main.cpp + +RESOURCES += textedit.qrc +build_all:!build_pass { + CONFIG -= build_all + CONFIG += release +} + +# install +target.path = $$[QT_INSTALL_DEMOS]/textedit +sources.files = $$SOURCES $$HEADERS $$RESOURCES *.pro *.html *.doc images +sources.path = $$[QT_INSTALL_DEMOS]/textedit +INSTALLS += target sources + +include($$QT_SOURCE_TREE/demos/demobase.pri) + diff --git a/demos/textedit/textedit.qrc b/demos/textedit/textedit.qrc new file mode 100644 index 0000000..7d6efd7 --- /dev/null +++ b/demos/textedit/textedit.qrc @@ -0,0 +1,44 @@ + + + images/logo32.png + images/mac/editcopy.png + images/mac/editcut.png + images/mac/editpaste.png + images/mac/editredo.png + images/mac/editundo.png + images/mac/exportpdf.png + images/mac/filenew.png + images/mac/fileopen.png + images/mac/fileprint.png + images/mac/filesave.png + images/mac/textbold.png + images/mac/textcenter.png + images/mac/textitalic.png + images/mac/textjustify.png + images/mac/textleft.png + images/mac/textright.png + images/mac/textunder.png + images/mac/zoomin.png + images/mac/zoomout.png + images/win/editcopy.png + images/win/editcut.png + images/win/editpaste.png + images/win/editredo.png + images/win/editundo.png + images/win/exportpdf.png + images/win/filenew.png + images/win/fileopen.png + images/win/fileprint.png + images/win/filesave.png + images/win/textbold.png + images/win/textcenter.png + images/win/textitalic.png + images/win/textjustify.png + images/win/textleft.png + images/win/textright.png + images/win/textunder.png + images/win/zoomin.png + images/win/zoomout.png + example.html + + diff --git a/demos/undo/commands.cpp b/demos/undo/commands.cpp new file mode 100644 index 0000000..4802e34 --- /dev/null +++ b/demos/undo/commands.cpp @@ -0,0 +1,180 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "commands.h" + +static const int setShapeRectCommandId = 1; +static const int setShapeColorCommandId = 2; + +/****************************************************************************** +** AddShapeCommand +*/ + +AddShapeCommand::AddShapeCommand(Document *doc, const Shape &shape, QUndoCommand *parent) + : QUndoCommand(parent) +{ + m_doc = doc; + m_shape = shape; +} + +void AddShapeCommand::undo() +{ + m_doc->deleteShape(m_shapeName); +} + +void AddShapeCommand::redo() +{ + // A shape only gets a name when it is inserted into a document + m_shapeName = m_doc->addShape(m_shape); + setText(QObject::tr("Add %1").arg(m_shapeName)); +} + +/****************************************************************************** +** RemoveShapeCommand +*/ + +RemoveShapeCommand::RemoveShapeCommand(Document *doc, const QString &shapeName, + QUndoCommand *parent) + : QUndoCommand(parent) +{ + setText(QObject::tr("Remove %1").arg(shapeName)); + m_doc = doc; + m_shape = doc->shape(shapeName); + m_shapeName = shapeName; +} + +void RemoveShapeCommand::undo() +{ + m_shapeName = m_doc->addShape(m_shape); +} + +void RemoveShapeCommand::redo() +{ + m_doc->deleteShape(m_shapeName); +} + +/****************************************************************************** +** SetShapeColorCommand +*/ + +SetShapeColorCommand::SetShapeColorCommand(Document *doc, const QString &shapeName, + const QColor &color, QUndoCommand *parent) + : QUndoCommand(parent) +{ + setText(QObject::tr("Set %1's color").arg(shapeName)); + + m_doc = doc; + m_shapeName = shapeName; + m_oldColor = doc->shape(shapeName).color(); + m_newColor = color; +} + +void SetShapeColorCommand::undo() +{ + m_doc->setShapeColor(m_shapeName, m_oldColor); +} + +void SetShapeColorCommand::redo() +{ + m_doc->setShapeColor(m_shapeName, m_newColor); +} + +bool SetShapeColorCommand::mergeWith(const QUndoCommand *command) +{ + if (command->id() != setShapeColorCommandId) + return false; + + const SetShapeColorCommand *other = static_cast(command); + if (m_shapeName != other->m_shapeName) + return false; + + m_newColor = other->m_newColor; + return true; +} + +int SetShapeColorCommand::id() const +{ + return setShapeColorCommandId; +} + +/****************************************************************************** +** SetShapeRectCommand +*/ + +SetShapeRectCommand::SetShapeRectCommand(Document *doc, const QString &shapeName, + const QRect &rect, QUndoCommand *parent) + : QUndoCommand(parent) +{ + setText(QObject::tr("Change %1's geometry").arg(shapeName)); + + m_doc = doc; + m_shapeName = shapeName; + m_oldRect = doc->shape(shapeName).rect(); + m_newRect = rect; +} + +void SetShapeRectCommand::undo() +{ + m_doc->setShapeRect(m_shapeName, m_oldRect); +} + +void SetShapeRectCommand::redo() +{ + m_doc->setShapeRect(m_shapeName, m_newRect); +} + +bool SetShapeRectCommand::mergeWith(const QUndoCommand *command) +{ + if (command->id() != setShapeRectCommandId) + return false; + + const SetShapeRectCommand *other = static_cast(command); + if (m_shapeName != other->m_shapeName) + return false; + + m_newRect = other->m_newRect; + return true; +} + +int SetShapeRectCommand::id() const +{ + return setShapeRectCommandId; +} diff --git a/demos/undo/commands.h b/demos/undo/commands.h new file mode 100644 index 0000000..f98cb6d --- /dev/null +++ b/demos/undo/commands.h @@ -0,0 +1,112 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef COMMANDS_H +#define COMMANDS_H + +#include +#include "document.h" + +class AddShapeCommand : public QUndoCommand +{ +public: + AddShapeCommand(Document *doc, const Shape &shape, QUndoCommand *parent = 0); + void undo(); + void redo(); + +private: + Document *m_doc; + Shape m_shape; + QString m_shapeName; +}; + +class RemoveShapeCommand : public QUndoCommand +{ +public: + RemoveShapeCommand(Document *doc, const QString &shapeName, QUndoCommand *parent = 0); + void undo(); + void redo(); + +private: + Document *m_doc; + Shape m_shape; + QString m_shapeName; +}; + +class SetShapeColorCommand : public QUndoCommand +{ +public: + SetShapeColorCommand(Document *doc, const QString &shapeName, const QColor &color, + QUndoCommand *parent = 0); + + void undo(); + void redo(); + + bool mergeWith(const QUndoCommand *command); + int id() const; + +private: + Document *m_doc; + QString m_shapeName; + QColor m_oldColor; + QColor m_newColor; +}; + +class SetShapeRectCommand : public QUndoCommand +{ +public: + SetShapeRectCommand(Document *doc, const QString &shapeName, const QRect &rect, + QUndoCommand *parent = 0); + + void undo(); + void redo(); + + bool mergeWith(const QUndoCommand *command); + int id() const; + +private: + Document *m_doc; + QString m_shapeName; + QRect m_oldRect; + QRect m_newRect; +}; + +#endif // COMMANDS_H diff --git a/demos/undo/document.cpp b/demos/undo/document.cpp new file mode 100644 index 0000000..df435fd --- /dev/null +++ b/demos/undo/document.cpp @@ -0,0 +1,445 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include +#include +#include +#include +#include "document.h" +#include "commands.h" + +static const int resizeHandleWidth = 6; + +/****************************************************************************** +** Shape +*/ + +const QSize Shape::minSize(80, 50); + +Shape::Shape(Type type, const QColor &color, const QRect &rect) + : m_type(type), m_rect(rect), m_color(color) +{ +} + +Shape::Type Shape::type() const +{ + return m_type; +} + +QRect Shape::rect() const +{ + return m_rect; +} + +QColor Shape::color() const +{ + return m_color; +} + +QString Shape::name() const +{ + return m_name; +} + +QRect Shape::resizeHandle() const +{ + QPoint br = m_rect.bottomRight(); + return QRect(br - QPoint(resizeHandleWidth, resizeHandleWidth), br); +} + +QString Shape::typeToString(Type type) +{ + QString result; + + switch (type) { + case Rectangle: + result = QLatin1String("Rectangle"); + break; + case Circle: + result = QLatin1String("Circle"); + break; + case Triangle: + result = QLatin1String("Triangle"); + break; + } + + return result; +} + +Shape::Type Shape::stringToType(const QString &s, bool *ok) +{ + if (ok != 0) + *ok = true; + + if (s == QLatin1String("Rectangle")) + return Rectangle; + if (s == QLatin1String("Circle")) + return Circle; + if (s == QLatin1String("Triangle")) + return Triangle; + + if (ok != 0) + *ok = false; + return Rectangle; +} + +/****************************************************************************** +** Document +*/ + +Document::Document(QWidget *parent) + : QWidget(parent), m_currentIndex(-1), m_mousePressIndex(-1), m_resizeHandlePressed(false) +{ + m_undoStack = new QUndoStack(this); + + setAutoFillBackground(true); + setBackgroundRole(QPalette::Base); + + QPalette pal = palette(); + pal.setBrush(QPalette::Base, QPixmap(":/icons/background.png")); + pal.setColor(QPalette::HighlightedText, Qt::red); + setPalette(pal); +} + +QString Document::addShape(const Shape &shape) +{ + QString name = Shape::typeToString(shape.type()); + name = uniqueName(name); + + m_shapeList.append(shape); + m_shapeList[m_shapeList.count() - 1].m_name = name; + setCurrentShape(m_shapeList.count() - 1); + + return name; +} + +void Document::deleteShape(const QString &shapeName) +{ + int index = indexOf(shapeName); + if (index == -1) + return; + + update(m_shapeList.at(index).rect()); + + m_shapeList.removeAt(index); + + if (index <= m_currentIndex) { + m_currentIndex = -1; + if (index == m_shapeList.count()) + --index; + setCurrentShape(index); + } +} + +Shape Document::shape(const QString &shapeName) const +{ + int index = indexOf(shapeName); + if (index == -1) + return Shape(); + return m_shapeList.at(index); +} + +void Document::setShapeRect(const QString &shapeName, const QRect &rect) +{ + int index = indexOf(shapeName); + if (index == -1) + return; + + Shape &shape = m_shapeList[index]; + + update(shape.rect()); + update(rect); + + shape.m_rect = rect; +} + +void Document::setShapeColor(const QString &shapeName, const QColor &color) +{ + + int index = indexOf(shapeName); + if (index == -1) + return; + + Shape &shape = m_shapeList[index]; + shape.m_color = color; + + update(shape.rect()); +} + +QUndoStack *Document::undoStack() const +{ + return m_undoStack; +} + +bool Document::load(QTextStream &stream) +{ + m_shapeList.clear(); + + while (!stream.atEnd()) { + QString shapeType, shapeName, colorName; + int left, top, width, height; + stream >> shapeType >> shapeName >> colorName >> left >> top >> width >> height; + if (stream.status() != QTextStream::Ok) + return false; + bool ok; + Shape::Type type = Shape::stringToType(shapeType, &ok); + if (!ok) + return false; + QColor color(colorName); + if (!color.isValid()) + return false; + + Shape shape(type); + shape.m_name = shapeName; + shape.m_color = color; + shape.m_rect = QRect(left, top, width, height); + + m_shapeList.append(shape); + } + + m_currentIndex = m_shapeList.isEmpty() ? -1 : 0; + + return true; +} + +void Document::save(QTextStream &stream) +{ + for (int i = 0; i < m_shapeList.count(); ++i) { + const Shape &shape = m_shapeList.at(i); + QRect r = shape.rect(); + stream << Shape::typeToString(shape.type()) << QLatin1Char(' ') + << shape.name() << QLatin1Char(' ') + << shape.color().name() << QLatin1Char(' ') + << r.left() << QLatin1Char(' ') + << r.top() << QLatin1Char(' ') + << r.width() << QLatin1Char(' ') + << r.height(); + if (i != m_shapeList.count() - 1) + stream << QLatin1Char('\n'); + } + m_undoStack->setClean(); +} + +QString Document::fileName() const +{ + return m_fileName; +} + +void Document::setFileName(const QString &fileName) +{ + m_fileName = fileName; +} + +int Document::indexAt(const QPoint &pos) const +{ + for (int i = m_shapeList.count() - 1; i >= 0; --i) { + if (m_shapeList.at(i).rect().contains(pos)) + return i; + } + return -1; +} + +void Document::mousePressEvent(QMouseEvent *event) +{ + event->accept(); + int index = indexAt(event->pos());; + if (index != -1) { + setCurrentShape(index); + + const Shape &shape = m_shapeList.at(index); + m_resizeHandlePressed = shape.resizeHandle().contains(event->pos()); + + if (m_resizeHandlePressed) + m_mousePressOffset = shape.rect().bottomRight() - event->pos(); + else + m_mousePressOffset = event->pos() - shape.rect().topLeft(); + } + m_mousePressIndex = index; +} + +void Document::mouseReleaseEvent(QMouseEvent *event) +{ + event->accept(); + m_mousePressIndex = -1; +} + +void Document::mouseMoveEvent(QMouseEvent *event) +{ + event->accept(); + + if (m_mousePressIndex == -1) + return; + + const Shape &shape = m_shapeList.at(m_mousePressIndex); + + QRect rect; + if (m_resizeHandlePressed) { + rect = QRect(shape.rect().topLeft(), event->pos() + m_mousePressOffset); + } else { + rect = shape.rect(); + rect.moveTopLeft(event->pos() - m_mousePressOffset); + } + + QSize size = rect.size().expandedTo(Shape::minSize); + rect.setSize(size); + + m_undoStack->push(new SetShapeRectCommand(this, shape.name(), rect)); +} + +static QGradient gradient(const QColor &color, const QRect &rect) +{ + QColor c = color; + c.setAlpha(160); + QLinearGradient result(rect.topLeft(), rect.bottomRight()); + result.setColorAt(0, c.dark(150)); + result.setColorAt(0.5, c.light(200)); + result.setColorAt(1, c.dark(150)); + return result; +} + +static QPolygon triangle(const QRect &rect) +{ + QPolygon result(3); + result.setPoint(0, rect.center().x(), rect.top()); + result.setPoint(1, rect.right(), rect.bottom()); + result.setPoint(2, rect.left(), rect.bottom()); + return result; +} + +void Document::paintEvent(QPaintEvent *event) +{ + QRegion paintRegion = event->region(); + QPainter painter(this); + QPalette pal = palette(); + + for (int i = 0; i < m_shapeList.count(); ++i) { + const Shape &shape = m_shapeList.at(i); + + if (!paintRegion.contains(shape.rect())) + continue; + + QPen pen = pal.text().color(); + pen.setWidth(i == m_currentIndex ? 2 : 1); + painter.setPen(pen); + painter.setBrush(gradient(shape.color(), shape.rect())); + + QRect rect = shape.rect(); + rect.adjust(1, 1, -resizeHandleWidth/2, -resizeHandleWidth/2); + + // paint the shape + switch (shape.type()) { + case Shape::Rectangle: + painter.drawRect(rect); + break; + case Shape::Circle: + painter.setRenderHint(QPainter::Antialiasing); + painter.drawEllipse(rect); + painter.setRenderHint(QPainter::Antialiasing, false); + break; + case Shape::Triangle: + painter.setRenderHint(QPainter::Antialiasing); + painter.drawPolygon(triangle(rect)); + painter.setRenderHint(QPainter::Antialiasing, false); + break; + } + + // paint the resize handle + painter.setPen(pal.text().color()); + painter.setBrush(Qt::white); + painter.drawRect(shape.resizeHandle().adjusted(0, 0, -1, -1)); + + // paint the shape name + painter.setBrush(pal.text()); + if (shape.type() == Shape::Triangle) + rect.adjust(0, rect.height()/2, 0, 0); + painter.drawText(rect, Qt::AlignCenter, shape.name()); + } +} + +void Document::setCurrentShape(int index) +{ + QString currentName; + + if (m_currentIndex != -1) + update(m_shapeList.at(m_currentIndex).rect()); + + m_currentIndex = index; + + if (m_currentIndex != -1) { + const Shape ¤t = m_shapeList.at(m_currentIndex); + update(current.rect()); + currentName = current.name(); + } + + emit currentShapeChanged(currentName); +} + +int Document::indexOf(const QString &shapeName) const +{ + for (int i = 0; i < m_shapeList.count(); ++i) { + if (m_shapeList.at(i).name() == shapeName) + return i; + } + return -1; +} + +QString Document::uniqueName(const QString &name) const +{ + QString unique; + + for (int i = 0; ; ++i) { + unique = name; + if (i > 0) + unique += QString::number(i); + if (indexOf(unique) == -1) + break; + } + + return unique; +} + +QString Document::currentShapeName() const +{ + if (m_currentIndex == -1) + return QString(); + return m_shapeList.at(m_currentIndex).name(); +} + diff --git a/demos/undo/document.h b/demos/undo/document.h new file mode 100644 index 0000000..0b12ad0 --- /dev/null +++ b/demos/undo/document.h @@ -0,0 +1,125 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef DOCUMENT_H +#define DOCUMENT_H + +#include + +QT_FORWARD_DECLARE_CLASS(QUndoStack) +QT_FORWARD_DECLARE_CLASS(QTextStream) + +class Shape +{ +public: + enum Type { Rectangle, Circle, Triangle }; + + Shape(Type type = Rectangle, const QColor &color = Qt::red, const QRect &rect = QRect()); + + Type type() const; + QString name() const; + QRect rect() const; + QRect resizeHandle() const; + QColor color() const; + + static QString typeToString(Type type); + static Type stringToType(const QString &s, bool *ok = 0); + + static const QSize minSize; + +private: + Type m_type; + QRect m_rect; + QColor m_color; + QString m_name; + + friend class Document; +}; + +class Document : public QWidget +{ + Q_OBJECT + +public: + Document(QWidget *parent = 0); + + QString addShape(const Shape &shape); + void deleteShape(const QString &shapeName); + Shape shape(const QString &shapeName) const; + QString currentShapeName() const; + + void setShapeRect(const QString &shapeName, const QRect &rect); + void setShapeColor(const QString &shapeName, const QColor &color); + + bool load(QTextStream &stream); + void save(QTextStream &stream); + + QString fileName() const; + void setFileName(const QString &fileName); + + QUndoStack *undoStack() const; + +signals: + void currentShapeChanged(const QString &shapeName); + +protected: + void paintEvent(QPaintEvent *event); + void mousePressEvent(QMouseEvent *event); + void mouseReleaseEvent(QMouseEvent *event); + void mouseMoveEvent(QMouseEvent *event); + +private: + void setCurrentShape(int index); + int indexOf(const QString &shapeName) const; + int indexAt(const QPoint &pos) const; + QString uniqueName(const QString &name) const; + + QList m_shapeList; + int m_currentIndex; + int m_mousePressIndex; + QPoint m_mousePressOffset; + bool m_resizeHandlePressed; + QString m_fileName; + + QUndoStack *m_undoStack; +}; + +#endif // DOCUMENT_H diff --git a/demos/undo/icons/background.png b/demos/undo/icons/background.png new file mode 100644 index 0000000..3bc5ed8 Binary files /dev/null and b/demos/undo/icons/background.png differ diff --git a/demos/undo/icons/blue.png b/demos/undo/icons/blue.png new file mode 100644 index 0000000..4e181bb Binary files /dev/null and b/demos/undo/icons/blue.png differ diff --git a/demos/undo/icons/circle.png b/demos/undo/icons/circle.png new file mode 100644 index 0000000..ed16c6e Binary files /dev/null and b/demos/undo/icons/circle.png differ diff --git a/demos/undo/icons/exit.png b/demos/undo/icons/exit.png new file mode 100644 index 0000000..539cb2e Binary files /dev/null and b/demos/undo/icons/exit.png differ diff --git a/demos/undo/icons/fileclose.png b/demos/undo/icons/fileclose.png new file mode 100644 index 0000000..c5483d1 Binary files /dev/null and b/demos/undo/icons/fileclose.png differ diff --git a/demos/undo/icons/filenew.png b/demos/undo/icons/filenew.png new file mode 100644 index 0000000..57e57e3 Binary files /dev/null and b/demos/undo/icons/filenew.png differ diff --git a/demos/undo/icons/fileopen.png b/demos/undo/icons/fileopen.png new file mode 100644 index 0000000..33e0d63 Binary files /dev/null and b/demos/undo/icons/fileopen.png differ diff --git a/demos/undo/icons/filesave.png b/demos/undo/icons/filesave.png new file mode 100644 index 0000000..57fd5e2 Binary files /dev/null and b/demos/undo/icons/filesave.png differ diff --git a/demos/undo/icons/green.png b/demos/undo/icons/green.png new file mode 100644 index 0000000..e2e7cc9 Binary files /dev/null and b/demos/undo/icons/green.png differ diff --git a/demos/undo/icons/ok.png b/demos/undo/icons/ok.png new file mode 100644 index 0000000..e355ea9 Binary files /dev/null and b/demos/undo/icons/ok.png differ diff --git a/demos/undo/icons/rectangle.png b/demos/undo/icons/rectangle.png new file mode 100644 index 0000000..3a7d979 Binary files /dev/null and b/demos/undo/icons/rectangle.png differ diff --git a/demos/undo/icons/red.png b/demos/undo/icons/red.png new file mode 100644 index 0000000..58c3e72 Binary files /dev/null and b/demos/undo/icons/red.png differ diff --git a/demos/undo/icons/redo.png b/demos/undo/icons/redo.png new file mode 100644 index 0000000..5591517 Binary files /dev/null and b/demos/undo/icons/redo.png differ diff --git a/demos/undo/icons/remove.png b/demos/undo/icons/remove.png new file mode 100644 index 0000000..7a7b048 Binary files /dev/null and b/demos/undo/icons/remove.png differ diff --git a/demos/undo/icons/triangle.png b/demos/undo/icons/triangle.png new file mode 100644 index 0000000..2969131 Binary files /dev/null and b/demos/undo/icons/triangle.png differ diff --git a/demos/undo/icons/undo.png b/demos/undo/icons/undo.png new file mode 100644 index 0000000..8cf63a8 Binary files /dev/null and b/demos/undo/icons/undo.png differ diff --git a/demos/undo/main.cpp b/demos/undo/main.cpp new file mode 100644 index 0000000..f36a6e8 --- /dev/null +++ b/demos/undo/main.cpp @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include +#include "mainwindow.h" + +int main(int argc, char **argv) +{ + Q_INIT_RESOURCE(undo); + + QApplication app(argc, argv); + + MainWindow win; + win.resize(800, 600); + win.show(); + + return app.exec(); +}; diff --git a/demos/undo/mainwindow.cpp b/demos/undo/mainwindow.cpp new file mode 100644 index 0000000..409fd14 --- /dev/null +++ b/demos/undo/mainwindow.cpp @@ -0,0 +1,446 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include +#include +#include +#include +#include +#include +#include "document.h" +#include "mainwindow.h" +#include "commands.h" + +MainWindow::MainWindow(QWidget *parent) + : QMainWindow(parent) +{ + setupUi(this); + + QWidget *w = documentTabs->widget(0); + documentTabs->removeTab(0); + delete w; + + connect(actionOpen, SIGNAL(triggered()), this, SLOT(openDocument())); + connect(actionClose, SIGNAL(triggered()), this, SLOT(closeDocument())); + connect(actionNew, SIGNAL(triggered()), this, SLOT(newDocument())); + connect(actionSave, SIGNAL(triggered()), this, SLOT(saveDocument())); + connect(actionExit, SIGNAL(triggered()), this, SLOT(close())); + connect(actionRed, SIGNAL(triggered()), this, SLOT(setShapeColor())); + connect(actionGreen, SIGNAL(triggered()), this, SLOT(setShapeColor())); + connect(actionBlue, SIGNAL(triggered()), this, SLOT(setShapeColor())); + connect(actionAddCircle, SIGNAL(triggered()), this, SLOT(addShape())); + connect(actionAddRectangle, SIGNAL(triggered()), this, SLOT(addShape())); + connect(actionAddTriangle, SIGNAL(triggered()), this, SLOT(addShape())); + connect(actionRemoveShape, SIGNAL(triggered()), this, SLOT(removeShape())); + connect(actionAddRobot, SIGNAL(triggered()), this, SLOT(addRobot())); + connect(actionAddSnowman, SIGNAL(triggered()), this, SLOT(addSnowman())); + connect(actionAbout, SIGNAL(triggered()), this, SLOT(about())); + connect(actionAboutQt, SIGNAL(triggered()), this, SLOT(aboutQt())); + + connect(undoLimit, SIGNAL(valueChanged(int)), this, SLOT(updateActions())); + connect(documentTabs, SIGNAL(currentChanged(int)), this, SLOT(updateActions())); + + actionOpen->setShortcut(QString("Ctrl+O")); + actionClose->setShortcut(QString("Ctrl+W")); + actionNew->setShortcut(QString("Ctrl+N")); + actionSave->setShortcut(QString("Ctrl+S")); + actionExit->setShortcut(QString("Ctrl+Q")); + actionRemoveShape->setShortcut(QString("Del")); + actionRed->setShortcut(QString("Alt+R")); + actionGreen->setShortcut(QString("Alt+G")); + actionBlue->setShortcut(QString("Alt+B")); + actionAddCircle->setShortcut(QString("Alt+C")); + actionAddRectangle->setShortcut(QString("Alt+L")); + actionAddTriangle->setShortcut(QString("Alt+T")); + + m_undoGroup = new QUndoGroup(this); + undoView->setGroup(m_undoGroup); + undoView->setCleanIcon(QIcon(":/icons/ok.png")); + + QAction *undoAction = m_undoGroup->createUndoAction(this); + QAction *redoAction = m_undoGroup->createRedoAction(this); + undoAction->setIcon(QIcon(":/icons/undo.png")); + redoAction->setIcon(QIcon(":/icons/redo.png")); + menuShape->insertAction(menuShape->actions().at(0), undoAction); + menuShape->insertAction(undoAction, redoAction); + + toolBar->addAction(undoAction); + toolBar->addAction(redoAction); + + newDocument(); + updateActions(); +}; + +void MainWindow::updateActions() +{ + Document *doc = currentDocument(); + m_undoGroup->setActiveStack(doc == 0 ? 0 : doc->undoStack()); + QString shapeName = doc == 0 ? QString() : doc->currentShapeName(); + + actionAddRobot->setEnabled(doc != 0); + actionAddSnowman->setEnabled(doc != 0); + actionAddCircle->setEnabled(doc != 0); + actionAddRectangle->setEnabled(doc != 0); + actionAddTriangle->setEnabled(doc != 0); + actionClose->setEnabled(doc != 0); + actionSave->setEnabled(doc != 0 && !doc->undoStack()->isClean()); + undoLimit->setEnabled(doc != 0 && doc->undoStack()->count() == 0); + + if (shapeName.isEmpty()) { + actionRed->setEnabled(false); + actionGreen->setEnabled(false); + actionBlue->setEnabled(false); + actionRemoveShape->setEnabled(false); + } else { + Shape shape = doc->shape(shapeName); + actionRed->setEnabled(shape.color() != Qt::red); + actionGreen->setEnabled(shape.color() != Qt::green); + actionBlue->setEnabled(shape.color() != Qt::blue); + actionRemoveShape->setEnabled(true); + } + + if (doc != 0) { + int index = documentTabs->indexOf(doc); + Q_ASSERT(index != -1); + static const QIcon unsavedIcon(":/icons/filesave.png"); + documentTabs->setTabIcon(index, doc->undoStack()->isClean() ? QIcon() : unsavedIcon); + + if (doc->undoStack()->count() == 0) + doc->undoStack()->setUndoLimit(undoLimit->value()); + } +} + +void MainWindow::openDocument() +{ + QString fileName = QFileDialog::getOpenFileName(this); + if (fileName.isEmpty()) + return; + + QFile file(fileName); + if (!file.open(QIODevice::ReadOnly)) { + QMessageBox::warning(this, + tr("File error"), + tr("Failed to open\n%1").arg(fileName)); + return; + } + QTextStream stream(&file); + + Document *doc = new Document(); + if (!doc->load(stream)) { + QMessageBox::warning(this, + tr("Parse error"), + tr("Failed to parse\n%1").arg(fileName)); + delete doc; + return; + } + + doc->setFileName(fileName); + addDocument(doc); +} + +QString MainWindow::fixedWindowTitle(const Document *doc) const +{ + QString title = doc->fileName(); + + if (title.isEmpty()) + title = tr("Unnamed"); + else + title = QFileInfo(title).fileName(); + + QString result; + + for (int i = 0; ; ++i) { + result = title; + if (i > 0) + result += QString::number(i); + + bool unique = true; + for (int j = 0; j < documentTabs->count(); ++j) { + const QWidget *widget = documentTabs->widget(j); + if (widget == doc) + continue; + if (result == documentTabs->tabText(j)) { + unique = false; + break; + } + } + + if (unique) + break; + } + + return result; +} + +void MainWindow::addDocument(Document *doc) +{ + if (documentTabs->indexOf(doc) != -1) + return; + m_undoGroup->addStack(doc->undoStack()); + documentTabs->addTab(doc, fixedWindowTitle(doc)); + connect(doc, SIGNAL(currentShapeChanged(QString)), this, SLOT(updateActions())); + connect(doc->undoStack(), SIGNAL(indexChanged(int)), this, SLOT(updateActions())); + connect(doc->undoStack(), SIGNAL(cleanChanged(bool)), this, SLOT(updateActions())); + + setCurrentDocument(doc); +} + +void MainWindow::setCurrentDocument(Document *doc) +{ + documentTabs->setCurrentWidget(doc); +} + +Document *MainWindow::currentDocument() const +{ + return qobject_cast(documentTabs->currentWidget()); +} + +void MainWindow::removeDocument(Document *doc) +{ + int index = documentTabs->indexOf(doc); + if (index == -1) + return; + + documentTabs->removeTab(index); + m_undoGroup->removeStack(doc->undoStack()); + disconnect(doc, SIGNAL(currentShapeChanged(QString)), this, SLOT(updateActions())); + disconnect(doc->undoStack(), SIGNAL(indexChanged(int)), this, SLOT(updateActions())); + disconnect(doc->undoStack(), SIGNAL(cleanChanged(bool)), this, SLOT(updateActions())); + + if (documentTabs->count() == 0) { + newDocument(); + updateActions(); + } +} + +void MainWindow::saveDocument() +{ + Document *doc = currentDocument(); + if (doc == 0) + return; + + for (;;) { + QString fileName = doc->fileName(); + + if (fileName.isEmpty()) + fileName = QFileDialog::getSaveFileName(this); + if (fileName.isEmpty()) + break; + + QFile file(fileName); + if (!file.open(QIODevice::WriteOnly)) { + QMessageBox::warning(this, + tr("File error"), + tr("Failed to open\n%1").arg(fileName)); + doc->setFileName(QString()); + } else { + QTextStream stream(&file); + doc->save(stream); + doc->setFileName(fileName); + + int index = documentTabs->indexOf(doc); + Q_ASSERT(index != -1); + documentTabs->setTabText(index, fixedWindowTitle(doc)); + + break; + } + } +} + +void MainWindow::closeDocument() +{ + Document *doc = currentDocument(); + if (doc == 0) + return; + + if (!doc->undoStack()->isClean()) { + int button + = QMessageBox::warning(this, + tr("Unsaved changes"), + tr("Would you like to save this document?"), + QMessageBox::Yes, QMessageBox::No); + if (button == QMessageBox::Yes) + saveDocument(); + } + + removeDocument(doc); + delete doc; +} + +void MainWindow::newDocument() +{ + addDocument(new Document()); +} + +static QColor randomColor() +{ + int r = (int) (3.0*(rand()/(RAND_MAX + 1.0))); + switch (r) { + case 0: + return Qt::red; + case 1: + return Qt::green; + default: + break; + } + return Qt::blue; +} + +static QRect randomRect(const QSize &s) +{ + QSize min = Shape::minSize; + + int left = (int) ((0.0 + s.width() - min.width())*(rand()/(RAND_MAX + 1.0))); + int top = (int) ((0.0 + s.height() - min.height())*(rand()/(RAND_MAX + 1.0))); + int width = (int) ((0.0 + s.width() - left - min.width())*(rand()/(RAND_MAX + 1.0))) + min.width(); + int height = (int) ((0.0 + s.height() - top - min.height())*(rand()/(RAND_MAX + 1.0))) + min.height(); + + return QRect(left, top, width, height); +} + +void MainWindow::addShape() +{ + Document *doc = currentDocument(); + if (doc == 0) + return; + + Shape::Type type; + + if (sender() == actionAddCircle) + type = Shape::Circle; + else if (sender() == actionAddRectangle) + type = Shape::Rectangle; + else if (sender() == actionAddTriangle) + type = Shape::Triangle; + else return; + + Shape newShape(type, randomColor(), randomRect(doc->size())); + doc->undoStack()->push(new AddShapeCommand(doc, newShape)); +} + +void MainWindow::removeShape() +{ + Document *doc = currentDocument(); + if (doc == 0) + return; + + QString shapeName = doc->currentShapeName(); + if (shapeName.isEmpty()) + return; + + doc->undoStack()->push(new RemoveShapeCommand(doc, shapeName)); +} + +void MainWindow::setShapeColor() +{ + Document *doc = currentDocument(); + if (doc == 0) + return; + + QString shapeName = doc->currentShapeName(); + if (shapeName.isEmpty()) + return; + + QColor color; + + if (sender() == actionRed) + color = Qt::red; + else if (sender() == actionGreen) + color = Qt::green; + else if (sender() == actionBlue) + color = Qt::blue; + else + return; + + if (color == doc->shape(shapeName).color()) + return; + + doc->undoStack()->push(new SetShapeColorCommand(doc, shapeName, color)); +} + +void MainWindow::addSnowman() +{ + Document *doc = currentDocument(); + if (doc == 0) + return; + + // Create a macro command using beginMacro() and endMacro() + + doc->undoStack()->beginMacro(tr("Add snowman")); + doc->undoStack()->push(new AddShapeCommand(doc, + Shape(Shape::Circle, Qt::blue, QRect(51, 30, 97, 95)))); + doc->undoStack()->push(new AddShapeCommand(doc, + Shape(Shape::Circle, Qt::blue, QRect(27, 123, 150, 133)))); + doc->undoStack()->push(new AddShapeCommand(doc, + Shape(Shape::Circle, Qt::blue, QRect(11, 253, 188, 146)))); + doc->undoStack()->endMacro(); +} + +void MainWindow::addRobot() +{ + Document *doc = currentDocument(); + if (doc == 0) + return; + + // Compose a macro command by explicitly adding children to a parent command + + QUndoCommand *parent = new QUndoCommand(tr("Add robot")); + + new AddShapeCommand(doc, Shape(Shape::Rectangle, Qt::green, QRect(115, 15, 81, 70)), parent); + new AddShapeCommand(doc, Shape(Shape::Rectangle, Qt::green, QRect(82, 89, 148, 188)), parent); + new AddShapeCommand(doc, Shape(Shape::Rectangle, Qt::green, QRect(76, 280, 80, 165)), parent); + new AddShapeCommand(doc, Shape(Shape::Rectangle, Qt::green, QRect(163, 280, 80, 164)), parent); + new AddShapeCommand(doc, Shape(Shape::Circle, Qt::blue, QRect(116, 25, 80, 50)), parent); + new AddShapeCommand(doc, Shape(Shape::Rectangle, Qt::green, QRect(232, 92, 80, 127)), parent); + new AddShapeCommand(doc, Shape(Shape::Rectangle, Qt::green, QRect(2, 92, 80, 125)), parent); + + doc->undoStack()->push(parent); +} + +void MainWindow::about() +{ + QMessageBox::about(this, tr("About Undo"), tr("The Undo demonstration shows how to use the Qt Undo framework.")); +} + +void MainWindow::aboutQt() +{ + QMessageBox::aboutQt(this, tr("About Qt")); +} diff --git a/demos/undo/mainwindow.h b/demos/undo/mainwindow.h new file mode 100644 index 0000000..5340e94 --- /dev/null +++ b/demos/undo/mainwindow.h @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the demonstration applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef MAINWINDOW_H +#define MAINWINDOW_H + +#include +#include "ui_mainwindow.h" + +class Document; + +class MainWindow : public QMainWindow, public Ui::MainWindow +{ + Q_OBJECT + +public: + MainWindow(QWidget *parent = 0); + + void addDocument(Document *doc); + void removeDocument(Document *doc); + void setCurrentDocument(Document *doc); + Document *currentDocument() const; + +public slots: + void openDocument(); + void saveDocument(); + void closeDocument(); + void newDocument(); + + void addShape(); + void removeShape(); + void setShapeColor(); + + void addSnowman(); + void addRobot(); + + void about(); + void aboutQt(); + +private slots: + void updateActions(); + +private: + QUndoGroup *m_undoGroup; + + QString fixedWindowTitle(const Document *doc) const; +}; + +#endif // MAINWINDOW_H diff --git a/demos/undo/mainwindow.ui b/demos/undo/mainwindow.ui new file mode 100644 index 0000000..91a0b43 --- /dev/null +++ b/demos/undo/mainwindow.ui @@ -0,0 +1,322 @@ + + MainWindow + + + + 0 + 0 + 567 + 600 + + + + + 32 + 32 + + + + + + 0 + + + 0 + + + + + 0 + + + + Tab 1 + + + + + + + + + + 0 + 0 + 567 + 27 + + + + + File + + + + + + + + + + + Edit + + + + Macros + + + + + + + + + + + + + + + + + + + Help + + + + + + + + + + + + File actions + + + Qt::Horizontal + + + TopToolBarArea + + + false + + + + + + + + + + Shape actions + + + Qt::Vertical + + + LeftToolBarArea + + + false + + + + + + + + + + + + + Undo Stack + + + 2 + + + + + 0 + + + 4 + + + + + 0 + + + 6 + + + + + Qt::Horizontal + + + + 40 + 20 + + + + + + + + Undo limit + + + + + + + + + + + + false + + + + + + + + + :/icons/fileopen.png + + + &Open + + + + + :/icons/fileclose.png + + + &Close + + + + + :/icons/filenew.png + + + &New + + + + + :/icons/filesave.png + + + &Save + + + + + :/icons/exit.png + + + E&xit + + + + + :/icons/red.png + + + Red + + + + + :/icons/green.png + + + Green + + + + + :/icons/blue.png + + + Blue + + + + + :/icons/rectangle.png + + + Add Rectangle + + + + + :/icons/circle.png + + + Add Circle + + + + + :/icons/remove.png + + + Remove Shape + + + + + Add robot + + + + + Add snowan + + + + + :/icons/triangle.png + + + addTriangle + + + + + About + + + + + About Qt + + + + + + QUndoView + QListView +
qundoview.h
+ + + + + + + diff --git a/demos/undo/undo.pro b/demos/undo/undo.pro new file mode 100644 index 0000000..bf7017b --- /dev/null +++ b/demos/undo/undo.pro @@ -0,0 +1,19 @@ +SOURCES += main.cpp mainwindow.cpp commands.cpp document.cpp +HEADERS += mainwindow.h commands.h document.h +FORMS += mainwindow.ui + +build_all:!build_pass { + CONFIG -= build_all + CONFIG += release +} + +RESOURCES += undo.qrc + +# install +target.path = $$[QT_INSTALL_DEMOS]/undo +sources.files = $$SOURCES $$HEADERS *.pro icons $$RESOURCES $$FORMS +sources.path = $$[QT_INSTALL_DEMOS]/undo +INSTALLS += target sources + +include($$QT_SOURCE_TREE/demos/demobase.pri) + diff --git a/demos/undo/undo.qrc b/demos/undo/undo.qrc new file mode 100644 index 0000000..65619b8 --- /dev/null +++ b/demos/undo/undo.qrc @@ -0,0 +1,20 @@ + + + icons/background.png + icons/blue.png + icons/circle.png + icons/exit.png + icons/fileclose.png + icons/filenew.png + icons/fileopen.png + icons/filesave.png + icons/green.png + icons/ok.png + icons/rectangle.png + icons/red.png + icons/redo.png + icons/remove.png + icons/triangle.png + icons/undo.png + + diff --git a/dist/README b/dist/README new file mode 100644 index 0000000..110be1c --- /dev/null +++ b/dist/README @@ -0,0 +1,134 @@ +This is Qt version %VERSION%. + +Qt is a comprehensive cross-platform C++ application framework. Qt 4 +introduces new features and many improvements over the 3.x series. See +http://doc.trolltech.com/latest/qt4-intro.html for details. + +The Qt 4.x series is not binary compatible or source compatible with +the 3.x series. For more information on porting from Qt 3 to Qt 4, see +http://doc.trolltech.com/latest/porting4.html. + + +INSTALLING Qt + +On Windows and Mac OS X, if you want to install the precompiled binary +packages, simply launch the package and follow the instructions in the +installation wizard. + +On Mac OS X, the binary package requires Mac OS X 10.4.x (Tiger) or +later and GCC 4.0.1 to develop applications. Its applications will run +on Mac OS X 10.3.9 and above. + +If you have a source package (a .tar.gz, .tar.bz2, or .zip file), +follow the instructions in the INSTALL file. + + +DEMOS AND EXAMPLES + +Once Qt is installed, we suggest that you take a look at the demos and +examples to see Qt in action. Run the Qt Examples and Demos either by +typing 'qtdemo' on the command line or through the desktop's Start +menu. On Mac OS X, you can find it in /Developers/Applications/Qt. + + +REFERENCE DOCUMENTATION + +The Qt reference documentation is available locally in Qt's doc/html +directory. You can use Qt Assistant to view it; to launch Assistant, +type 'assistant' on the command line or use the Start menu. On Mac OS +X, you can find it in /Developer/Applications/Qt. The latest +documentation is available at http://doc.trolltech.com/. + + +SUPPORTED PLATFORMS + +For this release, the following platforms have been tested: + + win32-g++ (mingw) + win32-msvc + win32-msvc2003 + win32-msvc2005 + win32-msvc2008 + + aix-xlc + aix-xlc-64 + hpux-acc + hpux-acc-64 + hpux-acc-o64 + hpux-g++ + hpux-g++-64 + hpuxi-acc-32 + hpuxi-acc-64 + linux-g++ + linux-icc + linux-icc-32 + linux-icc-64 + solaris-cc + solaris-cc-64 + solaris-g++ + solaris-g++-64 + + macx-g++ + macx-g++42 + + qws/linux-x86-g++ + qws/linux-arm-g++ + + wince50standard-armv4i-msvc2005 + wince50standard-armv4i-msvc2008 + wince50standard-mipsii-msvc2005 + wince50standard-mipsii-msvc2008 + wince50standard-x86-msvc2005 + wince50standard-x86-msvc2008 + wincewm50pocket-msvc2005 + wincewm50pocket-msvc2008 + wincewm50smart-msvc2005 + wincewm50smart-msvc2008 + wincewm60professional-msvc2005 + wincewm60professional-msvc2008 + wincewm60standard-msvc2005 + wincewm60standard-msvc2008 + +For a complete list of supported platforms, see +http://www.qtsoftware.com/developer/supported-platforms/supported-platforms/ + +For a description of Qt's platform support policy, see +http://www.qtsoftware.com/support-services/support/platform-support-policy + + +COMMERCIAL EDITIONS + +Desktop Edition licensees can use all the modules provided with their +Qt package. + +GUI Framework licensees may only use the classes contained in +the QtCore, QtGui (except QGraphicsView), QtTest, QtDBus and +Qt3Support modules. + +For a full listing of the contents of each module, please refer to +http://doc.trolltech.com/4.4/modules.html. + + +HOW TO REPORT A BUG + +If you think you have found a bug in Qt, we would like to hear about +it so that we can fix it. Before reporting a bug, please check +http://qtsoftware.com/developer/faqs/ and +http://qtsoftware.com/products/appdev/platform/platforms/ to see if the to see if +the issue is already known. + +Always include the following information in your bug report: the name +and version number of your compiler; the name and version number of +your operating system; the version of Qt you are using, and what +configure options it was compiled with. + +If the problem you are reporting is only visible at run-time, try to +create a small test program that shows the problem when run. Often, +such a program can be created with some minor changes to one of the +many example programs in Qt's examples directory. Please submit the +bug report using the Task Tracker on the Trolltech website: + +http://qtsoftware.com/developer/task-tracker + + +Qt is a trademark of Nokia Corporation and/or its subsidiary(-ies). diff --git a/dist/changes-0.92 b/dist/changes-0.92 new file mode 100644 index 0000000..1226d65 --- /dev/null +++ b/dist/changes-0.92 @@ -0,0 +1,101 @@ +Here is a list of changes in Qt from 0.91 to 0.92. Also look out +for a few new classes; QPrinter, QFileDialog, QDir and QFileInfo. + + +QApplication: +------------- + Use setMainWidget( x ), not exec( x ). + +QString: +-------- + upper(), lower(), stripWhiteSpace() and simplifyWhiteSpace() etc. + do NOT modify the string, instead they return a new string. + +QList and QVector: +------------------ + Changed argument in QList::toVector() from reference to pointer + Changed argument in QVector::toList() from reference to pointer + Removed QVector::apply() + Removed QList::apply() + +QPainter: +--------- + pen(), brush() and font() no longer returns references. + You cannot do this any longer: + QPainter p; + ... + p.pen().setColor( red ); + p.brush().setStyle( NoBrush ); + Instead, set a new pen or brush: + p.setPen( red ); + p.setBrush( NoBrush ); + This enables us to do better optimization, particularly for complex + programs. + +QFile, QFileInfo (new): +----------------------- + Removed QFile::setFileName, + QFile::isRegular => QFileInfo::isFile + QFile::isDirectory => QFileInfo::isDir + QFile::isSymLink => QFileInfo::isSymLink + +Q2DMatrix/QWMatrix: +--------- + Q2DMatrix has been replaced with QWMatrix (qwmatrix.h) + +QPixmap: +-------- + enableImageCache() renamed to setOptimization(). + Optimization is now default ON. See doc for other optimization functions. + +QImage: +------- + scanline() => scanLine() + +QLineEdit/QLCDNumber: +--------------------- + signal textChanged( char * ) => textChanged( const char * ); + slot display( char * ) => display( const char * ) + +QCursor: +-------- + hourGlassCursor => waitCursor + +QButton and friends: +-------------------- + QIconButton removed, setPixmap() added to QButton to replace QIconButton + +QTableWidget: +------------- + Renamed to QTableView (qtablevw.h) + Using int to identify rows and columns, not long. + +QRangeControl: +-------------- + Using int values, not long. + +QScrollBar: +----------- + Using int values, not long. + +QListBox: +--------- + removed setStrList(), use clear(); insertStrList( ... , 0 ); instead + +QColor: +------- + setRGB => setRgb + getRGB => rgb + setHSV => setHsv + getHSV => hsv + +QFontMetrics and QFontInfo: +--------------------------- + Get font metrics from QWidget::fontMetrics() and QPainter::fontMetrics(). + Get font info from QWidget::fontInfo() and QPainter::fontInfo(). + The QFontMetrics(QFont) constructor no longer works. + We had to do these changes to support printing and Windows. + + +There are more changes, left out because we consider them minor and +uninteresting or because we forgot to mention them. :) diff --git a/dist/changes-0.93 b/dist/changes-0.93 new file mode 100644 index 0000000..892395b --- /dev/null +++ b/dist/changes-0.93 @@ -0,0 +1,74 @@ +Here is a list of (major) changes in Qt from 0.92 to 0.93. + +Bug-fixes, optimizations and much improved documentation, of course. + +There are not many changes in the API interface. +Here's a list of the most important changes. + + +QApplication: +------- + setCursor(), restoreCursor() now uses a stack of cursors. + quit() is now a slot. + exit() replaces the old static quit() function. + + +QColor: +------- + New constructor that makes you set an RGB or HSV color directly, + like this: QColor(320, 255, 240, QColor::Hsv) + + +QObject: +-------- + Has now a timerEvent(), which was moved from QWidget. + Compatible with old code. + + +QPainter: +--------- + GC caching (internal optimization) makes drawing very fast. + + drawShade* obsolete, moved to qdrawutl.h and renamed to qDrawShade* + - These are now global functions that take QPainter * and QColorGroup + - Added qDrawWinPanel and qDrawWinButton for Windows 95 look + - Added qDrawPlainRect + + +QPixmap: +------- + New fill() function that fills the pixmap with the background color + OR background pixmap of a widget. + + +QRect: +------ + fixup() renamed to normalize(), returns a new QRect. + + +QWidget: +------- + New function setCaption(), setIcon() and setIconText(), moved from QWindow. + + +New classes: +------------ + QSocketNotifier, makes it possible to write async socket code. + + +New global functions: +--------------------- + qInstallMsgHandler() and qRound(), in qglobal.h. + + +moc: +---- + Supports templates. + + +Documentation: +-------------- + A tutorial. + Template classes (QArray, QList etc.) are documented. + Many more links in the examples. + Postscript documentation (around 400 pages). diff --git a/dist/changes-0.94 b/dist/changes-0.94 new file mode 100644 index 0000000..5353e12 --- /dev/null +++ b/dist/changes-0.94 @@ -0,0 +1,33 @@ +Here is a list of (major) changes in Qt from 0.93 to 0.94. + +Bug-fixes, optimizations and much improved documentation, of course. + +There are not many changes in the API interface. + + +QTextStream: +------------ + eos() renamed to eof() for iostream compatibility. + operator>> for double, float, char*, QString are implemented + get() and getline() added. + + +QDataStream: +------------ + eos() renamed to eof() for iostream compatibility. + + +QPixmap: +-------- + Support for transparency: setMask(QBitmap) and bitBlt. + + +QImage: +------- + Scanline data is aligned on a 32 bit boundary (it used to be 8 + bits). Conversion to and from QPixmap is now faster. + + +Documentation: +-------------- + More documentation fixes. diff --git a/dist/changes-0.95 b/dist/changes-0.95 new file mode 100644 index 0000000..205a476 --- /dev/null +++ b/dist/changes-0.95 @@ -0,0 +1,54 @@ +Here is a list of (major) changes in Qt from 0.93 to 0.95. + +Bug-fixes, optimizations and much improved documentation, of course. + +There are few changes in the API (Qt header files). + + +QPixmap: +-------- + Can draw transparent pixmaps. Call QPixmap::setMask(QBitmap) to + set a mask. + + +QPainter: +--------- + Unified transformation. setWindow() and setViewport() now use + the same code as setWorldXForm() etc. + Internal xform routines have been optimized. + + +QButton: +-------- + isUp() is obsolete, use !isDown() instead. + isOff() is obsolete, use !isOn() instead. + switchOn() is obsolete, use setOn(TRUE) instead. + switchOff() is obsolete, use setOn(FALSE) instead. + + +QPushButton: +------------ + A push button can now be a toggle button. + + +QWidget: +-------- + isActive() was never used and is now obsolete. + + +QTextStream: +------------ + eos() renamed to eof() for iostream compatibility. + operator>> for double, float, char*, QString are implemented + get() and getline() added. + + +QDataStream: +------------ + eos() renamed to eof() for iostream compatibility. + + +QImage: +------- + Scanline data is aligned on a 32 bit boundary (it used to be 8 + bits). Conversion to and from QPixmap is now faster. diff --git a/dist/changes-0.96 b/dist/changes-0.96 new file mode 100644 index 0000000..52555d1 --- /dev/null +++ b/dist/changes-0.96 @@ -0,0 +1,263 @@ +Here is a list of (major) changes in Qt from 0.95 to 0.96. + +Bug-fixes, optimizations and improved documentation, of course. +QClipboard is new. + +There are some changes in the API (Qt header files). Some functions have +been renamed or the arguments have changed. The old versions of these +functions have been obsoleted. A call to an obsoleted function will by +default generate a runtime warning the first time it is called, but it +will be executed correctly. If you really need to ship code fast, you can +turn off the runtime obsolescence warnings by calling +qSuppressObsoleteWarnings(). + +Obsoleted functions will disappear in a future release. To get +compile-time errors for each use of an obsoleted function, compile your +code with -DTEST_OBSOLETE. You should recompile without this option when +you have upgraded your code (otherwise, you may get linking errors). +Note: it is probably not a good idea to compile the Qt library with +-DTEST_OBSOLETE, it may cause problems if you try to link or run +programs that use obsoleted functions. + +For new users: obsoleted functions are no longer documented, in fact they +are not even visible in the documentation. + +*************** Changes that might affect runtime behavior ***************** + +QFileInfo: +---------- + size() returns uint(previousy int), 0 if the size cannot be fetched (was -1). + Use isFile() to check. + + +QPopupMenu +------------ + When a popup menu is a submenu (directly or as a subsub...menu) of a + menu bar(QMenuBar), the menu bar will now always emit the activated() or + highlighted() signal when a submenu emits these signals. This fix might + have undesired effects if you previously have worked around it by + connecting to signals both in menu bar and its submenus. + +*************** Changes that might generate compile errors ***************** +************** when compiling old code ***************** + +QDataStream: +----------- + Serialization of int and uint is no longer supported. Use INT32 and + UINT32 instead. This had to be changed in order to run Qt on 64-bit + architectures. + + +QImage: +------- + 24-bpp pixel format no longer supported, use 32-bpp instead. + + This means that you have to use uint* instead of uchar* when accessing + pixel values. You cannot use the uchar* pointer directly, because the + pixel format depends on the byte order on the underlying platform. Use + qRgb() and friends (qcolor.h) to access the pixels. + + +QWidget: +-------- + setMouseTracking() does not return bool. Call hasMouseTracking() to + determine the mouse tracking state. (This only affects code that + actually uses the return value.) + + (There are other changes in QWidget, see below) + + +*************** Type changes that might generate warnings: ***************** + + +QCache/QIntCache: +----------------- + Using int/uint instead of long/ulong. + + +QDate/QTime/QDateTime: +---------------------- + Using int/uint instead of long/ulong (MS-DOS required long). + + +QIODevice/QBuffer/QFile: +------------------------ + Using int/uint instead of long/ulong. + + +QKeyEvent: +---------- + ascii() now returns int (previously uchar). + + +QTableView: +------------ + uint used instead of ulong (tableFlags() etc.) + + +QTextStream: +------------ + int used instead of long (flags() etc.) + + +***************** Obsoleted functions ********************** + +QAccel: +------- + enable(), disable() and isDisabled() are obsolete. + Use setEnabled(TRUE/FALSE) and !isEnabled() instead. + isItemDisabled(), enableItem(), disableItem() are obsolete. + Use !isItemEnabled(), setItemEnabled(TRUE/FALSE) instead. + + +QApplication: +------------- + cursor(), setCursor() and restoreCursor() obsoleted. + Use overrideCursor(), setOverrideCursor() and restoreOverrideCursor() + instead. + + +QBitmap: +-------- + Constructor takes "const uchar *bits" instead of "const char *" + because of sign problems (uchar = unsigned char). Old constructors are + obsolete. + + +QButton: +-------- + toggleButton() is obsolete, renamed to isToggleButton(). + + +QColor: +------- + The functions QRED, QGREEN, QBLUE, QRGB, QGRAY obsolete. + Instead, use qRed, qGreen, qBlue, qRgb, qGray. + + +QComboBox: +---------- + setStrList() obsolete, use clear() + insertStrList() instead. + string() obsolete, use text() instead. + + +QLCDNumber: +---------- + longValue() is obsolete, use intValue() instead. + + +QListbox: +--------- + The macro LBI_String is obsolete, use LBI_text instead. + string() obsolete, use text() instead. + stringCopy() and setStringCopy() are obsolete. + + +QMenuData: +---------- + string() obsolete, use text() instead. + isItemDisabled(), enableItem(), disableItem() are obsolete. + Use !isItemEnabled(), setItemEnabled(TRUE/FALSE) instead. + checkItem() and uncheckItem() are obsolete. + Use setItemChecked(TRUE/FALSE) instead. + + +QPainter: +--------- + + drawBezier() is obsolete, general Bezier curves are rarely used and + cost too much. Qt will only support drawQuadBezier() (four-point + Bezier) in the future. + +QPointArray: +----------- + move() is obsolete, use translate() instead. + bezier() is obsolete, general Bezier curves are rarely used and + cost too much. Qt will only support quadBezier() (four-point + Bezier) in the future. + + + +QRect: +------ + move() is obsolete, use moveBy() instead. + setTopLeft(), setTopRight(), setBottomLeft(), setBottomRight() and + setCenter() is obsolete, use moveTopLeft(), moveTopRight(), + moveBottomLeft(), moveBottomRight() and moveCenter() instead. + + +QRegion: +------- + move() is obsolete, use translate() instead. + + +QSocketNotifier: +---------------- + enabled() is obsolete. Use isEnabled() instead. + + +QWidget: +-------- + enable(), disable() and isDisabled() are obsolete. + Use setEnabled(TRUE/FALSE) and !isEnabled() instead. + + setMinimumSize(), setMaximumSize(), minimumSize(), maximumSize() are obsolete + use setMinSize(), setMaxSize(), minSize(), maxSize() instead. + + enableUpdates() obsolete, use isUpdatesEnabled()/setUpdatesEnabled(). + + id() is obsolete, it has been renamed to winId(). + +***************** All other changes from 0.95 to 0.96 ********************** + +moc +---------- + Gives a warning if no output is generated. + + +qglobal.h: +---------- + INT32 and UINT32 typedefs changed to work with DEC Alpha. + + +QApplication: +------------- + clipboard() is new. + + +QButtonGroup: +------------- + Exclusive group setting added (isExclusive and setExclusive). + find() is new. + + +QColor: +------- + New type QRgb (uint), used for RGB triplet. + + +QLineEdit: +---------- + You can now mark text, and copy and paste to/from the clipboard. + + +QPaintDevice: +--------- + The bitblt function now takes an ignoreMask parameter. It has a default + value, so no old code will be broken. + +QPrinter: +------------ + fixed minor bugs in handling of polygons and beziers. + + +QWidget: +-------- + New protected virtual functions styleChange(), backgroundColorChange(), + backgroundPixmapChange(), paletteChange() and fontChange(). + These functions are called from setStyle(), setBackgroundColor() etc. + You can reimplement them to if you need to know when widget properties + changed and to optimize updates. + + The destroyed() signal has been moved to QObject. + diff --git a/dist/changes-0.98 b/dist/changes-0.98 new file mode 100644 index 0000000..a36abeb --- /dev/null +++ b/dist/changes-0.98 @@ -0,0 +1,98 @@ +Here is a list of (major) changes in Qt from 0.96 to 0.98. +As usual, we fixed some bugs and improved the documentation. + + +*************** Changes that might affect runtime behavior ***************** + +QWidget: +-------- + setMinimumSize() and setMaximumSize() now force the widget to + a legal size. resize() and setGeometry() obey the widget's + minimum/maximum size. + + The default behaviour of QWidget::closeEvent is now to hide the widget, + not to delete it as before (which was potentially dangerous). This means + that if you have a top level widget and the user closes it via the close + box, it will now hide itself if you have not reimplemented closeEvent(). + See the QWidget::closeEvent() and QCloseEvent documentation for details. + + (There are other changes in QWidget, see below) + + +*************** Changes that might generate compile errors ***************** +************** when compiling old code ***************** + +Disabled copy constructors and operators= +----------------------------------------- + Copy constructors and operators= are disabled in the classes that cannot + be copied (this includes all classes that inherit from QObject). This + will let the compiler find bugs in your code, you'll get compile time + errors where you most probably would have gotten core dumps before. + This change has been done in the following classes: + + QAccel QApplication QBuffer QButton QButtonGroup QCheckBox QClipboard + QComboBox QConnection QDataStream QDialog QFile QFileDialog QFrame + QGroupBox QIODevice QImageIO QLCDNumber QLabel QLineEdit QListBox + QMenuBar QMenuData QMenuItem QMessageBox QMetaObject QObject + QPSPrinter QPaintDevice QPainter QPicture QPopupMenu QPrintDialog + QPrinter QPushButton QRadioButton QRangeControl QScrollBar QSignal + QSocketNotifier QTableView QTextStream QTimer QWidget QWindow + + The other classes all have sensible copy constructors and operators=. + +QDate: +------ + These were protected, now private: + static const char *monthNames[]; + static const char *weekdayNames[]; + uint jd; + +QListBox: +--------- + The internals of QListBox are completely reworked. Definition of custom + QListBoxItems is now much easier. This is *not* compatible with the old + way of defining custom QLBItems. See the QListBoxItem documentation for + details. + +QTime: +------ + This was protected, now private: + uint ds; + +*************** Type changes that might generate warnings: ***************** + +none + +***************** Obsoleted functions ********************** + +none + +***************** All other changes from 0.96 to 0.98 ********************** + +moc: +---- + Moc previously gave a syntax error when the word "class" was found + in a string outside a class declaration. This bug has now been + fixed. + + More moc arguments, check the manpage for details. + +QFont: +------ + Two new convenience functions; bold() and setBold(). + +QLabel: +------- + setMargin() and margin() are new. setMargin() specifies a minimum margin + when the label contents are justified. + +QWidget: +-------- + You can specify a custom widget frame for top level widgets, including + no frame at all. See the widget constructor doc. for details. + + Qt now has enter and leave events. Reimplement the virtual functions + void enterEvent( QEvent * ) and void leaveEvent( QEvent * ) to receive + events when the mouse cursor leaves or enters the visible part of the + widget. + diff --git a/dist/changes-0.99 b/dist/changes-0.99 new file mode 100644 index 0000000..80be555 --- /dev/null +++ b/dist/changes-0.99 @@ -0,0 +1,60 @@ +Here is a list of user-visible changes in Qt from 0.98 to 0.99. +As usual, we fixed some bugs and improved the documentation. + +Qt 0.99 includes makefiles for Linux, Solaris, SunOS, FreeBSD, OSF/1, +Irix, BSD/OS, SCO and HP-UX. + + +*************** Changes that might affect runtime behavior ***************** + +none + +*************** Changes that might generate compile errors ***************** +************** when compiling old code ***************** + +QVector: +-------- + +Removed operator const type**(). + +*************** Type changes that might generate warnings: ***************** + +none + +***************** Obsoleted functions ********************** + +none + +***************** All other changes from 0.98 to 0.99 ********************** + +QApplication: +------------- +Added beep() to make a sound. + + +QFileInfo +--------- +Added readLink() to return the name of the file a symlink points to, +fixed bug in isSymlink(). + + +QPrinter: +--------- +The X11 version now supports landscape printing and different paper sizes. + + +QTableView: +----------- +The functions horizontalScrollBar and verticalScrollBar gives access +to the internal scroll bars so you can connect to their signals. + + +QWidget: +-------- +Added sizeHint virtual function which is implemented in subclasses to +return a recommended size. + +Added new function setFixedSize() to set both the minimum and maximum sizes +at the same time. + +Added clearFocus() function to take keyboard focus from the widget. diff --git a/dist/changes-1.0 b/dist/changes-1.0 new file mode 100644 index 0000000..cf9f7a1 --- /dev/null +++ b/dist/changes-1.0 @@ -0,0 +1,62 @@ +Here is a list of user-visible changes in Qt from 0.99 to 1.0. +As usual, we fixed some bugs and improved the documentation. + + +**************************************************************************** +* Changes that might affect runtime behavior * +**************************************************************************** + +QComboBox: +---------- +The combo box is resized to the largest item when automatic resizing +is enabled. In 0.99 it resized itself to the current item. + + + +**************************************************************************** +* Changes that might generate compile errors * +* when compiling old code * +**************************************************************************** + +none + + + +**************************************************************************** +* Type changes that might generate warnings: * +**************************************************************************** + +none + + + +**************************************************************************** +* Obsoleted functions * +**************************************************************************** + +All pre-1.0 obsoleted functions are now removed. + + + +**************************************************************************** +* All other changes from 0.99 to 1.0 * +**************************************************************************** + +QBitmap: +-------- +Added constructor that takes a file name. Loads an image from file. + + +QDialog: +-------- +QDialog inherits QWidget instead of QWindow. + + +QPixmap: +-------- +Added constructor that takes a file name. Loads an image from file. + + +QTimer: +------- +Added static function singleShot(). Convenient function. diff --git a/dist/changes-1.1 b/dist/changes-1.1 new file mode 100644 index 0000000..ff9d2a7 --- /dev/null +++ b/dist/changes-1.1 @@ -0,0 +1,110 @@ +Here is a list of user-visible changes in Qt from 1.0 to 1.1. As +usual, we fixed some bugs, made some more speedups, and improved the +documentation. + + +**************************************************************************** +* Changes that might affect runtime behavior * +**************************************************************************** + +We've added keyboard interface to more widgets, and changed the +default focus policy radically. For example, by default you can TAB +to button, but it does not grab focus when you click it. The new +QWidget::setFocusPolicy() function can be used to change focus policy +for all widgets. + +The font matching algorithm has been tweaked in order to provide more +predictable fonts in more cases. For some users (such as those with a +75dpi X server and only 100dpi fonts installed) it may change the +output of some programs. + +sizeHint() and hence default size has been tweaked for some widgets; +QMenuBar and QPushButton in particular. + + +**************************************************************************** +* Changes that might generate compile errors * +* when compiling old code * +**************************************************************************** + +We've renamed "declare" in qgeneric.h to Q_DECLARE due to naming +conflicts. Though we try to provide backward compatibility, there may +be problems for a few programs. + + +**************************************************************************** +* Type changes that might generate warnings: * +**************************************************************************** + +none + + +**************************************************************************** +* Obsoleted functions * +**************************************************************************** + +none + + +**************************************************************************** +* New classes * +**************************************************************************** + +QTabDialog (and QTabBar) provide a tabbed dialog. examples/pref shows +simple usage of QTabDialog. + +QMultiLineEditor is the long-awaited multi-line editor. + +QGridLayout provides grid-like geometry management for any widget, +with flexible row/column elasticity, minimum and maximum sizes. + +QBoxLayout provides more complex and powerful geometry management: +boxes and widgets stacked inside other boxes, and finally a top-level +box connected to a widget. + +QToolTip provides tool tips for any widget. + + +**************************************************************************** +* Other changes from 1.0 to 1.1 * +**************************************************************************** + +Added QApplication::setColorMode() and colorMode(). + +Added QColor::setAllocContext() and friends; these functions enable +applications to allocate discardable colors and then discard them. + +Removed some GNU-make features from the makefiles. + +Added a QPalette constructor to construct an entire palette from a single +background color, for convenience. + +moc output now has a version number #define. + +AIX support added. IRIX and NetBSD fixed. + +Rewrote a couple of functions to work around compiler bugs, or +purify/boundschecker overzealousness. + +Fixed that ugly man-page SYNOPSIS bug. + +Added the static function QMessageBox::query(). + +QRect::unite() now produces the desired results if exactly one of the +rectangles is invalid. + +QObject::parent() is now public. + +QPainter::drawWinFocusRect() draws a Windows 95-style focus rectangle. +(A focus rectangle can not be drawn using ordinary Windows drawing +functions.) + +QApplication::processEvents() added to cater for long-running +computations; it processes one round of window system events and +timers and then returns. + +QComboBox has been extended to provide an editable combo box and Motif +2.x compatible look and feel. + +We've also added a host of new workarounds for bugs in Borland C++, +Microsoft VC++, DEC CXX and HP CC. diff --git a/dist/changes-1.2 b/dist/changes-1.2 new file mode 100644 index 0000000..d4d2c2c --- /dev/null +++ b/dist/changes-1.2 @@ -0,0 +1,119 @@ +Here is a list of user-visible changes in Qt from 1.1 to 1.2. As +usual, we fixed some bugs, made some more speedups, and improved the +documentation. + + +**************************************************************************** +* Changes that might affect runtime behavior * +**************************************************************************** + +QGridLayout::addWidget() and addMultiCellWidget(): The align parameter +is now interpreted correctly. (Previously up/down and right/left were +reversed.) If you have worked around this bug, your widgets may now be +incorrectly aligned. + +QWidget: Every widget is now guaranteed move and resize events. The +event is deferred until the first show(). This may cause problems in +rare cases involving event filters. + +**************************************************************************** +* Changes that might generate compile errors * +* when compiling old code * +**************************************************************************** + +none + +**************************************************************************** +* Type changes that might generate warnings: * +**************************************************************************** + +none + +**************************************************************************** +* Deprecated functions * +**************************************************************************** + +QApplication::setColorMode() and colorMode() will be obsoleted. Use +setColorSpec() and colorSpec() instead. + +qchecksum() will be obsoleted. Please use qChecksum() instead. + +**************************************************************************** +* New classes * +**************************************************************************** + +QSlider is a widget to input values from a range. If you have been +using a standalone QScrollBar, you will probably want to switch to a +QSlider. + +OpenGL/Mesa support: QGLWidget, QGLContext and QGLFormat. To use these +classes you need to build the Qt/OpenGL library (qgl) in qt/opengl/src. + +**************************************************************************** +* Other changes from 1.1 to 1.2 * +**************************************************************************** + +QApplication::setColorSpec() can specify private colormaps or +non-default visuals + +New function QButton::setAutoRepeat(). + +QComboBox: New function currentText(), two new insertion policies: +AfterCurrent and BeforeCurrent. + +QCursor: added new global cursor blankCursor. + +QFont::key(), new function for caching. + +QFontMetrics::QFontMetrics( const QFont& ) new constructor gives +fontmetrics directly for a font. This is much faster than using +QWidget::fontMetrics() or QPainter::fontmetrics(). + +QImage: image load/save functions: + QImage( const char *filename ) + imageFormat(), load(), loadFromData(), save() + operator>>(), operator<<() + XPM support, QImage( const *xpm[] ) + Alpha channel support: + hasAlphaBuffer(), setAlphaBuffer() + createAlphaMask(), + Automatic mask generaton: createHeuristicMask() + Filling the entire image: fill() + +QLCDNumber now supports filled segments: + setSegmentStyle(), segmentStyle() + +QLabel now supports accellerated labels: + setBuddy(), buddy() and a new constructor. + +QLineEdit new functions: + show/hide frame: setFrame(), frame() + password entry mode: setEchoMode(), echoMode() + +QMouseEvent: x() and y() convenience functions. + +QPainter: new constructor QPainter( const QPaintDevice* ) does automatic +begin() and end(). New function flush(). + +QPixmap new functions: + serialNumber() for caching purposes. + selfMask() QPixmap( const char *xpm[] ) + createHeuristicMask() + +QPopupMenu: Added functions to enable checkmarks: + setCheckable(), isCheckable() + +QScrollBar: sizeHint() implemented. + +QTabBar now supports keyboard input. New function currentTab(). + +QTabDialog: new function setOKButton(). + +Added support for XFree86 on OS/2. + +New examples: + examples/tooltip demonstrates dynamic tooltips + examples/table demonstrates QTableView + examples/hello is a different program + +examples/xshape has been removed. diff --git a/dist/changes-1.30 b/dist/changes-1.30 new file mode 100644 index 0000000..255d89c --- /dev/null +++ b/dist/changes-1.30 @@ -0,0 +1,278 @@ +Here is a list of user-visible changes in Qt from 1.2 to 1.30. As +usual, we fixed some bugs, made some more speedups, and improved the +documentation. + +Keyboard accelerators and traversal are significantly improved. + +Two new extensions included with Qt 1.30. They are not part of the library: + +Netscape plugin support. You can now write portable Netscape plugins +using Qt. See the qt/extensions/nsplugin directory in the distribution. + +The ImageIO extension library gives a framework for adding new image +formats, including PNG and JPEG in this release. See the qt/extensions/imageio +directory in the distribution. + +The OpenGL extension for Qt now resides in qt/extensions. + + +**************************************************************************** +* New classes * +**************************************************************************** + +* QProgressBar displays a progress bar. + +* QProgressDialog uses QProgressBar to give the user feedback during long + operations, as well as a means of aborting. + +* QMovie supports animated GIFs and incremental loading of images. + +* QHBoxLayout and QVBoxLayout are convenience classes giving a simpler + interface to QBoxLayout. + +* QValidator provides a mechanism for validating input. + + +**************************************************************************** +* Enhancements from 1.2 to 1.30 * +**************************************************************************** + +QFont now supports charsets latin1 through latin9. + +New command-line arguments: -style motif and -style windows are +accepted, as well as -style=motif and -style=windows, -visual, -ncols, +-cmap. + +QMultiLineEdit is usable for much bigger documents than in 1.2 + +More sizeHint() functions added, some existing ones tweaked. + +Many widgets have improved look and feel, particularly changes to +Windows GUI style to match Windows more closely. + +Improved Postscript output. + +Color handling has been improved; better 32-to-8 conversion; Qt +prefers to use Macintosh/Netscape color cube in 8-bit mode; more and +better dithering support. + +GIF and PPM support. + +QMessageBox has a number of new static functions to replace the +venerable message(): information(), warning(), critical() and about(). + +QPopupMenu can now display icon and text in the same item. + +QPopupMenu::exec() to pop up a synchronous popup menu. + +QListBox now supports multi selection. + +QWidget::setBackgroundMode() gives a powerful way of managing widget +backgrounds, to reduce flicker. + +QWidget::setIcon() now works under both X11 and Windows. + +The file dialog now remembers the previously selected directory. + +QApplication::setWinStyleHighlightColor() sets the highlight color in +windows style. + +QApplication::setDoubleClickInterval() sets the double click timeout + +The layout example is new and more informative. + +There is a new openGL example; extension/opengl/examples/box/ shows +how to control an openGL widget using Qt user interface components. + + +**************************************************************************** +* Changes that might affect runtime behavior * +**************************************************************************** + +Tab/Shift-Tab handling has been improved a lot; this means that +widgets which couldn't get keyboard focus before now can. + +Some widgets (buttons, tab bars, tab dialogs) semi-automatically set +up keyboard accelerators. ( setText("E&xit") will give Alt-X as an +accelerator.) In some very rare cases, this will cause changes of +behaviour. + +The QColor::light() function now works, and anything which relied on +its buggy behaviour might be a little darker than expected until changed, +usually just recompiling (the default argument has also changed). + +The colors used have been tuned a bit; pixmaps that "know" the RGB +values of colorGroup().background() and the like will look just a tiny +bit wrong. + +QApplication calls setlocale to the local environment, except for +LC_NUMERIC which is set to the C locale. This means that input/output +of floating point numbers will always use '.' as the decimal separator, +while all other locale dependant operations will use the default locale. + + +**************************************************************************** +* Changes that might generate compile errors * +* when compiling old code * +**************************************************************************** + +none + +**************************************************************************** +* Type changes that might generate warnings: * +**************************************************************************** + +none + +**************************************************************************** +* Deprecated functions * +**************************************************************************** + +QApplication::setColorMode() + - see QApplication::setColorSpec(int) +QRegion::xor() + - see QRegion::eor() +QMessageBox::message() + - see QMessageBox::information/warning/critical +QMultiLineEdit::getCursorPosition() + - see QMultiLineEdit::cursorPosition() +QTabDialog::setOKButton() + - see QTabDialog::setOkButton() + +**************************************************************************** +* New public/protected functions added to existing classes * +**************************************************************************** + +QAccel::repairEventFilter() +QApplication::activeModalWidget() +QApplication::activePopupWidget() +QApplication::allWidgets() +QApplication::doubleClickInterval() +QApplication::hasGlobalMouseTracking() +QApplication::processEvents(int) +QApplication::processOneEvent() +QApplication::setDoubleClickInterval(int) +QApplication::setGlobalMouseTracking(bool) +QApplication::setWinStyleHighlightColor(QColor const &) +QApplication::winStyleHighlightColor() +QApplication::x11ProcessEvent(_XEvent *) +QBoxLayout::className() const +QButton::accel() const +QButton::animateClick() +QButton::enabledChange(bool) +QButton::setAccel(int) +QComboBox::clearValidator() +QComboBox::setStyle(GUIStyle) +QComboBox::setValidator(QValidator *) +QComboBox::validator() const +QDir::convertSeparators(char const *) +QFrame::sizeHint() const +QGridLayout::addColSpacing(int, int) +QGridLayout::addRowSpacing(int, int) +QGridLayout::className() const +QImage::convertDepth(int, int) const +QImage::create(QSize const &, int, int, QImage::Endian) +QImage::createAlphaMask(int) const +QImage::inputFormats() +QImage::outputFormats() +QImage::pixel(int, int) const +QImage::pixelIndex(int, int) const +QImage::setPixel(int, int, unsigned int) +QImage::valid(int, int) const +QImageIO::inputFormats() +QImageIO::outputFormats() +QLabel::movie() const +QLabel::setMovie(QMovie const &) +QLayout::className() const +QLineEdit::clearValidator() +QLineEdit::setValidator(QValidator *) +QLineEdit::sizeHint() const +QLineEdit::validator() const +QListBox::clearSelection() +QListBox::focusOutEvent(QFocusEvent *) +QListBox::highlighted(char const *) +QListBox::isMultiSelection() const +QListBox::isSelected(int) const +QListBox::selected(char const *) +QListBox::selectionChanged() +QListBox::setMultiSelection(bool) +QListBox::setSelected(int, bool) +QListBox::toggleCurrentItem() +QMenuBar::heightForWidth(int) const +QMenuBar::leaveEvent(QEvent *) +QMenuBar::separator() const +QMenuBar::setSeparator(QMenuBar::Separator) +QMenuData::changeItem(QPixmap const &, char const *, int) +QMenuData::insertItem(QPixmap const &, char const *, QObject const *, char const *, int) +QMenuData::insertItem(QPixmap const &, char const *, QPopupMenu *, int, int) +QMenuData::insertItem(QPixmap const &, char const *, int, int) +QMessageBox::about(QWidget *, char const *, char const *) +QMessageBox::aboutQt(QWidget *, char const *) +QMessageBox::buttonText(int) const +QMessageBox::critical(QWidget *, char const *, char const *, char const *, char const *, char const *, int, int) +QMessageBox::critical(QWidget *, char const *, char const *, int, int, int) +QMessageBox::icon() const +QMessageBox::iconPixmap() const +QMessageBox::information(QWidget *, char const *, char const *, char const *, char const *, char const *, int, int) +QMessageBox::information(QWidget *, char const *, char const *, int, int, int) +QMessageBox::setButtonText(int, char const *) +QMessageBox::setIcon(QMessageBox::Icon) +QMessageBox::setIconPixmap(QPixmap const &) +QMessageBox::setStyle(GUIStyle) +QMessageBox::standardIcon(QMessageBox::Icon, GUIStyle) +QMessageBox::warning(QWidget *, char const *, char const *, char const *, char const *, char const *, int, int) +QMessageBox::warning(QWidget *, char const *, char const *, int, int, int) +QMultiLineEdit::cursorPoint() const +QMultiLineEdit::cursorPosition(int *, int *) const +QMultiLineEdit::getMarkedRegion(int *, int *, int *, int *) const +QPainter::drawPoints(QPointArray const &, int, int) +QPainter::drawWinFocusRect( int, int, int, int, const QColor & ) +QPalette::detach() +QPicture::data() const +QPicture::isNull() const +QPicture::setData(char const *, unsigned int) +QPicture::size() const +QPixmap::convertFromImage(QImage const &, int) +QPixmap::load(char const *, char const *, int) +QPixmap::loadFromData(unsigned char const *, unsigned int, char const *, int) +QPopupMenu::exec() +QPopupMenu::setActiveItem(int) +QRegion::eor(QRegion const &) const +QSize::transpose() +QTabBar::setCurrentTab(QTab *) +QTabBar::setCurrentTab(int) +QTabBar::setShape(QTabBar::Shape) +QTabBar::shape() const +QTabBar::tab(int) +QTabBar::tabList() +QTabDialog::addTab(QWidget *, QTab *) +QTabDialog::hasOkButton() const +QTabDialog::selected(char const *) +QTabDialog::setTabBar(QTabBar *) +QTabDialog::showPage(QWidget *) +QTabDialog::styleChange(GUIStyle) +QTabDialog::tabBar() const +QTabDialog::tabLabel(QWidget *) +QTableView::minViewX() const +QTableView::minViewY() const +QTableView::updateTableSize() +QToolTip::font() +QToolTip::palette() +QToolTip::setFont(QFont const &) +QToolTip::setPalette(QPalette const &) +QWidget::backgroundMode() const +QWidget::create(unsigned int, bool, bool) +QWidget::destroy(bool, bool) +QWidget::focusProxy() const +QWidget::focusWidget() const +QWidget::isVisibleToTLW() const +QWidget::setBackgroundMode(QWidget::BackgroundMode) +QWidget::setFixedHeight(int) +QWidget::setFixedWidth(int) +QWidget::setFocusProxy(QWidget *) +QWidget::setMaximumHeight(int) +QWidget::setMaximumWidth(int) +QWidget::setMinimumHeight(int) +QWidget::setMinimumWidth(int) +QWidget::setTabOrder(QWidget *, QWidget *) +QWidget::update(QRect const &) diff --git a/dist/changes-1.31 b/dist/changes-1.31 new file mode 100644 index 0000000..b6b2d65 --- /dev/null +++ b/dist/changes-1.31 @@ -0,0 +1,34 @@ +1.31 is a bug-fix release of Qt and only contains minor changes compared +to Qt 1.30 + +Here is a list of the bug-fixes made in Qt from 1.30 to 1.31. + +Changing the font of a QButton, QPushButton, QCheckBox or QRadioButton now +works correctly. + +QRadiobutton: Correct toggling in a QButtonGroup when activated by an + accelerator. + +QPopupMenu: Items updated correctly when activated by an accelerator. + +QProgressBar: Base color is no longer fixed to white. + +QProgressDialog: setLabel() and setCancelButton() now ensure that a given + widget is shown and is a child of QProgressDialog. + +QWidget: setEnabled( FALSE ) now moves focus correctly. + +QLineEdit and +QMultiLineEdit: In keyPressEvent() backspace no longer inserts an + unprintable character with some rare keyboard layouts. + +QMenubar: Mouse presses on items without any popup menu are now + always recognized. + +Changes to fix compile problems under IRIX. + +Changes to fix compile problems on some versions of AIX. + +Changes to fix compile problems with aCC on HP-UX. + +Minor documentation fixes. diff --git a/dist/changes-1.39-19980327 b/dist/changes-1.39-19980327 new file mode 100644 index 0000000..3c5843d --- /dev/null +++ b/dist/changes-1.39-19980327 @@ -0,0 +1,963 @@ +src/widgets/qlabel.cpp 2.21 agulbra +9 -5 + + new sizeHint(); "yes\nyes" is as tall as "Yes\nYes" + + +src/tools/qstrlist.h 2.7 hanord +10 -9 (1997/10/16) + + Fixed STL crash reported by ust@egd.igd.fhg.de + + +src/kernel/qregion.cpp 2.5 agulbra +3 -3 (1997/10/19) +src/kernel/qregion.h 2.6 agulbra +2 -2 + + USL C++ understands xor + + +src/kernel/qkeycode.h 2.5 hanord +13 -2 (1997/10/22) + + Added function keys F25..F35 for X only + + +src/widgets/qpushbt.cpp 2.33 hanord +5 -9 + + Always clear button background in Windows style + + +src/widgets/qpushbt.cpp 2.32 hanord +8 -8 + + Fixed background color for windows style + + +src/kernel/qcur_win.cpp 2.5 hanord +15 -5 + + Fix the cursor bug on Win95 + + +src/kernel/qobject.cpp 2.36 eiriken +3 -3 +src/kernel/qwid_win.cpp 2.39 eiriken +19 -17 + + Fixed bugs in setMaximumSize and setMinimumSize + + +src/widgets/qlabel.cpp 2.23 agulbra +11 -2 +src/widgets/qlabel.h 2.5 agulbra +2 -1 + + add clear() + + +src/kernel/qapp.cpp 2.38 eiriken +8 -2 (1997/10/31) + + Added warning in QApplication::palette() if called before a QApplication + is created. + + +src/kernel/qcolor.h 2.8 hanord +6 -7 + + Fixed the color== operator + + +src/kernel/qcol_win.cpp 2.16 hanord +13 -41 +src/kernel/qcolor.cpp 2.12 hanord +118 -36 +src/kernel/qcolor.h 2.7 hanord +7 -6 + + Moved platform independent functions into qcolor.cpp + Optimized setNamedColor for #RRGGBB style color names. + Doc warns that RGB bit format may change in the future. + setRgb(QRgb) optimized. + Added static class member color_init (not a global file variable) + + +src/kernel/qapp_win.cpp 2.64 hanord +67 -50 + + Detects the Windows version using GetVersionEx. + Moved the timer function to the appropriate section. + + +src/kernel/qclb_x11.cpp 2.4 agulbra +6 -5 + + call XInternAtoms() once instead of XInternAtom N times. should + improve start-up time by about 3-5 times the ping time to the server. + + +src/widgets/qlistbox.h 2.12 agulbra +2 -1 (1997/11/09) + + don't let down-arrow set the current item to be half-visible + + +src/kernel/qpainter.cpp 2.17 hanord +61 -5 (1997/11/12) +src/kernel/qpainter.h 2.12 hanord +2 -1 + + Added new begin() which takes a paint device and a widget to copy pen, font + etc. from. + Fixed inverted dense pattern on Windows. + + +src/widgets/qslider.cpp 2.45 paul +3 -2 + + fixing bug when setting value in constructor followed by resetting value + to zero. + + +src/kernel/qimage.cpp 2.65.2.1 agulbra +4 -4 + + avoid segfaults for image handlers where either read or + write is 0. enables gif image handlers. + + +src/qt.pro 2.6 agulbra +4 -2 (1997/11/20) +src/kernel/qdragobject.cpp 2.1 agulbra initial checkin +src/kernel/qdragobject.h 2.1 agulbra initial checkin +src/kernel/qevent.h 2.6 agulbra +59 -2 +src/widgets/qlined.cpp 2.54 agulbra +92 -3 +src/widgets/qlined.h 2.19 agulbra +3 -1 + + QDragObject and related goodies. not ready for prime time, but hey! + + +src/widgets/qcombo.cpp 2.68 agulbra +52 -2 +src/widgets/qcombo.h 2.20 agulbra +5 -1 + + new function setListBox() - allows custom combos like the ones in ACT + + +src/kernel/qapp_win.cpp 2.65 warwick +4 -3 +src/kernel/qwid_win.cpp 2.43 warwick +51 -19 + + Reimplement QWidget::recreate(), using almost same code as X11 version. + + +src/kernel/qptr_win.cpp 2.21.2.1 hanord +8 -8 (1997/11/25) + + Fixed bad dense patterns + + +src/widgets/qchkbox.cpp 2.17 warwick +16 -7 (1997/11/28) +src/widgets/qradiobt.cpp 2.21 warwick +18 -7 + + Check pixmap in sizeHint() + + +src/kernel/qpainter.h 2.14 hanord +3 -1 (1997/12/02) + + Added xForm and xFormDev with index,npoints arguments + + +src/kernel/qpainter.cpp 2.19 hanord +399 -2 +src/kernel/qptr_x11.cpp 2.31 hanord +45 -333 + + Moved platform-independent xForm functions into qpainter.cpp. + Fixed bugs in drawPoints, drawPolyline, drawLineSegments and + drawPolygon where index > 0 or npoints < array size. + Added xForm(pointarray,index,size) and similar xFormDev(). + Now Purify should shut up. + Removed some tests for cpen.style() != NoPen. Makes some code + somewhat slower, but makes QPainter more consistent. + + +src/kernel/qptd_x11.cpp 2.9 hanord +11 -3 +src/kernel/qptr_x11.cpp 2.30 hanord +11 -5 + + Set graphics exposures to FALSE except when bitBlt from widget to widget + + +src/kernel/qpm_win.cpp 2.29 hanord +12 -12 + + When converting an image to a pixmap, don't create a new pixmap unless + the depth or dimension changes. + + +src/widgets/qlined.cpp 2.56 agulbra +64 -41 +src/widgets/qlined.h 2.21 agulbra +6 -3 + + various small fixes, mostly to draw correctly. added setFont() and + setEnabled() to update correctly, I guess we need setStyle() and + setPalette() too. + + +src/dialogs/qmsgbox.cpp 2.40 warwick +8 -6 (1997/12/08) + + Correct layout for text smaller than icon. + + +src/widgets/qprogbar.cpp 2.15 warwick +22 -8 + + Ensure display is up-to-date when a progress bar is re-used. + + +src/kernel/qptr_x11.cpp 2.32 warwick +4 -2 + + Fix out-of-bounds clipping. + + +src/kernel/qapp_win.cpp 2.67 hanord +23 -8 + + Get the app name even for console applications (when WinMain isn't called) + + +src/kernel/qasyncimageio.cpp 1.23 warwick +57 -26 +src/kernel/qasyncimageio.h 1.12 warwick +2 -1 + + Handle nasty GIFs. + + +src/widgets/qspinbox.cpp 2.24 aavit +170 -25 (1997/12/09) +src/widgets/qspinbox.h 2.14 aavit +17 -8 + + Improved QSpinbox - now easier to subclass; and "Auto" choice added. + + +src/tools/qregexp.cpp 2.6 hanord +15 -12 + + Fixed serious bug: regular expression with characters > 127 now works. + + +src/kernel/qprn_x11.cpp 2.6 warwick +3 -3 + + QPrinter::newPage() previous always returned FALSE. Fixed. + + +src/widgets/qscrbar.cpp 2.30 agulbra +6 -6 + + be a bit kinder and gentler about the hot zone in windows style. the + old limit (30 pixels to either side of the bar) was too tight + + +src/kernel/qapp_win.cpp 2.68 hanord +6 -3 (1997/12/15) + + Fixed the modal loop problem related to synch popups with signals + + +src/widgets/qlined.cpp 2.57 agulbra +8 -8 (1998/01/05) + + don't allow paste from ****'ed line edits + + +src/kernel/qasyncimageio.cpp 1.25 warwick +14 -6 (1998/01/06) + + Be more forgiving about broken GIF - as forgiving as netscape + + +src/kernel/qasyncimageio.cpp 1.24 warwick +5 -2 + + Protection against more broken GIFs. + + +extensions/xt/doc.conf 1.1 warwick initial checkin (1998/01/07) +extensions/xt/doc/annotated.doc 1.1 warwick initial checkin +extensions/xt/doc/classes.doc 1.1 warwick initial checkin +extensions/xt/doc/examples.doc 1.1 warwick initial checkin +extensions/xt/doc/index.doc 1.1 warwick initial checkin +extensions/xt/examples/mainlyMotif/editor.cpp 1.1 warwick initial checkin +extensions/xt/examples/mainlyMotif/editor.pro 1.1 warwick initial checkin +extensions/xt/examples/mainlyQt/editor.cpp 1.1 warwick initial checkin +extensions/xt/examples/mainlyQt/editor.pro 1.1 warwick initial checkin +extensions/xt/examples/mainlyXt/editor.cpp 1.1 warwick initial checkin +extensions/xt/examples/mainlyXt/editor.pro 1.1 warwick initial checkin +extensions/xt/src/qxt.cpp 1.1 warwick initial checkin +extensions/xt/src/qxt.h 1.1 warwick initial checkin +extensions/xt/src/qxt.pro 1.1 warwick initial checkin + + Qt Xt/Motif Extension, examples, docs. + + +src/kernel/qevent.cpp 2.7 paul +48 -9 (1998/01/08) +src/kernel/qevent.h 2.9 paul +17 -1 +src/kernel/qgmanagr.cpp 2.22 paul +97 -10 +src/kernel/qgmanagr.h 2.7 paul +3 -1 +src/kernel/qlayout.cpp 2.27 paul +2 -23 +src/kernel/qwid_win.cpp 2.44 paul +19 -3 +src/kernel/qwidget.cpp 2.85 paul +10 -2 + + New events ChildInserted, ChildRemoved and LayoutHint. Not tested on Windows. + Use new events in GM. + + +src/qt.pro 2.11 paul +2 -0 +src/widgets/qsplitter.cpp 1.1 paul initial checkin +src/widgets/qsplitter.h 1.1 paul initial checkin + + New widget QSplitter + + +src/kernel/qpntarry.cpp 2.12 warwick +4 -4 + + Fix quad bezier for small curves + + +src/kernel/qwidget.cpp 2.87 agulbra +71 -16 +src/kernel/qwidget.h 2.38 agulbra +5 -2 +src/kernel/qwindefs.h 2.20 agulbra +2 -1 + + added setAutoMinimumSize(). fixed a couple of documentation errors. + + +src/kernel/qwid_win.cpp 2.45 warwick +4 -3 (1998/01/13) + + Fix case of recreate(0,...) on tlw. + + +src/widgets/qbutton.cpp 2.40.2.1 agulbra +7 -7 + + paint correctly when there is a background color + + +src/widgets/qlined.cpp 2.58 paul +18 -8 (1998/01/14) + + Correct cursor when end(). Better blinking + + +src/dialogs/qtabdlg.cpp 2.36 agulbra +172 -213 +src/dialogs/qtabdlg.h 2.17 agulbra +2 -1 +src/kernel/qgmanagr.cpp 2.23 agulbra +22 -21 +src/widgets/qtabbar.cpp 2.30 agulbra +12 -15 +src/widgets/qwidgetstack.cpp 2.1 agulbra initial checkin +src/widgets/qwidgetstack.h 2.1 agulbra initial checkin + + The new class QWidgetStack encapsulates a bunch of widgets of the same + size, where the one on top of the stack is visible. It provides slots + to raise any of the widgets to the top of the stack and so on. + + QTabDialog now uses QWidgetStack. A couple of hacks went away, and it + now uses QBoxLayout to manage its children. Some more minor changes + are desirable here. + + QTabBar now uses autoMinimumSize() appropriately, and is closer to the + new Windows look and feel (ie. it lost the bold stuff). QTabDialog is + adapted accordingly. + + QGManager now has a one-line VERY INEFFICENT fix that SORELY NEEDS + OPTIMIZATION to make layout hint events propagate outwards correctly. + There's about twenty hashes on the relevant line. This change is the + whole point of the check-in: Most things that use QWidgetStack will + really need this fix. Paul, optimize it, please? + + +src/kernel/qobject.cpp 2.42 agulbra +13 -2 + + show geometry and visibility too in dumpObjectTree() + + +src/qt.pro 2.12 agulbra +10 -0 +src/widgets/qmainwindow.cpp 2.1 agulbra initial checkin +src/widgets/qmainwindow.h 2.1 agulbra initial checkin +src/widgets/qstatusbar.cpp 2.1 agulbra initial checkin +src/widgets/qstatusbar.h 2.1 agulbra initial checkin +src/widgets/qtoolbar.cpp 2.1 agulbra initial checkin +src/widgets/qtoolbar.h 2.1 agulbra initial checkin +src/widgets/qtoolbutton.cpp 2.1 agulbra initial checkin +src/widgets/qtoolbutton.h 2.1 agulbra initial checkin + + several new classes. very rough and ready, but they're good enough to + talk about and play with. + + +src/widgets/qframe.cpp 2.11 paul +33 -5 +src/widgets/qframe.h 2.4 paul +8 -2 + + New function setMargin() + + +examples/showimg/showimg.cpp 2.18 warwick +25 -6 (1998/01/21) +examples/showimg/showimg.h 2.6 warwick +3 -1 +src/kernel/qimage.h 2.22 warwick +5 -1 + + QImage::smoothScale(int with, int height) + + +src/widgets/qpopmenu.h 2.10 agulbra +3 -2 + + new signal aboutToShow(), like the one in QTabDialog. + + +src/tools/qstring.cpp 2.16 warwick +44 -3 (1998/01/23) + + Make QString implicitly shared. Activates in Qt 2.00. + Try enabling this protection next time you have some weird bug. + + +src/kernel/qclb_x11.cpp 2.6 hanord +155 -46 + + INCR paste works. + + +src/qt.pro 2.13 agulbra +2 -0 +src/widgets/qwhatsthis.cpp 2.1 agulbra initial checkin +src/widgets/qwhatsthis.h 2.1 agulbra initial checkin + + what's this? + it's not perfect, but it definitely is nice. + + +extensions/imageio/src/qpngio.cpp 1.6 warwick +9 -4 (1998/01/27) + + Don't set alpha if not necessary. + + +src/kernel/qpm_win.cpp 2.31 hanord +5 -11 + + Preserves mask when converting an image to a pixmap + + +src/kernel/qapp.cpp 2.42 agulbra +7 -7 + + corrected dark shadow colour - has been too dark since warwick fixed + QColor::dark(). + + +src/kernel/qprn_win.cpp 2.6 hanord +11 -5 + + Printing now works on DeskJet 890c (StretchDIBits didn't work) + We now do StretchBlt. + + +src/widgets/qpopmenu.h 2.12 warwick +2 -1 (1998/02/06) + + Allow position in QPopupMenu::exec(...) + + +src/kernel/qpntarry.cpp 2.13 warwick +14 -15 + + QPointArray::makeArc() now works with negative "alen" angle. + - QPainter::drawArc() uses this for arcs under transformation. + + +src/widgets/qbttngrp.cpp 2.8 aavit +34 -10 +src/widgets/qbttngrp.h 2.3 aavit +2 -1 + + bugfix: Untoggling of other buttons in an exclusive group + if a button was set with setChecked() did not work. + + +src/widgets/qslider.cpp 2.47 agulbra +15 -28 + + made valueChanged() work correctly with middle-button dragging when + !tracking(). simplified the mouse state machine a little. + + +src/tools/qdir.cpp 2.16 hanord +4 -8 (1998/02/11) +src/tools/qfile.cpp 2.13 hanord +36 -2 +src/tools/qfile.h 2.3 hanord +4 -1 + + Added QFile::remove() which removes a file + + +src/widgets/qlined.cpp 2.60 agulbra +12 -2 (1998/02/19) +src/widgets/qlined.h 2.23 agulbra +5 -3 + + add clear(), make setText() and insert() public + + +src/widgets/qlistview.cpp 2.52 agulbra +33 -2 +src/widgets/qlistview.h 2.25 agulbra +3 -1 + + added a sizeHint() + + +src/tools/qdir.cpp 2.17 agulbra +4 -4 +src/tools/qfileinf.cpp 2.7 agulbra +5 -4 + + do what the docs say for absFilePath() (ie. no /usr/../usr/bin/ls names) + + +src/widgets/qtablevw.cpp 2.41 agulbra +31 -23 + + scrollLast*Cell and clipToCell could not be combined. now they can. + + +src/widgets/qframe.cpp 2.13 warwick +4 -4 (1998/02/20) + + Fix Box and H/VLine frames with margin() != 0. + + +src/qt.pro 2.15 warwick +2 -0 +src/widgets/qlabelled.cpp 1.1 warwick initial checkin +src/widgets/qlabelled.h 1.1 warwick initial checkin + + QLabelled widget (experimental) + + +src/kernel/qapp.cpp 2.45 agulbra +28 -13 +src/kernel/qapp_win.cpp 2.73 agulbra +14 -13 + + deliver mouse events to application-wide event filters even if the + receiver object is disabled. this allows tooltips to work for + disabled widgets. + + +src/widgets/qcombo.h 2.23 agulbra +3 -2 + + make eventFilter() public. this may break binary compatibility on + msvc++, if anyone's built a dll yet. + + +src/widgets/qradiobt.cpp 2.23 agulbra +7 -17 + + support exclusive button group behaviour even when one of the buttons + is not a QRadioButton. + + +src/qt.pro 2.16 paul +6 -0 +src/widgets/qgrid.cpp 1.1 paul initial checkin +src/widgets/qgrid.h 1.1 paul initial checkin +src/widgets/qhbox.cpp 1.1 paul initial checkin +src/widgets/qhbox.h 1.1 paul initial checkin +src/widgets/qvbox.cpp 1.1 paul initial checkin +src/widgets/qvbox.h 1.1 paul initial checkin + + New layout widgets + + +src/tools/qdstream.h 2.4 warwick +2 -2 + + QDataStream::eof() now returns TRUE if no device is set (as documented). + + +src/tools/qfile.cpp 2.14 warwick +36 -19 +src/tools/qiodev.cpp 2.8 warwick +8 -5 + + Test the file in QFile::open(FILE*) to see if it is seekable (not a + char device, fifo, or socket), rather than assuming stdin/out/err are not. + Set type to Sequential for such files, not default Direct. + + Don't use feof(fh) to mean at()==size(). QFile::atEnd() now works the + same as QIODevice and QBuffer. + + setStatus(IO_ReadError) in appropriate places (wasn't ever set for files). + Reading EOF is considered an error in the QIODevice model (see QBuffer). + + +src/kernel/qasyncimageio.cpp 1.26 warwick +37 -30 +src/kernel/qasyncimageio.h 1.13 warwick +2 -2 + + Work for even weirder GIFs. + + +src/tools/qfile.cpp 2.16 agulbra +5 -4 (1998/02/25) + + -1 in case of error... + + +src/qt.pro 2.17 paul +2 -0 +src/widgets/qbuttonrow.cpp 1.1 paul initial checkin +src/widgets/qbuttonrow.h 1.1 paul initial checkin + + New layout widget + + +examples/aclock/GNUmakefile 2.1 hanord initial checkin +examples/aclock/Makefile 2.2 hanord +6 -53 +examples/aclock/aclock.pro 1.4 hanord +6 -6 +examples/application/GNUmakefile 1.1 hanord initial checkin +examples/application/application.pro 1.2 hanord +6 -6 +examples/biff/GNUmakefile 2.1 hanord initial checkin +examples/biff/Makefile 2.2 hanord +6 -54 +examples/biff/biff.pro 1.4 hanord +6 -6 +examples/connect/GNUmakefile 2.1 hanord initial checkin +examples/connect/Makefile 2.2 hanord +6 -46 +examples/connect/connect.pro 1.4 hanord +5 -5 +examples/cursor/GNUmakefile 2.1 hanord initial checkin +examples/cursor/Makefile 2.2 hanord +6 -46 +examples/cursor/cursor.pro 1.4 hanord +5 -5 +examples/dclock/GNUmakefile 2.1 hanord initial checkin +examples/dclock/Makefile 2.2 hanord +6 -54 +examples/dclock/dclock.pro 1.4 hanord +6 -6 +examples/desktop/GNUmakefile 2.1 hanord initial checkin +examples/desktop/Makefile 2.2 hanord +6 -46 +examples/desktop/desktop.pro 1.4 hanord +5 -5 +examples/dirview/GNUmakefile 1.1 hanord initial checkin +examples/drawdemo/GNUmakefile 2.1 hanord initial checkin +examples/drawdemo/Makefile 2.2 hanord +6 -52 +examples/drawdemo/drawdemo.pro 1.4 hanord +5 -5 +examples/forever/GNUmakefile 2.1 hanord initial checkin +examples/forever/Makefile 2.3 hanord +6 -42 +examples/forever/forever.pro 1.4 hanord +5 -5 +examples/hello/GNUmakefile 2.1 hanord initial checkin +examples/hello/Makefile 2.8 hanord +6 -61 +examples/hello/hello.pro 1.5 hanord +6 -5 +examples/layout/GNUmakefile 1.1 hanord initial checkin +examples/layout/Makefile 1.11 hanord +7 -50 +examples/layout/layout.pro 1.5 hanord +5 -4 +examples/life/GNUmakefile 2.1 hanord initial checkin +examples/life/Makefile 2.2 hanord +6 -57 +examples/life/life.pro 2.3 hanord +8 -8 +examples/menu/GNUmakefile 2.1 hanord initial checkin +examples/menu/Makefile 2.4 hanord +6 -55 +examples/menu/menu.pro 2.3 hanord +5 -5 +examples/movies/GNUmakefile 1.1 hanord initial checkin +examples/movies/Makefile 1.11 hanord +6 -50 +examples/movies/movies.pro 1.4 hanord +5 -5 +examples/network/GNUmakefile 1.1 hanord initial checkin +examples/network/Makefile 1.7 hanord +6 -82 +examples/picture/GNUmakefile 2.1 hanord initial checkin +examples/picture/Makefile 2.2 hanord +6 -49 +examples/picture/picture.pro 1.2 hanord +6 -3 +examples/pref/GNUmakefile 1.1 hanord initial checkin +examples/pref/Makefile 1.4 hanord +6 -53 +examples/pref/pref.pro 1.4 hanord +6 -6 +examples/progress/GNUmakefile 1.1 hanord initial checkin +examples/progress/Makefile 1.9 hanord +6 -47 +examples/progress/progress.pro 1.3 hanord +5 -5 +examples/qmag/GNUmakefile 2.1 hanord initial checkin +examples/qmag/Makefile 2.2 hanord +6 -52 +examples/qmag/qmag.pro 2.3 hanord +5 -5 +examples/qwerty/GNUmakefile 1.1 hanord initial checkin +examples/qwerty/Makefile 1.6 hanord +5 -66 +examples/qwerty/qwerty.pro 1.4 hanord +6 -6 +examples/scrollview/GNUmakefile 1.1 hanord initial checkin +examples/scrollview/Makefile 1.4 hanord +6 -56 +examples/scrollview/scrollview.pro 1.3 hanord +5 -5 +examples/sheet/GNUmakefile 2.1 hanord initial checkin +examples/sheet/Makefile 2.3 hanord +6 -59 +examples/showimg/GNUmakefile 2.1 hanord initial checkin +examples/showimg/Makefile 2.12 hanord +6 -58 +examples/showimg/showimg.pro 2.7 hanord +6 -9 +examples/table/GNUmakefile 1.1 hanord initial checkin +examples/table/Makefile 1.5 hanord +5 -67 +examples/table/table.pro 1.4 hanord +6 -6 +examples/tetrix/GNUmakefile 2.1 hanord initial checkin +examples/tetrix/Makefile 2.5 hanord +6 -70 +examples/tetrix/tetrix.pro 2.4 hanord +14 -14 +examples/tictac/GNUmakefile 2.1 hanord initial checkin +examples/tictac/Makefile 2.2 hanord +6 -54 +examples/tictac/tictac.pro 2.3 hanord +6 -6 +examples/timestmp/GNUmakefile 2.1 hanord initial checkin +examples/timestmp/Makefile 2.2 hanord +6 -46 +examples/tooltip/GNUmakefile 1.1 hanord initial checkin +examples/tooltip/Makefile 1.3 hanord +6 -53 +examples/tooltip/tooltip.pro 1.3 hanord +6 -6 +examples/validator/GNUmakefile 1.1 hanord initial checkin +examples/validator/Makefile 1.3 hanord +6 -38 +examples/widgets/GNUmakefile 2.1 hanord initial checkin +examples/widgets/Makefile 2.4 hanord +6 -67 +examples/widgets/widgets.pro 2.3 hanord +5 -9 +examples/xform/GNUmakefile 2.1 hanord initial checkin +examples/xform/Makefile 2.4 hanord +6 -52 +examples/xform/xform.pro 2.3 hanord +6 -5 +src/GNUmakefile 2.1 hanord initial checkin +src/Makefile 2.22 hanord +6 -156 + + New makefile system + + +src/widgets/qframe.cpp 2.14 agulbra +6 -6 + + no reason to call drawContents() in [HV]Line mode + + +src/kernel/qfont.cpp 2.18 warwick +3 -2 +src/kernel/qfontdta.h 2.8 warwick +2 -1 +src/kernel/qfontmet.h 2.6 warwick +9 -3 +src/kernel/qpainter.cpp 2.20 warwick +564 -2 +src/kernel/qpainter.h 2.16 warwick +2 -1 +src/kernel/qptr_x11.cpp 2.34 warwick +2 -546 + + QPainter::drawText(...tf...) now takes into account the left and + right bearings of the font. The bounding rectangle of text may now + be slightly larger (particularly italic text). QFontMetrics has + the additional functionality allowing this. + + +src/kernel/qaccel.cpp 2.8 agulbra +70 -2 (1998/02/28) + + added common accelerator keys for later inclusion into docs + + +src/kernel/qfont.cpp 2.21 warwick +110 -2 (1998/03/01) +src/kernel/qfontmet.h 2.8 warwick +7 -1 +src/kernel/qpainter.cpp 2.22 warwick +43 -26 +src/kernel/qpainter.h 2.17 warwick +5 -1 +src/widgets/qchkbox.cpp 2.18 warwick +23 -29 +src/widgets/qpushbt.cpp 2.35 warwick +5 -5 +src/widgets/qradiobt.cpp 2.24 warwick +24 -29 + + QFontMetrics::size() and QFontMetrics::boundingRect() with all the + functionality of QPainter::boundingRect() - code now shared. + + Use QFontMetrics::size() in button size hints, thus allowing multi-line + button labels. Position checkbox/radiobutton top-left. + + +src/kernel/qpm_x11.cpp 2.30 eiriken +78 -3 (1998/03/02) + + Fix convertToImage() for pixmaps with other than 8-bit-per-channel. + + +src/kernel/qpixmap.cpp 2.24 hanord +7 -33 +src/kernel/qpixmap.h 2.16 hanord +21 -2 +src/kernel/qpm_win.cpp 2.32 hanord +110 -51 +src/kernel/qpm_x11.cpp 2.31 hanord +165 -84 +src/kernel/qptd_win.cpp 2.7 hanord +102 -29 +src/kernel/qptd_x11.cpp 2.10 hanord +41 -11 + + Implemented masked bitBlt for Windows 95. + Added QPixmap::setOptimization() which replaces the old optimize function. + E.g. setOptimization(QPixmap::BestOptim) to get much faster masked bitBlts. + Removed the dirty system, instead delete cached data whenever the pixmap + is changed. + + +src/kernel/qprinter.h 2.3 eiriken +6 -1 +src/kernel/qprn_win.cpp 2.7 eiriken +17 -7 +src/kernel/qprn_x11.cpp 2.7 eiriken +10 -5 +src/kernel/qpsprn.cpp 2.9 eiriken +8 -10 + + Take display vs. font resolution into account for printer font metrics. + + +src/kernel/qpshdr.txt 2.3 agulbra +91 -3 +src/kernel/qpsprn.cpp 2.10 agulbra +644 -88 + + added iso-8859-1 support + + also added better font support. try to print palatino, and the printer + goes "hm, is palatino installed? if not, perhaps garamond is installed? + if not, is times installed? if not, well, courier MUST work". + + finally, if I understand the postscript book correctly I think I made + two-font postscript text output a little faster. the code now attempts + to use variables for fonts and call findfont/makefont just once per font + change per page. + + this code is not perfect. the hacky stuff that does font substitution + needs tweaking, and at present the code believes that all the world is + iso-8859-1. will fix that. + + postscript is fun. + + +src/widgets/qmenudta.cpp 2.10 warwick +4 -4 + + Fix this->changeItem(this->pixmap(), "crashme") + + +src/kernel/qapp_win.cpp 2.74 agulbra +7 -2 (1998/03/10) + + Set WState_Visible correctly when the window is (de)iconified. + + +src/kernel/qdrawutl.cpp 2.16 warwick +5 -3 (1998/03/11) +src/kernel/qpmcache.cpp 2.3 warwick +77 -5 +src/kernel/qpmcache.h 2.3 warwick +3 -1 +src/kernel/qptr_x11.cpp 2.36 warwick +5 -3 +src/tools/qgcache.cpp 2.5 warwick +10 -2 + + Fix extremely-unlikely-to-be-triggered undeleted cached pixmaps. + Provide safer QPixmapCache find() and insert(). + + +src/widgets/qbutton.h 2.14 agulbra +3 -2 (1998/03/12) + + add toggle() + + +src/tools/qregexp.cpp 2.7 agulbra +23 -18 + + implement [] in wildcard mode + + +src/kernel/qobject.cpp 2.44 agulbra +29 -11 +src/kernel/qobject.h 2.9 agulbra +5 -1 +src/widgets/qbuttonrow.cpp 1.3 agulbra +8 -6 +src/widgets/qframe.cpp 2.16 agulbra +4 -4 +src/widgets/qheader.cpp 2.30 agulbra +6 -4 +src/widgets/qlcdnum.cpp 2.9 agulbra +7 -5 +src/widgets/qmainwindow.cpp 2.9 agulbra +4 -3 +src/widgets/qscrbar.cpp 2.33 agulbra +14 -14 +src/widgets/qslider.cpp 2.48 agulbra +4 -4 +src/widgets/qtablevw.cpp 2.42 agulbra +10 -8 +src/widgets/qtoolbar.cpp 2.10 agulbra +4 -4 + + provide QObject::name( const char * defaultName ). + + use name( "unnamed" ) in all the debug() calls, to avoid segfaults + where printf() won't handle null pointers. + + +src/tools/qstring.cpp 2.18 agulbra +5 -9 + + toDouble() of a null string now sets ok to FALSE + + +src/widgets/qcombo.cpp 2.73 agulbra +54 -49 +src/widgets/qcombo.h 2.25 agulbra +3 -1 + + tweaked size hint for toolbar use. provide functions to change the + line-edit without changint the combo's contents. + + +src/kernel/qapp_win.cpp 2.78 warwick +13 -2 + + Don't let Windows beep on WM_SYSCHAR events. + Beep on unaccepted accelerations. + + +src/kernel/qpainter.cpp 2.29 hanord +96 -17 +src/kernel/qptr_x11.cpp 2.40 hanord +2 -70 + + Fixed QPainter::drawPixmap() bug (mono bitmaps with self-masks) + Moved platform indep. code to qpainter.cpp + Put back CtorBegin + + +src/widgets/qbttngrp.cpp 2.9 agulbra +14 -2 +src/widgets/qbttngrp.h 2.5 agulbra +3 -1 + + added setButton() - very useful when you want to force one member of + an exclusive button group to on but not keep around pointers to + umpteen radio buttons. + + +src/kernel/qprinter.cpp 2.5 agulbra +31 -6 +src/kernel/qprinter.h 2.5 agulbra +6 -2 + + added setPageOrder() + + +src/kernel/qobject.cpp 2.45 agulbra +18 -2 + + give better warnings in case of connect() mismatches. + + +src/dialogs/qprndlg.cpp 2.4 agulbra +258 -112 +src/dialogs/qprndlg.h 2.5 agulbra +9 -2 + + it's finished. please have a look. and please do debug. I don't + know about any bugs now, but I'm sure there are some. + + +src/widgets/qcombo.cpp 2.75 agulbra +15 -6 + + magic hack to make combos usable in dialogs. (QDialog breaks the + combo Enter key press.) + + +src/dialogs/qprndlg.cpp 2.3 agulbra +543 -187 +src/dialogs/qprndlg.h 2.4 agulbra +24 -10 +src/kernel/qprn_x11.cpp 2.8 agulbra +4 -2 + + new better-looking print dialog and a new static function to configure + a QPrinter (replaces QPrinter::setup() - kernel/* should not use + dialogs/*). + + noteworthy points: + + - the new static function appears to write over something it + shouldn't. I don't see why, but it does seem to cause crashes + later on. the old function works. I'm committing so I can run + purify on solaris. + - the dialog lacks accelerators. + - I haven't put in solaris /etc/lp/ support yet. should be fairly + easy, but I haven't done it. + - the layout will benefit from Warwick's alternative space + distribution + - the awful message in qprndlg.h is gone gone gone. + + +src/dialogs/qprndlg.cpp 2.5 agulbra +119 -23 (1998/03/15) + + /etc/lp support + + +src/widgets/qcombo.cpp 2.76 agulbra +2 -3 + + don't ignore key events, just don't accept them. + + +src/kernel/qapp.cpp 2.48 agulbra +3 -2 +src/kernel/qfont.cpp 2.27 agulbra +11 -5 + + look at $LANG and try to pick an application font that suits $LANG. + the application font used is 12-point helvetica. if the locale isn't + in the list I built from XFree86's locale.alias, I assume 8859-1 is + okay. + + copy character set from defFont in the relevant QFont constructor. + + this code assumes that helvetica includes the appropriate character + set. + + +examples/qmag/qmag.cpp 2.13 warwick +39 -2 + + Crazy hard-disk chewing MultiSave option. Great when you want to make + animated GIFs for your web pages. + + +src/dialogs/qprndlg.cpp 2.8 warwick +4 -4 +src/kernel/qsize.cpp 2.6 warwick +9 -3 +src/kernel/qsize.h 2.6 warwick +9 -3 + + Add QSize::expandedTo(), and boundedTo(). + + +src/kernel/qwidget.cpp 2.92 agulbra +7 -6 + + remove the widget's willingness to accept focus-in events very early + in the destructor + + +src/tools/qgdict.cpp 2.11 warwick +56 -11 (1998/03/17) +src/tools/qgdict.h 2.3 warwick +3 -1 + + Add QDict::resize(int). + + +src/widgets/qlined.cpp 2.64 agulbra +46 -9 +src/widgets/qlined.h 2.25 agulbra +6 -2 + + add setSelection() and setCursorPosition() + + +src/widgets/qcombo.cpp 2.77 agulbra +86 -11 +src/widgets/qcombo.h 2.26 agulbra +4 -1 + + setAutoCompletion() - works really nicely. + + +src/kernel/qiconset.cpp 2.1 agulbra initial checkin +src/kernel/qiconset.h 2.1 agulbra initial checkin + + QIconSet first checking. QIconSet is neat: You give it one or more + icons, and it completes the set so you get large and small disabled, + active and normal icons. QToolButton uses it, QMenuData will soon. + + +src/kernel/qpainter.cpp 2.31 agulbra +18 -2 +src/kernel/qpainter.h 2.22 agulbra +2 -1 + + added drawImage() by request of eng. did NOT implement the QPrinter + shortcut he asked for. + + +src/kernel/qapp.cpp 2.49 warwick +10 -6 (1998/03/19) + + Ensure mouserelease goes to widget that got mousepress. + Document -ncols better. + + +examples/qdir/GNUmakefile 1.1 warwick initial checkin +examples/qdir/Makefile 1.1 warwick initial checkin +examples/qdir/qdir.cpp 1.1 warwick initial checkin + + Tests QFileDialog features. + + +extensions/nsplugin/src/qnp.cpp 1.18 warwick +4 -1 + + Work for multi-visual displays. + + +extensions/opengl/examples/box/.cvsignore 1.2 aavit +0 -1 +extensions/opengl/examples/box/glbox.cpp 1.4 aavit +15 -6 +extensions/opengl/examples/box/glbox.h 1.5 aavit +2 -1 +extensions/opengl/examples/gear/gear.cpp 1.5 aavit +26 -35 +extensions/opengl/src/qgl.cpp 1.18 aavit +127 -41 +extensions/opengl/src/qgl.h 1.8 aavit +80 -77 + + New features in OpenGL extension: + 1) virtual initalizeGL() method in QGLWidget; facilitates easier GL initialization. + 2) Added support for using shared OpenGL display lists + 3) Added sharedbox example showing this feature. + + diff --git a/dist/changes-1.39-19980406 b/dist/changes-1.39-19980406 new file mode 100644 index 0000000..63b3dbb --- /dev/null +++ b/dist/changes-1.39-19980406 @@ -0,0 +1,286 @@ +src/kernel/qpainter.cpp 2.127 agulbra +37 -6 (1998/03/30) + + sort of parse $LANG + + +src/kernel/qpainter.cpp 2.35 warwick +5 -4 (1998/03/30) + + Fix TAB expansion in QPainter::drawText (and hence QMultiLineEdit). + + +src/widgets/qlined.cpp 2.68 agulbra +3 -3 + + didn't repaint cursor properly when moving the cursor leftwards + + +src/kernel/qfnt_x11.cpp 2.34 warwick +20 -13 (1998/03/31) + + Some fonts don't have per_char information. + + +src/kernel/qrgn_win.cpp 2.6 hanord +11 -9 (1998/04/01) + + Bug fixes for the new getRects and boundingRect functions + + +src/kernel/qregion.h 2.8 hanord +4 -1 +src/kernel/qrgn_win.cpp 2.5 hanord +42 -2 +src/kernel/qrgn_x11.cpp 2.5 hanord +50 -2 + + New QRegion functions: + boundingRect() returns the bounding rectangle of the region + getRects() returns an array of the rectangles that make up the region + + +src/widgets/qmainwindow.cpp 2.13 agulbra +46 -3 (1998/04/02) +src/widgets/qmainwindow.h 2.9 agulbra +9 -4 +src/widgets/qtoolbar.cpp 2.15 agulbra +20 -5 +src/widgets/qtoolbar.h 2.7 agulbra +5 -2 +src/widgets/qtoolbutton.cpp 2.20 agulbra +25 -17 + + button pixmap size change support + + +src/kernel/qiconset.cpp 2.5 agulbra +18 -4 +src/kernel/qiconset.h 2.3 agulbra +4 -3 +src/widgets/qpushbt.cpp 2.37 agulbra +62 -3 +src/widgets/qpushbt.h 2.7 agulbra +5 -1 +src/widgets/qtoolbutton.cpp 2.19 agulbra +31 -5 +src/widgets/qtoolbutton.h 2.4 agulbra +6 -2 + + new functionality, menu buttons + + +src/kernel/qgmanagr.cpp 2.30 paul +18 -2 +src/kernel/qgmanagr.h 2.11 paul +3 -2 +src/widgets/qhbox.cpp 1.9 paul +53 -2 +src/widgets/qhbox.h 1.6 paul +6 -1 + + pack() added, addStretch() now work + + +src/kernel/qpainter.cpp 2.37 warwick +36 -8 (1998/04/03) +src/kernel/qpainter.h 2.23 warwick +11 -1 + + Add more QPainter::drawImage calls (but still not implement QPrinter stuff) + + +src/widgets/qmainwindow.cpp 2.14 warwick +4 -4 +src/widgets/qmainwindow.h 2.10 warwick +2 -2 + + Allow WFlags to QMainWindow. + + +src/kernel/qregion.cpp 2.7 warwick +4 -2 +src/kernel/qrgn_x11.cpp 2.6 warwick +4 -3 + + Disable BOP + + +src/widgets/qscrollview.cpp 2.23 warwick +7 -5 +src/widgets/qscrollview.h 2.13 warwick +2 -2 + + Emit signal earlier. + + +src/widgets/qscrollview.cpp 2.22 warwick +34 -16 +src/widgets/qscrollview.h 2.12 warwick +3 -1 + + Low level hook for painting on existing painter. + Direct position set function. + + +src/kernel/qimage.cpp 2.80 warwick +64 -6 + + Optimize a very common case. + + +examples/showimg/showimg.cpp 2.21 warwick +67 -9 +examples/showimg/showimg.h 2.8 warwick +7 -0 + + Use new QImage bitBlt + + +src/dialogs/qprndlg.cpp 2.15 agulbra +35 -2 +src/dialogs/qprndlg.h 2.8 agulbra +2 -1 +src/kernel/qprinter.cpp 2.7 agulbra +53 -8 +src/kernel/qprinter.h 2.6 agulbra +6 -2 + + added QPrinter::ColorMode and corresponding stuff in the printer + dialog. + + +src/kernel/qimage.cpp 2.79 warwick +183 -3 +src/kernel/qimage.h 2.25 warwick +16 -1 +src/kernel/qpaintd.h 2.6 warwick +5 -1 +src/kernel/qpainter.cpp 2.36 warwick +12 -2 +src/kernel/qpixmap.h 2.19 warwick +3 -1 + + bitBlt for QImages + - copy image subarea to position in paintdevice or an image + + +src/kernel/qgmanagr.cpp 2.31 paul +89 -25 + + handle empty layouts in a slightly better way + + +src/dialogs/qprndlg.cpp 2.17 agulbra +14 -5 + + move focus intelligently when the users clicks 'print to file' or + 'print to printer' + + +src/dialogs/qfiledlg.cpp 2.51 agulbra +64 -4 +src/dialogs/qfiledlg.h 2.13 agulbra +5 -1 + + new function, addWidgets(). very limited extensibility, designed so + that it's easier to reimplement it as syntax sugar if/when we put in a + proper extension method. + + +src/dialogs/qprndlg.cpp 2.16 agulbra +7 -12 + + no A3 + + +src/dialogs/qfiledlg.cpp 2.52 agulbra +11 -7 + + save a little memory, be a little bug-free + + +src/widgets/qcombo.cpp 2.81 agulbra +24 -19 + + use 1-pixel frame around lineedit in motif style. + + +src/widgets/qmainwindow.cpp 2.15 agulbra +82 -14 +src/widgets/qmainwindow.h 2.11 agulbra +7 -4 +src/widgets/qtoolbar.cpp 2.16 agulbra +46 -11 +src/widgets/qtoolbar.h 2.8 agulbra +8 -2 +src/widgets/qtoolbutton.cpp 2.21 agulbra +4 -4 + + various improvements in look&feel, stretchable space, stretchable widgets + + +src/kernel/qpainter.cpp 2.38 hanord +72 -64 (1998/04/04) +src/kernel/qpainter.h 2.24 hanord +14 -4 +src/kernel/qptr_x11.cpp 2.43 hanord +115 -2 + + Added QPainter::drawTiledPixmap, not for Windows yet + + +src/kernel/qpainter.cpp 2.39 hanord +6 -2 +src/kernel/qpainter.h 2.25 hanord +8 -2 +src/kernel/qptr_x11.cpp 2.44 hanord +5 -6 + + Added overloaded drawTiledPixmap( const QRect &r, const QPixmap &pm ) + + +src/widgets/qlistview.cpp 2.87 warwick +5 -5 +src/widgets/qscrollview.cpp 2.25 warwick +266 -96 +src/widgets/qscrollview.h 2.15 warwick +19 -5 + + Allow arbitrary child objects positioned at int coords in QScrollView. + + +src/widgets/qlistview.cpp 2.86 warwick +5 -5 +src/widgets/qscrollview.cpp 2.24 warwick +35 -11 +src/widgets/qscrollview.h 2.14 warwick +3 -2 + + Fix refresh problen in QScrollView. + + +examples/widgets/widgets.cpp 2.39 warwick +4 -0 + + Show bug in recreate + + +examples/scrollview/scrollview.cpp 1.8 warwick +49 -5 + + Test new arbitrary-number-of-children code. + + +src/qt.pro 2.20 warwick +2 -0 + + fix dependencies + + +src/widgets/qstatusbar.cpp 2.4 agulbra +4 -2 + + less flicker + + +src/widgets/qmainwindow.cpp 2.16 agulbra +10 -18 +src/widgets/qtoolbar.cpp 2.17 agulbra +6 -5 + + move motif style away from what the OSF probably would have done, + closer towards what Netscape and Microsoft has done. + + +src/kernel/qptr_x11.cpp 2.45 hanord +8 -11 + + tilepixmap optimized for the common case (no mask) + +src/widgets/qmenudta.cpp 2.13 eiriken +101 -2 (1998/04/05) +src/widgets/qmenudta.h 2.10 eiriken +12 -1 + + Added new insertItem functions + + +src/widgets/qmlined.cpp 2.89 eiriken +14 -1 +src/widgets/qmlined.h 2.33 eiriken +3 -1 + + Added setFixedVisibleLines + + +src/widgets/qscrollview.cpp 2.29 warwick +10 -4 +src/widgets/qscrollview.h 2.17 warwick +2 -1 + + Fix child deletion. + + +src/widgets/qscrollview.cpp 2.32 warwick +2 -2 +src/widgets/qtoolbutton.cpp 2.22 warwick +12 -2 + + Focus indication in toolbutton. + + +src/kernel/qfocusdata.h 2.1 warwick initial checkin +src/kernel/qwidget.cpp 2.97 warwick +24 -15 +src/kernel/qwidget.h 2.47 warwick +4 -2 +src/widgets/qscrollview.cpp 2.31 warwick +59 -7 +src/widgets/qscrollview.h 2.18 warwick +3 -1 + + Focus traversal among QScrollView children. + + +examples/scrollview/scrollview.cpp 1.9 warwick +19 -20 +src/widgets/qlistview.cpp 2.88 warwick +18 -18 +src/widgets/qscrollview.cpp 2.27 warwick +38 -61 +src/widgets/qscrollview.h 2.16 warwick +2 -1 + + Negate position sense. + + +src/dialogs/qprndlg.cpp 2.18 hanord +4 -3 +src/kernel/qprn_x11.cpp 2.9 hanord +4 -4 + + QPrinter::setup() uses the QPrintDialog::getPrinterSetup() function + + +src/kernel/qptr_win.cpp 2.31 hanord +108 -2 + + Tiled pixmap implemented, but no optimization yet + +src/widgets/qlined.cpp 2.69 agulbra +21 -3 + + handle double-click correctly + handle c-k + +src/widgets/qlistview.cpp 2.90 eiriken +17 -2 (1998/04/06) +src/widgets/qlistview.h 2.42 eiriken +2 -1 +src/widgets/qstatusbar.cpp 2.5 eiriken +8 -7 + + Added rightButtonPressed signal and removed the resizer + diff --git a/dist/changes-1.39-19980414 b/dist/changes-1.39-19980414 new file mode 100644 index 0000000..11e9b37 --- /dev/null +++ b/dist/changes-1.39-19980414 @@ -0,0 +1,173 @@ +examples/qdir/qdir.cpp 1.2 warwick +4 -3 (1998/04/06) + + better captions + + +src/widgets/qscrollview.cpp 2.34 warwick +11 -1 + + clean up in destructor code. + + +src/widgets/qlined.cpp 2.70 agulbra +6 -4 + + don't start drags just now + + +examples/scrollview/scrollview.cpp 1.10 warwick +2 -2 + + make it Big + + +src/kernel/qapp_x11.cpp 2.127 agulbra +37 -6 +src/kernel/qfont.h 2.9 agulbra +3 -2 + + sort of parse $LANG + + +examples/application/main.cpp 1.2 warwick +3 -2 + + use setMainWidget + + +extensions/opengl/src/qgl.pro 1.8 warwick +1 -1 (1998/04/08) + + Building libqgl doesn't need -lqgl + + +src/dialogs/qfiledlg.cpp 2.54 agulbra +74 -21 +src/dialogs/qfiledlg.h 2.14 agulbra +5 -3 + + allow setting of initial file name when using statics. + +src/dialogs/qfiledlg.cpp 2.55 agulbra +11 -11 + + allow setting thename of a nonexistent file as initial default in + getSaveFileName() + + +src/kernel/qpsprn.cpp 2.13 agulbra +4 -4 + + avoid at-least-a-warning-at-most-an-UMR. + + +src/moc/moc.pro 1.9 warwick +1 -1 + + include qt include + + +extensions/opengl/src/qgl.pro 1.9 warwick +1 -1 + + more -lqgl + + +src/tools/qglobal.h 2.48 agulbra +4 -1 + + openbsd + + +src/widgets/qsplitter.h 1.7 agulbra +3 -3 + + remove semicolon after Q_OBJECT + + +src/dialogs/qfiledlg.cpp 2.53 agulbra +15 -3 + + say "Readable, writable" and so on instead of ASHR (shades of MS-DOS) + + +src/widgets/qlcdnum.cpp 2.11 agulbra +17 -2 +src/widgets/qlcdnum.h 2.7 agulbra +3 -1 + + sizeHint(). decent minimum size using the golden mean. + + +src/moc/GNUmakefile 2.4 warwick +11 -3 +src/moc/moc.pro 1.8 warwick +1 -1 +src/moc/moc.t 1.11 warwick +1 -1 +src/moc/moc.t 1.10 warwick +1 -1 + + yacc flags + + +src/kernel/qpainter.cpp 2.40 warwick +4 -4 (1998/04/09) +src/widgets/qmlined.cpp 2.90 warwick +4 -2 +src/widgets/qscrollview.cpp 2.35 warwick +39 -33 + + Fixed cursor position in QMultiLineEdit. + Fixed focus navigation in QScrollView. + + +src/widgets/qscrollview.cpp 2.36 agulbra +8 -3 + + be a little more careful about event processing - removeChild() was + called from QScrollViewData destructor and didn't like that. + + +src/kernel/qprn_x11.cpp 2.10 agulbra +62 -77 +src/kernel/qpsprn.cpp 2.14 agulbra +1525 -157 +src/kernel/qpsprn.h 2.5 agulbra +17 -9 + + added support for character encodings other than iso 8859-1. the + header is computed dynamically; the fonts and encodings used on the + first few pages are put in the header, any other fonts and encodings + are added to the output stream as necessary. removed the need for a + temporary file. rewrote the font name cache so two QPSPrinter objects + printing at the same time won't conflict. put back in the header size + compression. + + +src/widgets/qcombo.cpp 2.82 warwick +3 -3 (1998/04/13) + + Correct sizeHint. + + +src/widgets/qscrollview.cpp 2.37 warwick +22 -18 +src/widgets/qscrollview.h 2.19 warwick +1 -2 + + Improve focus tabbing. + + +src/kernel/qwidget.cpp 2.98 warwick +60 -16 +src/kernel/qwidget.h 2.48 warwick +3 -1 + + Inherit *parents* palette, not application palette *** CHANGED BEHAVIOUR *** + Generalize isEnabledToTLW and isVisibleToTLW + + +src/widgets/qtablevw.cpp 2.44 warwick +8 -28 + + Propagate palette changes to scrollbars. + Combine common code. + + +src/widgets/qlistview.cpp 2.91 warwick +24 -6 +src/widgets/qlistview.h 2.43 warwick +5 -3 + + Provide parent() of list view item. + + +src/widgets/qlistbox.cpp 2.61 warwick +45 -3 +src/widgets/qlistbox.h 2.15 warwick +6 -2 + + Update maxItemWidth on font change. + Add sizeHint() + +src/kernel/qregion.cpp 2.8 hanord +84 -51 (1998/04/14) +src/kernel/qregion.h 2.9 hanord +12 -3 +src/kernel/qrgn_win.cpp 2.11 hanord +39 -25 +src/kernel/qrgn_x11.cpp 2.11 hanord +48 -29 + + Removed the internal (and slow) byte array. + Uses the region rectangles for saving complex regions. + + +src/widgets/qchkbox.cpp 2.20 warwick +5 -4 +src/widgets/qradiobt.cpp 2.25 warwick +9 -4 + + Small sizeHint when no text or pixmap. + + +src/kernel/qptr_win.cpp 2.32 agulbra +5 -2 +src/kernel/qptr_x11.cpp 2.46 agulbra +5 -2 + + clip properly in drawPixmap(). diff --git a/dist/changes-1.39-19980506 b/dist/changes-1.39-19980506 new file mode 100644 index 0000000..35d9ed0 --- /dev/null +++ b/dist/changes-1.39-19980506 @@ -0,0 +1,555 @@ +doc/classes.doc 1.5 warwick +3 -3 + + 4 columns, not 3. + + +doc/headers.doc 1.5 warwick +4 -2 + + Multicolumns. + + +doc/moc.doc 2.11 eiriken +11 -4 + + Corrected nested classes bug + + +examples/application/application.cpp 1.4 agulbra +2 -3 + + updated for new qtoolbar api + + +examples/scrollview/scrollview.cpp 1.11 warwick +25 -9 + + Use older style. + + +extensions/opengl/examples/sharedbox/GNUmakefile 1.1 hanord initial checkin +extensions/opengl/examples/sharedbox/Makefile 1.2 hanord +6 -90 + + new makefiles + + +extensions/opengl/examples/sharedbox/sharedbox.pro 1.2 hanord +1 -1 + + Added "opengl" to CONFIG + + +src/dialogs/qfiledlg.cpp 2.56 paul +3 -3 + + make it compile on windows + + +src/dialogs/qfiledlg.cpp 2.57 warwick +6 -5 + + Implement "initial selection" for Win-specific calls. + + +src/dialogs/qfiledlg.cpp 2.58 agulbra +21 -2 + + insert the root drives in the paths combo + + +src/dialogs/qfiledlg.cpp 2.59 agulbra +11 -11 + + alight size stuff correctly + list all drives under windows + + there's an aborted attempt at handling double-click in multi-column + view in there, too. I'll think about it and complete it asap. + + +src/dialogs/qfiledlg.cpp 2.60 agulbra +21 -8 + + draw the icons again. + + +src/dialogs/qfiledlg.cpp 2.61 agulbra +23 -6 + + output date and time in a better format. handle column width better. + + +src/dialogs/qfiledlg.cpp 2.62 agulbra +190 -23 +src/dialogs/qfiledlg.h 2.15 agulbra +20 -1 + + more polish. in this round: + - correct handling of double-click and arrow keys in the multi-column + list (partly done using an evil hack, see mouseDoubleClickEvent()) + - the ability to install file type icons (the default draws a + directory icon, nothing else) + - correct enter handling in the paths and types combo boxes + - correct tab order + + +src/dialogs/qfiledlg.cpp 2.63 agulbra +21 -26 + + setEnabled( cd up button ) + tweak accessibility texts + + +src/dialogs/qfiledlg.cpp 2.64 hanord +3 -3 + + Adds cast to avoid compiling problem for MSVC++ + + +src/dialogs/qfiledlg.cpp 2.65 agulbra +29 -7 + + experimental filename completion. hacky and a little buggy in certain + odd and harmless cases. + + +src/dialogs/qfiledlg.h 2.16 agulbra +4 -5 + + remove unnecessary friend declaration + + +src/dialogs/qprndlg.cpp 2.19 agulbra +3 -3 + + work around broken gcc warning + + +src/kernel/qapp_win.cpp 2.84 warwick +5 -2 + + Work-around focus problem with recreate. + + +src/kernel/qapp_win.cpp 2.85 warwick +5 -4 + + Robustness. + + +src/kernel/qapp_x11.cpp 2.128 warwick +9 -9 +src/kernel/qclb_x11.cpp 2.9 warwick +4 -4 +src/kernel/qcol_x11.cpp 2.26 warwick +13 -12 +src/kernel/qimage.cpp 2.83 warwick +11 -10 +src/kernel/qnpsupport.cpp 2.7 warwick +3 -3 +src/kernel/qpm_x11.cpp 2.33 warwick +12 -12 +src/kernel/qpsprn.cpp 2.16 warwick +3 -3 +src/kernel/qrgn_x11.cpp 2.12 warwick +3 -3 +src/kernel/qt_xdnd.cpp 2.7 warwick +5 -5 +src/kernel/qwid_x11.cpp 2.89 warwick +21 -19 +src/tools/qdatetm.cpp 2.12 warwick +4 -4 + + Avoid warnings. + + +src/kernel/qapp_x11.cpp 2.130 warwick +3 -3 + + strcasecmp -> qstricmp + + +src/kernel/qapp_x11.cpp 2.131 agulbra +14 -3 +src/kernel/qclipbrd.cpp 2.7 agulbra +2 -6 +src/kernel/qdnd_win.cpp 2.3 agulbra +23 -1 +src/kernel/qdnd_x11.cpp 2.3 agulbra +84 -8 +src/kernel/qdragobject.cpp 2.11 agulbra +24 -23 +src/kernel/qdragobject.h 2.7 agulbra +6 -3 + + some more stuff works + + +src/kernel/qapp_x11.cpp 2.132 eiriken +4 -3 +src/kernel/qcol_x11.cpp 2.27 eiriken +6 -4 +src/kernel/qimage.cpp 2.84 eiriken +11 -7 +src/kernel/qmetaobj.cpp 2.7 eiriken +6 -4 +src/kernel/qmovie.cpp 1.31 eiriken +8 -5 +src/kernel/qpm_x11.cpp 2.34 eiriken +6 -4 +src/kernel/qwid_win.cpp 2.52 eiriken +4 -4 +src/kernel/qwid_x11.cpp 2.91 eiriken +4 -4 +src/kernel/qwidget.cpp 2.101 eiriken +6 -4 + + Check for delete[] 0 to avoid purify warnings. + + +src/kernel/qclb_x11.cpp 2.8 hanord +5 -2 + + Debugging code commented out + + +src/kernel/qclipbrd.h 2.4 agulbra +2 -1 +src/kernel/qfocusdata.h 2.2 agulbra +2 -2 +src/widgets/qlistview.h 2.45 agulbra +3 -3 +src/widgets/qsplitter.h 1.8 agulbra +2 -2 + + "friend class", not "friend" + + +src/kernel/qdnd_win.cpp 2.2 agulbra +2 -2 +src/kernel/qdnd_x11.cpp 2.2 agulbra +3 -3 +src/kernel/qevent.h 2.13 agulbra +2 -2 + + return a proper object for the drag data, not a reference to a + probably-deleted object. + + +src/kernel/qdnd_x11.cpp 2.4 agulbra +24 -18 +src/kernel/qdragobject.h 2.8 agulbra +1 -2 + + another little bit. + + +src/kernel/qdnd_x11.cpp 2.5 agulbra +6 -24 + + drop some of the debugging messages + + +src/kernel/qevent.cpp 2.13 aavit +9 -6 + + Doc. + + +src/kernel/qfnt_win.cpp 2.26 warwick +4 -4 + + Typo. Will fix (unreported) strange problems with some fonts on Windows. + + +src/kernel/qgmanagr.cpp 2.32 warwick +26 -22 + + Flatten. + + +src/kernel/qimage.cpp 2.82 warwick +6 -3 +src/widgets/qlistbox.cpp 2.62 warwick +14 -2 +src/widgets/qlistview.cpp 2.98 warwick +4 -4 +src/widgets/qscrollview.cpp 2.41 warwick +5 -5 + + docs + + +src/kernel/qpaintdc.h 2.5 eiriken +4 -2 +src/kernel/qpainter.cpp 2.44 eiriken +38 -11 +src/kernel/qprn_win.cpp 2.8 eiriken +31 -13 +src/kernel/qpsprn.cpp 2.18 eiriken +46 -30 +src/kernel/qpsprn.h 2.6 eiriken +4 -1 +src/kernel/qptr_win.cpp 2.34 eiriken +4 -2 +src/kernel/qregion.h 2.10 eiriken +2 -1 + + drawImage support in QPrinter + + +src/kernel/qpainter.cpp 2.41 warwick +17 -2 + + Fix OpaqueMode in drawText(...QRect...). + + +src/kernel/qpainter.cpp 2.42 warwick +5 -9 + + fix. + + +src/kernel/qpainter.cpp 2.43 warwick +2 -12 + + Revert drawText semantics changed. + + +src/kernel/qpainter.cpp 2.45 hanord +6 -2 +src/kernel/qprn_win.cpp 2.9 hanord +5 -4 + + Fixed Windows-specific typos, now compiles + + +src/kernel/qprn_x11.cpp 2.11 agulbra +14 -6 + + avoid getdtablesize(), and set FD_CLOEXEC on just the X connection + instead of on all open files. + + +src/kernel/qpsprn.cpp 2.15 agulbra +6 -6 + + mention the defining rfc for koi8-r + + +src/kernel/qpsprn.cpp 2.17 warwick +438 -428 + + Avoid a HUGE C string, save some memory. + + +src/kernel/qptd_x11.cpp 2.12 warwick +4 -4 + + Restore speed of normal-optimized pixmaps to Qt 1.3x height. + + +src/kernel/qptd_x11.cpp 2.13 hanord +7 -9 + + Warwick's change ACK'd + + +src/kernel/qptr_win.cpp 2.32 agulbra +5 -2 +src/kernel/qptr_x11.cpp 2.46 agulbra +5 -2 + + clip properly in drawPixmap(). + + +src/kernel/qptr_x11.cpp 2.47 eiriken +21 -17 + + Fixed infinite loop bug in internal function drawTile and + renamed variables to make the code readable. + + +src/kernel/qregion.cpp 2.8 hanord +84 -51 +src/kernel/qregion.h 2.9 hanord +12 -3 +src/kernel/qrgn_win.cpp 2.11 hanord +39 -25 +src/kernel/qrgn_x11.cpp 2.11 hanord +48 -29 + + Removed the internal (and slow) byte array. + Uses the region rectangles for saving complex regions. + + +src/kernel/qregion.cpp 2.9 warwick +14 -2 + + Implement missing function. + + +src/kernel/qsignalmapper.cpp 1.2 warwick +2 -2 +src/kernel/qsignalmapper.h 1.2 warwick +2 -2 + + fix function name + + +src/kernel/qsignalmapper.cpp 1.3 warwick +2 -2 +src/widgets/qtablevw.cpp 2.45 warwick +3 -3 + + oops + + +src/kernel/qwid_win.cpp 2.51 agulbra +7 -2 + + if recreating a widget with no children that accept focus, and which + does not accept focus itself, to be a top-level widget, set up a focus + chain. hopefully this will fix a focus bug on windows. + + +src/kernel/qwidget.cpp 2.100 agulbra +4 -4 +src/kernel/qwidget.cpp 2.99 agulbra +9 -7 + + try a little harder to make QWidget::focusWidget() return something. + this should make focus in top-level widgets created by recreate() + behave like in top-level widgets created by new. + + +src/moc/moc.1 2.6 eiriken +20 -5 + + Corrected nested classes bug. + + +src/moc/moc.y 2.21 eiriken +3 -5 + + Removed warning "unexpected ':'" in nested classes. + + +src/qt.pro 2.21 warwick +2 -1 + + Dependencies under Windows. + + +src/qt.pro 2.23 warwick +2 -0 +src/kernel/qsignalmapper.cpp 1.1 warwick initial checkin +src/kernel/qsignalmapper.h 1.1 warwick initial checkin + + QSignalMapper - like a button group superclass. + + +src/tools/qdir.cpp 2.19 agulbra +36 -4 +src/tools/qdir.h 2.7 agulbra +3 -1 + + added new QDir::drives() + + this breaks windows horribly, because I simply couldn't remember the + function call to use there. haavard, add a few lines of code in the + morning, will you? + + +src/tools/qdir.cpp 2.20 agulbra +18 -10 + + implement drives() for windows. now to test. + + +src/tools/qfile.cpp 2.20 warwick +10 -10 + + Casts from off_t to int. + + +src/tools/qglobal.h 2.49 warwick +4 -1 + + GNU Hurd + + +src/tools/qglobal.h 2.50 warwick +4 -1 + + DG Unix + + +src/tools/qtstream.cpp 2.12 warwick +14 -4 +src/widgets/qscrollview.cpp 2.42 warwick +7 -1 + + doc + + +src/widgets/qchkbox.cpp 2.20 warwick +5 -4 +src/widgets/qradiobt.cpp 2.25 warwick +9 -4 + + Small sizeHint when no text or pixmap. + + +src/widgets/qcombo.cpp 2.83 agulbra +10 -2 + + make sure highlighted() is emitted whenever current changes, as per + val gough's bug report. + + +src/widgets/qframe.cpp 2.17 agulbra +13 -2 + + added a hack to make kscd binaries keep working. put in a nice + #if QT_VERSION >= 200 so the hack won't stay too long. + + +src/widgets/qlabel.cpp 2.28 warwick +6 -3 + + Flicker-free when no background. + + +src/widgets/qlined.cpp 2.71 warwick +3 -3 + + Efficiency. + + +src/widgets/qlined.cpp 2.73 agulbra +2 -10 + + disable some buggy code + + +src/widgets/qlined.h 2.26 agulbra +5 -4 + + make validateAndSet() public. It's not a trvial function, but it + appears that event filters can reasonably want to use it. + + +src/widgets/qlistview.cpp 2.100 agulbra +30 -28 + + slightly better pixmap support + + +src/widgets/qlistview.cpp 2.101 agulbra +27 -9 + + added an evil hack to make sizeHint() return more realistic values + before the automagic column resizing magic has done its job. + + +src/widgets/qlistview.cpp 2.102 agulbra +3 -3 + + the list view is now the viewport's focus proxy, rather than the other + way around. + + +src/widgets/qlistview.cpp 2.103 agulbra +6 -7 + + fixed some logical/actual confusion. + + +src/widgets/qlistview.cpp 2.92 agulbra +22 -13 + + hamdle quick drags correctly, as per dimitri van heesch's bug report. + + +src/widgets/qlistview.cpp 2.93 warwick +3 -3 +src/widgets/qlistview.h 2.46 warwick +2 -2 + + paintBranches is non-const + + +src/widgets/qlistview.cpp 2.94 warwick +6 -7 + + Remove unnecessary initial repaints. + + +src/widgets/qlistview.cpp 2.95 agulbra +16 -12 + + try to draw a little more efficiently by using OpaqueMode, and by + never inserting list view items into the repaint dict twice. exposes + a QPainter::drawText() bug. + + +src/widgets/qlistview.cpp 2.96 agulbra +178 -53 +src/widgets/qlistview.h 2.47 agulbra +13 -5 + + added column alignment (worked first try) and real pixmap support + (untested - I try not to push my luck) + + +src/widgets/qlistview.cpp 2.97 agulbra +13 -11 + + draw focus rectangle in the correct place + + +src/widgets/qlistview.cpp 2.99 warwick +9 -12 + + Revert change that required drawText semantics changed. + + +src/widgets/qlistview.h 2.44 agulbra +2 -1 + + avoid hiding text(int) with text() in qchecklistitem + + +src/widgets/qmainwindow.cpp 2.17 agulbra +35 -34 +src/widgets/qmainwindow.h 2.12 agulbra +4 -3 + + handle children being deleted + + +src/widgets/qmenubar.cpp 2.48 warwick +9 -3 +src/widgets/qpopmenu.cpp 2.67 warwick +4 -2 + + Accept keys so they don't propagate. + + +src/widgets/qmenubar.cpp 2.49 warwick +2 -5 +src/widgets/qpopmenu.cpp 2.68 warwick +2 -4 + + undo accept() + + +src/widgets/qmenubar.cpp 2.50 agulbra +3 -4 + + remove unused variable + + +src/widgets/qpopmenu.cpp 2.70 agulbra +13 -16 +src/widgets/qpopmenu.cpp 2.69 agulbra +10 -3 + + minor tweak of right/left submenu position algorithm + + +src/widgets/qpopmenu.cpp 2.71 warwick +5 -2 + + Add a reminder. + + +src/widgets/qscrollview.cpp 2.39 warwick +86 -67 + + Docs. + Remove over-optimization. + + +src/widgets/qscrollview.cpp 2.40 warwick +3 -3 + + Simplify. + + +src/widgets/qscrollview.cpp 2.43 warwick +45 -12 + + Propagate mouse events. + + +src/widgets/qscrollview.h 2.20 warwick +6 -1 + + Propagate mouse evetns. + + +src/widgets/qtoolbutton.cpp 2.23 warwick +4 -3 + + Make receiver/slot optional. + + +src/widgets/qvalidator.cpp 2.18 agulbra +19 -6 + + validate number of decimals. amy watson. diff --git a/dist/changes-1.39-19980529 b/dist/changes-1.39-19980529 new file mode 100644 index 0000000..6c40f61 --- /dev/null +++ b/dist/changes-1.39-19980529 @@ -0,0 +1,232 @@ + +src/dialogs/qfiledlg.cpp 2.67 aavit +24 -1 + + Fixed non-modality bug in GetOpen/SaveFileName on Windows. + + +src/dialogs/qprndlg.cpp 2.21 agulbra +14 -11 + + avoid double-delete of invisible QButtonGroup objects + + +src/dialogs/qprndlg.cpp 2.22 eiriken +4 -3 +src/tools/qregexp.cpp 2.9 eiriken +4 -3 +src/widgets/qheader.cpp 2.36 eiriken +5 -3 +src/widgets/qmenubar.cpp 2.51 eiriken +6 -4 +src/widgets/qwhatsthis.cpp 2.12 eiriken +3 -3 + + More tests before delete [] to avoid purify warnings. + + +src/kernel/qapp_win.cpp 2.86 agulbra +10 -19 +src/kernel/qapp_x11.cpp 2.134 agulbra +35 -44 + + move the pending-events iterator to the next event before dispatching + the current one. prevents recursion if enter_loop() is called within + the event handler. + + +src/kernel/qapp_x11.cpp 2.133 warwick +12 -4 +src/kernel/qevent.h 2.16 warwick +27 -1 +src/kernel/qwidget.cpp 2.103 warwick +9 -2 + + Provide Event_Hide and Event_Show. + + +src/kernel/qasyncimageio.cpp 1.31 warwick +32 -16 +src/kernel/qasyncimageio.h 1.16 warwick +7 -1 +src/kernel/qasyncio.cpp 1.8 warwick +3 -2 +src/kernel/qimage.cpp 2.88 warwick +11 -2 +src/kernel/qpainter.cpp 2.47 warwick +10 -4 + + QAsyncImageIO classes are now public. + + +src/kernel/qdragobject.cpp 2.12 agulbra +10 -4 + + stop the drag when appropriate + + +src/kernel/qevent.cpp 2.14 agulbra +24 -2 +src/kernel/qevent.h 2.15 agulbra +2 -1 + + added new convenience function provides( const char * mimeType ) + + +src/kernel/qevent.h 2.14 agulbra +2 -2 + + return a real QByteArray + + +src/kernel/qpainter.cpp 2.48 warwick +4 -4 + + Fix bitBlt with negative width/height. + + +src/kernel/qpicture.cpp 2.4 eiriken +13 -2 + + Added support for drawImage() + + +src/kernel/qprn_x11.cpp 2.12 agulbra +18 -10 + + close open files before exec'ing lpr. + + +src/kernel/qpsprn.cpp 2.20 eiriken +100 -24 +src/kernel/qpsprn.h 2.7 eiriken +3 -2 +src/kernel/qptr_x11.cpp 2.48 eiriken +4 -3 +src/kernel/qrgn_x11.cpp 2.13 eiriken +3 -3 + + QPrinter now supports clipping of any arbitrary region. + The catch is that resolution is 72 dpi. + + Fixed bug in save()/restore() over page boundaries + + +src/kernel/qpsprn.cpp 2.23 agulbra +6 -3 + + setPen() immediately before drawPoly(most things) did not work. now + it does. + + +src/kernel/qptr_x11.cpp 2.49 warwick +13 -2 + + Probably fix aix-g++ internal compiler error. + + +src/kernel/qregion.cpp 2.10 eiriken +7 -5 +src/kernel/qregion.h 2.11 eiriken +2 -3 + + Rename getRects() to rects() + + +src/kernel/qregion.cpp 2.12 hanord +18 -56 + + New region serializing code, writes only raw rectangles. + In Qt pre 2.0, we write a sort of recursive structure for backward + compatibility. It's large and inefficient. In Qt 2.0, we start using + a much slimmer structure and the reading code for this has already + been added for Qt 1.40. I.e. Qt 1.3x programs won't be able to read + regions serialized with Qt 2.x. + + +src/kernel/qregion.h 2.12 hanord +2 -7 +src/kernel/qrgn_win.cpp 2.13 hanord +12 -44 +src/kernel/qrgn_x11.cpp 2.15 hanord +15 -50 + + Simplified the implementation, now it works with rects only, + + +src/kernel/qwid_win.cpp 2.53 agulbra +4 -3 +src/kernel/qwid_x11.cpp 2.92 agulbra +4 -3 + + update() with w == 0 || h == 0 is a no-op, so exit quickly + + +src/kernel/qwid_win.cpp 2.54 agulbra +6 -2 +src/kernel/qwid_x11.cpp 2.93 agulbra +8 -2 +src/kernel/qwidget.cpp 2.104 agulbra +3 -10 +src/widgets/qmainwindow.cpp 2.20 agulbra +16 -6 + + make isVisible() return TRUE during showEvent(), to match + e.g. resizeEvent(). make QMainWindow fix its geometry when toolbars + are hidden and shown. + + +src/kernel/qwidget.h 2.49 agulbra +2 -6 + + removed autoMinimumSize + + +src/widgets/qbttngrp.cpp 2.10 agulbra +3 -3 + + don't delete buttons in the list + + +src/widgets/qbuttonrow.cpp 1.6 paul +1 -1 +src/widgets/qbuttonrow.h 1.4 paul +1 -1 +src/widgets/qgrid.cpp 1.9 paul +1 -1 +src/widgets/qgrid.h 1.7 paul +1 -1 +src/widgets/qhbox.cpp 1.10 paul +1 -1 +src/widgets/qhbox.h 1.7 paul +1 -1 +src/widgets/qlabelled.cpp 1.5 paul +1 -1 +src/widgets/qlabelled.h 1.4 paul +1 -1 +src/widgets/qvbox.cpp 1.5 paul +1 -1 +src/widgets/qvbox.h 1.5 paul +1 -1 + + removing the layout widgets from the library, moved to examples/layouts + + +src/widgets/qheader.cpp 2.38 paul +121 -62 +src/widgets/qheader.h 2.18 paul +6 -11 + + Implemented setClickEnabled, setResizeEnabled and setMovingEnabled + + +src/widgets/qlined.cpp 2.74 aavit +8 -5 +src/widgets/qspinbox.cpp 2.30 aavit +52 -19 +src/widgets/qspinbox.h 2.17 aavit +3 -1 + + lineedit: better sizehint() + spinbox: added valuechanged( const char* ) signal + + +src/widgets/qlined.cpp 2.75 agulbra +11 -6 + + start drags when appropriate + fold multi-line paste to one line instead of truncating to the \n + + +src/widgets/qlistview.cpp 2.109 agulbra +17 -12 +src/widgets/qlistview.h 2.48 agulbra +4 -4 + + addColumn() return the column number + + +src/widgets/qmainwindow.cpp 2.18 warwick +18 -2 +src/widgets/qmainwindow.h 2.13 warwick +2 -1 + + Show/Hide event filters + + +src/widgets/qmainwindow.cpp 2.19 agulbra +19 -17 +src/widgets/qmainwindow.h 2.14 agulbra +11 -11 + + make set* private as they're not really meaningful any more. + +src/widgets/qmainwindow.cpp 2.22 agulbra +17 -1 + + be slightly more clever about autodetecting menu and status bar. + + +src/widgets/qscrollview.cpp 2.45 warwick +8 -4 + + Only enable WPaintClever in viewport if specifically requested. + + +src/widgets/qstatusbar.cpp 2.8 agulbra +9 -4 + + make sure the status bar is tall enough for text, even when there's + nothing in it. + + +src/widgets/qtablevw.cpp 2.46 agulbra +4 -4 + + last{Row,Col}Visible() could return >= num{Row,Col}s. no more. + + +src/kernel/qapp_x11.cpp 2.137 eiriken +5 -2 + + Fixed bug when there are no events in the X queue and there are posted + events. The posted events will now be handled. + + +src/kernel/qwidget.cpp 2.106 eiriken +5 -2 + + Fixed bug in destruction of main widget. The application now + actually quits. + +src/kernel/qapp.cpp 2.55 hanord +8 -4 + + The QApplication contructor now accepts argc=0 and argv=0. diff --git a/dist/changes-1.39-19980611 b/dist/changes-1.39-19980611 new file mode 100644 index 0000000..d99b636 --- /dev/null +++ b/dist/changes-1.39-19980611 @@ -0,0 +1,194 @@ +doc/binary.doc 1.2 warwick +23 -26 + + Include margins into header graphic + + +doc/examples.doc 2.15 agulbra +19 -2 +examples/dirview/dirview.cpp 1.8 agulbra +2 -2 +src/widgets/qlistview.cpp 2.112 agulbra +163 -28 +src/widgets/qlistview.h 2.49 agulbra +4 -4 + + rename children() to childCount() + add two images to the docs + update dirview and add it to the docs + + +src/dialogs/qfiledlg.cpp 2.68 hanord +8 -12 + + Rewrote setFilter to use QString and mid() - simpler code. + Borland C++ complained about modifying const char *. + + +src/dialogs/qfiledlg.cpp 2.69 agulbra +9 -7 +src/dialogs/qmsgbox.cpp 2.48 agulbra +3 -1 +src/dialogs/qprndlg.cpp 2.26 agulbra +213 -2 +src/widgets/qwidgetstack.cpp 2.6 agulbra +8 -3 + + Call setPalettePropagation() and setFontPropagation() in the + initialization. Note that QWidgetStack now defaults to use + AllChildren. + + +src/dialogs/qmsgbox.cpp 2.47 hanord +3 -3 + + icon widget gets widget name "icon" (previously none) + buttons get widget names button1, button2 (previously space before number) + + +src/dialogs/qprndlg.cpp 2.24 agulbra +163 -7 + + parse /etc/lp/member and /etc/printers.conf. we still probably don't + detect the printers on irix and digital unix (except through sheer + good luck - I suppose there is a chance that digital or sgi might + choose to be compatible with something). + + +src/dialogs/qprndlg.cpp 2.25 agulbra +10 -10 + + one more minor cleanup. + + looks like the code we have works on both irix and digital unix. + + +src/kernel/qapp_win.cpp 2.88 hanord +2 -3 + + Posted event fix + + +src/kernel/qapp_win.cpp 2.89 agulbra +2 -2 +src/kernel/qapp_x11.cpp 2.138 agulbra +3 -3 + + don't delete events destined for other objects in target-specific + sendPostedEvents() + + +src/kernel/qasyncimageio.cpp 1.33 warwick +42 -42 +src/kernel/qasyncimageio.h 1.17 warwick +15 -15 + + New names. + + +src/kernel/qdnd_x11.cpp 2.14 agulbra +8 -5 +src/kernel/qdragobject.cpp 2.14 agulbra +21 -9 + + right cursor + + +src/kernel/qdnd_x11.cpp 2.15 agulbra +6 -9 + + comment out old debug messages; delete some + + +src/kernel/qdragobject.cpp 2.15 agulbra +4 -6 + + ignore totally unexpected events + + +src/kernel/qfnt_win.cpp 2.28 agulbra +4 -4 +src/kernel/qfont.cpp 2.34 agulbra +2 -4 + + be slightly more robust about setting the character encoding to the + defFont's. + + +src/kernel/qfont.cpp 2.31 agulbra +115 -63 + + overhauled class documentation; man function descriptions probably + also need an overhaul. + + +src/kernel/qfont.cpp 2.32 agulbra +56 -65 + + fixed some typos; removed some misleading text from the function + descriptions. + + +src/kernel/qgmanagr.cpp 2.34 paul +22 -66 + + Rolled back "empty layout" change, since it broke existing code. + + +src/kernel/qiconset.cpp 2.9 paul +16 -8 + + Handle mask better when generating disabled pixmaps + + +src/kernel/qprn_x11.cpp 2.14 agulbra +12 -1 + + if the application hasn't specified a non-default print program, try + HARD to find a decent lpr or lp. + + +src/kernel/qpsprn.cpp 2.25 agulbra +12 -7 + + discussed the "sometimes cannot print to /usr/bin/lpr even though + every other program works perfectly" bug with the code. + + also shrunk the output by a few bytes by removing extraneous newlines + and one comment. + + +src/tools/qdatetm.cpp 2.14 agulbra +19 -5 + + QDateTime::addSecs() used to not work across midnight or backwards. + + +src/tools/qglobal.h 2.51 agulbra +4 -2 + + detect unixware 7; detect bool on more irix stuff + + +src/widgets/qbttngrp.cpp 2.12 agulbra +5 -1 + + mention the existence of set*Propagation() + + +src/widgets/qbutton.cpp 2.60 agulbra +16 -17 +src/widgets/qbutton.h 2.16 agulbra +3 -2 + + make setDown() public; this breaks binary compatibility on MSVC++ + + The way to start a context menu on press used to be to make a + synthetic QMouseEvent indicating a release, and sendEvent() that. + not terribly nice. + + +src/widgets/qheader.cpp 2.41 paul +6 -1 + + Fix "Index out of range" bug. + + +src/widgets/qlined.cpp 2.78 agulbra +3 -6 + + when pasting multi-line stuff, fold to one line. + + +src/widgets/qlined.cpp 2.79 paul +2 -2 + + Fix "index out of range" bug when typing past maxLength. + + +src/widgets/qpopmenu.cpp 2.75 aavit +2 -2 + + minimal improvement of checkmark look in windows style. + + +src/widgets/qsplitter.cpp 1.13 agulbra +12 -12 + + more doc; mention setFixed() + + +src/widgets/qtoolbar.cpp 2.21 agulbra +46 -12 + + paint a tool bar handle in motif style too + + +src/widgets/qtoolbar.cpp 2.22 paul +3 -2 + + Don't override max/min sizes for children + + +src/widgets/qtoolbutton.cpp 2.27 agulbra +24 -22 + + handle text label correctly; check for null pointer; minor doc + improvements diff --git a/dist/changes-1.39-19980616 b/dist/changes-1.39-19980616 new file mode 100644 index 0000000..831dd87 --- /dev/null +++ b/dist/changes-1.39-19980616 @@ -0,0 +1,810 @@ +doc/metaobjects.doc 2.9 warwick +3 -3 +doc/tutorial.doc 2.13 warwick +4 -4 +examples/aclock/aclock.h 2.3 warwick +2 -2 +examples/aclock/main.cpp 2.3 warwick +2 -2 +examples/application/application.cpp 1.12 warwick +8 -8 +examples/application/main.cpp 1.6 warwick +2 -2 +examples/biff/biff.cpp 2.3 warwick +2 -2 +examples/biff/biff.h 2.3 warwick +2 -2 +examples/biff/main.cpp 2.3 warwick +2 -2 +examples/connect/connect.cpp 2.5 warwick +2 -2 +examples/cursor/cursor.cpp 2.3 warwick +2 -2 +examples/dclock/dclock.cpp 2.4 warwick +2 -2 +examples/dclock/dclock.h 2.3 warwick +2 -2 +examples/dclock/main.cpp 2.3 warwick +2 -2 +examples/desktop/desktop.cpp 2.4 warwick +2 -2 +examples/dirview/dirview.cpp 1.9 warwick +2 -2 +examples/dirview/main.cpp 1.7 warwick +2 -2 +examples/drawdemo/drawdemo.cpp 2.7 warwick +5 -5 +examples/forever/forever.cpp 2.4 warwick +2 -2 +examples/hello/hello.cpp 2.5 warwick +2 -2 +examples/hello/main.cpp 2.6 warwick +2 -2 +examples/layout/layout.cpp 1.6 warwick +6 -6 +examples/layouts/layouts.cpp 1.5 warwick +6 -6 +examples/layouts/qtbuttonrow.cpp 1.4 warwick +4 -3 +examples/layouts/qthbox.cpp 1.4 warwick +2 -2 +examples/life/life.cpp 2.5 warwick +4 -4 +examples/life/lifedlg.cpp 2.8 warwick +5 -5 +examples/life/main.cpp 2.3 warwick +2 -2 +examples/menu/menu.cpp 2.15 warwick +4 -4 +examples/movies/main.cpp 1.11 warwick +4 -4 +examples/network/connection.cpp 1.7 warwick +2 -2 +examples/network/finger.cpp 1.7 warwick +6 -6 +examples/network/prime.cpp 1.6 warwick +5 -5 +examples/network/primed.cpp 1.8 warwick +4 -4 +examples/network/primespeed.cpp 1.5 warwick +5 -5 +examples/network/server.cpp 1.8 warwick +2 -2 +examples/network/share.cpp 1.6 warwick +4 -4 +examples/picture/picture.cpp 1.6 warwick +3 -3 +examples/pref/main.cpp 1.7 warwick +2 -2 +examples/pref/pref.cpp 1.20 warwick +5 -5 +examples/progress/progress.cpp 1.13 warwick +4 -4 +examples/qdir/qdir.cpp 1.6 warwick +3 -3 +examples/qmag/qmag.cpp 2.16 warwick +5 -5 +examples/qwerty/main.cpp 1.6 warwick +2 -2 +examples/qwerty/qwerty.cpp 1.11 warwick +7 -7 +examples/qwerty/qwerty.h 1.8 warwick +2 -2 +examples/scrollview/scrollview.cpp 1.15 warwick +6 -6 +examples/sheet/main.cpp 2.5 warwick +2 -2 +examples/sheet/sheet.cpp 2.5 warwick +2 -2 +examples/sheet/sheetdlg.cpp 2.5 warwick +2 -2 +examples/sheet/sheetdlg.h 2.3 warwick +2 -2 +examples/sheet/table.cpp 2.4 warwick +2 -2 +examples/sheet/table.h 2.4 warwick +3 -3 +examples/showimg/main.cpp 2.18 warwick +2 -2 +examples/showimg/showimg.cpp 2.24 warwick +5 -5 +examples/table/main.cpp 1.4 warwick +3 -3 +examples/table/table.h 1.5 warwick +2 -2 +examples/tetrix/qdragapp.cpp 2.3 warwick +5 -4 +examples/tetrix/qdragapp.h 2.3 warwick +2 -2 +examples/tetrix/qtetrix.cpp 2.7 warwick +3 -3 +examples/tetrix/qtetrix.h 2.4 warwick +3 -3 +examples/tictac/main.cpp 2.3 warwick +2 -2 +examples/tictac/tictac.cpp 2.8 warwick +6 -6 +examples/tictac/tictac.h 2.3 warwick +2 -2 +examples/timestmp/timestmp.cpp 2.4 warwick +3 -3 +examples/tooltip/main.cpp 1.5 warwick +2 -2 +examples/tooltip/tooltip.cpp 1.6 warwick +2 -2 +examples/validator/main.cpp 1.5 warwick +2 -2 +examples/validator/motor.cpp 1.9 warwick +3 -3 +examples/validator/vw.cpp 1.8 warwick +4 -4 +examples/widgets/widgets.cpp 2.43 warwick +13 -13 +examples/xform/xform.cpp 2.9 warwick +8 -8 +extensions/imageio/src/qjpegio.cpp 1.5 warwick +2 -2 +extensions/imageio/src/qpngio.cpp 1.7 warwick +2 -2 +extensions/nsplugin/examples/grapher/grapher.cpp 1.10 warwick +3 -3 +extensions/nsplugin/examples/qtimage/qtimage.cpp 1.6 warwick +2 -2 +extensions/nsplugin/examples/trivial/trivial.cpp 1.7 warwick +1 -1 +extensions/nsplugin/src/qnp.cpp 1.19 warwick +9 -9 +extensions/opengl/examples/box/globjwin.cpp 1.4 warwick +4 -4 +extensions/opengl/examples/box/main.cpp 1.4 warwick +1 -1 +extensions/opengl/examples/gear/gear.cpp 1.6 warwick +1 -1 +extensions/opengl/examples/sharedbox/globjwin.cpp 1.2 warwick +4 -4 +extensions/opengl/examples/sharedbox/main.cpp 1.2 warwick +1 -1 +extensions/xt/examples/mainlyMotif/editor.cpp 1.3 warwick +2 -2 +extensions/xt/examples/mainlyQt/editor.cpp 1.2 warwick +2 -2 +extensions/xt/examples/mainlyXt/editor.cpp 1.2 warwick +2 -2 +extensions/xt/src/qxt.cpp 1.3 warwick +6 -6 +extensions/xt/src/qxt.h 1.2 warwick +2 -2 +src/qt.pro 2.26 warwick +110 -110 +src/qtinternal.pro 2.7 warwick +5 -5 +src/dialogs/qfiledialog.cpp 2.71 warwick +12 -12 +src/dialogs/qfiledialog.h 2.18 warwick +4 -4 +src/dialogs/qfiledlg.cpp 2.71 warwick +1 -1 +src/dialogs/qfiledlg.h 2.18 warwick +2 -146 +src/dialogs/qfontdialog.cpp 2.13 warwick +7 -7 +src/dialogs/qmessagebox.cpp 2.49 warwick +5 -5 +src/dialogs/qmessagebox.h 2.26 warwick +4 -4 +src/dialogs/qmsgbox.cpp 2.49 warwick +1 -1 +src/dialogs/qmsgbox.h 2.26 warwick +1 -132 +src/dialogs/qprintdialog.cpp 2.28 warwick +10 -10 +src/dialogs/qprintdialog.h 2.9 warwick +4 -4 +src/dialogs/qprndlg.cpp 2.28 warwick +1 -1 +src/dialogs/qprndlg.h 2.9 warwick +2 -63 +src/dialogs/qprogdlg.cpp 2.27 warwick +1 -1 +src/dialogs/qprogdlg.h 2.14 warwick +2 -75 +src/dialogs/qprogressdialog.cpp 2.27 warwick +6 -6 +src/dialogs/qprogressdialog.h 2.14 warwick +6 -6 +src/dialogs/qtabdialog.cpp 2.41 warwick +7 -6 +src/dialogs/qtabdialog.h 2.19 warwick +4 -4 +src/dialogs/qtabdlg.cpp 2.41 warwick +1 -1 +src/dialogs/qtabdlg.h 2.19 warwick +1 -84 +src/kernel/qaccel.cpp 2.13 warwick +2 -2 +src/kernel/qapp.cpp 2.57 warwick +1 -1 +src/kernel/qapp.h 2.27 warwick +1 -205 +src/kernel/qapp_os2.cpp 2.5 warwick +4 -3 +src/kernel/qapp_win.cpp 2.90 warwick +1 -1 +src/kernel/qapp_x11.cpp 2.141 warwick +1 -1 +src/kernel/qapplication.cpp 2.57 warwick +13 -11 +src/kernel/qapplication.h 2.27 warwick +5 -5 +src/kernel/qapplication_win.cpp 2.90 warwick +9 -7 +src/kernel/qapplication_x11.cpp 2.141 warwick +13 -11 +src/kernel/qasyncio.cpp 1.9 warwick +2 -2 +src/kernel/qclb_win.cpp 2.7 warwick +1 -1 +src/kernel/qclb_x11.cpp 2.13 warwick +1 -1 +src/kernel/qclipboard.cpp 2.9 warwick +4 -4 +src/kernel/qclipboard.h 2.5 warwick +4 -4 +src/kernel/qclipboard_win.cpp 2.7 warwick +4 -4 +src/kernel/qclipboard_x11.cpp 2.13 warwick +5 -5 +src/kernel/qclipbrd.cpp 2.9 warwick +1 -1 +src/kernel/qclipbrd.h 2.5 warwick +2 -55 +src/kernel/qcol_win.cpp 2.18 warwick +1 -1 +src/kernel/qcol_x11.cpp 2.31 warwick +1 -1 +src/kernel/qcolor.cpp 2.15 warwick +2 -2 +src/kernel/qcolor.h 2.10 warwick +2 -2 +src/kernel/qcolor_win.cpp 2.18 warwick +2 -2 +src/kernel/qcolor_x11.cpp 2.31 warwick +4 -4 +src/kernel/qconnect.cpp 2.5 warwick +1 -1 +src/kernel/qconnect.h 2.5 warwick +2 -46 +src/kernel/qconnection.cpp 2.5 warwick +3 -3 +src/kernel/qconnection.h 2.5 warwick +4 -4 +src/kernel/qcur_os2.cpp 2.3 warwick +2 -2 +src/kernel/qcur_win.cpp 2.7 warwick +1 -1 +src/kernel/qcur_x11.cpp 2.11 warwick +1 -1 +src/kernel/qcursor.cpp 2.8 warwick +2 -2 +src/kernel/qcursor_win.cpp 2.7 warwick +3 -3 +src/kernel/qcursor_x11.cpp 2.11 warwick +3 -3 +src/kernel/qdialog.cpp 2.19 warwick +5 -4 +src/kernel/qdnd_win.cpp 2.6 warwick +2 -2 +src/kernel/qdnd_x11.cpp 2.18 warwick +8 -7 +src/kernel/qdragobject.cpp 2.17 warwick +4 -3 +src/kernel/qdrawutil.cpp 2.18 warwick +3 -3 +src/kernel/qdrawutil.h 2.7 warwick +4 -4 +src/kernel/qdrawutl.cpp 2.18 warwick +1 -1 +src/kernel/qdrawutl.h 2.7 warwick +2 -91 +src/kernel/qevent.h 2.17 warwick +2 -2 +src/kernel/qfnt_win.cpp 2.30 warwick +1 -1 +src/kernel/qfnt_x11.cpp 2.39 warwick +1 -1 +src/kernel/qfont.cpp 2.35 warwick +11 -11 +src/kernel/qfont.h 2.10 warwick +2 -2 +src/kernel/qfont_win.cpp 2.30 warwick +5 -5 +src/kernel/qfont_x11.cpp 2.39 warwick +2 -2 +src/kernel/qfontdata.h 2.11 warwick +4 -4 +src/kernel/qfontdta.h 2.11 warwick +2 -65 +src/kernel/qfontinf.h 2.7 warwick +1 -79 +src/kernel/qfontinfo.h 2.7 warwick +4 -4 +src/kernel/qfontmet.h 2.14 warwick +1 -95 +src/kernel/qfontmetrics.h 2.14 warwick +4 -4 +src/kernel/qgmanager.cpp 2.36 warwick +5 -5 +src/kernel/qgmanager.h 2.13 warwick +4 -4 +src/kernel/qgmanagr.cpp 2.36 warwick +1 -1 +src/kernel/qgmanagr.h 2.13 warwick +2 -84 +src/kernel/qiconset.cpp 2.10 warwick +2 -2 +src/kernel/qimage.cpp 2.91 warwick +3 -3 +src/kernel/qlayout.h 2.18 warwick +2 -2 +src/kernel/qmetaobj.cpp 2.9 warwick +1 -1 +src/kernel/qmetaobj.h 2.4 warwick +2 -66 +src/kernel/qmetaobject.cpp 2.9 warwick +5 -4 +src/kernel/qmetaobject.h 2.4 warwick +5 -5 +src/kernel/qmovie.cpp 1.33 warwick +3 -3 +src/kernel/qmutex.h 1.5 warwick +2 -2 +src/kernel/qnpsupport.cpp 2.11 warwick +6 -6 +src/kernel/qobjcoll.h 2.6 warwick +1 -1 +src/kernel/qobjdefs.h 2.4 warwick +1 -78 +src/kernel/qobject.cpp 2.51 warwick +5 -4 +src/kernel/qobject.h 2.10 warwick +2 -2 +src/kernel/qobjectdefs.h 2.4 warwick +4 -4 +src/kernel/qobjectdict.h 2.1 warwick initial checkin +src/kernel/qobjectlist.h 2.1 warwick initial checkin +src/kernel/qpaintd.h 2.7 warwick +1 -170 +src/kernel/qpaintdc.h 2.6 warwick +2 -97 +src/kernel/qpaintdevice.h 2.7 warwick +6 -6 +src/kernel/qpaintdevice_win.cpp 2.10 warwick +5 -5 +src/kernel/qpaintdevice_x11.cpp 2.15 warwick +6 -6 +src/kernel/qpaintdevicedefs.h 2.6 warwick +5 -5 +src/kernel/qpaintdevicemetrics.cpp 2.4 warwick +3 -3 +src/kernel/qpaintdevicemetrics.h 2.3 warwick +7 -7 +src/kernel/qpainter.cpp 2.53 warwick +7 -7 +src/kernel/qpainter.h 2.26 warwick +5 -5 +src/kernel/qpainter_win.cpp 2.37 warwick +5 -5 +src/kernel/qpainter_x11.cpp 2.52 warwick +4 -4 +src/kernel/qpalette.cpp 2.18 warwick +2 -2 +src/kernel/qpalette.h 2.14 warwick +2 -2 +src/kernel/qpdevmet.cpp 2.4 warwick +1 -1 +src/kernel/qpdevmet.h 2.3 warwick +2 -37 +src/kernel/qpic_win.cpp 2.3 warwick +1 -1 +src/kernel/qpic_x11.cpp 2.3 warwick +1 -1 +src/kernel/qpicture.cpp 2.6 warwick +3 -3 +src/kernel/qpicture.h 2.5 warwick +2 -2 +src/kernel/qpixmap.cpp 2.26 warwick +2 -2 +src/kernel/qpixmap.h 2.20 warwick +2 -2 +src/kernel/qpixmap_win.cpp 2.35 warwick +3 -3 +src/kernel/qpixmap_x11.cpp 2.37 warwick +3 -3 +src/kernel/qpixmapcache.cpp 2.7 warwick +3 -3 +src/kernel/qpixmapcache.h 2.4 warwick +4 -4 +src/kernel/qpm_win.cpp 2.35 warwick +1 -1 +src/kernel/qpm_x11.cpp 2.37 warwick +1 -1 +src/kernel/qpmcache.cpp 2.7 warwick +1 -1 +src/kernel/qpmcache.h 2.4 warwick +2 -31 +src/kernel/qpntarry.cpp 2.16 warwick +1 -1 +src/kernel/qpntarry.h 2.7 warwick +1 -155 +src/kernel/qpoint.cpp 2.4 warwick +3 -3 +src/kernel/qpoint.h 2.3 warwick +2 -2 +src/kernel/qpointarray.cpp 2.16 warwick +6 -6 +src/kernel/qpointarray.h 2.7 warwick +4 -4 +src/kernel/qprinter.cpp 2.9 warwick +3 -3 +src/kernel/qprinter.h 2.7 warwick +2 -2 +src/kernel/qprinter_win.cpp 2.11 warwick +2 -2 +src/kernel/qprinter_x11.cpp 2.16 warwick +6 -6 +src/kernel/qprn_win.cpp 2.11 warwick +1 -1 +src/kernel/qprn_x11.cpp 2.16 warwick +1 -1 +src/kernel/qpsprinter.cpp 2.26 warwick +4 -4 +src/kernel/qpsprinter.h 2.8 warwick +5 -5 +src/kernel/qpsprn.cpp 2.26 warwick +1 -1 +src/kernel/qpsprn.h 2.8 warwick +2 -70 +src/kernel/qptd_os2.cpp 2.3 warwick +2 -2 +src/kernel/qptd_win.cpp 2.10 warwick +1 -1 +src/kernel/qptd_x11.cpp 2.15 warwick +1 -1 +src/kernel/qptr_os2.cpp 2.4 warwick +2 -2 +src/kernel/qptr_win.cpp 2.37 warwick +1 -1 +src/kernel/qptr_x11.cpp 2.52 warwick +1 -1 +src/kernel/qrect.cpp 2.8 warwick +3 -3 +src/kernel/qregion.cpp 2.14 warwick +3 -3 +src/kernel/qregion_win.cpp 2.15 warwick +2 -2 +src/kernel/qregion_x11.cpp 2.16 warwick +2 -2 +src/kernel/qrgn_os2.cpp 2.4 warwick +2 -2 +src/kernel/qrgn_win.cpp 2.15 warwick +1 -1 +src/kernel/qrgn_x11.cpp 2.16 warwick +1 -1 +src/kernel/qsemimodal.cpp 2.6 warwick +2 -2 +src/kernel/qsignal.cpp 2.5 warwick +2 -2 +src/kernel/qsize.cpp 2.9 warwick +3 -3 +src/kernel/qsocketnotifier.cpp 2.7 warwick +3 -3 +src/kernel/qsocketnotifier.h 2.4 warwick +4 -4 +src/kernel/qsocknot.cpp 2.7 warwick +1 -1 +src/kernel/qsocknot.h 2.4 warwick +2 -60 +src/kernel/qt_x11.cpp 2.4 warwick +1 -1 +src/kernel/qthread.h 1.5 warwick +2 -2 +src/kernel/qtimer.cpp 2.9 warwick +4 -3 +src/kernel/qwid_os2.cpp 2.6 warwick +3 -2 +src/kernel/qwid_win.cpp 2.56 warwick +1 -1 +src/kernel/qwid_x11.cpp 2.96 warwick +1 -1 +src/kernel/qwidcoll.h 2.5 warwick +1 -1 +src/kernel/qwidget.cpp 2.111 warwick +10 -8 +src/kernel/qwidget.h 2.50 warwick +5 -5 +src/kernel/qwidget_win.cpp 2.56 warwick +11 -9 +src/kernel/qwidget_x11.cpp 2.96 warwick +10 -8 +src/kernel/qwidgetintdict.h 2.1 warwick initial checkin +src/kernel/qwidgetlist.h 2.1 warwick initial checkin +src/kernel/qwindefs.h 2.23 warwick +1 -313 +src/kernel/qwindowdefs.h 2.23 warwick +5 -5 +src/kernel/qwmatrix.cpp 2.5 warwick +3 -3 +src/kernel/qwmatrix.h 2.3 warwick +3 -3 +src/moc/GNUmakefile 2.5 warwick +13 -13 +src/moc/Makefile 2.10 warwick +42 -42 +src/moc/moc.pro 1.10 warwick +4 -4 +src/moc/moc.y 2.23 warwick +5 -5 +src/tools/qbitarray.cpp 2.7 warwick +5 -5 +src/tools/qbitarray.h 2.5 warwick +4 -4 +src/tools/qbitarry.cpp 2.7 warwick +1 -1 +src/tools/qbitarry.h 2.5 warwick +2 -134 +src/tools/qbuffer.h 2.5 warwick +2 -2 +src/tools/qcollect.cpp 2.5 warwick +1 -1 +src/tools/qcollect.h 2.3 warwick +2 -46 +src/tools/qcollection.cpp 2.5 warwick +3 -3 +src/tools/qcollection.h 2.3 warwick +4 -4 +src/tools/qdatastream.cpp 2.14 warwick +3 -3 +src/tools/qdatastream.h 2.6 warwick +5 -5 +src/tools/qdatetime.cpp 2.15 warwick +6 -6 +src/tools/qdatetime.h 2.4 warwick +4 -4 +src/tools/qdatetm.cpp 2.15 warwick +1 -1 +src/tools/qdatetm.h 2.4 warwick +2 -180 +src/tools/qdir.cpp 2.22 warwick +3 -3 +src/tools/qdir.h 2.8 warwick +2 -2 +src/tools/qdstream.cpp 2.14 warwick +1 -1 +src/tools/qdstream.h 2.6 warwick +2 -117 +src/tools/qfile.cpp 2.22 warwick +2 -2 +src/tools/qfile.h 2.5 warwick +2 -2 +src/tools/qfiledef.h 2.8 warwick +3 -153 +src/tools/qfiledefs.h 2.8 warwick +2 -2 +src/tools/qfileinf.cpp 2.11 warwick +1 -1 +src/tools/qfileinf.h 2.3 warwick +2 -96 +src/tools/qfileinfo.cpp 2.11 warwick +6 -6 +src/tools/qfileinfo.h 2.3 warwick +5 -5 +src/tools/qgcache.h 2.3 warwick +2 -2 +src/tools/qgdict.cpp 2.16 warwick +2 -2 +src/tools/qgdict.h 2.5 warwick +2 -2 +src/tools/qglist.cpp 2.5 warwick +2 -2 +src/tools/qglist.h 2.3 warwick +2 -2 +src/tools/qglobal.cpp 2.15 warwick +2 -2 +src/tools/qglobal.h 2.52 warwick +2 -2 +src/tools/qgvector.cpp 2.7 warwick +2 -2 +src/tools/qgvector.h 2.3 warwick +2 -2 +src/tools/qintcach.h 2.3 warwick +1 -168 +src/tools/qintcache.h 2.3 warwick +4 -4 +src/tools/qiodev.cpp 2.11 warwick +1 -1 +src/tools/qiodev.h 2.5 warwick +2 -128 +src/tools/qiodevice.cpp 2.11 warwick +3 -3 +src/tools/qiodevice.h 2.5 warwick +4 -4 +src/tools/qstring.cpp 2.21 warwick +2 -2 +src/tools/qstrlist.h 2.11 warwick +2 -2 +src/tools/qstrvec.h 2.4 warwick +2 -2 +src/tools/qtextstream.cpp 2.15 warwick +4 -4 +src/tools/qtextstream.h 2.7 warwick +5 -5 +src/tools/qtstream.cpp 2.15 warwick +1 -1 +src/tools/qtstream.h 2.7 warwick +2 -216 +src/widgets/qbttngrp.cpp 2.13 warwick +1 -1 +src/widgets/qbttngrp.h 2.6 warwick +2 -61 +src/widgets/qbutton.cpp 2.61 warwick +3 -3 +src/widgets/qbutton.h 2.17 warwick +2 -2 +src/widgets/qbuttongroup.cpp 2.13 warwick +3 -3 +src/widgets/qbuttongroup.h 2.6 warwick +5 -5 +src/widgets/qcheckbox.cpp 2.23 warwick +5 -5 +src/widgets/qcheckbox.h 2.6 warwick +4 -4 +src/widgets/qchkbox.cpp 2.23 warwick +1 -1 +src/widgets/qchkbox.h 2.6 warwick +2 -47 +src/widgets/qcombo.cpp 2.87 warwick +1 -1 +src/widgets/qcombo.h 2.27 warwick +2 -132 +src/widgets/qcombobox.cpp 2.87 warwick +8 -8 +src/widgets/qcombobox.h 2.27 warwick +3 -3 +src/widgets/qframe.cpp 2.19 warwick +2 -2 +src/widgets/qgroupbox.cpp 2.12 warwick +3 -3 +src/widgets/qgroupbox.h 2.4 warwick +4 -4 +src/widgets/qgrpbox.cpp 2.12 warwick +1 -1 +src/widgets/qgrpbox.h 2.4 warwick +2 -46 +src/widgets/qheader.cpp 2.45 warwick +3 -3 +src/widgets/qheader.h 2.19 warwick +2 -2 +src/widgets/qlabel.cpp 2.32 warwick +2 -2 +src/widgets/qlcdnum.cpp 2.13 warwick +1 -1 +src/widgets/qlcdnum.h 2.8 warwick +2 -95 +src/widgets/qlcdnumber.cpp 2.13 warwick +4 -4 +src/widgets/qlcdnumber.h 2.8 warwick +5 -5 +src/widgets/qlined.cpp 2.81 warwick +1 -1 +src/widgets/qlined.h 2.28 warwick +2 -138 +src/widgets/qlineedit.cpp 2.81 warwick +7 -7 +src/widgets/qlineedit.h 2.28 warwick +4 -4 +src/widgets/qlistbox.cpp 2.69 warwick +4 -4 +src/widgets/qlistbox.h 2.16 warwick +2 -2 +src/widgets/qlistview.cpp 2.117 warwick +3 -3 +src/widgets/qmainwindow.cpp 2.27 warwick +4 -3 +src/widgets/qmenubar.cpp 2.54 warwick +3 -3 +src/widgets/qmenubar.h 2.11 warwick +2 -2 +src/widgets/qmenudata.cpp 2.16 warwick +5 -5 +src/widgets/qmenudata.h 2.11 warwick +4 -4 +src/widgets/qmenudta.cpp 2.16 warwick +1 -1 +src/widgets/qmenudta.h 2.11 warwick +1 -182 +src/widgets/qmlined.cpp 2.93 warwick +1 -1 +src/widgets/qmlined.h 2.36 warwick +2 -189 +src/widgets/qmultilined.cpp 2.93 warwick +6 -6 +src/widgets/qmultilined.h 2.36 warwick +5 -5 +src/widgets/qpopmenu.cpp 2.78 warwick +1 -1 +src/widgets/qpopmenu.h 2.14 warwick +2 -110 +src/widgets/qpopupmenu.cpp 2.78 warwick +6 -6 +src/widgets/qpopupmenu.h 2.14 warwick +6 -6 +src/widgets/qprogbar.cpp 2.19 warwick +1 -1 +src/widgets/qprogbar.h 2.9 warwick +2 -65 +src/widgets/qprogressbar.cpp 2.19 warwick +5 -5 +src/widgets/qprogressbar.h 2.9 warwick +4 -4 +src/widgets/qpushbt.cpp 2.41 warwick +1 -1 +src/widgets/qpushbt.h 2.8 warwick +2 -70 +src/widgets/qpushbutton.cpp 2.41 warwick +6 -6 +src/widgets/qpushbutton.h 2.8 warwick +4 -4 +src/widgets/qradiobt.cpp 2.28 warwick +1 -1 +src/widgets/qradiobt.h 2.8 warwick +2 -55 +src/widgets/qradiobutton.cpp 2.28 warwick +6 -6 +src/widgets/qradiobutton.h 2.8 warwick +4 -4 +src/widgets/qrangecontrol.cpp 2.6 warwick +3 -3 +src/widgets/qrangecontrol.h 2.3 warwick +4 -4 +src/widgets/qrangect.cpp 2.6 warwick +1 -1 +src/widgets/qrangect.h 2.3 warwick +2 -76 +src/widgets/qscrbar.cpp 2.38 warwick +1 -1 +src/widgets/qscrbar.h 2.6 warwick +2 -115 +src/widgets/qscrollbar.cpp 2.38 warwick +3 -3 +src/widgets/qscrollbar.h 2.6 warwick +6 -6 +src/widgets/qscrollview.cpp 2.46 warwick +5 -4 +src/widgets/qscrollview.h 2.21 warwick +2 -2 +src/widgets/qslider.cpp 2.52 warwick +2 -2 +src/widgets/qslider.h 2.23 warwick +2 -2 +src/widgets/qspinbox.cpp 2.35 warwick +3 -3 +src/widgets/qspinbox.h 2.20 warwick +2 -2 +src/widgets/qsplitter.cpp 1.16 warwick +2 -2 +src/widgets/qstatusbar.cpp 2.14 warwick +3 -3 +src/widgets/qtableview.cpp 2.49 warwick +5 -5 +src/widgets/qtableview.h 2.10 warwick +4 -4 +src/widgets/qtablevw.cpp 2.49 warwick +1 -1 +src/widgets/qtablevw.h 2.10 warwick +2 -241 +src/widgets/qtoolbar.cpp 2.23 warwick +5 -4 +src/widgets/qtoolbutton.cpp 2.28 warwick +3 -3 +src/widgets/qtooltip.cpp 2.47 warwick +4 -4 +src/widgets/qwellarray.cpp 1.4 warwick +4 -3 +src/widgets/qwellarray.h 1.5 warwick +2 -2 +src/widgets/qwhatsthis.cpp 2.15 warwick +3 -3 +src/widgets/qwidgetstack.cpp 2.7 warwick +3 -2 +tutorial/t1/main.cpp 2.1 warwick +2 -2 +tutorial/t10/lcdrange.cpp 2.1 warwick +2 -2 +tutorial/t10/main.cpp 2.3 warwick +4 -4 +tutorial/t11/lcdrange.cpp 2.1 warwick +2 -2 +tutorial/t11/main.cpp 2.3 warwick +4 -4 +tutorial/t12/cannon.cpp 2.3 warwick +1 -1 +tutorial/t12/lcdrange.cpp 2.1 warwick +2 -2 +tutorial/t12/main.cpp 2.3 warwick +4 -4 +tutorial/t13/cannon.cpp 2.3 warwick +1 -1 +tutorial/t13/gamebrd.cpp 2.1 warwick +3 -3 +tutorial/t13/lcdrange.cpp 2.1 warwick +2 -2 +tutorial/t13/main.cpp 2.3 warwick +1 -1 +tutorial/t14/cannon.cpp 2.3 warwick +1 -1 +tutorial/t14/gamebrd.cpp 2.2 warwick +3 -3 +tutorial/t14/lcdrange.cpp 2.1 warwick +2 -2 +tutorial/t14/main.cpp 2.3 warwick +1 -1 +tutorial/t2/main.cpp 2.1 warwick +2 -2 +tutorial/t3/main.cpp 2.1 warwick +2 -2 +tutorial/t4/main.cpp 2.1 warwick +2 -2 +tutorial/t5/main.cpp 2.1 warwick +4 -4 +tutorial/t6/main.cpp 2.1 warwick +4 -4 +tutorial/t7/lcdrange.cpp 2.1 warwick +2 -2 +tutorial/t7/main.cpp 2.1 warwick +4 -4 +tutorial/t8/lcdrange.cpp 2.1 warwick +2 -2 +tutorial/t8/main.cpp 2.1 warwick +4 -4 +tutorial/t9/lcdrange.cpp 2.1 warwick +2 -2 +tutorial/t9/main.cpp 2.3 warwick +4 -4 + + The Big Renaming of '98 + + +doc/tutorial.doc 2.14 agulbra +4 -4 + + new header files + + +examples/validator/motor.cpp 1.8 agulbra +2 -71 +examples/validator/motor.h 1.7 agulbra +2 -29 +examples/validator/vw.cpp 1.7 agulbra +11 -11 +examples/validator/vw.h 1.4 agulbra +3 -3 + + some fixes for current QSpinBox + + +extensions/nsplugin/src/qnp.pro 1.2 warwick +1 -1 + + tmake workaround + + +src/dialogs/qfiledialog.cpp 2.70 agulbra +46 -1 +src/dialogs/qfiledialog.h 2.17 agulbra +3 -1 +src/dialogs/qfiledlg.cpp 2.70 agulbra +46 -1 +src/dialogs/qfiledlg.h 2.17 agulbra +3 -1 + + support multile file types + + +src/dialogs/qfiledlg.h 2.19 warwick +0 -0 +src/dialogs/qmsgbox.h 2.27 warwick +0 -0 +src/dialogs/qprndlg.h 2.10 warwick +0 -0 +src/dialogs/qprogdlg.h 2.15 warwick +0 -0 +src/dialogs/qtabdlg.h 2.20 warwick +0 -0 +src/kernel/qapp.h 2.28 warwick +0 -0 +src/kernel/qclipbrd.h 2.6 warwick +0 -0 +src/kernel/qconnect.h 2.6 warwick +0 -0 +src/kernel/qdrawutl.h 2.8 warwick +0 -0 +src/kernel/qfontdta.h 2.12 warwick +0 -0 +src/kernel/qfontinf.h 2.8 warwick +0 -0 +src/kernel/qfontmet.h 2.15 warwick +0 -0 +src/kernel/qgmanagr.h 2.14 warwick +0 -0 +src/kernel/qmetaobj.h 2.5 warwick +0 -0 +src/kernel/qobjdefs.h 2.5 warwick +0 -0 +src/kernel/qpaintd.h 2.8 warwick +0 -0 +src/kernel/qpaintdc.h 2.7 warwick +0 -0 +src/kernel/qpdevmet.h 2.4 warwick +0 -0 +src/kernel/qpmcache.h 2.5 warwick +0 -0 +src/kernel/qpntarry.h 2.8 warwick +0 -0 +src/kernel/qpsprn.h 2.9 warwick +0 -0 +src/kernel/qsocknot.h 2.5 warwick +0 -0 +src/kernel/qwindefs.h 2.24 warwick +0 -0 +src/tools/qbitarry.h 2.6 warwick +0 -0 +src/tools/qcollect.h 2.4 warwick +0 -0 +src/tools/qdatetm.h 2.5 warwick +0 -0 +src/tools/qdstream.h 2.7 warwick +0 -0 +src/tools/qfiledef.h 2.9 warwick +0 -0 +src/tools/qfileinf.h 2.4 warwick +0 -0 +src/tools/qintcach.h 2.4 warwick +0 -0 +src/tools/qiodev.h 2.6 warwick +0 -0 +src/tools/qtstream.h 2.8 warwick +0 -0 +src/widgets/qbttngrp.h 2.7 warwick +0 -0 +src/widgets/qchkbox.h 2.7 warwick +0 -0 +src/widgets/qcombo.h 2.28 warwick +0 -0 +src/widgets/qgrpbox.h 2.5 warwick +0 -0 +src/widgets/qlcdnum.h 2.9 warwick +0 -0 +src/widgets/qlined.h 2.29 warwick +0 -0 +src/widgets/qmenudta.h 2.12 warwick +0 -0 +src/widgets/qmlined.h 2.37 warwick +0 -0 +src/widgets/qpopmenu.h 2.15 warwick +0 -0 +src/widgets/qprogbar.h 2.10 warwick +0 -0 +src/widgets/qpushbt.h 2.9 warwick +0 -0 +src/widgets/qradiobt.h 2.9 warwick +0 -0 +src/widgets/qrangect.h 2.4 warwick +0 -0 +src/widgets/qscrbar.h 2.7 warwick +0 -0 +src/widgets/qtablevw.h 2.11 warwick +0 -0 + + Move compatibility files out of the way. + + +src/dialogs/qprintdialog.cpp 2.27 agulbra +67 -1 +src/dialogs/qprndlg.cpp 2.27 agulbra +67 -1 + + val's irix 6.3 printer discovery code + + +src/kernel/qapp.cpp 2.56 agulbra +14 -6 +src/kernel/qapplication.cpp 2.56 agulbra +14 -6 +src/kernel/qasyncimageio.cpp 1.34 agulbra +53 -15 +src/kernel/qregion.cpp 2.13 agulbra +1 -8 +src/kernel/qregion.h 2.13 agulbra +1 -4 +src/widgets/qheader.cpp 2.44 agulbra +4 -5 + + Reginald Stadlbauer's alpha's egcs said to do this. it doesn't like + static objects with non-default constructors. + + +src/kernel/qapp_os2.cpp 2.6 warwick +1 -1 +src/kernel/qcol_os2.cpp 2.4 warwick +1 -1 +src/kernel/qcur_os2.cpp 2.4 warwick +1 -1 +src/kernel/qfnt_os2.cpp 2.3 warwick +1 -1 +src/kernel/qpic_os2.cpp 2.3 warwick +1 -1 +src/kernel/qpm_os2.cpp 2.3 warwick +1 -1 +src/kernel/qptd_os2.cpp 2.4 warwick +1 -1 +src/kernel/qptr_os2.cpp 2.5 warwick +1 -1 +src/kernel/qrgn_os2.cpp 2.5 warwick +1 -1 +src/kernel/qwid_os2.cpp 2.7 warwick +1 -1 + + Remove OS2 code. + + +src/kernel/qapp_x11.cpp 2.139 hanord +2 -4 +src/kernel/qapplication_x11.cpp 2.139 hanord +2 -4 + + Fixed keyboard release event bug when the key press was done outside the + window (Morten Eriksen bug report). + + +src/kernel/qapp_x11.cpp 2.140 warwick +5 -5 +src/kernel/qapplication_x11.cpp 2.140 warwick +5 -5 +src/kernel/qfnt_x11.cpp 2.37 warwick +9 -23 +src/kernel/qfont_x11.cpp 2.37 warwick +9 -23 +src/kernel/qimage.cpp 2.90 warwick +13 -13 +src/kernel/qnpsupport.cpp 2.10 warwick +2 -1 +src/kernel/qwidget.cpp 2.109 warwick +17 -16 + + Fix pointer-to-int casts that 64-bit compiler don't like. + + +src/kernel/qcol_x11.cpp 2.30 hanord +2 -2 +src/kernel/qcolor_x11.cpp 2.30 hanord +2 -2 +src/widgets/qheader.cpp 2.42 hanord +2 -2 + + Don't do big changes in 1.40, wait until 1.49 + + +src/kernel/qdialog.cpp 2.18 warwick +20 -4 + + Stay on-screen when centering relative to parent. This code should + be shared. + + +src/kernel/qdnd_x11.cpp 2.15 agulbra +6 -9 + + comment out old debug messages; delete some + + +src/kernel/qdnd_x11.cpp 2.16 agulbra +8 -5 + + workaround for gcc/alpha brokenness. + + +src/kernel/qdnd_x11.cpp 2.17 warwick +9 -9 +src/kernel/qpainter.cpp 2.52 warwick +14 -11 +src/kernel/qwid_x11.cpp 2.95 warwick +2 -2 +src/kernel/qwidget_x11.cpp 2.95 warwick +2 -2 +src/widgets/qwellarray.cpp 1.3 warwick +10 -1 +src/widgets/qwellarray.h 1.4 warwick +2 -1 + + Avoid HPUX warnings. + + +src/kernel/qdragobject.cpp 2.15 agulbra +4 -6 + + ignore totally unexpected events + + +src/kernel/qdragobject.cpp 2.16 agulbra +2 -2 + + stop warning + + +src/kernel/qfnt_win.cpp 2.29 warwick +3 -3 +src/kernel/qfnt_x11.cpp 2.38 warwick +4 -4 +src/kernel/qfont_win.cpp 2.29 warwick +3 -3 +src/kernel/qfont_x11.cpp 2.38 warwick +4 -4 + + Fix width(char) for signed characters. + + +src/kernel/qgmanager.cpp 2.35 paul +48 -20 +src/kernel/qgmanager.h 2.12 paul +3 -1 +src/kernel/qgmanagr.cpp 2.35 paul +48 -20 +src/kernel/qgmanagr.h 2.12 paul +3 -1 +src/kernel/qlayout.cpp 2.32 paul +36 -22 + + Better debug output. + + +src/kernel/qimage.cpp 2.92 warwick +3 -3 +src/kernel/qlayout.cpp 2.34 agulbra +10 -25 +src/kernel/qpainter.cpp 2.50 agulbra +6 -12 +src/tools/qregexp.cpp 2.11 agulbra +3 -3 +src/widgets/qstatusbar.cpp 2.12 agulbra +4 -4 + + doc + + +src/kernel/qlayout.cpp 2.31 agulbra +75 -24 +src/widgets/qlistview.cpp 2.114 agulbra +7 -2 + + some docs + + +src/kernel/qlayout.cpp 2.33 agulbra +183 -34 +src/widgets/qlistview.cpp 2.115 agulbra +93 -22 +src/widgets/qlistview.h 2.50 agulbra +4 -1 +src/widgets/qwhatsthis.cpp 2.14 agulbra +152 -29 + + doc, doc, doc. this round pushes qt over 3250 documented functions. + the next milestone is five megs of html doc (sixty-odd k left). + + +src/kernel/qobjcoll.h 2.7 warwick +4 -20 +src/kernel/qwidcoll.h 2.6 warwick +3 -14 + + Broken in rename. + + +src/kernel/qobjcoll.h 2.8 warwick +1 -1 +src/kernel/qwidcoll.h 2.7 warwick +1 -1 + + Moved. + + +src/kernel/qpainter.cpp 2.51 warwick +2 -2 + + Improve robustness. + + +src/kernel/qprinter_x11.cpp 2.15 agulbra +2 -1 +src/kernel/qprn_x11.cpp 2.15 agulbra +2 -1 + + #include ; necessary for some unixes + + +src/kernel/qwidget.cpp 2.110 agulbra +2 -2 + + make tab focus change work (at all!) in dialogs + + +src/tools/qfileinf.cpp 2.10 agulbra +17 -8 +src/tools/qfileinfo.cpp 2.10 agulbra +17 -8 + + double the speed of isSymLink() (and hence the file dialog's repaint) + in one easy change. + + +src/tools/qgdict.cpp 2.15 warwick +2 -2 + + 64-bit pointer to long fix. + + +src/tools/qstring.cpp 2.20 warwick +2 -2 + + Obscure safety improvement. + + +src/widgets/qcombo.cpp 2.86 agulbra +2 -2 +src/widgets/qcombobox.cpp 2.86 agulbra +2 -2 +src/widgets/qlabel.cpp 2.31 agulbra +2 -2 + + fix logic to decide when to locate the listbox above the combo itself + instead of below. + + +src/widgets/qheader.cpp 2.43 agulbra +2 -3 + + remove a "this should not happen" debug() because that situation + should happen. can happen, anyway. + + +src/widgets/qlined.cpp 2.80 warwick +24 -6 +src/widgets/qlined.h 2.27 warwick +2 -1 +src/widgets/qlineedit.cpp 2.80 warwick +24 -6 +src/widgets/qlineedit.h 2.27 warwick +2 -1 +src/widgets/qmlined.cpp 2.92 warwick +36 -7 +src/widgets/qmlined.h 2.35 warwick +2 -1 +src/widgets/qmultilined.cpp 2.92 warwick +36 -7 +src/widgets/qmultilined.h 2.35 warwick +2 -1 + + Make WindowsStyle under X11 still meet the X11 user's expectations + regarding auto-copy, while allowing the highlight-and-paste action + familiar to Windows users. A compromise. + + Also make qmlined more similar to qlined. + + +src/widgets/qlistbox.cpp 2.68 warwick +2 -2 + + Use maximumSize() correctly. + (fixes kdisplay background problem) + + +src/widgets/qlistview.cpp 2.116 agulbra +25 -12 + + tweak mouse state machine a little. make it harder to select a + non-selectable item. doc fixes. + + +src/widgets/qmainwindow.cpp 2.25 agulbra +3 -5 +src/widgets/qmainwindow.cpp 2.24 agulbra +245 -26 +src/widgets/qmainwindow.h 2.15 agulbra +2 -1 + + if a dock contained only hidden toolbars, layout would be wrong. + also contains ifdef-ed out broken docking code. + + +src/widgets/qmainwindow.cpp 2.26 warwick +3 -1 +src/widgets/qsplitter.cpp 1.15 warwick +3 -1 +src/widgets/qstatusbar.cpp 2.13 warwick +3 -1 + + New documentation images. + + +src/widgets/qmainwindow.h 2.16 agulbra +2 -3 + + setRightJustification is now a slot + + +src/widgets/qmenudata.cpp 2.15 warwick +4 -2 +src/widgets/qmenudta.cpp 2.15 warwick +4 -2 + + Warning about setCheckable in setItemChecked. + + +src/widgets/qpopmenu.cpp 2.76 warwick +4 -9 +src/widgets/qpopupmenu.cpp 2.76 warwick +4 -9 + + Fix "need more than one off-menu click to cancel" bug. + Make Escape only pop down one popup (as per Windows and Motif). + + +src/widgets/qpopmenu.cpp 2.77 warwick +4 -2 +src/widgets/qpopupmenu.cpp 2.77 warwick +4 -2 + + Correct drop-down-on-no-selection behaviour. + + +src/widgets/qspinbox.cpp 2.33 agulbra +5 -7 + + minor changes; this really need to take the validator into + consideration when the user has typed but I can't fix that now. + + +src/widgets/qspinbox.cpp 2.34 agulbra +18 -3 +src/widgets/qspinbox.h 2.19 agulbra +3 -1 + + handle setEnabled() correctly + + +src/widgets/qsplitter.cpp 1.14 paul +10 -10 + + Fixed off-by-one error + + +src/widgets/qtabbar.h 2.11 agulbra +2 -1 + + one variable wasn't initialized. initialize it. + + +src/widgets/qtooltip.cpp 2.46 agulbra +3 -3 + + stay up for ten seconds, not four. + + +src/widgets/qvalidator.cpp 2.20 agulbra +7 -4 + + "-" is a valid state for both validator; allows typing of -42 in the + natural way if -42 is valid. + diff --git a/dist/changes-1.39-19980623 b/dist/changes-1.39-19980623 new file mode 100644 index 0000000..0a40bf9 --- /dev/null +++ b/dist/changes-1.39-19980623 @@ -0,0 +1,545 @@ +doc/annotated.doc 1.5 warwick +6 -3 + + Try new tabled annotated list. + + +doc/tutorial.doc 2.14 agulbra +4 -4 + + new header files + + +examples/application/application.cpp 1.13 warwick +2 -2 +examples/layout/layout.cpp 1.7 warwick +2 -2 +examples/network/finger.cpp 1.8 warwick +2 -2 +examples/pref/pref.cpp 1.21 warwick +2 -2 +examples/qwerty/qwerty.h 1.9 warwick +2 -2 +examples/scrollview/scrollview.cpp 1.16 warwick +2 -2 +examples/widgets/widgets.cpp 2.44 warwick +2 -2 +src/widgets/qmultilinedit.cpp 2.94 warwick +2 -2 + + Rename fix - "qmultilinedit.h" not "qmultilined.h" + + +examples/application/application.cpp 1.14 agulbra +32 -18 + + use QWhatsThis + + +examples/application/application.cpp 1.15 warwick +7 -6 +examples/application/application.h 1.5 warwick +2 -1 + + Use persistent QPrinter. + + +examples/dragdrop/.cvsignore 1.1 warwick initial checkin +examples/dragdrop/dragdrop.pro 1.1 warwick initial checkin +examples/dragdrop/main.cpp 1.6 warwick +20 -7 +src/qt.pro 2.28 warwick +3 -3 + + upd + + +examples/dragdrop/GNUmakefile 1.1 warwick initial checkin +examples/dragdrop/Makefile 1.1 warwick initial checkin +examples/dragdrop/main.cpp 1.2 warwick +2 -1 + + Quit. + + +examples/dragdrop/dropsite.cpp 1.1 agulbra initial checkin +examples/dragdrop/dropsite.h 1.1 agulbra initial checkin +examples/dragdrop/main.cpp 1.1 agulbra initial checkin + + kind of like simple.c, except not 2000 lines + + +examples/dragdrop/dropsite.cpp 1.2 warwick +22 -3 +examples/dragdrop/main.cpp 1.3 warwick +3 -3 + + Fixes, more debug options. + + +examples/dragdrop/dropsite.cpp 1.3 warwick +36 -34 +examples/dragdrop/main.cpp 1.4 warwick +2 -2 + + Better feedback, more examples. + + +examples/dragdrop/dropsite.cpp 1.4 warwick +5 -3 + + Visualize DragLeave events. + + +examples/dragdrop/dropsite.cpp 1.5 warwick +15 -43 +examples/dragdrop/dropsite.h 1.2 warwick +1 -7 +examples/dragdrop/main.cpp 1.5 warwick +2 -10 + + Remove format choice - QImageDragObject deals with that. + + +examples/dragdrop/dropsite.cpp 1.6 warwick +4 -5 +src/kernel/qdragobject.cpp 2.25 warwick +11 -6 +src/kernel/qdragobject.h 2.12 warwick +3 -2 + + Set MIME format in QStoredDragObject constructor. + + +examples/dragdrop/dropsite.cpp 1.7 warwick +10 -3 +examples/dragdrop/dropsite.h 1.3 warwick +2 -1 + + Use Event_DragEnter + + +examples/movies/main.cpp 1.12 warwick +4 -4 + + Warnings, robustness. + + +examples/showimg/.cvsignore 2.1 warwick +5 -0 + + Ignore images + + +extensions/nsplugin/examples/Makefile 1.1 warwick initial checkin +extensions/xt/doc.conf 1.4 warwick +1 -1 + + Oddsnends + + +extensions/nsplugin/src/qnp.cpp 1.20 warwick +19 -20 + + show() not required now. + + +extensions/nsplugin/src/qnp.pro 1.2 warwick +1 -1 + + tmake workaround + + +src/compat/qmlined.h 1.2 warwick +1 -1 + + edit not ed + + +src/compat/qobjcoll.h 1.1 warwick initial checkin +src/compat/qwidcoll.h 1.1 warwick initial checkin +src/kernel/qobjcoll.h 2.8 warwick +1 -1 +src/kernel/qwidcoll.h 2.7 warwick +1 -1 + + Moved. + + +src/dialogs/qfiledialog.cpp 2.72 agulbra +79 -54 + + avoid one more static + + +src/dialogs/qfiledialog.cpp 2.73 agulbra +3 -3 + + use the right column width in multi-column mode + + +src/dialogs/qfiledialog.cpp 2.74 agulbra +1 -2 + + commit -without- debug feature + + +src/dialogs/qfiledialog.cpp 2.75 agulbra +22 -8 + + handle "type name of directory then press enter" case by switching to + that directory + + +src/dialogs/qfiledialog.cpp 2.76 agulbra +10 -7 + + minor tweak to make the ok button change less often + + +src/dialogs/qfiledialog.cpp 2.77 agulbra +2 -2 + + slightly better row height in the multi-column view + + +src/kernel/qapp.cpp 2.56 agulbra +14 -6 +src/kernel/qapplication.cpp 2.56 agulbra +14 -6 +src/kernel/qasyncimageio.cpp 1.34 agulbra +53 -15 +src/kernel/qregion.cpp 2.13 agulbra +1 -8 +src/kernel/qregion.h 2.13 agulbra +1 -4 +src/widgets/qheader.cpp 2.44 agulbra +4 -5 + + Reginald Stadlbauer's alpha's egcs said to do this. it doesn't like + static objects with non-default constructors. + + +src/kernel/qapplication_win.cpp 2.91 warwick +10 -1 +src/kernel/qdnd_x11.cpp 2.20 warwick +1 -7 +src/kernel/qdragobject.h 2.9 warwick +1 -4 +src/kernel/qwidget.cpp 2.112 warwick +4 -11 +src/kernel/qwidget_win.cpp 2.57 warwick +20 -3 +src/kernel/qwidget_x11.cpp 2.97 warwick +12 -4 +src/kernel/qwindowdefs.h 2.24 warwick +5 -1 + + Drag&dropery. + + +src/kernel/qapplication_win.cpp 2.93 warwick +4 -2 +src/kernel/qdnd_win.cpp 2.10 warwick +483 -135 +src/kernel/qdnd_x11.cpp 2.24 warwick +21 -1 +src/kernel/qdragobject.cpp 2.18 warwick +5 -5 +src/kernel/qevent.cpp 2.17 warwick +1 -21 +src/kernel/qimage.cpp 2.93 warwick +73 -34 +src/kernel/qwidget_win.cpp 2.59 warwick +4 -3 + + Windows Drap & Drop. + + +src/kernel/qasyncimageio.cpp 1.35 agulbra +2 -2 + + make cleanup() static + + +src/kernel/qasyncimageio.cpp 1.37 warwick +4 -2 +src/kernel/qasyncimageio.cpp 1.36 warwick +30 -7 +src/kernel/qdragobject.cpp 2.22 warwick +7 -5 +src/kernel/qimage.cpp 2.96 warwick +4 -1 +src/kernel/qimage.cpp 2.95 agulbra +8 -9 +src/kernel/qimage.cpp 2.92 warwick +3 -3 +src/tools/qdir.cpp 2.24 agulbra +7 -1 + + doc + + +src/kernel/qclipboard_x11.cpp 2.14 agulbra +26 -20 + + avoid statics that are troublesome on the alpha + + +src/kernel/qdialog.cpp 2.20 agulbra +39 -18 + + frameGeometry() is normally not meaningful before show(), so I + switched to a different way of ensuring that the dialog's default + position is entirely on-screen. may not work perfectly with + Enlightenment :) + + +src/kernel/qdnd_win.cpp 2.11 warwick +5 -1 +src/kernel/qdnd_x11.cpp 2.25 warwick +56 -1 +src/kernel/qdragobject.cpp 2.19 warwick +8 -59 + + Move QDragManager::eventFilter code to X11-specifics. + + +src/kernel/qdnd_win.cpp 2.12 warwick +44 -31 + + Follow DnD API changes. + Add leave event. + + +src/kernel/qdnd_win.cpp 2.13 warwick +8 -3 +src/kernel/qevent.h 2.19 warwick +15 -5 + + DragEnter events and final DragLeave to DropEvent targets. + + +src/kernel/qdnd_win.cpp 2.14 warwick +2 -6 + + spacing + + +src/kernel/qdnd_win.cpp 2.7 warwick +989 -12 + + First inclusion from tests/olednd code. + + +src/kernel/qdnd_win.cpp 2.9 warwick +162 -98 + + DND. + + +src/kernel/qdnd_x11.cpp 2.17 warwick +9 -9 +src/kernel/qpainter.cpp 2.52 warwick +14 -11 +src/kernel/qwid_x11.cpp 2.95 warwick +2 -2 +src/kernel/qwidget_x11.cpp 2.95 warwick +2 -2 +src/widgets/qwellarray.cpp 1.3 warwick +10 -1 +src/widgets/qwellarray.h 1.4 warwick +2 -1 + + Avoid HPUX warnings. + + +src/kernel/qdnd_x11.cpp 2.19 agulbra +29 -25 + + egcs/alpha workarounds. + + +src/kernel/qdnd_x11.cpp 2.22 agulbra +2 -2 +src/kernel/qwidget_x11.cpp 2.98 agulbra +2 -2 + + don't segfault on first registerDropType() + + +src/kernel/qdnd_x11.cpp 2.23 paul +5 -3 + + Ignore windows without clients. + + +src/kernel/qdnd_x11.cpp 2.26 warwick +18 -1 +src/kernel/qdragobject.cpp 2.20 warwick +1 -16 + + Move DND cursor into X11-specifics. + + +src/kernel/qdnd_x11.cpp 2.27 warwick +16 -10 +src/kernel/qdragobject.cpp 2.23 warwick +130 -71 +src/kernel/qdragobject.h 2.11 warwick +14 -25 + + Multi-format QDragObject API. + + +src/kernel/qdnd_x11.cpp 2.28 agulbra +47 -18 + + updated to match windows version + + +src/kernel/qdragobject.cpp 2.21 warwick +99 -14 +src/kernel/qdragobject.h 2.10 warwick +45 -3 + + QImageDragObject + Mark out problem areas for fixing. + + +src/kernel/qdragobject.cpp 2.24 agulbra +2 -2 +src/kernel/qlayout.cpp 2.35 agulbra +3 -3 +src/kernel/qpixmapcache.cpp 2.8 agulbra +2 -1 +src/tools/qgcache.cpp 2.7 agulbra +12 -8 +src/widgets/qpushbutton.cpp 2.43 agulbra +3 -3 + + speling + + +src/kernel/qdragobject.cpp 2.26 warwick +9 -17 +src/kernel/qdragobject.h 2.13 warwick +3 -4 + + Simplify QStoredDragObject. + + +src/kernel/qevent.h 2.20 agulbra +9 -3 + + added no-answer-necessary rectangle to drag move event + + +src/kernel/qfocusdata.h 2.3 warwick +11 -3 +src/widgets/qscrollview.cpp 2.48 warwick +12 -7 +src/widgets/qscrollview.cpp 2.47 warwick +6 -4 + + Focus wrapping. + + +src/kernel/qfont.cpp 2.36 agulbra +19 -7 + + more alpha/egcs/linux workarounds + + +src/kernel/qfont_x11.cpp 2.40 warwick +3 -3 + + Go gray. + + +src/kernel/qimage.cpp 2.94 warwick +22 -1 +src/kernel/qimage.h 2.28 warwick +2 -1 +src/kernel/qpixmap.cpp 2.27 warwick +24 -1 +src/kernel/qpixmap.h 2.21 warwick +5 -2 + + Convenient input from QByteArray. + + +src/kernel/qimage.cpp 2.97 warwick +2 -2 +src/kernel/qpixmap.cpp 2.28 warwick +2 -2 + + Fix. + + +src/kernel/qmovie.cpp 1.34 warwick +11 -2 + + Code to be added and tested later. + + +src/kernel/qmovie.cpp 1.35 warwick +5 -9 +src/kernel/qmovie.h 1.11 warwick +3 -2 + + Provide QDataSource source to QMovie. + + +src/kernel/qobjcoll.h 2.7 warwick +4 -20 +src/kernel/qwidcoll.h 2.6 warwick +3 -14 + + Broken in rename. + + +src/kernel/qprinter_x11.cpp 2.17 agulbra +4 -3 + + roll back to 1.33 version + + +src/kernel/qwidget.cpp 2.113 paul +3 -2 + + Send queued-up childEvents before the first resize event + + +src/kernel/qwidget.h 2.51 warwick +3 -1 + + Separate sys-dep extra data create/delete. + + +src/qt.pro 2.27 warwick +1 -0 +src/dialogs/qfiledlg.cpp 2.72 warwick +2 -1 +src/kernel/qapplication_win.cpp 2.92 warwick +4 -4 +src/kernel/qdnd_win.cpp 2.8 warwick +115 -505 +src/kernel/qdnd_x11.cpp 2.21 warwick +2 -2 +src/kernel/qevent.h 2.18 warwick +2 -2 +src/kernel/qwidget_win.cpp 2.58 warwick +3 -1 + + Drag&Dropery. + + +src/qt.pro 2.29 warwick +2 -0 +src/kernel/qfocusdata.cpp 2.1 warwick initial checkin +src/kernel/qfocusdata.h 2.4 warwick +6 -12 +src/kernel/qwidget.cpp 2.114 warwick +3 -1 +src/widgets/qscrollview.cpp 2.49 warwick +5 -8 + + Make QFocusData clean and public. + + +src/tools/qdir.cpp 2.23 agulbra +2 -2 + + avoid a static. saves some memory. + + +src/tools/qglobal.cpp 2.16 agulbra +6 -4 + + void statics + + +src/widgets/qbutton.cpp 2.62 agulbra +5 -9 + + emit toggled() and clicked() even if this is a toggle button and will + not toggle off. + + +src/widgets/qbutton.cpp 2.63 agulbra +4 -4 + + correct toggling-when-in-group behaviour + + +src/widgets/qheader.cpp 2.46 paul +4 -4 + + Fix off by one error that caused "index out of range". + + +src/widgets/qlistview.cpp 2.118 agulbra +19 -12 + + much faster scrolling in unsorted mode; use about half as much memory + per item; free the items properly + + +src/widgets/qlistview.cpp 2.119 agulbra +2 -2 + + unsort/sort correctly + + +src/widgets/qlistview.cpp 2.120 agulbra +3 -3 + + finalize QListViewItem in the right way + + +src/widgets/qlistview.cpp 2.121 agulbra +35 -17 + + cut memory usage by another fifty per cent in the common case. QLVI + now uses 150-200 bytes of memory, down from ~800 last week. + + default to the correct height (including itemMargin()). + + change itemMargin default to one pixel, from two. + + use itemMargin both on the left and on the right edge of each column. + + ensure that children are sorted correctly in QLV::firstChild(), as + they are in QLVI::firstChild(). + + +src/widgets/qlistview.h 2.51 agulbra +2 -2 + + make setItemMargin() virtual. who put in a non-virtual setter + function? + + +src/widgets/qmenudata.cpp 2.17 agulbra +8 -6 + + DWIM: call setCheckable() in setItemChecked() if necessary + + +src/widgets/qmultilinedit.h 2.37 warwick +3 -3 + + EDIT, not ED. + + +src/widgets/qpopupmenu.cpp 2.79 warwick +2 -4 + + Roll-back my menu-stays-up "fix". + + +src/widgets/qpopupmenu.cpp 2.80 warwick +7 -2 + + Worse but better fix for allow both popup and pulldown/pushup menus. + + +src/widgets/qpushbutton.cpp 2.42 agulbra +16 -57 + + use alternative (windows-like) motif indication of default button + status, rather than the nextstep/xforms/gtk-like indication. + + +src/widgets/qsplitter.cpp 1.17 paul +6 -5 +src/widgets/qsplitter.h 1.9 paul +3 -2 + + Changed QSplitter::setFixed() to start counting at 0 instead of 1. + + *** WILL BREAK OLD CODE *** + + Also introduced FirstWidget and SecondWidget enum values to make setFixed() + calls more readable. + + +src/widgets/qsplitter.cpp 1.18 paul +160 -141 +src/widgets/qsplitter.h 1.10 paul +16 -17 + + Reworked QSplitter API. Splitter now detects its children, addFirstWidget etc + disappears. + *** WILL BREAK OLD CODE *** + + +src/widgets/qtooltip.cpp 2.48 agulbra +4 -4 + + tweak periods a bit + + +src/widgets/qtooltip.cpp 2.49 agulbra +4 -3 + + paranoia fix: don't let buggy programs introduce an infinte loop by + calling tip() with the "wrong" rectangle. + + +src/widgets/qwidgetstack.cpp 2.8 agulbra +4 -1 +src/widgets/qwidgetstack.h 2.5 agulbra +5 -1 + + aboutToShow() + + +src/widgets/qwidgetstack.cpp 2.9 agulbra +69 -12 +src/widgets/qwidgetstack.h 2.6 agulbra +4 -2 + + added decent docs. + added a visibleWidget() access function + added an aboutToShow() signal. + fixed "value of NaN" bug (0 vs. -1) + diff --git a/dist/changes-1.39-19980625 b/dist/changes-1.39-19980625 new file mode 100644 index 0000000..c71578f --- /dev/null +++ b/dist/changes-1.39-19980625 @@ -0,0 +1,119 @@ + +examples/application/application.cpp 1.14 agulbra +32 -18 + + use QWhatsThis + + +examples/application/application.cpp 1.15 warwick +7 -6 +examples/application/application.h 1.5 warwick +2 -1 + + Use persistent QPrinter. + + +examples/dragdrop/dropsite.cpp 1.8 warwick +44 -24 + + Improved usage #1. + + +examples/dragdrop/dropsite.cpp 1.9 warwick +36 -81 +examples/dragdrop/dropsite.h 1.4 warwick +7 -9 +src/qt.pro 2.30 warwick +2 -0 +src/kernel/qclipboard_x11.cpp 2.15 warwick +10 -8 +src/kernel/qdnd_win.cpp 2.15 warwick +1 -18 +src/kernel/qdnd_x11.cpp 2.33 warwick +62 -67 +src/kernel/qdragobject.cpp 2.29 warwick +73 -27 +src/kernel/qdragobject.h 2.16 warwick +18 -12 +src/kernel/qdropsite.cpp 2.1 warwick initial checkin +src/kernel/qdropsite.h 2.1 warwick initial checkin +src/kernel/qwidget.h 2.52 warwick +3 -2 +src/kernel/qwidget_win.cpp 2.60 warwick +17 -7 +src/kernel/qwidget_x11.cpp 2.99 warwick +22 -12 +src/kernel/qwindowdefs.h 2.25 warwick +7 -3 +src/widgets/qlineedit.cpp 2.85 warwick +3 -3 + + Don't declare MIME types for drop sites in advance, just enable drops. + + +examples/examples.pro 2.9 agulbra +1 -0 + + add dragdrop to examples makefile + + +examples/movies/main.cpp 1.13 agulbra +9 -2 + + add use of setFilters(). + + +examples/splitter/splitter.cpp 1.1 paul initial checkin +examples/splitter/splitter.pro 1.1 paul initial checkin + + Simple QSplitter example + + +src/dialogs/qprintdialog.cpp 2.29 warwick +57 -60 + + Fixed QPrinter->QPrintDialog state-transfer bugs. + + +src/kernel/qapplication_x11.cpp 2.142 agulbra +7 -12 +src/kernel/qdnd_x11.cpp 2.37 agulbra +22 -23 +src/kernel/qdragobject.cpp 2.32 agulbra +5 -25 +src/kernel/qdragobject.h 2.19 agulbra +1 -4 + + Completely reworked drag'n'drop. + + +src/kernel/qimage.cpp 2.99 agulbra +7 -6 +src/kernel/qimage.cpp 2.98 agulbra +18 -14 +src/kernel/qmovie.cpp 1.38 agulbra +8 -7 +src/kernel/qmovie.cpp 1.37 agulbra +12 -3 + + discuss patent issues + + +src/widgets/qlineedit.cpp 2.82 agulbra +2 -3 + + reject drags that don't provide text/plain + + +src/widgets/qlistview.cpp 2.122 warwick +3 -3 + + Fix multiple-calls-to-setText() unreported bug. + + +src/widgets/qlistview.cpp 2.123 paul +16 -21 +src/widgets/qlistview.h 2.52 paul +2 -2 + + Make setPixmap() override default pixmap + + +src/widgets/qlistview.cpp 2.124 agulbra +16 -17 + + adjust drawing of focus rectangle for trees + + +src/widgets/qlistview.cpp 2.126 agulbra +1 -2 +src/widgets/qlistview.cpp 2.125 agulbra +6 -2 + + try even harder to not sort unless sorting is actually requested. + + +src/widgets/qmultilinedit.cpp 2.95 agulbra +4 -4 + + doc correction + + +src/widgets/qsplitter.cpp 1.19 paul +48 -45 + + fixing odds and ends after the API change + + +src/widgets/qsplitter.cpp 1.23 warwick +5 -4 + + Position internalsplitter in middle of mouse when dragging. + + +src/widgets/qsplitter.cpp 1.24 warwick +48 -45 + + Make bitmaps correspond to splitter dimensions. + diff --git a/dist/changes-1.39-19980706 b/dist/changes-1.39-19980706 new file mode 100644 index 0000000..80e814a --- /dev/null +++ b/dist/changes-1.39-19980706 @@ -0,0 +1,320 @@ +doc/indices.doc 2.17 agulbra +4 -4 +doc/misc.doc 2.29 agulbra +4 -4 +doc/qcache.doc 2.4 agulbra +598 -304 +doc/qdict.doc 2.5 agulbra +4 -3 + + documented QCache/QIntCache and the iterators, fixed some types + + +doc/indices.doc 2.18 agulbra +7 -7 +extensions/imageio/doc/index.doc 1.6 agulbra +3 -3 +extensions/nsplugin/doc/annotated.doc 1.2 agulbra +2 -2 +extensions/nsplugin/doc/classes.doc 1.2 agulbra +2 -2 +extensions/opengl/src/qgl.cpp 1.20 agulbra +5 -6 +extensions/xt/doc/annotated.doc 1.2 agulbra +2 -2 +extensions/xt/doc/classes.doc 1.2 agulbra +2 -2 +src/tools/qtextstream.cpp 2.16 agulbra +1 -2 + + finished merge of qt/extensions documentation in one directory. + + +doc/indices.doc 2.20 aavit +3 -3 +doc/qcache.doc 2.8 aavit +9 -1 +examples/application/application.cpp 1.16 aavit +17 -17 +examples/widgets/widgets.cpp 2.45 aavit +29 -5 +extensions/nsplugin/src/qnp.cpp 1.22 aavit +5 -5 +extensions/opengl/doc.conf 1.14 aavit +7 -0 +extensions/opengl/src/qgl.cpp 1.23 aavit +4 -4 +extensions/xt/doc/index.doc 1.4 aavit +18 -8 +extensions/xt/src/qxt.cpp 1.5 aavit +3 -3 +src/dialogs/qmessagebox.cpp 2.50 aavit +5 -5 + + Improved doc of extensions. + + +doc/qcache.doc 2.9 aavit +47 -8 + + Documented the remaining functions in qcache et al. + + +examples/dragdrop/dropsite.cpp 1.12 paul +76 -22 +examples/dragdrop/dropsite.h 1.5 paul +14 -2 +examples/dragdrop/main.cpp 1.7 paul +8 -3 + + How to make your own dragobject class + + +examples/dragdrop/dropsite.cpp 1.9 warwick +36 -81 +examples/dragdrop/dropsite.h 1.4 warwick +7 -9 +src/qt.pro 2.30 warwick +2 -0 +src/kernel/qclipboard_x11.cpp 2.15 warwick +10 -8 +src/kernel/qdnd_win.cpp 2.15 warwick +1 -18 +src/kernel/qdnd_x11.cpp 2.33 warwick +62 -67 +src/kernel/qdragobject.cpp 2.29 warwick +73 -27 +src/kernel/qdragobject.h 2.16 warwick +18 -12 +src/kernel/qdropsite.cpp 2.1 warwick initial checkin +src/kernel/qdropsite.h 2.1 warwick initial checkin +src/kernel/qwidget.h 2.52 warwick +3 -2 +src/kernel/qwidget_win.cpp 2.60 warwick +17 -7 +src/kernel/qwidget_x11.cpp 2.99 warwick +22 -12 +src/kernel/qwindowdefs.h 2.25 warwick +7 -3 +src/widgets/qlineedit.cpp 2.85 warwick +3 -3 + + Don't declare MIME types for drop sites in advance, just enable drops. + + +examples/examples.pro 2.10 hanord +1 -0 + + Added splitter + + +examples/examples.pro 2.9 agulbra +1 -0 + + add dragdrop to examples makefile + + +examples/layouts/layouts.cpp 1.6 aavit +2 -3 + + return value from main to avoid compiler warning + + +extensions/nsplugin/src/qnp.cpp 1.21 agulbra +34 -24 +extensions/opengl/src/qgl.cpp 1.22 agulbra +7 -1 +extensions/xt/src/qxt.cpp 1.4 agulbra +6 -2 + + use new \extension in qdoc + + +src/dialogs/qprintdialog.cpp 2.30 aavit +2 -2 +src/widgets/qspinbox.cpp 2.36 aavit +22 -29 +src/widgets/qspinbox.h 2.21 aavit +1 -3 + + spinbox: better looking in windows mode (more like win32) + + +src/kernel/qapplication_x11.cpp 2.142 agulbra +7 -12 +src/kernel/qdnd_x11.cpp 2.37 agulbra +22 -23 +src/kernel/qdragobject.cpp 2.32 agulbra +5 -25 +src/kernel/qdragobject.h 2.19 agulbra +1 -4 + + protect another little bit against the other application crashing + + +src/kernel/qclipboard_x11.cpp 2.16 agulbra +2 -2 + + avoid double delete in certain cases. would cause segfault. + + +src/kernel/qdnd_win.cpp 2.16 warwick +98 -59 +src/kernel/qdropsite.cpp 2.2 warwick +3 -3 +src/kernel/qwidget_win.cpp 2.61 warwick +1 -2 + + Update for X11 changes. + + +src/kernel/qdnd_win.cpp 2.17 warwick +22 -5 +src/kernel/qdnd_x11.cpp 2.36 warwick +5 -3 +src/kernel/qdragobject.cpp 2.30 warwick +63 -7 +src/kernel/qdragobject.h 2.17 warwick +10 -3 + + Renaming; make space in API for Copy vs. Move + + +src/kernel/qdnd_x11.cpp 2.32 agulbra +13 -12 +src/kernel/qdnd_x11.cpp 2.31 agulbra +33 -8 + + support accept/ignore rectangles properly. + + +src/kernel/qdnd_x11.cpp 2.34 agulbra +7 -2 +src/widgets/qlineedit.cpp 2.86 agulbra +13 -13 + + isAccepted() of one drag enter/move is the default state for the next + (until the target changes). + + +src/kernel/qdnd_x11.cpp 2.35 warwick +20 -13 + + Fix lost-leaves. + + +src/kernel/qdnd_x11.cpp 2.38 agulbra +23 -22 + + always give the right cursor + + +src/kernel/qdnd_x11.cpp 2.39 hanord +2 -2 + + Patch from Bernd Unger to compile on irix-n64 + + +src/kernel/qdnd_x11.cpp 2.40 hanord +5 -5 +src/widgets/qheader.cpp 2.47 hanord +5 -5 +src/widgets/qstatusbar.cpp 2.15 hanord +12 -12 +src/widgets/qtoolbar.cpp 2.24 hanord +14 -15 +src/widgets/qtoolbutton.cpp 2.29 hanord +4 -4 +src/widgets/qwellarray.cpp 1.5 hanord +8 -10 + + Removed Sun CC warnings. All these warnings come from use of local + variables inside member functions clashing with private variable names + in the class. I think this is a correct warning, because if somebody + wants to access a private variable from a member function where it's + already used as a local variable, he will be somewhat confused. + + +src/kernel/qdragobject.cpp 2.34 hanord +3 -2 + + Avoid array-bounds error when copying text + + +src/kernel/qdragobject.cpp 2.35 hanord +15 -18 +src/kernel/qdragobject.h 2.20 hanord +7 -7 + + QStoredDrag::setEncodedData takes a const byte array. + parent changed to dragSource everywhere. + + +src/kernel/qimage.cpp 2.102 agulbra +9 -5 +src/kernel/qpixmap.cpp 2.31 agulbra +22 -32 + + mention the QPixmap/QImage differences prominently. other minor doc + changes. + + +src/kernel/qimage.cpp 2.99 agulbra +7 -6 +src/kernel/qimage.cpp 2.98 agulbra +18 -14 +src/kernel/qmovie.cpp 1.38 agulbra +8 -7 +src/kernel/qmovie.cpp 1.37 agulbra +12 -3 + + warn about unisys $#@! and about possible removal of gif support in a + future version of qt. + + +src/kernel/qpainter_win.cpp 2.38 hanord +2 -3 +src/kernel/qpainter_x11.cpp 2.53 hanord +2 -3 + + Fixed UMR in drawText to external device. Could be serious and crash. + + +src/kernel/qprinter_x11.cpp 2.18 agulbra +38 -11 + + OS/2 fixes from miyata. + + +src/kernel/qpsprinter.cpp 2.28 agulbra +67 -19 + + oops. we broke kmail by not supporting QFont::AnyCharSet at all. + fixed. + + also contains two other fixes that I'd delayed committing: use + colorimage only where available, else image. produce 78-character + lines, not lines of several thousand characters. + + +src/kernel/qpsprinter.cpp 2.29 agulbra +49 -28 + + make the dicts slightly bigger so more level 1 printers are happy. + avoid a memory leak in drawPixmap(). + + +src/kernel/qwidget.cpp 2.116 hanord +2 -2 + + Does destroy() AFTER deleteExtra(), because deleteExtra() calls + deleteSysExtra() which unregisters OLE stuff on Windows (and needs the Win + ID). + + +src/moc/moc.1 2.7 hanord +11 -3 +src/moc/moc.l 2.3 hanord +57 -7 +src/moc/moc.y 2.24 hanord +22 -12 + + Warwick's support for #ifdef and #ifndef added + + +src/qt.pro 2.33 hanord +8 -7 + + Changed DEPENDPATH to relative, makes makefiles movable. + Sorted a couple of filenames. + + +src/qt.pro 2.34 hanord +1 -1 + + Changed version number to 1.40 + + +src/tools/qglobal.h 2.53 agulbra +3 -3 + + 1.40. yes it's true. + + +src/tools/qglobal.h 2.55 agulbra +3 -3 + + make one final snapshot + + +src/widgets/qbuttongroup.cpp 2.14 agulbra +3 -3 + + roll back my "don't delete twice" fix: it was a "don't delete once" + fix, in fact. oops. + + +src/widgets/qheader.cpp 2.49 agulbra +2 -1 + + memory leak gone + + +src/widgets/qlabel.cpp 2.34 agulbra +6 -9 + + respect buddy's focus policy and other accessibility. + + +src/widgets/qlineedit.cpp 2.83 agulbra +4 -4 + + use enter event and accept drops in the entire rectangle. + + +src/widgets/qlineedit.cpp 2.84 agulbra +8 -1 + + ...and the drop should happen in the right place. oooh, this is so + polished :) + + +src/widgets/qlineedit.cpp 2.88 agulbra +2 -2 + + avoid memory leak when dragging out of qle + + +src/widgets/qlineedit.cpp 2.89 agulbra +5 -1 + + #ifdef out dnd support. it works on x11, not quite on windows. + besides, having QLineEdit work differently from typical windows + widgets and cannot be changed is a bad policy. + + +src/widgets/qlistview.cpp 2.129 agulbra +3 -2 + + don't accept() enter/return key presses. qdialog. + + +src/widgets/qlistview.cpp 2.130 agulbra +8 -9 + + avoid a couple of memory leaks + + +src/widgets/qprogressbar.cpp 2.21 aavit +10 -1 +src/widgets/qtableview.cpp 2.51 aavit +2 -2 + + Progressbar: allow changing of guistyle before show(). Should really + implement styleChanged(); in 2.0. + Tableview: Avoid infinite loop. + + +src/widgets/qspinbox.cpp 2.38 aavit +2 -2 +src/widgets/qwidgetstack.cpp 2.11 aavit +13 -9 + + Widgetstack: be robust when got no children. spinbox: comment + + +src/widgets/qsplitter.cpp 1.24 warwick +48 -45 + + Make bitmaps correspond to splitter dimensions. diff --git a/dist/changes-1.40 b/dist/changes-1.40 new file mode 100644 index 0000000..1f5f986 --- /dev/null +++ b/dist/changes-1.40 @@ -0,0 +1,291 @@ +Here is a list of user-visible changes in Qt from 1.33 to 1.40. + +Qt 1.40 supports drag and drop, with a simple, platform independent +API. There are eleven new widget classes in 1.40. Asynchronous I/O +support is now in the official Qt API. + +Since Qt no longer supports any platforms that only supports 8.3 +format file names, the file names of the Qt source and include files +have been made simpler. #include instead of qcombo.h, +etc. The old names are still present for compatibility. + +The new Qt Xt/Motif Extension allows Qt widgets and applications to +coexist with old Xt/Motif-based applications and widgets. + +There are more than one hundred new functions added to existing +classes and, as usual, we fixed some bugs, made some more speedups, +and improved the documentation. + + +**************************************************************************** +* New classes * +**************************************************************************** + +* New widgets + + QHeader - Table header + QListView - Multicolun listview/treeview + QMainWindow - Application main window + QScrollView - Scrolling area (successor of QwViewPort) + QSpinBox - Spin button + QSplitter - Paned window + QStatusBar - Status bar + QToolBar - Container for tool buttons (and other widgets) + QToolButton - Fancy push button with auto-raise + QWhatsThis - Light weight help system + QWidgetStack - Stack of widgets + +* Support classes + + QFileIconProvider - Provides icons for the file dialog + QIconSet - Set of icons for different states + QListViewItem - Content of a QListView + QCheckListItem - Checkable list view item + +* Drag and drop related classes + + QDragObject + QStoredDrag + QTextDrag + QImageDrag + QDragManager + QDropSite + +* Asynchronous I/O + + QAsyncIO + QDataPump + QDataSink + QDataSource + QDataStream + QIODeviceSource + QImageConsumer + QImageDecoder + QImageFormat + QImageFormatType + + +* New Events + + QShowEvent + QHideEvent + QDragMoveEvent + QDragEnterEvent + QDragResponseEvent + QDragLeaveEvent + QDropEvent + QChildEvent + + + +**************************************************************************** +* Enhancements from 1.33 to 1.40 * +**************************************************************************** + +The file and print dialogs are far better. + +Layouts will now automatically readjust if child widgets change +maximum/minimum sizes, or are deleted. + +QFont now supports KOI8R + +The reference documentation of the extensions is now integrated with +the main reference documentation in the qt/html directory. + +**************************************************************************** +* Changes that might affect runtime behavior * +**************************************************************************** + +None known. + + +**************************************************************************** +* Changes that might generate compile errors * +* when compiling old code * +**************************************************************************** + +none + +**************************************************************************** +* Type changes that might generate warnings: * +**************************************************************************** + +none + +**************************************************************************** +* Deprecated functions * +**************************************************************************** +Old function: Replaced by: +------------- ----------- +QPixmap::isOptimized QPixmap::optimization +QPixmap::optimize QPixmap::setOptimization +QPixmap::isGloballyOptimized QPixmap::defaultOptimization +QPixmap::optimizeGlobally QPixmap::setDefaultOptimization + + +**************************************************************************** +* New global functions +**************************************************************************** + + bitBlt( QImage* dst, int dx, int dy, const QImage* src, + int, int, int, int, int conversion_flags ); + + bitBlt( QPaintDevice *dst, int, int, const QImage* src, + int, int, int, int, int conversion_flags ); + +**************************************************************************** +* New public/protected functions added to existing classes * +**************************************************************************** + +QApplication::sendPostedEvents( QObject *receiver, int event_type ) [static] + +QButton::setDown() +QButton::toggle() + +QButtonGroup::setButton( int id ) +QButtonGroup::buttonToggled( bool on ) + +QComboBox::setListBox( QListBox * ) +QComboBox::listBox() + +QComboBox::setAutoCompletion( bool ) +QComboBox::autoCompletion() + +QComboBox::clearEdit() +QComboBox::setEditText( const char * ) + +QDict::resize() + +QDir::drives() [static] +QDir::remove() + +QFileDialog::getExistingDirectory() [static] +QFileDialog::setIconProvider() [static] +QFileDialog::iconProvider() [static] +QFileDialog::setSelection( const char* ) +QFileDialog::setMode( Mode ) +QFileDialog::mode() +QFileDialog::setFilter( const char * ) +QFileDialog::setFilters( const char ** ) +QFileDialog::setFilters( const QStrList & ) +QFileDialog::addWidgets( QLabel *, QWidget *, QPushButton * ) [protected] + +QFont::isCopyOf( const QFont & ) + +QFontMetrics::minLeftBearing() +QFontMetrics::minRightBearing() +QFontMetrics::inFont(char) +QFontMetrics::leftBearing(char) +QFontMetrics::rightBearing(char) +QFontMetrics::boundingRect( int x, int y, int w, int h, int flags, + const char *str, int, int, int *, char ** ) +QFontMetrics::size( int flags, char *str, int, int, int *, char ** ) + +QFrame::margin() +QFrame::setMargin( int ) + +QGManager::unFreeze() +QGManager::remove( QWidget *w ) +QGManager::setName( QChain *, const char * ) + +QGridLayout::numRows() +QGridLayout::numCols() +QGridLayout::expand( int rows, int cols ) + + +QImage::copy(int x, int y, int w, int h, int conversion_flags=0) +QImage::copy(QRect&) +QImage::allGray() +QImage::isGrayscale() +QImage::convertDepthWithPalette( int, QRgb* p, int pc, int cf=0 ) +QImage::smoothScale(int width, int height) +QImage::loadFromData( QByteArray data, const char *format=0 ) + +QIntDict::resize() + +QLabel::clear() + +QLCDNumber::sizeHint() const + +QLineEdit::setEnabled( bool ) +QLineEdit::setFont( const QFont & ) +QLineEdit::setSelection( int, int ) +QLineEdit::setCursorPosition( int ) +QLineEdit::cursorPosition() const +QLineEdit::validateAndSet( const char *, int, int, int ) +QLineEdit::insert( const char * ) +QLineEdit::clear() +QLineEdit::repaintArea( int, int ) [protected] + +QListBox::setFixedVisibleLines( int lines ) +QListBox::sizeHint() +QListBox::ensureCurrentVisible( int ) + +QMenuData::insertItem( const char *text, + const QObject *receiver, const char *member, + int accel, int id, int index = -1 ) +QMenuData::insertItem( const QPixmap &pixmap, + const QObject *receiver, const char *member, + int accel, int id, int index = -1 ) +QMenuData::insertItem( const QPixmap &pixmap, const char *text, + const QObject *receiver, const char *member, + int accel, int id, int index = -1 ) +QMenuData::findItem( int id, QMenuData ** parent ) + + +QMovie::QMovie(QDataSource*, int bufsize=1024) + +QMultiLineEdit::setFixedVisibleLines( int lines ) + +QObject::tr( const char * ) +QObject::name( const char * defaultName ) + +QPainter::QPainter( const QPaintDevice *, const QWidget * ) +QPainter::begin( const QPaintDevice *, const QWidget * ) +QPainter::xForm( const QPointArray &, int index, int npoints ) +QPainter::xFormDev( const QPointArray &, int index, int npoints ) +QPainter::drawImage() +QPainter::drawTiledPixmap() +QPainter::drawPicture( const QPicture & ) + +QPalette::isCopyOf( const QPalette & ) + +QPixmap::loadFromData( QByteArray data, + const char *, + int ) +QPixmap::optimization() +QPixmap::setOptimization( Optimization ) +QPixmap::defaultOptimization() +QPixmap::setDefaultOptimization( Optimization ) + +QPopupMenu::exec( const QPoint &, int ) +QPopupMenu::aboutToShow() + +QPrinter::setPageOrder( PageOrder ) +QPrinter::pageOrder() +QPrinter::setColorMode( ColorMode ) +QPrinter::colorMode() + +QPtrDict::resize() + +QPushButton::setIsMenuButton( bool ) +QPushButton::isMenuButton() + +QRegion::QRegion( int x, int y, int w, int h, RegionType = Rectangle ) +QRegion::boundingRect() +QRegion::rects() + +QSize::expandedTo() +QSize::boundedTo() + +QWidget::isEnabledTo(QWidget*) +QWidget::isEnabledToTLW() +QWidget::fontPropagation() +QWidget::setFontPropagation( PropagationMode ) +QWidget::palettePropagation() +QWidget::setPalettePropagation( PropagationMode ) +QWidget::isVisibleTo(QWidget*) +QWidget::setAcceptDrops( bool on ) +QWidget::acceptDrops() +QWidget::focusData() [protected] + diff --git a/dist/changes-1.41 b/dist/changes-1.41 new file mode 100644 index 0000000..31ccc55 --- /dev/null +++ b/dist/changes-1.41 @@ -0,0 +1,76 @@ +Here is a list of user-visible changes in Qt from 1.40 to 1.41 + +QT is now available as a DLL on Windows. + +Many bugfixes have been added. The Windows keys are supported on X11, +and the file dialog has been improved a little. + +Drag and drop has been considerably improved, both on Windows and X11. + +QPrinter now knows many more paper sizes. + +It now possible to create masked (nonrectangular) widgets. + +QScrollBar now supports insanely big ranges. + +QSlider now supports page step as well as line step. + +**************************************************************************** +* New classes * +**************************************************************************** + +None. + +**************************************************************************** +* Enhancements from 1.33 to 1.40 * +**************************************************************************** + + +**************************************************************************** +* Changes that might affect runtime behavior * +**************************************************************************** + +None. + + +**************************************************************************** +* Changes that might generate compile errors * +* when compiling old code * +**************************************************************************** + +None + +**************************************************************************** +* Type changes that might generate warnings: * +**************************************************************************** + +None + +**************************************************************************** +* Deprecated functions * +**************************************************************************** + +None. + + +**************************************************************************** +* New global functions * +**************************************************************************** + +None. + +**************************************************************************** +* New public/protected functions added to existing classes * +**************************************************************************** + +QFileDialog::getOpenFileNames() +QProgressDialog::setMinimumDuration( int ) +QProgressDialog::minimumDuration() const +QMouseEvent::globalPos() const +QMouseEvent::globalX() const +QMouseEvent::globalY() const +QFont::rawName() const +QWidget::setMask(const QRegion& region) +QWidget::setMask(QBitmap bitmap) +QWidget::clearMask() +QListView/QListViewItem: Various functions to create children in specified order diff --git a/dist/changes-1.42 b/dist/changes-1.42 new file mode 100644 index 0000000..7e47a53 --- /dev/null +++ b/dist/changes-1.42 @@ -0,0 +1,71 @@ +Here is a list of user-visible changes in Qt from 1.41 to 1.42. The +usual bugfixes have been added. + +**************************************************************************** +* New classes * +**************************************************************************** + +None. + +**************************************************************************** +* Enhancements from 1.41 to 1.42 * +**************************************************************************** + +The Windows version now builds as a DLL. + +The file dialog has various UI tweaks. + +More sanity checks have been added. + +On X11, the postscript output from a few programs will be much smaller +than it used to be. + +Windows 98 is now treated as a separate version of Windows, like NT +and Windows 95. + +The keyboard interface of buttons groups/dialogs has been improved. + +QMultiLineEdit avoids flicker in some cicumstances where it would +flicker up to now. + +**************************************************************************** +* Changes that might affect runtime behavior * +**************************************************************************** + +QKeyEvent now behaves as documented: isAccepted() is TRUE by default +where it would sometimes default to FALSE. Some dialogs may depend on +the bug. The most likely symptom of such buggy dialogs is that the +Enter/Return key does not work, and the most likely fix for such bugs +is to insert "e->ignore();" at the start of keyPressEvent(QKeyEvent*e) +in such dialogs. + +**************************************************************************** +* Changes that might generate compile errors * +* when compiling old code * +**************************************************************************** + +None + +**************************************************************************** +* Type changes that might generate warnings: * +**************************************************************************** + +None + +**************************************************************************** +* Deprecated functions * +**************************************************************************** + +None. + + +**************************************************************************** +* New global functions * +**************************************************************************** + +None. + +**************************************************************************** +* New public/protected functions added to existing classes * +**************************************************************************** + diff --git a/dist/changes-2.0.1 b/dist/changes-2.0.1 new file mode 100644 index 0000000..4a224bf --- /dev/null +++ b/dist/changes-2.0.1 @@ -0,0 +1,101 @@ +Changes in Qt 2.0.1 +------------------- + +Qt 2.0.1 is a bugfix release, forward and backward compatible with Qt 2.0. +While all changes are behind the API, some bugfixes may cause differences +in runtime behaviour - such fixes are marked in yellow with a "*". + + +General improvements +-------------------- + +PNG/IO Fix crash on empty images. + +QAccel Fix accelerators using Shift with other metakeys. + +QFileInfo Fix for AIX/gcc. + +QFontDatabase Fix centered text for extreme-bearing fonts. + +QHeader Resizing cells of horizontal header is now more flicker-free. + +*QLayout Fix deletion of child layouts. Let minimumSize() override +Fixed sizePolicy(). + +QLcdNumber Reduced flicker. + +QLineEdit Home etc. now clear selection even if the cursor doesn't move. + +QListBox Draw focus rect correctly. Fix keyboard navigation. + +QListView Make resizing flicker-free. No selection on release. + +QMainWindow Fix crash in addToolBar(). + +QMap Work on more compilers. + +QMenuBar Less flicker. + +QPainter Fix QFontMetrics::width(QChar). Speedup drawText/boundingRect. + +*QScrollView Put the scrollbars inside the frame in WindowsStyle. + +QSplitter Fix bug where a handle could be moved past the next. + +QString Fix QString::replace(QRegExp(),...). Speed ups. Fix fill() +with zero length crash. + +QTL AIX fixes. + +QTextBrowser Fixed type=detail popup. + +*QTextCodec Use the defacto KOI8 standard if no charset specified for +ru_ locale. + +QValueList AIX, aCC fixes. + +msg2qm More robust. + + + +Windows-specific fixes +---------------------- + +QApplication Fix Key_Enter (was always Key_Return). Fix numeric +accelerators. + +QFontDatabase Fix italic fonts in Window font dialog. + +*QMime Use CRLF with text clip/dnd on Windows. + +QPainter Avoid failure when painting pixmap xformed into nothing. +Improved drawing of scaled fonts on win95/98. + +*QPixmap Fix mask on QPixmap::convertToImage(). + +QPrinter Fix setup() on Win95/98. + +QToolTip Use system settings for tool tips on Windows. + +*QWidget Fix QWidget::scroll(rect) for non-topleft rectangles. + + +X11-specific fixes +------------------ + +DnD Fix Escape during DnD. + +*QApplication Generate MouseMove event on XCrossingEvent. Support more +XIM servers (eg. VJE Delta). Use 11pt font as default rather than 12pt +on larger than 95DPI displays. + +*QFont Correct DPI for fontsets (as for regular fonts). Prefer unscaled +(ie. perfect-match bitmaps) over scaled fonts. + +*QPaintDevice Round DPI. + +QWidget QWidget::showMaximized() works on X11 now. Fixed ReparentNotify +handling. + +Xt extension Fixes. + diff --git a/dist/changes-2.00 b/dist/changes-2.00 new file mode 100644 index 0000000..1dcfea7 --- /dev/null +++ b/dist/changes-2.00 @@ -0,0 +1,151 @@ +Qt 2.0 introduces a wide range of major new features as well as +substantial improvements over the 1.x series. The documentation has +been significally extended and improved. + +This file will only give an overview of the main changes since version +1.44. A complete list would simply be too large to be useful. For +more detail see the online documentation which is included in this +distribution, and also available on http://doc.trolltech.com/ + +The Qt version 2.x series is not binary compatible with the 1.x +series. This means programs compiled with Qt version 1.x must be +recompiled to work with Qt 2.0. + +Qt 2.0 is mostly, but not completely, source compatible with Qt 1.x. +See the document "Porting from Qt 1.x to Qt 2.0" in the Online +Reference Documentation for information on how to port an existing Qt +1.x-based program to Qt 2.0. Note in particular the automatic porting +script included - it does a lot of the work for you. + +As for 1.x, the API and functionality of Qt is completely portable +between Microsoft Windows and X11. And between Windows 95, 98 and NT: +Unlike most toolkits, Qt lets a single executable work on all three. + +**************************************************************************** +* New major features * +**************************************************************************** + + +* Support for international software development: + QTranslator and the QObject::tr() function + QTextCodec (and subclasses) + QString is now a 16-bit Unicode string with good support for + legacy 8-bit interoperation. (The old 8-bit string class + from Qt 1.x has been renamed to QCString.) + QChar - a Unicode character + +* Rich Text + QTextView - formatted text and images + QTextBrowser - navigate formatted text and images + QStyleSheet - define your own XML formatting tags + QSimpleRichText - display rich text anywhere + +* Convenient and powerful new collection classes: + QMap - QDict with arbitrary keys + QValueList - QList of types other than pointers + QStringList - QValueList with helper functions + +* Dialogs + QColorDialog - user picks a color + QFontDialog - user picks a font + QWizard - framework for leading users through steps + +* Layout + QGrid/QHBox/QVBox - grid and boxes of widgets automatically assembled + QHGroupBox/QVGroupBox - easy framed groups of widgets + QSizePolicy - a widget's abilities to change size in different ways + +* Custom layouts + New, much simpler and more powerful API for creating custom layouts + +* PNG Support + PNG support is now included in the core library + +* Support for generalized configurable GUI styles: + QStyle and subclasses + +* Session management + QSessionManager - saving state when the system shuts down + +* Extended coordinate system + QPoint, QPointArray, QSize and QRect now have 32-bit coordinates + +* Cleaner namespace + Global functions, enums and macros now either start with a 'q' or + have been moved into the new namespace class "Qt" + +**************************************************************************** +* List of removed classes * +**************************************************************************** + +* QGManager + Use the new custom layout API. + +* QPointVal, QPointData + Use QPoint. + +* QUrlDrag + Changed to QUriDrag + +* QWindow + Use QWidget + +**************************************************************************** +* List of new classes * +**************************************************************************** + +* QCDEStyle +* QChar +* QColorDialog +* QCommonStyle +* QConstString +* QCString +* QDragEnterEvent +* QDragLeaveEvent +* QDropSite +* QFontDialog +* QGLayoutIterator +* QGrid +* QHBox +* QHButtonGroup +* QHGroupBox +* QHideEvent +* QLayoutItem +* QLayoutIterator +* QMimeSource +* QMimeSourceFactory +* QMotifStyle +* QPlatinumStyle +* QSessionManager +* QShowEvent +* QSimpleRichText +* QSizeGrip +* QSizePolicy +* QSortedList +* QSpacerItem +* QStringList +* QStyle +* QStyleSheet +* QStyleSheetItem +* Qt +* QTab +* QTabWidget +* QTextBrowser +* QTextCodec +* QTextDecoder +* QTextEncoder +* QTextIStream +* QTextOStream +* QTextView +* QTranslator +* QUriDrag +* QVBox +* QVButtonGroup +* QVGroupBox +* QWheelEvent +* QWidgetItem +* QWindowsStyle +* QWizard + +For details, see e.g http://doc.trolltech.com/qcdestyle.html (or any +other class name, lowercased). diff --git a/dist/changes-2.00beta1 b/dist/changes-2.00beta1 new file mode 100644 index 0000000..5dccbad --- /dev/null +++ b/dist/changes-2.00beta1 @@ -0,0 +1,61 @@ + +The Qt version 2.x series is not binary compatible with the 1.x +series. This means programs compiled with Qt version 1.x must be +recompiled to work with Qt 2.0. + +Qt 2.0 is mostly, but not completely, source compatible with Qt 1.x. +See the document "Porting from Qt 1.x to Qt 2.0" in the Online +Reference Documentation for information on how to port an existing +Qt 1.x-based program to Qt 2.0. + + +**************************************************************************** +* New classes * +**************************************************************************** + + +* Support for generalized configrable styles: + + QStyle and subclasses + +* Support for international software development: + + QTranslator and the QObject::tr() function + QTextCodec (and subclasses) + QString - a Unicode string + QChar - a Unicode character + +* Convenient and powerful new collection classes: + QMap - QDict with arbitrary keys + QValueList - QList of types other than pointers + QStringList - QValueList with helper functions + +* Dialogs + QColorDialog - user picks a color + QFontDialog - user picks a font + QWizard - framework for leading users through steps + +* Layout + QGrid/QHBox/QVBox - grid and boxes of widgets automatically assembled + QHGroupBox/QVGroupBox - easy framed groups of widgets + +* PNG Support + PNG support is always compiled into Qt + +* Rich Text + QTextView - formatted text and images + QTextBrowser - navigate formatted text and images + QStyleSheet - define your own XML formatting tags + QSimpleRichText - display rixh text anywhere + +* Session management + QSessionManager - safe state when system shuts down + + +**************************************************************************** +* Major changes in existing classes * +**************************************************************************** + +QString is now 16-bit Unicode. + +QPoint, QPointArray, QSize and QRect now have 32-bit coordinates. \ No newline at end of file diff --git a/dist/changes-2.00beta2 b/dist/changes-2.00beta2 new file mode 100644 index 0000000..943c368 --- /dev/null +++ b/dist/changes-2.00beta2 @@ -0,0 +1,85 @@ +Qt 2.0 Beta2 is not binary compatible with Beta1, this means that any +programs linked with Beta1 must be recompiled. + +The most important fixes since Beta 1: + +configure + Fixed the libzlib typo. + Added -lflags argument. + +Platforms + Fixes for Borland C++, Solaris and AIX + +QFileDialog + Several user interface improvements + +QPrinter + Plain text printing works again. + Multiple page printing fixed. + +QWidget + New widget flag WStyle_Dialog + + +Major changes since 1.4x: + +The Qt version 2.x series is not binary compatible with the 1.x +series. This means programs compiled with Qt version 1.x must be +recompiled to work with Qt 2.0. + +Qt 2.0 is mostly, but not completely, source compatible with Qt 1.x. +See the document "Porting from Qt 1.x to Qt 2.0" in the Online +Reference Documentation for information on how to port an existing +Qt 1.x-based program to Qt 2.0. + + +**************************************************************************** +* New classes * +**************************************************************************** + + +* Support for generalized configrable styles: + + QStyle and subclasses + +* Support for international software development: + + QTranslator and the QObject::tr() function + QTextCodec (and subclasses) + QString - a Unicode string + QChar - a Unicode character + +* Convenient and powerful new collection classes: + QMap - QDict with arbitrary keys + QValueList - QList of types other than pointers + QStringList - QValueList with helper functions + +* Dialogs + QColorDialog - user picks a color + QFontDialog - user picks a font + QWizard - framework for leading users through steps + +* Layout + QGrid/QHBox/QVBox - grid and boxes of widgets automatically assembled + QHGroupBox/QVGroupBox - easy framed groups of widgets + +* PNG Support + PNG support is always compiled into Qt + +* Rich Text + QTextView - formatted text and images + QTextBrowser - navigate formatted text and images + QStyleSheet - define your own XML formatting tags + QSimpleRichText - display rixh text anywhere + +* Session management + QSessionManager - safe state when system shuts down + + +**************************************************************************** +* Major changes in existing classes * +**************************************************************************** + +QString is now 16-bit Unicode. + +QPoint, QPointArray, QSize and QRect now have 32-bit coordinates. \ No newline at end of file diff --git a/dist/changes-2.00beta3 b/dist/changes-2.00beta3 new file mode 100644 index 0000000..08f222a --- /dev/null +++ b/dist/changes-2.00beta3 @@ -0,0 +1,35 @@ +Qt 2.0 Beta3 is not binary compatible with Beta2, this means that any +programs linked with Beta2 must be recompiled. + +The most important fixes since Beta 2: + +platforms + 64-bits, FreeBSD and gcc 2.7 fixes + +QLayoutIterator/QGLayoutIterator + The custom layout API has been changed: void removeCurrent() + has been replaced by QLayoutItem* takeCurrent(). + +QLabel + The functions setMargin() and margin() have been renamed to + setIndent() and indent, to avoid collision with QFrame::setMargin(). + +QAccel + Non-latin1 accelerators are now supported. + +QTranslator/findtr/msg2qm/mergetr + All reported bugs fixed and improvements made. + +Rich Text + Many improvements and fixes such as supressed warnings in the + QBrowser example. Support for logical font sizes. + +QApplication + lastWindowClosed() now works with virtual desktops. Desktop settings + on Windows improved. + +QScrollView / QMultiLineEdit + Speedups with a new widget flag: WNorthWestGravity. + +QPopupMenu / QMenuBar + Speedups, less flicker. diff --git a/dist/changes-2.1.0 b/dist/changes-2.1.0 new file mode 100644 index 0000000..a0794cf --- /dev/null +++ b/dist/changes-2.1.0 @@ -0,0 +1,314 @@ +Qt 2.1 introduces new features as well as many improvements over the +2.0.x series. This file will only give an overview of the main changes +since version 2.0.2. A complete list would simply be too large to be +useful. For more detail see the online documentation which is included +in this distribution, and also available on +http://doc.trolltech.com/ + +The Qt version 2.1 series is binary compatible with the 2.0.x +series - applications compiled for 2.0 will continue to run with 2.1. + +As with previous Qt releases, the API and functionality of Qt is +completely portable between Microsoft Windows and X11. It is also portable +between Windows 95, 98 and NT; unlike most toolkits, Qt lets a single +executable work on all three. + +**************************************************************************** +* Overview * +**************************************************************************** + +As usual, large sections of the documentation have been revised and +lots of new documentation has been added. + +Much work went into existing classes, based on all the feedback we got +from our users. A warm thank you to you all at this point, we honestly +hope to satisfy most of your wishes with the new release. + +Among the things that got a lot of polishing is the new geometry +management system that was introduced with the 2.x series. Some +classes, such as QBoxLayout, have been rewritten and many size hints +and size policies were optimized. As usual with newly introduced +systems, the occasional bug has been fixed as well. As a result, +layout in Qt-2.1 is not only nicer but also faster. + +Big parts of the file dialog have been rewritten. It is now +synchronized in terms of features with the common Windows dialog, +including fancy drag'n'drop and in-place renaming. You can customize +both parts of the dialog, the front-end with info and preview widgets, +the back-end with different network protocols (see the QFileDialog and +QNetworkProtocol documentation for details). + +Especially interesting for dynamic Qt applications is the newly +introduced property system. Many interesting things, from scripting up +to graphical user interface builders, become easier. The technology +requires a new macro Q_PROPERTY and a new revision of Qt's meta object +compiler (moc). See the Qt documentation for details. + +Due to strong customer demand, we added a cross-platform way to easily +implement multi-document interfaces (known as 'MDI'). The widget is +called QWorkspace and makes this task trivial. + +On X11, text dropping from Motif drag'n'drop applications has been +added, to make your Qt applications inter-operable with those Motif +applications that survived Y2K. + +The rich text system, first introduced in Qt-2.0, has been +revised. Apart from great speed improvements, it now supports HTML +tables as well as floating images. + +QMultiLineEdit, the text input field in Qt, got the missing word wrap +functionality. It's probably the last big extension we will add to +that widget. In Qt 3.0, it will be replaced by a fancier, faster and +more powerful QTextEdit widget that also deals with different colors +and fonts in a way similar to the existing QTextView. + +Qt follows the respective GUI style guides even more closely. This +includes honoring desktop settings, and keyboard shortcuts such as +Ctrl-Z/Y for undo/redo in line edit and multi-line edit +controls. Dialog handling for both modal and non-modal dialogs has +been improved to follow the platform conventions precisely. + +With QIconView, we added a powerful new visualization widget similar +to QListView and QListBox. It contains optinally labelled pixmap items +that the user can select, drag around, rename, delete and more. + +Compared to the previous release, we have managed to reduce overall +memory consumption while improving execution speed and features. + +Below is a list of the major new features in existing classes as well +as short descriptions of all new classes and the changes in some of +the extensions shipped with Qt. + + +**************************************************************************** +* New major features in existing classes * +**************************************************************************** + +QApplication - new function wakeUpGuiThread() to simplify using threads + with Qt. + +QArray - added sorting and binary search. + +QColor - custom color support added. qRgb(r,g,b) helper function + now sets an opaque alpha value instead of a transparent + one. + +QComboBox - support for text items with icons. + +QFileDialog - many new features including fancy drag'n'drop + and in-place renaming. + Methods like setInfoPreviewWidget()and + setContentsPreviewWidget() make it easy to customize + the dialog extensively. With QUrlOperator and the + QNetworkProtocol abstraction, the dialog can operate + transparently by various different network protocols, + such as HTTP and FTP (see the Network Extension). + +QFocusEvent - carries a reason() for the event. Possible reasons are + Mouse, Tab, ActiveWindow, ShortCut and other. The + addition makes line edit controls behave properly. + +QHeader - added optional visual sort indicator. Revisited API that + operates on sections only (solves the 'logical' vs. 'actual' + index confusion). A reworked 'table' example shows how + to use QHeader in combination with a scrollview to create + a simple spreadsheet. + +QListBox - many signals and functions added for convenience and + greater flexibility. + +QListView - various selections modes similar to QListBox, many + new functions and signals added for convenience and + greater flexibility. + +QMainWindow - implemented draggable and hidable toolbars. A menubar + can be made draggable by simply putting it in a toolbar. + +QMetaObject - Parts of the API made public. The meta object allows + applications to access information about an object's + properties as well as its signals and slots. + +QMultiLineEdit - added different word wrap modes: WidgetWidth, + FixedPixelWidth and FixedColumnWidth. + +QObject - property access functions property() and setProperty(). + +QPen - added adjustable cap and join styles. + +QPopupMenu - added support for tear-off menus, custom items + and widget items. + A new function setItemParameter() makes it possible + to distinguish between several menu items connected to + one single slot. + +QPrinter - Now allows printing to the default printer without doing + setup() first. + +QProgressDialog - auto-reset and auto-close modes. + +QPushButton - added a menu button mode with setPopup(). + +QScrollView - support for auto-scrolling on drag move events (drag + auto scroll mode). + +QSignal - optional additional integer parameter for the emitted + signal. + +QSimpleRichText - added adjustSize() function that implements a clever + size hint. Vertical break support for printing. inText() + hit test. + +QSpinBox - different button symbols, currently UpDownArrows and + PlusMinus. + +QSplitter - supports three resize modes now, Stretch, KeepSize + and FollowSizeHint. + +QString - new functions setUnicode(), setUnicodeCodes(), setLatin1(), + startsWith() and endsWith() + +QStringList - new functions fromStrList(), split(), join() and grep(). + +QStyle - some extensions for menu button indicators, default + button indicators, variable scrollbar extends and toolbar + handles. + +QStyleSheet - a couple of tags added to the default sheet, such as + U, NOBR, HEAD, DL, DT, DD and table support (TABLE, TR, + TD, TH). Many attributes added to existing tags. + +QTextView - basic table support. Contents is selectable, selections + can be pasted/dragged into other widgets. + +QToolBar - stretchable depending on the orientation (setHorizontalStretchable() + and setVerticalStretchable(). Added orientationChanged() signal. + +QToolButton - added optional delayed menu with setPopup() and + setPopupDelay(). Auto-raise behaviour adjustable. + +QWidget - new widget flag WStyle_ContextHelp that adds a + context-help button to the window titlebar. The + button triggers "What's This?"-help. The flag works + with MS-Windows and future versions of X11 desktops + such as KDE-2.0. + + - New function showFullScreen(). + + - Enabling and disabling with setEnabled() propagates to + children. + + - Changed isVisible(). It now returns whether a widget + is mapped up to the toplevel widget (the previous + implementation only returned isVisibleTo(parentWidget()). + + - New property 'backgroundOrigin' that lets a widget draw + its background relatively to its parent widget's coordinate + system. This makes pseudo-transparency possible, without + the overhead of a real widget mask. + + +**************************************************************************** +* New clases * +**************************************************************************** + +QCustomMenuItem - an abstract base class for custom menu items in + popup menus. + +QFontDataBase - provides information about the available fonts. Not really + a new class (it was used internally for the QFontDialog), + but for the first time public API. + +QGuardedPtr - a template class that provides guarded pointers to + QObjects. + +QIconView - a sophisticated new widget similar to QListView and + QListBox. An iconview contains optinally labelled pixmap + items that the user can select, drag around, rename, delete + and more. The widget is highly optimized for speed and + large amounts of icons. + +QInputDialog - a convenience dialog to get some simple input values from + the user. + +QMetaProperty - stores meta data about properties. Part of the meta + object system. + +QNetworkProtocol- base class for network protocols, provides + a common API for network protocols. + +QUrl/ +QUrlOperator - provides an easy way to work with URLs. + +QVariant - a tagged union for the most common Qt data types. + +QValueStack - a value-based stack container. + +QWorkspace - provides a workspace that can contain decorated + windows as opposed to frameless child widgets. + QWorkspace makes it easy to implement a multi-document + interface (MDI). + +QBig5Codec - provides support for the Big5 Chinese encoding. + + +**************************************************************************** +* Changes which may affect runtime behaviour * +**************************************************************************** + +QDataStream / QPicture + To accomodate for improved functionality, the stream serialization format + of QString and QPen has changed in Qt 2.1. The format version + number has been increased to 3. Compatibility has been kept, so + applications built with this version of Qt are automatically able to read + QDataStream and QPicture data generated by earlier Qt 2.x versions. But if + your application needs to generate data that must be readable by + applications that are compiled with earlier versions of Qt, you must use + QDataStream::setVersion() (if the data contains QString or QPen objects). + See the documentation of this function for further discussion. + +QPainter::drawPolygon() + An outline is no longer drawn in the brush color if NoPen is specified. + This matches the behaviour on Windows and ensures that the area + painted in this case is the same pixels defined by a QRegion made + from the polygon. To get the old behaviour, you can call + painter.setPen(painter.brush()) prior to painting, which will also + work on Windows. + +QPushButton::sizeHint() + The size hint of auto-default push buttons has been slightly + increased in order to reserve space for a default button indicator + frame. This is necessary for a proper Motif or Platinum emulation. If + this change destroys your geometry management, a auto-default button + is probably not what you wanted anyway. Simply call + setAutoDefault(FALSE) on these push buttons to get the old behaviour. + +QWidget + Font and palette propagation has changed totally (from "almost + brain-dead" to working). In practice, the only changes we've seen are + to the better. + +QColor + qRgb(r,g,b) now sets a default opaque alpha value of 0xff instead of + a transparent 0x00 alpha value formerly. Use qRgb(r,g,b,a) if you do + need a transparent alpha value. + +QPalette + It turned out that the old normal/active/disabled set of color groups + didn't work very well, except in the simplest hello-world examples, + that it couldn't be fixed without nasty hacks, and that during five + years nobody had discovered the bugs. So, we've dropped our broken + attempt at Tcl/Tk L&F compatibility, and added support for Windows + 2000 and Macintosh L&F compatibility instead. The Macintosh and + Windows 2000 looks differentiate between the window with focus and + other windows. Qt calls the color groups QPalette::active() and + QPalette::inactive() respectively. + +QGridLayout/QBoxLayout + setMargin() now also works on child layouts. As a result of this + change, the geometry() of a layout now includes margin(). This may + effect programs that use QLayout::geometry(). + +QToolButton + The now adjustable auto-raise behaviour defaults to TRUE only when + a button is used inside a QToolBar. That's usually what you want. If not, + call setAutoRaise(FALSE). diff --git a/dist/changes-2.1.1 b/dist/changes-2.1.1 new file mode 100644 index 0000000..bb653fe --- /dev/null +++ b/dist/changes-2.1.1 @@ -0,0 +1,71 @@ + +Qt 2.1.1 is a bugfix release. It keeps both forward and backward +compatibility (source and binary) with Qt 2.1. + + +**************************************************************************** +* General * +**************************************************************************** + +- Many documentation improvements + +- Various compilation problems relating to particular versions of xlC, +MipsPRO, Solaris, Japanese Windows, old X11 libraries, and gcc 2.7.2 +fixed + +- 64bit HP build targets added + +- Qt OpenGL Extension updated; see details in qt/extensions/opengl/CHANGES + +- As usual, many minor bugfixes, too small to be mentioned here. + + +**************************************************************************** +* Specific * +**************************************************************************** + +QToolbar: fix of layout-saving when moving out of dock + +QAccel: Support for non-alphanumeric keys + +QPrinter: Better tolerance for PS interpreter peculiarities + +QPainter: drawText() with rasterOp on Windows + +QIconView: Drawing fixes + +QDate: Ensure invalid status when created with invalid values + +Motif Dnd: Fix possible crash + +QWorkSpace: Proper minimize/maximize activation + +QListBox: Optimization: better performance for lists with thousands of + elements. Selection problem fixed. + +QFont: Fontset matching fix for X11 + +QMultiLineEdit: Wordwrap/selection workaround + +QTabBar: Refresh layout after style change. Optimization. + +QTimer: Zero-timers on Windows speedup + +QFileDialog: Correct caption on Windows + +QComboBox: Accept only left button. Do proper font propagation. + +QMenuBar: Accept only left button + +QDialog: Modal dialogs after QApplication::exec() returns + +QWidget: Optimization: fewer server round-trips + +QCheckBox: Fixed mask drawing + +QSpinBox: Accept '-' key, for negative values + +Dnd: Allow disabling on X11 + +QFontDatabase: Use QApplication's charset as default, + and fixed garbage on Win2000 diff --git a/dist/changes-2.2.0 b/dist/changes-2.2.0 new file mode 100644 index 0000000..d5444a8 --- /dev/null +++ b/dist/changes-2.2.0 @@ -0,0 +1,223 @@ + +Qt 2.2 introduces new features as well as many improvements over the +2.1.x series. This file will only give an overview of the main changes +since version 2.1. A complete list would simply be too large to be +useful. For more detail see the online documentation which is +included in this distribution, and also available on +http://doc.trolltech.com/ + +The Qt version 2.2 series is binary compatible with the 2.1.x and +2.0.x series - applications compiled for 2.0 or 2.1 will continue to +run with 2.2. + +As with previous Qt releases, the API and functionality of Qt is +completely portable between Microsoft Windows and X11. It is also +portable between Windows 95, 98, NT and 2000. + +**************************************************************************** +* Overview * +**************************************************************************** + +The greatest new feature in the 2.2 release is the Qt Designer, a +visual GUI design tool. It makes it possible to cut down on +development time even further through WYSIWYG dialog design. The +designer makes use of improved runtime flexibility and a revised +property system. Please see $QTDIR/doc/html/designer.html for a +feature overview. + +Qt 2.2 integrates now fully on MS-Windows 2000. This includes fade +and scroll effects for popup windows and title bar gradients for MDI +document windows in the MDI module. As with all Qt features, we +provide the same visual effects on Unix/X11. + +Two new classes QAction and QActionGroup make it much easier to +create sophisticated main windows for today's applications. A QAction +abstracts a user interface action that can appear both in menus and +tool bars. An action group makes it easier to deal with groups of +actions. It allows to add, remove or activate its children with a +single call and provides "one of many" semantics for toggle +actions. Changing an action's properties, for example using +setEnabled(),setOn() or setText(), immediately shows up in all +representations. + +Few people consider the original OSF Motif style the most elegant or +flashy GUI style. Therefore several attempts have been made to come up +with a slightly improved Motif-ish look and feel. One of them is the +thinner CDE style, that was supported by Qt since version 2.0. In the +2.2 release, we now added support for SGI's very own Motif version on +IRIX workstations. With its more elegant bevelling of 3D elements and +mouse-under highlight effects, it is quite appealing. For Linux users, +we added a Motif plus style, that resembles the bevelling used by the +GIMP toolkit (GTK+). Optionally, this style also does hovering +highlight on buttons. + +Last but not least we added support for multi-threaded +applications. The classes involved are QThread to start threads, +QMutex to serialize them and QCondition to signal the occurrence of +events between threads ("condition variables"). + +Another major change was done regarding distribution. In order to +address the steady growth of functionality in the Qt library, we +split the source code into distinct modules that can be compiled +in (or left out) separately. This also makes it possible for us to +keep the cost of entry into the commercial Qt world as low as possible. + +The modules available in Qt 2.2 are: + +- Tools: platform-independent Non-GUI API for I/O, encodings, containers, + strings, time & date, and regular expressions. + +- Kernel: platform-independent GUI API, a complete window-system API. + +- Widgets: portable GUI controls. + +- Dialogs: ready-made common dialogs for selection of colors, files, + printers, fonts, and basic types, plus a wizard framework, message + boxes and progress indicator. + +- OpenGL 3D Graphics: integration of OpenGL with Qt, making it very + easy to use OpenGL rendering in a Qt application. + +- Network: advanced socket and server-socket handling plus + asynchronous DNS lookup. + +- Canvas: a highly optimized 2D graphic area. + +- Table: a flexible and editable table widget + +- IconView: a powerful visualization widget similar to QListView and + QListBox. It contains optionally labelled pixmap items that the user + can select, drag around, rename, delete and more. + +- XML: a well-formed XML parser with SAX interface plus an + implementation of the DOM Level1 + +- Workspace: a workspace window that can contain decorated document + windows for Multi Document Interfaces (MDI). + + +Network, Canvas, Table and XML are entirely new modules. + +Below is a list of the major new features in existing classes as well +as short descriptions of all new classes. + + +**************************************************************************** +* New major features in existing classes * +**************************************************************************** + +QApplication: - "global strut", an adjustable minimum size for interactable + control elements like the entries in a listbox, useful for + touch-screens. Popup window effects ( setEffectEnabled() ) + and more threading support ( guiThreadTaken(), lock(), + unlock(), locked() ). + +QCheckBox: - "tristate" is now a property. + +QClipboard: - text() supports subtypes. + +QComboBox: - "editable" is now a property that is changeable at runtime + +QDialog: - support for extensible dialogs ("More...") with + setExtension() and setOrientation(). Optional size grip. + +QFont: - new functions styleStrategy() and setStyleHint() + +QIconSet: - new constructor that takes both a small and a large pixmap + +QKeyEvent: - numeric keypad keys now set a Keypad flag + +QLabel: - support for scaled pixmap contents, "pixmap" as property + +QLayout: - improved flexibility with setEnabled(), access to the + laid out menu bar with menuBar(). + +QListView: - "showSortIndicator" as property. New function + QListViewItem::moveItem() to simplify drag and drop. + +QMovie: - new functions pushSpace(), pushData(), frameImage() + +QMultiLineEdit: - new functions pasteSubType() and copyAvailable() + +QObject: - new function normalizeSignalSlot(), tr() now supports a comment. + +QPicture: - streaming to and from QDataStream + +QPopupMenu: - new signal aboutToHide() + +QRegExp: - new functions setPattern() and find() + +QRegion: - new function setRects() + +QScrollView: - new property "staticBackground" to define a pixmap + background that does not scroll with the contents. + +QStatusBar: - "sizeGripEnabled" as property + +QStyle: - themable menu bars with drawMenuBarItem(). New functions + buttonMargin(), toolBarHandleExtent(), sliderThickness() + +QTabWidget: - new functions currentPageIndex(), setCurrentPage(), new + signal currentChanged(). Similar extensions to QTabBar + and QTabDialog + +QTranslator: - new algorithmen for faster lookup. No more risk of + "hash collisions" when many translators are loaded. + +QVariant: - new subtype QSizePolicy. Necessary for QWidget's + new sizePolicy property. + +QWidget: - new properties "sizePolicy", "ownPalette", "ownFont", + "ownCursor" and "hidden". The size policy is now adjustable + at runtime with setSizePolicy(). Added convenience slot + setDisabled(). Fast geometry mapping functions mapTo() and + mapFrom(). On X11, support for a new background mode + X11ParentRelative. + +QWizard: - runtime changable titles with setTitle(), new signal + selected() + +QWorkspace: - support for more widget flags like WType_Tool. Titlebar + blending effects on MS-Windows 98/2000. + + +**************************************************************************** +* New classes * +**************************************************************************** + +QAction - Abstracts a user interface action that can appear both in + menus and tool bars. Changing an action's properties, for + example using setEnabled(),setOn() or setText(), + immediately shows up in all representations. + +QActionGroup - Combines actions to a group. An action group makes it easier + to deal with groups of actions. It allows to add, remove or + activate its children with a single call and provides + "one of many" semantics for toggle actions. + +QDial - A rounded rangecontrol (like a speedometer or + potentiometer). Both API- and UI-wise the dial is very + similar to a QSlider. + +QDom - [XML Module] DOM Level 1 Tree + +QMotifPlusStyle - This class implements a Motif-ish look and feel with more + sophisticated bevelling as used by the GIMP toolkit (GTK+) + for Unix/X11. + +QMutex: - Provides access serialization between threads. + +QSemaphore: - A robust integer semaphore. Another way of thread + serialization. + +QThread - Baseclass for platform-independent threads. + +QWaitCondition - Provides signalling of the occurrence of events between + threads ("condition variables") + +QCanvas - [Canvas Module] a highly optimized 2D graphic area. + +QTable - [Table Module] a flexible and editable table widget + +QXML - [XML Module] XML parser with SAX interface + diff --git a/dist/changes-2.2.1 b/dist/changes-2.2.1 new file mode 100644 index 0000000..1df0851 --- /dev/null +++ b/dist/changes-2.2.1 @@ -0,0 +1,160 @@ + +Qt 2.2.1 is a maintainance release. It keeps backward binary compatibility +with Qt 2.1 and both forward and backward source compatibility with Qt 2.2.x. + +Qt 2.2.0 had a binary compatibility problem with the following: + + bool QRect::contains( const QRect &r, bool proper=FALSE ) const + +Qt 2.2.1 corrects this. Programs compiled with 2.1.x now continue +running with 2.2.1. Programs compiled with versions other than 2.2.0 +may not run with 2.2.0, so upgrading to 2.2.1 is additionally important. + + +**************************************************************************** +* General * +**************************************************************************** + +- Various compilation problems on particular platforms fixed + +- Many improvments in QThread. More platforms supported + (e.g. HPUX 11.x), uses native threads on Solaris rather than + compatibility posix threads + +- A few newly discovered memory leaks and free memory reads fixed + +- As usual, many minor bugfixes, too small to be mentioned here. + + +**************************************************************************** +* Designer * +**************************************************************************** + +- in KDE mode: don't show all KDE widgets in the toolbars, since we do + not have icons for them (yet). They are accessible through the menu + structure, though. + +- Introduced concept of a global /etc/designerrc and a templatePath + for the sake of Linux Standard Base (LSB) and the way Linux + ditributors like to package the Qt Free Edition. + +- Support for tab names in a QTabWidget, and page names in a QWizard. + +- Support for button IDs in a button group, makes it possible to utilize + one single slot for all buttons in a group. + +**************************************************************************** +* Library * +**************************************************************************** + +QClipboard: X11 only: fixed occasional crashes, possibly corrupted + list of provided types and hangups of several seconds under + certain circumstances. + +QFileDialog: Fixed update when renaming a file to an existing file + Unix only: Reset error status after attempting to read an + empty file + Fixed magical resetting of the "Open" label + Fixed duplicate entries in the history combobox + +QFont: Fixes for Hewbrew, Arabic and Thai encodings + Added support for Ukrainian encodings + X11 only: loading fonts for a locale other than the + current now possible (allows displaying japanese characters + in a latin1 application without relying on the existence of + a unicode font) + +QHeader: removing labels fixed, important for QTable and QListView + +QIconView: drawing problem with missleading font metrices and + bounding rectangles fixed + +QInputDialog, +QMessageBox: use the main widget's or parent's icon if available + +QLayout: synchronize the behaviour of sublayouts and subwidgets with + layouts. + +QLineEdit: Update cursor position if QValidator::fixup() truncates the + string + +QMainWindow: Fixed calculated minimum size. Sometimes, the minimum width + of the central widget was disregarded. + +QMenuBar: Sizing fixed for frameless menubars in toolbars in + Motif-based styles + +QMotifPlusStyle: correct drawing of triangular tabs + +QMovie: keep frameImage() during EndOfMovie signal + +QDom: add comments when reading a xml file into the dom + +QPrinter: MS-Windows only: Fixed invalidation when setup dialog was + cancelled + +QSgiStyle: Small drawing problem with QTabBar fixed. + Fixed drawing of special prefix in menu items + +QSizePolicy: setHeightForWidth() was broken, works now + +QTextCodec: significant speedups for latin1 conversion + +QTextStream: small speed improvements for readLine() + Added codec for ukrainian (koi8-u) encoding + +QWheelEvent: Support for the MSH_MOUSEWHEEL extension on MS-Windows 95 + +QWidget: X11 only: Fixed possible mouse lock-ups when re-entering + the event loop on mouse events for widgets of type + WType_Popup. + X11 only: set input context when setting the active + window + X11 only: when dialogs were closed, the main window looked + like it lost focus with some window managers. This has been + fixed now. + +QWidgetStack: potential flicker issue fixed + +QWorkspace: normalize minimized children when they get focus + removed occasional flashing (e.g. when maximizing child + windows) + Look and feel adjustments to emulate MS-Windows even + closer + Documented that the active window can be 0 if there is no + active window + Slightly modifed the button decorations to be more general + and less KDE2 specific + + +**************************************************************************** +* Changes that might affect runtime behavior * +**************************************************************************** + +QLayout: + +We synchronized the behaviour of sublayouts and subwidgets with +layouts. This shows great effect in the designer, were you usually +operate on container subwidgets in the design phase, but get a +complete layout in the preview mode or the generated code. For +example, the influence of a spacer item on a sublayout's size policy +has been reduced. The modifications may slightly affect the layout of +some dialogs. + + +**************************************************************************** +* Qt/Embedded-specific changes * +**************************************************************************** + +- Rotated displays & fonts +- QCOP, a simple interprocess messaging system +- Threading support +- Auto-detected mouse +- VGA16 support +- Improved thick lines +- Optimize some double-painting +- Allow setting of custom 8bpp colors: QApplication::qwsSetCustomColors() +- Fix masked widget drawing and clicking +- Fix mouse grabbing for popups + + diff --git a/dist/changes-2.2.2 b/dist/changes-2.2.2 new file mode 100644 index 0000000..5f271fe --- /dev/null +++ b/dist/changes-2.2.2 @@ -0,0 +1,154 @@ + +Qt 2.2.2 is a bugfix release. It keeps both forward and backward +compatibility (source and binary) with Qt 2.2.1 + + +**************************************************************************** +* General * +**************************************************************************** + +OpenGL: More Problems with the auto-detection of OpenGL + libraries have been fixed. + + +**************************************************************************** +* Designer * +**************************************************************************** + +uic: Added workaround for the QListView::Manual vs. + QScrollView::Manual enumeration clash. + Fixed backslashes inside strings. + Obeys user defined layout names. + +RC2UI: Converts Microsoft Dialog Resources (.rc) to + Qt Designer Dialog Userinterface Description Files (.ui). + You find it in $QTDIR/tools/designer/integration/rc2ui. + See the README file there. + +**************************************************************************** +* Library * +**************************************************************************** + +QAction: Fixed possible crash in removeFrom(). + +QApplication: X11 only: Add possibility to input text in more than + one encoding. + +QCanvas: Deletes items at canvas destruction time. Without a + canvas, items are not deletable anyway as they need to + access their canvas during destruction. + Some performance optimizations. + +QCanvasItem: More accurate rectangle collision detection. + +QClipboard: X11 only: 64bit cleanness when transferring data + with format==32 using dnd/clipboard. + +QColorDialog: MS-Windows only: Tries harder to use a nice icon. + +QDialog: Keypard-Enter triggers default button. + +QFile: Unix only: Safe access to files in the proc filesystem. + +QFileDialog: Fixed reentrancy problem when used with qFtp. + MS-Windows only: Tries harder to use a nice icon. + +QFontCache: Fixed possible crash in the rare case that the font + cache runs over. + +QGLWidget: MS-Windows only: Fix for GL context switching. + +QIconView: Fixed possible crash. + +QImage: Increased number of colors when writing XPM files from + 64^2 to 64^4. + Fixed 16-bit pixel(). + +QImageIO: MS-Windows only: exported qInitJpegIO function. + Fixed crash with libpng 1.0.8. + Fixed huge memory leak with PNG files. + +QLCDNumber: Sensible precision when displaying doubles. + +QLineEdit: Accepts text drops other than text/plain. + Fixed psosible crash when deleting a line edit while its + context menu is visible. + +QListView: Less flicker. Improved performance on insertItem(). + +QMainWindow: Deletes its layout first on destruction time to avoid + possible crashes with subclasses. + +QMotifPlusStyle:Tuned drawing of tabs. + +QPainter: Fixed rounded rectangle drawing with rotation and + viewport transformation turned on. + Ignores '\r' in drawText. + +QPopupMenu: Ensure to emit the aboutToShow() signal only once + for submenus. + +QPrinter: Unix only: Fixed output for when printing some but not all pages + of multi-page output. + Unix only: Fixed an infinite loop in the image compression + algorithm for some images. + Unix only: Added MIBs for 8859-13, -14 and -15. + MS-Windows only: Fixed system print dialog for Win9x. + +QPrintDialog: MS-Windows only: Tries harder to use a nice icon. + +QProgressBar: Fixed drawing problem with really large progress ranges. + +QPushButton: Implemented "flat" property as advertised. + +QPrinter: MS-Windows only: Keep the current printer name. + +QRichText: Fixed line breaking for asian scripts. Support for + chinese punctuation. + Obeys tags inside links. + +QString: Allows 'G' in sprintf. + +QTextCodec: Recognizes "he" and "he_IL" as 8859-8 locales. + Added latin4 locales. + Improved Thai support. + X11 only: fixed crashes when LANG=ko. + Improved conversion performance. + +QWidget: X11 only: fixed a crash in case XmbTextListToTextProperty + fails for a certain locale. + Visiblity fix when reparenting a widget to 0. + X11 only: Improved transient placement for embedded + windows. + X11 only: Maintains XDND state when reparented. + X11 only: No more crashes in setActiveWindow() with + or without XIM support. + X11 only: small ICCCM compatibility issue with subsequent + hide and show fixed. + +QWorkspace: Tab-focus remains inside a document window. + Fixed problem with menubars inside document windows. + Obeys initial child geometry. + Uses the children's size hint when cascading. + +QXmlInputSource:Fix for stream devices that do not support + direct access. + +**************************************************************************** +* Third party * +**************************************************************************** + +None + +**************************************************************************** +* Changes that might affect runtime behavior * +**************************************************************************** + +None + +**************************************************************************** +* Qt/Embedded-specific changes * +**************************************************************************** + + - Drawing speed-ups, especially rectangles, alpha blitting, horizontal lines. + - More control of qconfig.h diff --git a/dist/changes-3.0.0 b/dist/changes-3.0.0 new file mode 100644 index 0000000..1f6ad5b --- /dev/null +++ b/dist/changes-3.0.0 @@ -0,0 +1,720 @@ +Qt 3.0 adds a wide range of major new features as well as substantial +improvements over the Qt 2.x series. Some internals have undergone +major redesign and new classes and methods have been added. + +The Qt version 3.x series is not binary compatible with the 2.x +series. This means programs compiled with Qt version 2.x must be +recompiled to work with Qt 3.0. + +In addition to the traditional Qt platforms Linux, Unix and the +various flavours of MS-Windows. Qt 3.0 for the first time introduces a +native port to MacOS X. Like all Qt versions, Qt/Mac is source +compatible with the other editions and follows closely the platform's +native look and feel guidelines. + +We have tried to keep the API of Qt 3.0 as compatible as possible with +the Qt 2.x series. For most applications, only minor changes will be +needed to compile and run them successfully using Qt 3.0. + +One of the major new features that has been added in the 3.0 release +is a module allowing you to easily work with databases. The API is +platform independent and database neutral. This module is seamlessly +integrated into Qt Designer, greatly simplifying the process of +building database applications and using data aware widgets. + +Other major new features include a plugin architecture to extend Qt's +functionality, for styles, text encodings, image formats and database +drivers. The Unicode support of Qt 2.x has been greatly enhanced, it +now includes full support for scripts written from right to left +(e.g. Arabic and Hebrew) and also provides improved support for Asian +languages. + +Many new classes have been added to the Qt Library. Amongst them are +classes that provide a docking architecture (QDockArea/QDockWindow), a +powerful rich text editor (QTextEdit), a class to store and access +application settings (QSettings) and a class to create and communicate +with processes (QProcess). + +Apart from the changes in the library itself a lot has been done to +make the development of Qt applications with Qt 3.0 even easier than +before. Two new applications have been added: Qt Linguist is a tool to +help you translate your application into different languages; Qt +Assistant is an easy to use help browser for the Qt documentation that +supports bookmarks and can search by keyword. + +Another change concerns the Qt build system, which has been reworked +to make it a lot easier to port Qt to new platforms. You can use this +platform independent build system - called qmake - for your own +applications. + +And last but not least we hope you will enjoy the revisited and widely +extended documentation. + + +Qt/Embedded +---------- + +Qt/Embedded 3.0 provides the same features as Qt 3.0, but currently +lacks some of the memory optimizations and fine-tuning capabilities of +Qt/Embedded 2.3.x. We will add these in the upcoming maintainance +releases. + +If you develop a new product based on Qt/Embedded, we recommend +switching to 3.0 because of the greatly improved functionality. +However, if you are planning a release within the next two months and +require memory optimizations not available with Qt/Embedded 3.0, we +suggest using Qt/Embedded 2.3.x. + + +The Qt Library +======================================== + +A large number of new features has been added to Qt 3.0. The following +list gives an overview of the most important new and changed aspects +of the Qt library. + + +Database support +---------------- + +One of the major new features in Qt 3.0 is the SQL module that +provides cross-platform access to SQL databases, making database +application programming with Qt seamless and portable. The API, built +with standard SQL, is database-neutral and software development is +independent of the underlying database. + +A collection of tightly focused C++ classes are provided to give the +programmer direct access to SQL databases. Developers can send raw SQL +to the database server or have the Qt SQL classes generate SQL queries +automatically. Drivers for Oracle, PostgreSQL, MySQL and ODBC are +available and writing new drivers is straightforward. + +Tying the results of SQL queries to GUI components is fully supported +by Qt's SQL widgets. These classes include a tabular data widget +(for spreadsheet-like data presentation with in-place editing), a +form-based data browser (which provides data navigation and edit +functions) and a form-based data viewer (which provides read-only +forms). This framework can be extended by using custom field editors, +allowing for example, a data table to use custom widgets for in-place +editing. The SQL module fully supports Qt's signals/slots mechanism, +making it easy for developers to include their own data validation and +auditing code. + +Qt Designer fully supports Qt's SQL module. All SQL widgets can be +laid out within Qt Designer, and relationships can be established +between controls visually. Many interactions can be defined purely in +terms of Qt's signals/slots mechanism directly in Qt Designer. + + +Explicit linking and plugins +------------------------- + +The QLibrary class provides a platform independent wrapper for runtime +loading of shared libraries. + +Specialized classes that make it possible to extend Qt's functionality +with plugins: QStylePlugin for user interface styles, QTextCodecPlugin +for text encodings, QImageFormatPlugin for image formats and +QSqlDriverPlugin for database drivers. + +It is possible to remove unused components from the Qt library, and +easy to extend any application with 3rd party styles, database drivers +or text codecs. + +Qt Designer supports custom widgets in plugins, and will use the +widgets both when designing and previewing forms (QWidgetPlugin). + + +Rich text engine and editor +--------------------------- + +The rich text engine originally introduced in Qt 2.0 has been further +optimized and extended to support editing. It allows editing formatted +text with different fonts, colors, paragraph styles, tables and +images. The editor supports different word wrap modes, command-based +undo/redo, multiple selections, drag and drop, and many other +features. The engine is highly optimized for proccesing and displaying +large documents quickly and efficiently. + + +Unicode +------- + +Apart from the rich text engine, another new feature of Qt 3.0 that +relates to text handling is the greatly improved Unicode support. Qt +3.0 includes an implementation of the bidirectional algorithm (BiDi) +as defined in the Unicode standard and a shaping engine for Arabic, +which gives full native language support to Arabic and Hebrew speaking +people. At the same time the support for Asian languages has been +greatly enhanced. + +The support is almost transparent for the developer using Qt to +develop their applications. This means that developers who developed +applications using Qt 2.x will automatically gain the full support for +these languages when switching to Qt 3.0. Developers can rely on their +application to work for people using writing systems different from +Latin1, without having to worry about the complexities involved with +these scripts, as Qt takes care of this automatically. + + +Docked and Floating Windows +--------------------------- + +Qt 3.0 introduces the concept of dock windows and dock areas. Dock +windows are widgets, that can be attached to, and detached from, dock +areas. The most common kind of dock window is a tool bar. Any number of +dock windows may be placed in a dock area. A main window can have dock +areas, for example, QMainWindow provides four dock areas (top, left, +bottom, right) by default. The user can freely move dock windows and +place them at a convenient place in a dock area, or drag them out of +the application and have them float freely as top level windows in +their own right. Dock windows can also be minimized or hidden. + +For developers, dock windows behave just like ordinary widgets. QToolbar +for example is now a specialized subclass of a dock window. The API +of QMainWindow and QToolBar is source compatible with Qt 2.x, so +existing code which uses these classes will continue to work. + + +Regular Expressions +------------------- + +Qt has always provided regular expression support, but that support +was pretty much limited to what was required in common GUI control +elements such as file dialogs. Qt 3.0 introduces a new regular +expression engine that supports most of Perl's regex features and is +Unicode based. The most useful additions are support for parentheses +(capturing and non-capturing) and backreferences. + + +Storing application settings +---------------------------- + +Most programs will need to store some settings between runs, for +example, user selected fonts, colors and other preferences, or a list +of recently used files. The new QSettings class provides a platform +independent way to achieve this goal. The API makes it easy to store +and retrieve most of the basic data types used in Qt (such as basic +C++ types, strings, lists, colors, etc). The class uses the registry +on the Windows platform and traditional resource files on Unix. + + +Creating and controlling other processes +---------------------------------------- + +QProcess is a class that allows you to start other programs from +within a Qt application in a platform independent manner. It gives you +full control over the started program. For example you can redirect +the input and output of console applications. + + +Accessibility +--------------- + +Accessibility means making software usable and accessible to a wide +range of users, including those with disabilities. In Qt 3.0, most +widgets provide accessibility information for assistive tools that can +be used by a wide range of disabled users. Qt standard widgets like +buttons or range controls are fully supported. Support for complex +widgets, like e.g. QListView, is in development. Existing applications +that make use of standard widgets will become accessible just by using +Qt 3.0. + +Qt uses the Active Accessibility infrastructure on Windows, and needs +the MSAA SDK, which is part of most platform SDKs. With improving +standardization of accessibility on other platforms, Qt will support +assistive technologies on other systems too. + + +XML Improvements +---------------- + +The XML framework introduced in Qt 2.2 has been vastly improved. Qt +2.2 already supported level 1 of the Document Object Model (DOM), a +W3C standard for accessing and modifying XML documents. Qt 3.0 has +added support for DOM Level 2 and XML namespaces. + +The XML parser has been extended to allow incremental parsing of XML +documents. This allows you to start parsing the document directly +after the first parts of the data have arrived, and to continue +whenever new data is available. This is especially useful if the XML +document is read from a slow source, e.g. over the network, as it +allows the application to start working on the data at a very early +stage. + + +SVG support +----------- + +SVG is a W3C standard for "Scalable Vector Graphics". Qt 3.0's SVG +support means that QPicture can optionally generate and import static +SVG documents. All the SVG features that have an equivalent in +QPainter are supported. + + +Multihead support +----------------- + +Many professional applications, such as DTP and CAD software, are able +to display data on two or more monitors. In Qt 3.0 the QDesktopWidget +class provides the application with runtime information about the +number and geometry of the desktops on the different monitors and such +allows applications to efficiently use a multi-monitor setup. + +The virtual desktop of Windows 98 and 2000 is supported, as well as +the traditional multi-screen and the newer Xinerama multihead setups +on X11. + + +X11 specific enhancements +------------------------- + +Qt 3.0 now complies with the NET WM Specification, recently adopted +by KDE 2.0. This allows easy integration and proper execution with +desktop environments that support the NET WM specification. + +The font handling on X11 has undergone major changes. QFont no longer +has a one-to-one relation with window system fonts. QFont is now a +logical font that can load multiple window system fonts to simplify +Unicode text display. This completely removes the burden of +changing/setting fonts for a specific locale/language from the +programmer. For end-users, any font can be used in any locale. For +example, a user in Norway will be able to see Korean text without +having to set their locale to Korean. + +Qt 3.0 also supports the new render extension recently added to +XFree86. This adds support for anti-aliased text and pixmaps with +alpha channel (semi transparency) on the systems that support the +rendering extension (at the moment XFree 4.0.3 and later). + + +Printing +-------- + +Printing support has been enhanced on all platforms. The QPrinter +class now supports setting a virtual resolution for the painting +process. This makes WYSIWYG printing trivial, and also allows you to +take full advantage of the high resolution of a printer when painting +on it. + +The postscript driver built into Qt and used on Unix has been greatly +enhanced. It supports the embedding of true/open type and type1 fonts +into the document, and can correctly handle and display Unicode. +Support for fonts built into the printer has been enhanced and Qt now +knows about the most common printer fonts used for Asian languages. + + +Networking +----------- + +A new class QHttp provides a simple interface for HTTP downloads and +uploads. + + +Compatibility with the Standard Template Library (STL) +------------------------------------------------------ + +Support for the C++ Standard Template Library has been added to the Qt +Template Library (QTL). The QTL classes now contain appropriate copy +constructors and typedefs so that they can be freely mixed with other +STL containers and algorithms. In addition, new member functions have +been added to QTL template classes which correspond to STL-style +naming conventions (e.g., push_back()). + + +Qt Designer +======================================== + +Qt Designer was a pure dialog editor in Qt 2.2 but has now been +extended to provide the full functionality of a GUI design tool. + +This includes the ability to lay out main windows with menus and +toolbars. Actions can be edited within Qt Designer and then plugged +into toolbars and menu bars via drag and drop. Splitters can now be +used in a way similar to layouts to group widgets horizontally or +vertically. + +In Qt 2.2, many of the dialogs created by Qt Designer had to be +subclassed to implement functionality beyond the predefined signal and +slot connections. Whilst the subclassing approach is still fully +supported, Qt Designer now offers an alternative: a plugin for editing +code. The editor offers features such as syntax highlighting, +completion, parentheses matching and incremental search. + +The functionality of Qt Designer can now be extended via plugins. +Using Qt Designer's interface or by implementing one of the provided +interfaces in a plugin, a two way communication between plugin and Qt +Designer can be established. This functionality is used to implement +plugins for custom widgets, so that they can be used as real widgets +inside the designer. + +Basic support for project management has been added. This allows you +to read and edit *.pro files, add and remove files to/from the project +and do some global operations on the project. You can now open the +project file and have one-click access to all the *.ui forms in the +project. + +In addition to generating code via uic, Qt Designer now supports the +dynamic creation of widgets directly from XML user interface +description files (*.ui files) at runtime. This eliminates the need of +recompiling your application when the GUI changes, and could be used +to enable your customers to do their own customizations. Technically, +the feature is provided by a new class, QWidgetFactory in the +UI-library. + + +Qt Linguist +======================================== + +Qt Linguist is a GUI utility to support translating the user-visible +text in applications written with Qt. It comes with two command-line +tools: lupdate and lrelease. + +Translation of a Qt application is a three-step process: + + 1) Run lupdate to extract user-visible text from the C++ source + code of the Qt application, resulting in a translation source file + (a *.ts file). + 2) Provide translations for the source texts in the *.ts file using + Qt Linguist. + 3) Run lrelease to obtain a light-weight message file (a *.qm file) + from the *.ts file, which provides very fast lookup for released + applications. + +Qt Linguist is a tool suitable for use by translators. Each +user-visible (source) text is characterized by the text itself, a +context (usually the name of the C++ class containing the text), and +an optional comment to help the translator. The C++ class name will +usually be the name of the relevant dialog, and the comment will often +contain instructions that describe how to navigate to the relevant +dialog. + +You can create phrase books for Qt Linguist to provide common +translations to help ensure consistency and to speed up the +translation process. Whenever a translator navigates to a new text to +translate, Qt Linguist uses an intelligent algorithm to provide a list +of possible translations: the list is composed of relevant text from +any open phrase books and also from identical or similar text that has +already been translated. + +Once a translation is complete it can be marked as "done"; such +translations are included in the *.qm file. Text that has not been +"done" is included in the *.qm file in its original form. Although Qt +Linguist is a GUI application with dock windows and mouse control, +toolbars, etc., it has a full set of keyboard shortcuts to make +translation as fast and efficient as possible. + +When the Qt application that you're developing evolves (e.g. from +version 1.0 to version 1.1), the utility lupdate merges the source +texts from the new version with the previous translation source file, +reusing existing translations. In some typical cases, lupdate may +suggest translations. These translations are marked as unfinished, so +you can easily find and check them. + + +Qt Assistant +======================================== + +Due to the positive feedback we received about the help system built +into Qt Designer, we decided to offer this part as a separate +application called Qt Assistant. Qt Assistant can be used to browse +the Qt class documentation as well as the manuals for Qt Designer and +Qt Linguist. It offers index searching, a contents overview, bookmarks +history and incremental search. Qt Assistant is used by both Qt +Designer and Qt Linguist for browsing their help documentation. + + +qmake +======================================== + +qmake is a cross-platform make utility that makes it possible to build +the Qt library and Qt-based applications on various target platforms +from one single project description. It is the C++ successor of +'tmake' which required Perl. + +qmake offers additional functionallity that is difficult to reproduce +in tmake. Trolltech uses qmake in its build system for Qt and related +products and we have released it as free software. + + + +Detailed changes +============= + +Qt 3.0 went through 6 beta releases. These are the detailed changes +since Beta 6 only. For other changes, please see the changes notes +of the respective beta releases. + + +Qt 3.0 final is not binary compatible with Beta6; any programs linked +against Beta6 must be recompiled. + +Below you will find a description of general changes in the Qt +Library, Qt Designer and Qt Assistant. Followed by a detailed list of +changes in the API. + +**************************************************************************** +* General * +**************************************************************************** + +**************************************************************************** +* Library * +**************************************************************************** + +- QApplication + make sure we process deferred deletes before leaving the event + loop. This fixes some ocassions of memory leaks on exit. + win32: some improvements for modality and dockwindow handling + x11 only: read non-gui QSettings when running without GUI. + + +- QCheckListItem + Make the checkboxes respect the AlignCenter flag. Also make + the boxes look better in case they are not placed in the first + column. + +- QComboBox + if we have a currentItem and then we set the combobox to be + editable then set the text in the lineedit to be of the + current item. + +- QCommonStyle + QToolButton: spacing between a toolbutton's icon and its label. + QProgressBar: text color fixed. + +- QCursor + added the What's This? cursor to the collection. + +- QDataTable + fixed broken context menus. + +- QDate + fixed addMonth() overflow. + +- QDesktopWidget + win32 only: works now also for cases where the card handles + multiple monitors and GetSystemMetrics returns a single screen + only. + +- QDomAttr + fixed a memory leak in setNodeValue() + +- QDomNodeMap + added count() as a Qt-style alias for length() + +- QDragObject + default to the middle of the pixmap as a hot spot, this looks + nicer. + +- QFileDialog (internal dialog) + make viewMode() return the correct value even after the dialog + is finished. Fixed getOpenFileName and getSaveFileName for + non-existant directories. Make sure that when it's in + directory mode that the filters reflect this, and change the + label from file name to directory. + win32 only: Improved modality when using the native file + dialog. + +- QFont + x11 only: speed up fontloading with even more clever + caching. Make sure we can match scaled bitmap fonts by + default. Do not load a backup font for a script that is not + default. Make sure the pixel size is correct, even for fonts + that are unavailable. Try even harder to find a fontname that + is not understood. Some RENDER performance optimizations. + +- QFontDialog + make sure the content is set up correctly when initializing + the dialog. + +- QGLWidget + IRIX only: fixed reparent/resize bug, QGLContext::setContext() + is incredibly sensitive on different X servers. + +- QHeader + fixed missing updates on height resp. width changes like the + occur when changing the application font. + +- QIconView + fixed updates of non-auto-arranged views. + +- QImage + no gamma correction by default. + x11 only: some alignment issue with the alpha masked fixed. + +- QIODevice + fixed return value of QIODevice::readLine() for sequential + access. + +- QKeyEvent + win32 only: generate Direction_R/L events for bidirectional + input. + +- QLabel + handle setPixmap( *pixmap() ) gracefully. Apply the WordBreak + alignment flag to both plaintext and richtext. Improved alignment of + richtext labels. Removed some sizepolicy magic, QLabel now + works fine with Preferred/Preferred in all modes. + +- QLineEdit + fixed a crash when doing undo and a validator is set. Emit + textChanged() also if the text changed because of undo or redo. + +- QListBox + fixed RMB context-menu offset. + +- QListView + do not start renaming an item is CTRL or SHIFT is + pressed. Start renaming on mouse release, not mouse press, so + click + click + move on the same item does not start a rename + operation. + +- QMainWindow + show dock-menu also when clicking on the menubar. + +- QPainter + win32 only: improved printing performance through printer font + caching. + boundingRect(): ignore 0-width in the constrain rectangle. + +- QPicture + added overload for load() that takes a QIODevice. + +- QPrintDialog (internal dialog) + fixed enabling of the first page and last page labels. + +- QPrinter + win32 only: make setColorMode() work, some unicode fixes. Make + collate the default. Enable the collate checkbox without + losing the page selection if you want to print multiple + pages. Make the collateCopies property work that it knows + checks/unchecks the collate checkbox in the printing + dialog. Make settings also work when the print dialog is not + shown at all. + +- QProcess + added a new communication mode that duplicates stderr to + stdout (i.e. the equivalent of the shell's 2>&1). + +- QPSPrinter (unix) + fixed collate. + +- QRangeControl + simplified code. + +- QRichText + Propagate WhiteSpaceMode to subitems with + WhiteSpaceModeNormal. Hide DisplayModeNone + items without additional newline. Fixed links inside non-left + aligned tables. Fixed some bidi layout problems. Fixed last + line layout in right-aligned paragraphs. For plain text, + always use the palette's text color. + +- QScrollView + safer destruction. + +- QSettings + win32 only: fixed a dead lock situation when writing + to LOCAL_MACHINE, but reading from CURRENT_USER. + +- QSGIStyle + fixed drawing of checkable menu items. + +- QSimpleRichText + use the specified default font. + +- QSlider + optimized drawing in the new style engine. + +- QString + QString::replace() with a regular expression requires a + QRegExp object, passing a plain string will cause a compile + error. + +- QStyleSheet + additional parameter 'whitespacemode' for + QStyleSheet::convertFromPlainText(). Support for superscript + ('sup') and subscript ( 'sub' ). + +- QTabBar + react properly on runtime font changes, less flicker. + +- QTable + take the pixmap of a header section into account when + adjusting the size. + +- QTabWidget + use the embedded tabbar as focus proxy. + +- QThread + win32 only: possible crash with the thread dictionary fixed. + +- QValidator + In Q{Int,Double}Validator, consider '-' as Invalid rather than + Intermediate if bottom() >= 0. + +- QWidget + made showFullScreen() multihead aware. + win32 only: Better size and position restoring when switching + between fullscreen, maximized and minimized. + x11 only: improvements to XIM, overthespot works correctly + now. + +- QWorkspace + smarter placement of the minimize button when there is no + maximize button. Make titlebars of tool windows a bit smaller. + Improved styleability. Do not maximize a widget that has a + maximum size that is smaller than the workspace. + + + +**************************************************************************** +* Other * +**************************************************************************** + +- moc + fixed generation of uncompilable code in conjunction with + Q_ENUMS and signal/slots. + +- unicode + allow keyboard switching of paragraph directionality. + +- installation + install $QTDIR/doc/html/ instead of $QTDIR/doc/ + install Qt Designer templates as well. + +- improved build on + HP-UX with cc. + Solaris 8 with gcc 3.0.1. + AIX with xlC and aCC. + +- inputmethods + x11 only: do not reset the input context on focus changes. + +- uic + smaller improvements, handle additional form signals. + +- Qt Designer + make it possible to add new signals to a form without + subclassing. Minor fixes. + +- Qt Assistant + fixed Shift-LMB selection bug. Fixed new window and window + restoration on restart. + +- Qt Linguist + change fourth parameter of QApplication::translate() from bool + to enum type. This affects MOC (new revision) and lupdate (new + syntax to parse). Change Qt Linguist's XML file format (.ts) + to be consistent with QApplication: (rather than + ) to match QApp::defaultCodec(); encoding="UTF-8" + (rather than utf8="true") to match QApp::translate(). Fixed + window decoration on restart. Use 'finished', 'unfinished' and + 'unresolved' instead of the (!), (?) symbols on printouts. + +- QMsDev + merge "Add UIC" and "New Dialog". Better user interface and + general cleanup. Wwrite (and merge) qmake pro file with active + project. Load qmake pro files into Visual Studio. + + diff --git a/dist/changes-3.0.0-beta1 b/dist/changes-3.0.0-beta1 new file mode 100644 index 0000000..2c73e77 --- /dev/null +++ b/dist/changes-3.0.0-beta1 @@ -0,0 +1,1239 @@ +Qt 3.0 adds a lot of new features and improvements over the Qt 2.x +series. Some internals have undergone major redesign and new classes +and methods have been added. + +We have tried to keep the API of Qt 3.0 as compatible as possible with +the Qt 2.x series. For most applications only minor changes will be +needed to compile and run them successfully using Qt 3.0. + +One of the major new features that has been added in the 3.0 release +is a module allowing you to easily work with databases. The API is +platform independent and database neutral. This module is seamlessly +integrated into Qt Designer, greatly simplifying the process of +building database applications and using data aware widgets. + +Other major new features include a component architecture allowing you +to build cross platform components, 'plugins' with Qt. You can use +your own and third party plugins your own applications. The Unicode +support of Qt 2.x has been greatly enhanced, it now includes full +support for scripts written from right to left (e.g. Arabic and +Hebrew) and also provides improved support for Asian languages. + +Many new classes have been added to the Qt Library. Amongst them are +classes that provide a docking architecture (QDockArea/QDockWindow), a +powerful rich text editor (QTextEdit), a class to store and access +application settings (QSettings) and a class to create and communicate +with processes (QProcess). + +Apart from the changes in the library itself a lot has been done to +make the development of Qt applications with Qt 3.0 even easier than +before. Two new applications have been added: Qt Linguist is a tool to +help you translate your application into different languages; Qt +Assistant is an easy to use help browser for the Qt documentation that +supports bookmarks and can search by keyword. + +Another change concerns the Qt build system, which has been reworked +to make it a lot easier to port Qt to new platforms. You can use this +platform independent build system for your own applications. + + +The Qt Library +======================================== + +A large number of new features has been added to Qt 3.0. The following +list gives an overview of the most important new and changed aspects +of the Qt library. A full list of every new method follows the +overview. + + +Database support +---------------- + +One of the major new features in Qt 3.0 is the SQL module that +provides cross-platform access to SQL databases, making database +application programming with Qt seamless and portable. The API, built +with standard SQL, is database-neutral and software development is +independent of the underlying database. + +A collection of tightly focused C++ classes are provided to give the +programmer direct access to SQL databases. Developers can send raw SQL +to the database server or have the Qt SQL classes generate SQL queries +automatically. Drivers for Oracle, PostgreSQL, MySQL and ODBC are +available and writing new drivers is straightforward. + +Tying the results of SQL queries to GUI components is fully supported +by Qt's SQL widgets. These classes include a tabular data widget +(for spreadsheet-like data presentation with in-place editing), a +form-based data browser (which provides data navigation and edit +functions) and a form-based data viewer (which provides read-only +forms). This framework can be extended by using custom field editors, +allowing for example, a data table to use custom widgets for in-place +editing. The SQL module fully supports Qt's signal/slots mechanism, +making it easy for developers to include their own data validation and +auditing code. + +Qt Designer fully supports Qt's SQL module. All SQL widgets can be +laid out within Qt Designer, and relationships can be established +between controls visually. Many interactions can be defined purely in +terms of Qt's signals/slots mechanism directly in Qt Designer. + + +Component model - plugins +------------------------- + +The QLibrary class provides a platform independent wrapper for runtime +loading of shared libraries. Access to the shared libraries uses a +COM-like interface. QPluginManager makes it trivial to implement +plugin support in applications. The Qt library is able to load +additional styles, database drivers and text codecs from plugins which +implement the relevant interfaces, e.g. QStyleFactoryInterface, +QSqlDriverInterface or QTextCodecInterface. It is possible to remove +unused components from the Qt library, and easy to extend any +application with 3rd party styles, database drivers or text codecs. + +Qt Designer supports custom widgets in plugins, and will use the +widgets both when designing and previewing forms. + +QComponentFactory makes it easy to register any kind of component in a +global database (e.g. the Windows Registry) and to use any registered +component. + + +Rich text engine and editor +--------------------------- + +The rich text engine originally introduced in Qt 2.0 has been further +optimized and extended to support editing. It allows editing formatted +text with different fonts, colors, paragraph styles, tables and +images. The editor supports different word wrap modes, command-based +undo/redo, multiple selections, drag and drop, and many other +features. The engine is highly optimized for proccesing and displaying +large documents quickly and efficiently. + + +Unicode +------- + +Apart from the rich text engine, another new feature of Qt 3.0 that +relates to text handling is the greatly improved Unicode support. Qt +3.0 includes an implementation of the bidirectional algorithm (BiDi) +as defined in the Unicode standard and a shaping engine for Arabic, +which gives full native language support to Arabic and Hebrew speaking +people. At the same time the support for Asian languages has been +greatly enhanced. + +The support is almost transparent for the developer using Qt to +develop their applications. This means that developers who developed +applications using Qt 2.x will automatically gain the full support for +these languages when switching to Qt 3.0. Developers can rely on their +application to work for people using writing systems different from +Latin1, without having to worry about the complexities involved with +these scripts, as Qt takes care of this automatically. + + +Docked and Floating Windows +--------------------------- + +Qt 3.0 introduces the concept of Dock Windows and Dock Areas. Dock +windows are widgets, that can be attached to, and detached from, dock +areas. The commonest kind of dock window is a tool bar. Any number of +dock windows may be placed in a dock area. A main window can have dock +areas, for example, QMainWindow provides four dock areas (top, left, +bottom, right) by default. The user can freely move dock windows and +place them at a convenient place in a dock area, or drag them out of +the application and have them float freely as top level windows in +their own right. Dock windows can also be minimized or hidden. + +For developers, dock windows behave just like ordinary widgets. QToolbar +for example is now a specialized subclass of a dock window. The API +of QMainWindow and QToolBar is source compatible with Qt 2.x, so +existing code which uses these classes will continue to work. + + +Regular Expressions +------------------- + +Qt has always provided regular expression support, but that support +was pretty much limited to what was required in common GUI control +elements such as file dialogs. Qt 3.0 introduces a new regular +expression engine that supports most of Perl's regex features and is +Unicode based. The most useful additions are support for parentheses +(capturing and non-capturing) and backreferences. + + +Storing application settings +---------------------------- + +Most programs will need to store some settings between runs, for +example, user selected fonts, colors and other preferences, or a list +of recently used files. The new QSettings class provides a platform +independent way to achieve this goal. The API makes it easy to store +and retrieve most of the basic data types used in Qt (such as basic +C++ types, strings, lists, colors, etc). The class uses the registry +on the Windows platform and traditional resource files on Unix. + + +Creating and controlling other processes +---------------------------------------- + +QProcess is a class that allows you to start other programs from +within a Qt application in a platform independent manner. It gives you +full control over the started program, for example you can redirect +the input and output of console applications. + + +Accessibility (not part of the beta1 release) +--------------------------------------------- + +Accessibility means making software usable and accessible to a wide +range of users, including those with disabilities. In Qt 3.0, most +widgets provide accessibility information for assistive tools that can +be used by a wide range of disabled users. Qt standard widgets like +buttons or range controls are fully supported. Support for complex +widgets, like e.g. QListView, is in development. Existing applications +that make use of standard widgets will become accessible just by using +Qt 3.0. + +Qt uses the Active Accessibility infrastructure on Windows, and needs +the MSAA SDK, which is part of most platform SDKs. With improving +standardization of accessibility on other platforms, Qt will support +assistive technologies on other systems, too. + +The accessibility API in Qt is not yet stable, which is why we decided +not to make it a part of the beta1 release. + + +XML Improvements +---------------- + +The XML framework introduced in Qt 2.2 has been vastly improved. Qt +2.2 already supported level 1 of the Document Object Model (DOM), a +W3C standard for accessing and modifying XML documents. Qt 3.0 has +added support for DOM Level 2 and XML namespaces. + +The XML parser has been extended to allow incremental parsing of XML +documents. This allows you to start parsing the document directly +after the first parts of the data have arrived, and to continue +whenever new data is available. This is especially useful if the XML +document is read from a slow source, e.g. over the network, as it +allows the application to start working on the data at a very early +stage. + + +SVG support +----------- + +SVG is a W3C standard for "Scalable Vector Graphics". Qt 3.0's SVG +support means that QPicture can optionally generate and import static +SVG documents. All the SVG features that have an equivalent in +QPainter are supported. + + +Multihead support +----------------- + +Many professional applications, such as DTP and CAD software, are able +to display data on two or more monitors. In Qt 3.0 the QDesktopWidget +class provides the application with runtime information about the +number and geometry of the desktops on the different monitors and such +allows applications to efficiently use a multi-monitor setup. + +The virtual desktop of Windows 98 and 2000 is supported, as well as +the traditional multi-screen and the newer Xinerama multihead setups +on X11. + + +X11 specific enhancements +------------------------- + +Qt 3.0 now complies with the NET WM Specification, recently adopted +by KDE 2.0. This allows easy integration and proper execution with +desktop environments that support the NET WM specification. + +The font handling on X11 has undergone major changes. QFont no longer +has a one-to-one relation with window system fonts. QFont is now a +logical font that can load multiple window system fonts to simplify +Unicode text display. This completely removes the burden of +changing/setting fonts for a specific locale/language from the +programmer. For end-users, any font can be used in any locale. For +example, a user in Norway will be able to see Korean text without +having to set their locale to Korean. + +Qt 3.0 also supports the new render extension recently added to +XFree86. This adds support for anti aliased text and pixmaps with +alpha channel (semi transparency) on the systems that support the +rendering extension (at the moment XFree 4.0.3 and later). + + +Printing +-------- + +Printing support has been enhanced on all platforms. The QPrinter +class now supports setting a virtual resolution for the painting +process. This makes WYSIWYG printing trivial, and also allows you to +take full advantage of the high resolution of a printer when painting +on it. + +The postscript driver built into Qt and used on Unix has been greatly +enhanced. It supports the embedding of true/open type and type1 fonts +into the document, and can correctly handle and display Unicode. +Support for fonts built into the printer has been enhanced and Qt now +knows about the most common printer fonts used for Asian languages. + + +QHttp +----- + +This class provides a simple interface for HTTP downloads and uploads. + + +Compatibility with the Standard Template Library (STL) +------------------------------------------------------ + +Support for the C++ Standard Template Library has been added to the Qt +Template Library (QTL). The QTL classes now contain appropriate copy +constructors and typedefs so that they can be freely mixed with other +STL containers and algorithms. In addition, new member functions have +been added to QTL template classes which correspond to STL-style +naming conventions (e.g., push_back()). + + +Qt Designer +======================================== + +Qt Designer was a pure dialog editor in Qt 2.2 but has now been +extended to provide the full functionality of a GUI design tool. + +This includes the ability to lay out main windows with menus and +toolbars. Actions can be edited within Qt Designer and then plugged +into toolbars and menu bars via drag and drop. Splitters can now be +used in a way similar to layouts to group widgets horizontally or +vertically. + +In Qt 2.2, many of the dialogs created by Qt Designer had to be +subclassed to implement functionality beyond the predefined signal and +slot connections. Whilst the subclassing approach is still fully supported, +Qt Designer now offers an alternative: a plugin for editing +slots. The editor offers features such as syntax highlighting, +completion, parentheses matching and incremental search. + +The functionality of Qt Designer can now be extended via plugins. +Using Qt Designer's interface or by implementing one of the provided +interfaces in a plugin, a two way communication between plugin and Qt +Designer can be established. This functionality is used to implement +plugins for custom widgets, so that they can be used as real widgets +inside the designer. + +Basic support for project management has been added. This allows you +to read and edit *.pro files, add and remove files to/from the project +and do some global operations on the project. You can now open the +project file and have one-click access to all the *.ui forms in the +project. + +In addition to generating code via uic, Qt Designer now supports the +dynamic creation of widgets directly from XML user interface +description files (*.ui files) at runtime. This eliminates the need of +recompiling your application when the GUI changes, and could be used +to enable your customers to do their own customizations. Technically, +the feature is provided by a new class, QWidgetFactory in the +QResource library. + + +Qt Linguist +======================================== + +Qt Linguist is a GUI utility to support translating the user-visible +text in applications written with Qt. It comes with two command-line +tools: lupdate and lrelease. + +Translation of a Qt application is a three-step process: + + 1) Run lupdate to extract user-visible text from the C++ source + code of the Qt application, resulting in a translation source file + (a *.ts file). + 2) Provide translations for the source texts in the *.ts file using + Qt Linguist. + 3) Run lrelease to obtain a light-weight message file (a *.qm file) + from the *.ts file, which provides very fast lookup for released + applications. + +Qt Linguist is a tool suitable for use by translators. Each +user-visible (source) text is characterized by the text itself, a +context (usually the name of the C++ class containing the text), and +an optional comment to help the translator. The C++ class name will +usually be the name of the relevant dialog, and the comment will often +contain instructions that describe how to navigate to the relevant +dialog. + +You can create phrase books for Qt Linguist to provide common +translations to help ensure consistency and to speed up the +translation process. Whenever a translator navigates to a new text to +translate, Qt Linguist uses an intelligent algorithm to provide a list +of possible translations: the list is composed of relevant text from +any open phrase books and also from identical or similar text that has +already been translated. + +Once a translation is complete it can be marked as "done"; such +translations are included in the *.qm file. Text that has not been +"done" is included in the *.qm file in its original form. Although Qt +Linguist is a GUI application with dock windows and mouse control, +toolbars, etc., it has a full set of keyboard shortcuts to make +translation as fast and efficient as possible. + +When the Qt application that you're developing evolves (e.g. from +version 1.0 to version 1.1), the utility lupdate merges the source +texts from the new version with the previous translation source file, +reusing existing translations. In some typical cases, lupdate may +suggest translations. These translations are marked as unfinished, so +you can easily find and check them. + + +Qt Assistant +======================================== + +Due to the positive feedback we received about the help system built +into Qt Designer, we decided to offer this part as a separate +application called Qt Assistant. Qt Assistant can be used to browse +the Qt class documentation as well as the manuals for Qt Designer and +Qt Linguist. It offers index searching, a contents overview, bookmarks +history and incremental search. Qt Assistant is used by both Qt +Designer and Qt Linguist for browsing their help documentation. + + +QMake +======================================== + +To ease portability we now provide the qmake utility to replace tmake. +QMake is a C++ version of tmake which offers additional functionallity +that is difficult to reproduce in tmake. Trolltech uses qmake in its +build system for Qt and related products and we have released it as +free software. + + +Qt Functions +======================================== + +QAction +------- + +All new functions: + void addedTo( QWidget *actionWidget, QWidget *container ); + void addedTo( int index, QPopupMenu *menu ); + +QActionGroup +------------ + +New mode "uses drop down", where members are shown in a separate +subwidget such as a combobox or a submenu (enable with +setUsesDropDown(TRUE) ) + +All new functions: + void add(QAction*); + void addSeparator(); + void addedTo( QWidget *actionWidget, QWidget *container, QAction *a ); + void addedTo( int index, QPopupMenu *menu, QAction *a ); + void setUsesDropDown( bool enable ); + bool usesDropDown() const; + + +QApplication +------------ + +Added the setStyle(const QString&) overload that takes the name of the +style as its argument. This loads a style plugin via a QStyleFactory. + +desktop() now returns a QDesktopWidget that provides access to +multi-head information. Prior to 3.0, it returned a normal QWidget. + +New functions to define the library search path for plugins +(setLibraryPaths, ...). + +New functions to define reverse layout for bidirectional languages +(setReverseLayout, ...). + +All new functions: + bool hasPendingEvents() + + void setLibraryPaths(const QStringList &); + QStringList libraryPaths(); + void addLibraryPath(const QString &); + void removeLibraryPath(const QString &); + + void setReverseLayout( bool b ); + bool reverseLayout(); + int horizontalAlignment( int align ); + + + +QClipboard +---------- + +On systems that support it, for example X11, QClipboard now +differentiates between the primary selection and the data in the clipboard. + +All new functions: + bool supportsSelection() const; + bool ownsClipboard() const; + void setSelectionMode(bool enable); + bool selectionModeEnabled() const; +New signals: + void selectionChanged() + + + +QCursor +------- + +Now inherits Qt namespace. Enum values like ArrowCursor, +UpArrowCursor, CrossCursor etc. are now part of that namespace. + + +QDataStream +----------- + +Added missing operators for Q_LONG and Q_ULONG + + +QDateTime / QDate / QTime +------------------------- + +More sophisticated toString() function that takes a DateFormat, where +DateFormat can be either TextDate (the default), ISODate (ISO 8601) or +LocalDate (locale dependent). + +All new functions: + QDate addMonths( int months ) const; + QDate addYears( int years ) const; + QDate fromString( const QString& s, Qt::DateFormat f = Qt::TextDate ); + static QString shortMonthName( int month ); + static QString longMonthName( int month ); + static QString shortDayName( int weekday ); + static QString longDayName( int weekday ); + static void setShortMonthNames( const QStringList& names ); + static void setLongMonthNames( const QStringList& names ); + static void setShortDayNames( const QStringList& names ); + static void setLongDayNames( const QStringList& names ); + +QDialog +------- + +Merged with QSemiModal. Calling show() on a modal dialog will return +immediately, not enter a local event loop. Showing a modal dialog in +its own event loop is achieved using exec(). + +exec() is now a public slot. + +Usability: For widgets supporting What's This help, QDialog +automatically offers a context menu containing a "What's This?" entry. + + +QEvent +------ + +Mouse events are now propagated up to the toplevel widget if no widget +accepts them and no event filter filters them out. In previous Qt +versions, only key events were propagated. + +All events carry a flag 'spontaneous' to determine whether the even +came from the outside or was generated by code within the +applications. Previously, only show and hide events had this flag. + +Enter/Leave event generation has been fixed. Previously, a widget +received a leave event when the mouse pointer entered one of its +children. This was both unnatural and contradictive to the +documentation. + +QWheelevent now carries an orientation to differentiate between +horizontal and vertical wheels. + +QFocusEvent: new reason 'Backtab' (previously only 'Tab' was +available). This makes it possible to discover from what direction on +the tab-focus chain the widget was entered. + +New events: QContextMenuEvent, QIMEvent + + +QFile +----- + +Ported from int to Q_LONG to prepare for large file sizes on 64 bit +systems. + +Filter handling made more flexible. + + +QFileDialog +----------- + +All new Functions: + void setSelectedFilter( const QString& ); + void setSelectedFilter( int ); +New signals: + void filesSelected( const QStringList& ); + void filterSelected( const QString& ); + +If you try to specify an invalid file when using getOpenFileName(s), an error message +will appear and the file will not be accepted. In 2.x, this function behaved differently +because users were using getOpenFileName(s) as a Save File Dialog; you should use +getSaveFileName() when you require a Save File Dialog. + + +QCanvas Module +-------------- + + New classes: + QCanvasSpline - a multi-bezier spline + + QCanvasItemList + void update(); + + QCanvas: + QRect rect() const; + void setUnchanged( const QRect& area ); + void drawArea(const QRect&, QPainter* p, bool double_buffer); + void drawViewArea( QCanvasView* view, QPainter* p, const QRect& r, bool dbuf ); + QRect changeBounds(const QRect& inarea); + + QCanvasView: + const QWMatrix &worldMatrix() const; + const QWMatrix &inverseWorldMatrix() const; + void setWorldMatrix( const QWMatrix & ); + QCanvasSprite: + int leftEdge() const; + int topEdge() const; + int rightEdge() const; + int bottomEdge() const; + int leftEdge(int nx) const; + int topEdge(int ny) const; + int rightEdge(int nx) const; + int bottomEdge(int ny) const; + +QCanvasSprite can now be set to animate its frames without the need to +subclass. + + +QFont, QFontDatabase, QFontInfo, QFontMetrics +--------------------------------------------- + +The QFont::CharSet enum has been removed and replaced with the +QFont::Script enum. With this change, a QFont is not associated with a +specific character set. Instead, QFont uses Unicode Scripts for +loading fonts. On platforms where most fonts do not use the Unicode +encoding (currently only X11), multiple locale and character-set +dependent fonts can be loaded for the individual Unicode Scripts. + +Another new feature of QFont is a much more flexible substitution +mechanism. Each family can have a list of appropriate substitutes. The +font substitution feature allows you to specify a list of substitute +fonts. Substitute fonts are used when a font cannot be loaded, or if +the specified font doesn't have a particular character (X11 only). + +For example (on X11), you select the font Lucida, which doesn't have +Korean characters. For Korean text, you want to use the Mincho font +family. By adding Mincho to the list, any Korean characters not found +in Lucida will be used from Mincho. Because the font substitutions are +lists, you can also select multiple families, such as Song Ti (for use +with Chinese text). + +QFontInfo and QFontMetrics had small API changes related to the +disappearance of QFont::CharSet. In terms of functionality, the +behavior of these classes is unchanged. + +QFontDatabase had several API cleanups related to the disappearance of +QFont::CharSet. Most QFontDatabase member functions take one less +argument, yet compatibility functions still exist to keep old source +code working. + +Family and style names returned from QFontDatabase are now processed +and formatted in a way that is suitable for display to users. Family +and foundry names are capitalized and foundry names are enclosed in +square brackets after the family name. For example, the Helvetica +font family might have 3 different foundries: Adobe, Cronyx and +Phaisarn. In 2.x, QFontDatabase listed them like this: + + adobe-helvetica + cronyx-helvetica + phaisarn-helvetica + +Starting with 3.0, QFontDatabase lists them like this: + + Helvetica [Adobe] + Helvetica [Cronyx] + Helvetica [Phaisarn] + + +QFrame +------ + +Two new frame shapes for more sophisticated style features: +MenuBarPanel and ToolBarPanel. + + +QGrid +----- + +The member type + + enum Direction { Horizontal, Vertical }; + +has been eliminated, as it is redundant: use Qt::Orientation instead. +Old code referring to QGrid::Horizontal or QGrid::Vertical will still +work, as QGrid counts Qt among its ancestors. + + +QGroupBox +--------- + +More functionality of the built-in layout is exposed: + + int insideMargin() const; + int insideSpacing() const; + void setInsideMargin( int m ); + void setInsideSpacing( int s ); + + +QHeader +------- + +New property: bool stretching + +New functions: + bool isStretchEnabled( int section ); + void setStretchEnabled( bool b, int section ); + + +QIconSet +-------- + +In addition to the mode - which can be either Normal, Disabled or +Active - QIconSet now supports different pixmaps for a state, i.e. On +or Off. The functions pixmap() and setPixmap() have been extended +accordingly. + +The default constructor no longer initializes the iconset to +contain a null pixmap. QIconSet::isNull() returns TRUE for un- +initialized iconsets, and pixmap() still returns a null pixmap for +pixmaps that couldn't be generated. + + +QIconView +--------- + +Extended findItem() to support ComparisonFlags. Support for +soft-hyphens when doing word wrap. + +New signal: + contextMenuRequested( QIconViewItem*, const QPoint& pos); + + +QIconViewItem +------------- + +Added support for explicit rtti. + +New function: + int rtti() const; + + + +QListBox +-------- + +Extended findItem() to support ComparisonFlags. + +New signal: + void contextMenu( QListBoxItem *, const QPoint & ); + + +QListBoxItem +------------ + +Added support for explicit rtti. + +New function: + int rtti() const; + + + +QListView +--------- + +It was never really hard to implement drag and drop with QListView, +but since many applications demand this functionality today, we +decided to add it to the listview itself. + +In addition, in-place editing and per-item tooltips have been added. +Extended findItem() to support ComparisonFlags + +New properties: + bool showToolTips + ResizeMode resizeMode + +New signals: + contextMenuRequested( QIconViewItem*, const QPoint& pos); + void dropped( QDropEvent *e ); + void itemRenamed( QListViewItem *item, int col, const QString & ); + void itemRenamed( QListViewItem *item, int col ); + +New functions: + void setResizeMode( ResizeMode m ); + ResizeMode resizeMode() const; + QDragObject *dragObject(); + void startDrag(); + void startRename(); + + +QListViewItem +------------- + +Added support for explicit rtti. + +New functions: + void setDragEnabled( bool allow ); + void setDropEnabled( bool allow ); + bool dragEnabled() const; + bool dropEnabled() const; + bool acceptDrop( const QMimeSource *mime ) const; + void setVisible( bool b ); + bool isVisible() const; + void setRenameEnabled( int col, bool b ); + bool renameEnabled( int col ) const; + void startRename( int col ); + void setEnabled( bool b ); + bool isEnabled() const; + int rtti() const; + + void dropped( QDropEvent *e ); + void dragEntered(); + void dragLeft(); + void okRename( int col ); + void cancelRename( int col ); + + +QLabel +------ + +In addition to text, rich text, pixmaps and movies, QLabel can now +display QPicture vector graphics. + +New functions: + + QPicture *picture() const; + void setPicture( const QPicture & ); + + +QLineEdit +--------- + +New property: bool dragEnabled + +New signal: + contextMenuRequested( QIconViewItem*, const QPoint& pos); + +New functions: + void cursorForward( bool mark, int steps = 1 ); + void cursorBackward( bool mark, int steps = 1 ); + void cursorWordForward( bool mark ); + void cursorWordBackward( bool mark ); + bool dragEnabled(); + void setDragEnabled( bool b ); + + +QMainWindow +----------- + +Added a dock window architecture. Previous versions of QMainWindow +could only deal with toolbars, now they handle generalized dock +windows. QToolBar inherits QDockWindow. + + +New property: + bool dockWindowsMovable; + +New signals: + void dockWindowPositionChanged( QDockWindow * ); + +New functions: + void setDockEnabled( Dock dock, bool enable ); + bool isDockEnabled( Dock dock ) const; + bool isDockEnabled( QDockArea *area ) const; + void setDockEnabled( QDockWindow *tb, Dock dock, bool enable ); + bool isDockEnabled( QDockWindow *tb, Dock dock ) const; + bool isDockEnabled( QDockWindow *tb, QDockArea *area ) const; + + void addDockWindow( QDockWindow *, Dock = Top, bool newLine = FALSE ); + void addDockWindow( QDockWindow *, const QString &label, Dock = Top, bool newLine = FALSE ); + void moveDockWindow( QDockWindow *, Dock = Top ); + void moveDockWindow( QDockWindow *, Dock, bool nl, int index, int extraOffset = -1 ); + void removeDockWindow( QDockWindow * ); + + QDockArea *dockingArea( const QPoint &p ); + QDockArea *leftDock() const; + QDockArea *rightDock() const; + QDockArea *topDock() const; + QDockArea *bottomDock() const; + + bool isCustomizable() const; + bool appropriate( QDockWindow *dw ) const; + QPopupMenu *createDockWindowMenu( DockWindows dockWindows = AllDockWindows ) const; + + bool showDockMenu( const QPoint &globalPos ); + + +QMetaObject +----------- + +###TODO + + +QMimeSourceFactory +------------------ + +New static functions: + QMimeSourceFactory* takeDefaultFactory(); + static void addFactory( QMimeSourceFactory *f ); + + +QNetworkProtocol +---------------- + +Spelling fix in Error::ErrListChildren enum. + + +QRegExp +------- + +QRegExp now has a more complete regular expression engine similar to +Perl's, with full Unicode and backreference support. + +New functions: + bool minimal() const; + void setMinimal( bool minimal ); + bool exactMatch( const QString& str ); + bool exactMatch( const QString& str ) const; + int search( const QString& str, int start = 0 ); + int search( const QString& str, int start = 0 ) const; + int searchRev( const QString& str, int start = -1 ); + int searchRev( const QString& str, int start = -1 ) const; + int matchedLength(); + QStringList capturedTexts(); + QString cap( int nth = 0 ); + int pos( int nth = 0 ); + + +QSessionManager +--------------- + +Renamed the misnamed setProperty() overloads to setManagerProperty() +to resolve the conflict with the now virtual QObject::setProperty(). + + +QString +------- + +New functions: + bool endsWith( const QString & ); + int similarityWith( const QString & ); + +### TODO + +QStyle +------ + +### TODO + +QTabBar +------- + +The extended QTabWidget support in Qt Designer made two more +functions handy to have: + QTab * tabAt( int ) const; + int indexOf( int ) const; + + + +QToolBar +-------- + +Inherits QDockWindow now, previously only QWidget. + + +QToolButton +----------- + +New property: + QIconSet iconSet + +New functions: + QIconSet iconSet() const; + virtual void setIconSet( const QIconSet & ); + +QWidget +------- + +New functions: + + const QColor & eraseColor() const; + virtual void setEraseColor( const QColor & ); + const QPixmap * erasePixmap() const; + virtual void setErasePixmap( const QPixmap & ); + + + +QWizard +------- + +New property: QString titleFont + +New functions: + QFont titleFont() const; + void setTitleFont( const QFont & ); + int indexOf( QWidget* ) const; + + +QWMatrix +-------- + +New function: + bool isIdentity() const; + + +QGL Module +---------- + +QGLWidget +New functions: + QGLFormat requestedFormat() const; + QImage grabFrameBuffer( bool withAlpha = FALSE ); + + +QWorkspace Module +----------------- + +A new property scrollBarsEnabled makes it possible to add on-demand +scrollbars to the workspace. We define this property in Qt Designer to +make designing forms larger than the available space on the desktop +more comfortable. + +New property: + bool scrollBarsEnabled + + +QXML Module +----------- +Many new functions have been added: + QDomImplementation + QDomDocumentType createDocumentType( const QString& qName, const QString& publicId, const QString& systemId ); + QDomDocument createDocument( const QString& nsURI, const QString& qName, const QDomDocumentType& doctype ); + QDomNode + QDomNode insertBefore( const QDomNode& newChild, const QDomNode& refChild ); + QDomNode insertAfter( const QDomNode& newChild, const QDomNode& refChild ); + QDomNode replaceChild( const QDomNode& newChild, const QDomNode& oldChild ); + QDomNode removeChild( const QDomNode& oldChild ); + QDomNode appendChild( const QDomNode& newChild ); + bool hasChildNodes() const; + QDomNode cloneNode( bool deep = TRUE ) const; + void normalize(); + bool isSupported( const QString& feature, const QString& version ) const; + QString namespaceURI() const; + QString localName() const; + bool hasAttributes() const; + QDomDocument + bool setContent( const QCString& text, bool namespaceProcessing=FALSE ); + bool setContent( const QByteArray& text, bool namespaceProcessing=FALSE ); + bool setContent( const QString& text, bool namespaceProcessing=FALSE ); + bool setContent( QIODevice* dev, bool namespaceProcessing=FALSE ); + QDomNamedNodeMap + QDomNode namedItemNS( const QString& nsURI, const QString& localName ) const; + QDomNode setNamedItemNS( const QDomNode& newNode ); + QDomNode removeNamedItemNS( const QString& nsURI, const QString& localName ); + + QDomElement + QString attributeNS( const QString nsURI, const QString& localName, const QString& defValue ) const; + void setAttributeNS( const QString nsURI, const QString& qName, const QString& value ); + void setAttributeNS( const QString nsURI, const QString& qName, int value ); + void setAttributeNS( const QString nsURI, const QString& qName, uint value ); + void setAttributeNS( const QString nsURI, const QString& qName, double value ); + void removeAttributeNS( const QString& nsURI, const QString& localName ); + QDomAttr attributeNodeNS( const QString& nsURI, const QString& localName ); + QDomAttr setAttributeNodeNS( const QDomAttr& newAttr ); + QDomNodeList elementsByTagNameNS( const QString& nsURI, const QString& localName ) const; + bool hasAttributeNS( const QString& nsURI, const QString& localName ) const; + + + QXmlAttributes + void clear(); + void append( const QString &qName, const QString &uri, const QString &localPart, const QString &value ); + + QXmlInputSource: + void setData( const QByteArray& dat ); + void fetchData(); + QString data(); + QChar next(); + void reset(); + QString fromRawData( const QByteArray &data, bool beginning = FALSE ); + + QXmlSimpleReader: + bool parse( const QXmlInputSource& input, bool incremental ); + bool parseContinue(); + + QXmlEntityResolver: + bool startEntity( const QString& name ); + bool endEntity( const QString& name ); + + + +New classes +----------- + +QAquaStyle (only on MacOS X) +QCleanupHandler +QComponentFactory +QComponentFactoryInterface +QComponentServerInterface +QContextMenuEvent +QDesktopWidget +QDockArea +QDockWindow +QErrorMessage +QFeatureListInterface +QHttp [network] +QInterfaceListInterface +QInterfacePtr +QIMEvent +QLibrary +QLibraryInterface +QStyleFactory +QStyleInterface +QTextCodecInterface +QUnknownInterface +QUuid +QRegExpValidator +QTextEdit + + +Renamed Classes +--------------- + +QArray has been renamed QMemArray +QCollection has been renamed QPtrCollection +QList has been renamed QPtrList +QListIterator has been renamed QPtrListIterator +QQueue has been renamed QPtrQueue +QStack has been renamed QPtrStack +QVector has been renamed QPtrVector + +The include file names have changed accordingly (e.g., ). + + +New Modules +----------- + +SQL + QDataBrowser + QDataTable + QDataView + QDateTimeEdit + QEditFactory + + +Obsolete classes +---------------- + + QSemiModal, use QDialog instead. + QMultiLineEdit, use QTextEdit instead. + QTableView, use QScrollView or QTable instead. + QAsyncIO, QDataSink, QDataSource, QDataPump and QIODeviceSource + + +Obsolete functions +------------------ + QActionGroup::insert( QAction * ), use QActionGroup::add( QAction* ) instead. + QApplication::setWinStyleHighlightColor( const QColor &c ), use setPalette() instead + QApplication::winStyleHighlightColor(), use palette() instead + QDir::encodedEntryList( int filterSpec, int sortSpec ), use QDir::entryList() instead + QDir::encodedEntryList( const QString &nameFilter, int filterSpec, int sortSpec ), use QDir::entryList() instead + QMainWindow::addToolBar( QDockWindow *, Dock = Top, bool newLine = FALSE ); + QMainWindow::addToolBar( QDockWindow *, const QString &label, Dock = Top, bool newLine = FALSE ); + QMainWindow::moveToolBar( QDockWindow *, Dock = Top ); + QMainWindow::moveToolBar( QDockWindow *, Dock, bool nl, int index, int extraOffset = -1 ); + QMainWindow::removeToolBar( QDockWindow * ); + QMainWindow::toolBarsMovable() const; + QMainWindow::toolBars( Dock dock ) const; + QMainWindow::lineUpToolBars( bool keepNewLines = FALSE ); + QRegExp::match( const QString& str, int index = 0, int *len = 0, + bool indexIsStart = TRUE ); + QToolButton::setOnIconSet( const QIconSet & ) + QToolButton::setOffIconSet( const QIconSet & ) + QToolButton::onIconSet() const + QToolButton::offIconSet() const + QToolButton::setIconSet( const QIconSet & set, bool on ) + QToolButton::iconSet( bool on ) const + QXmlInputSource::QXmlInputSource( QFile& file ), use QXmlInputSource( QIODevice *dev ) instead. + QXmlInputSource::QXmlInputSource( QTextStream& stream ), use QXmlInputSource( QIODevice *dev ) instead. + +Removed functions: + QWidget::setFontPropagation + QWidget::setPalettePropagation + QMenuBar::setActItem + QMenuBar::setWindowsAltMode + QCheckListItem::paintBranches + QString::visual + QString::basicDirection + QRegExp::find( const QString& str, int index ) const; - has been renamed QRegExp::search() + QFont::charSet() const, not needed anymore + QFont::setCharSet( QFont::CharSet ), not needed anymore + QPushButton::upButton(), not relevant anymore + QPushButton::downButton(), not relevant anymore + QSpinBox::upButton(), not relevant anymore + QSpinBox::downButton(), not relevant anymore + + +Removed preprocessor directives +------------------------------- + + qcstring.h no longer contains the following defines: + + #define strlen qstrlen + #define strcpy qstrcpy + #define strcmp qstrcmp + #define strncmp qstrncmp + #define stricmp qstricmp + #define strnicmp qstrnicmp + + These directives were meant to automagically replace calls to the + above listed standard C functions with the equivalent Qt wrappers. + The latter pre-check the input parameters for null pointers as those + might cause crashes on some platforms. + + Although convenient, this trick turned out to sometimes conflict with + third-party code, or, simply be nullified by standard system and + library headers depending on version and include order. + + The name of some debugging macro variables has been changed. + + DEBUG becomes QT_DEBUG + NO_DEBUG becomes QT_NO_DEBUG + NO_CHECK becomes QT_NO_CHECK + CHECK_STATE becomes QT_CHECK_STATE + CHECK_RANGE becomes QT_CHECK_RANGE + CHECK_NULL becomes QT_CHECK_NULL + CHECK_MATH becomes QT_CHECK_MATH + + The name of some other debugging macro functions has also been changed + but source compatibility should not be affected if the macro variable + QT_CLEAN_NAMESPACE is not defined: + + ASSERT becomes Q_ASSERT + CHECK_PTR becomes Q_CHECK_PTR + + For the record these undocumented macro variables that are not part of + the API have been changed: + + _OS_*_ becomes Q_OS_* + _WS_*_ becomes Q_WS_* + _CC_*_ becomes Q_CC_* + + +[Qt 3.0] + diff --git a/dist/changes-3.0.0-beta2 b/dist/changes-3.0.0-beta2 new file mode 100644 index 0000000..0d55b12 --- /dev/null +++ b/dist/changes-3.0.0-beta2 @@ -0,0 +1,363 @@ +Qt 3.0 Beta2 is not binary compatible with Beta1, this means that any +programs linked with Beta1 must be recompiled. + +Below you'll find a description of general changes in the Qt Library +and Qt Designer followed by a detailed list of changes in the +programming API. + + +The Qt Library +======================================== + +Wacom Tablet Support +-------------------- + +Support for Wacom brand tablets has been introduced on Irix and +Windows. These devices generate a QTabletEvent that can be handled by +QWidget::tabletEvent(). The QTabletEvent holds information about +pressure, X and Y tilt, and which device is being used (e.g. stylus or +eraser). Note: at present, there are known issues with the Windows +version. + +Documentation +------------- + +Overall enhancements including fixed typos and the addition of several +images and code examples. + +QStyle (and derived classes) +---------------------------- + +The style API has been completely rewritten in Qt 3.0. The main reason +for doing this was because it was getting inconsistent, hard to +maintain and extend. Most of the old 2.x functions have been replaced +by a small set of more general functions. The new API is: + + - much more consistent + - less work have to be done to create custom styles + - easier to extend and maintain binary compatibility + +The old API relied upon a host of virtual functions that were +re-implemented in the different styles. These functions were used to +draw parts of, or entire widgets. The new API uses a small set of more +general functions. Enumerated values are passed as parameters to these +functions to specify which parts of a control or widget is to be drawn +(e.g drawPrimitive( PE_ArrowUp, ...)). + +To create custom styles with the new API, simply subclass from the +preferred base style and re-implement the function that draws the part +of the widget you want to change. If you for example want to change +the look of the arrows that are used in QWindowsStyle, subclass from +it and re-implement the drawPrimitive() function. Your drawPrimitive() +function may look something like this: + +void QMyStyle::drawPrimitive( PrimitiveElement pe, ... ) +{ + switch( pe ) { + case PE_ArrowUp: + // draw up arrow + break; + case PE_ArrowDown: + // draw down arrow + break; + default: + // let the base class handle the rest of the drawing + QWindowsStyle::drawPrimitive( ... ); + break; + } +} + +For more information about the new style API, please read the QStyle +documentation. + + +Qt Designer +======================================== + + - Improved indentation algorithm for the code editor. + - Allow multiple code editors to be open. This makes copy and paste + much easier. + + +Qt Functions +======================================== + +QCanvas +------- + + - QCanvas does not react on windowActivationChange() anymore. + - 64 bit cleanup. + +QChar +----- + + - The Unicode character is stored host ordered now. Main advantage is + that you can directly cast a QChar array to an array of unsigned shorts. + +QCom +---- + + - Introduced QS_OK, QS_FALSE, QE_NOINTERFACE, QE_INVALIDARG and + QE_NOIMPL as possible QRESULT return values. + +QDate, QTime and QDateTime +-------------------------- + + - New function for outputting free form strings and new DateFormat + enum Qt::LocalDate. + +New functions: + QString toString( const QString& format ); + +QDir +---- + + - entryInfoList() returns 0 for non-existing directories on Windows + as the documentation claims and the Unix version already does. + - On Windows, QDir tries a more failsafe way to determine the home + directory. + +QDom +---- + + - QDomNode::hasChildNodes() now works as documented. + - QDomDocument::toString() includes now namespaces in its output. + - QDomDocument::QDomDocument() constructor now allows adding children + to the document. + +QFileDialog +----------- + + - Various fixes in file type filter and handling of file names and + directories. + +QEvent +------ + + - New event type DeferredDelete. See QObject changes below. + +QGL +--- + + - Fix for Irix in respect of installing colormaps. + - Swapped arguments of QGLColormap::setEntries() in order to be able + to use a meaningful default argument. + +New class: + QGLColormap - class for manipulating colormaps in GL index mode. + +QGridView +--------- + +A new class that provides an abstract base for fixed-size grids. + +QIconSet +-------- + +New function: + void clearGenerated(); + +QImage +------ + + - Handlers for image formats can be dynamically loaded as a plug-in by + using the QImageFormatInterface. + +QLabel +------ + + - setIndent() behaves like documented. + +QLineEdit +--------- + +New function: + int characterAt( int xpos, QChar *chr ) const; + +QLibrary +-------- + +Enabled plug-in loading with static Qt library (Windows). + +QMovie +------ + + - Does pixmap caching now. Reduces load e.g. on the X Server in the + case of animated gifs. + +QObject +------- + + - Added a deferredDelete() function that will cause the object to + delete itself once the event loop is entered again. + + - A second type of destroyed signal - one that passes a pointer to + the destroyed object as a parameter - will be emitted in QObject's + destructor. + +New signal: + void destroyed( QObject* obj ); + +New slot: + void deferredDelete(); + +QPainter +-------- + + - So far clipping had always been done in the device coordinate + system. The newly introduced ClipMode allows clipping regions to be + set via setClipRect() and setClipRegion() in painter coordinates. + +New enum: + enum ClipMode { ClipDevice, ClipPainter }; + +Extended functions: + QRegion clipRegion( ClipMode = ClipDevice ) const; + void setClipRect( const QRect &, ClipMode = ClipDevice ) + void setClipRect( int x, int y, int w, int h, ClipMode = ClipDevice ); + void setClipRegion( const QRegion &, ClipMode = ClipDevice ); + +QPrintDialog +------------ + + - Allow overriding the default print dialog. This way it's possible + to better cope with the variety of existing print systems (API not + finalized, yet). + - The dialog reads current QPrinter on every invocation now. + +New functions: + static void setGlobalPrintDialog( QPrintDialog * ); + virtual bool setupPrinters ( QListView *printers ); + +QPrinter +-------- + + - X11 version only: Introduced Qt settings switch 'embedFonts' that + allows disabling font embedding to reduce size of PostScript output. + +QProcess +-------- + + - Added function to retrieve the pid (Unix) or PROCESS_INFORMATION + (Windows) from a running process. + - Extra parameter for environment settings in start() and launch() + functions. + +New/extended functions: + PID processIdentifier(); + virtual bool start( QStringList *env=0 ); + virtual bool launch( const QString& buf, QStringList *env=0 ); + virtual bool launch( const QByteArray& buf, QStringList *env=0 ); + +New signal: + void launchFinished(); + +QServerSocket +------------- + + - Set the SO_REUSEADDR option so that the server can be restarted. + +QSocket +------- + + - Make deletion of QSocket instances safe if it is in response to a + signal emitted by the object itself. + +SocketDevice +------------ + + - Optional boolean parameter to be able to distinguish between + timeout and connection closed by peer when waitForMore() returns. + +Extended functions: + int waitForMore( int msecs, bool *timeout=0 ) const; + +QStyleSheet +----------- + + - Added helper function that escapes HTML meta-characters. + +New function: + QString escape( const QString& plain); + +QSql +---- + + - The source of the SQL driver plug-ins have been moved to + $QTDIR/plugins/src/sqldrivers/. + - The postgres driver checks the version number of the server. So there is + no need for different drivers: QPSQL6 no longer exists -- use QPSQL7 + instead. + - Postgres driver supports now 3 PostgreSQL back ends: 6.x, 7.0.x and 7.1.x + - Better handling of errors coming from the database. + - SQL driver for Microsoft SQL Server and Sybase Adaptive Server (TDS). + - Added caching for forward-only cursors. + - Avoid crashes on the unloading of SQL plugins that occurred on some + platforms. + - QSqlResults can be forward only to improve performance + (QSqlResult::setForwardOnly()). + - QSqlDatabase passes the port number to the SQL driver. + +QTable +------ + + - No longer calls processEvents() in columnWidthChanged() and + rowHeightChanged() in order to avoid any side effects. + - Ensure that mousePressEvent doesn't emit contextMenuRequested(), + unless it is called from the contextMenu event handler. + - For more useful subclassing the new functions listed below have + been added. + +New functions: + bool isEditing() const; + EditMode editMode() const; + int currEditRow() const; + int currEditCol() const; + +QTextCodec +---------- + + - Fixes for characters in the 0x80..0xff range. + +QTextEdit +--------- + + - The rich text engine has seen many internal improvements and + additions to the QTextEdit class. + +New functions: + virtual void scrollToBottom(); + virtual void removeSelection( int selNum = 0 ); + virtual bool getParagraphFormat(...); + virtual void insertParagraph( const QString &text, int para ); + virtual void removeParagraph( int para ); + virtual void insertAt( const QString &text, int para, int index ); + QRect paragraphRect( int para ) const; + int paragraphAt( const QPoint &pos ) const; + int charAt( const QPoint &pos, int *para ) const; + +QUrlOperator +------------ + + - More precise error messages. + +QWidget +------- + + - Added a read-only property containing the widget's background brush. + +New function: + virtual const QBrush& backgroundBrush() const; + +QWMatrix +-------- + + - New functions for mapping of geometric elements via matrix + multiplication semantics. + +New functions: + QRect mapRect( const QRect & ); + QPoint operator * (const QPoint & ) const; + QRegion operator * (const QRect & ) const; + QRegion operator * (const QRegion & ) const; + QPointArray operator * ( const QPointArray &a ) const; diff --git a/dist/changes-3.0.0-beta3 b/dist/changes-3.0.0-beta3 new file mode 100644 index 0000000..cc49e6e --- /dev/null +++ b/dist/changes-3.0.0-beta3 @@ -0,0 +1,278 @@ +Qt 3.0 Beta3 is not binary compatible with Beta2, this means that any +programs linked with Beta2 must be recompiled. + +Below you'll find a description of general changes in the Qt Library +and Qt Designer followed by a detailed list of changes in the +programming API. + + +The Qt Library +======================================== + +Documentation +------------- + +Overall enhancements include fixed typos, corrected grammar and +spelling, and the addition of several images and code examples. Most +classes now have useful detailed descriptions. Documentation accuracy +and usability has been generally improved. + +Styles +------ + +In Qt 3.0.0 Beta2, only the Windows and Motif styles were implemented with +the new style API. Now the missing styles (MotifPlus, Platinum, SGI and +CDE) are included. + +MNG +--- + +Updated the libmng that is shipped with Qt to version 1.0.2. + +Wacom Tablet Support +-------------------- + +Fixes for Windows to solve the problem of creating a context for every +widget and the problem of opening the dialog and losing the ability to use +the tablet afterwards. + + +Qt Designer +======================================== + + - Added the ability to sort the property editor either by category + (default and old behaviour) or alphabetically. + + - Added the option "-nofwd" to uic which supresses the generation of + forward declarations for custom classes in the generated output. + +- The way how custom slots and editing these slots directly in the Qt + Designer is handled has been changed. Originally the code for these + slots was saved into the .ui XML file together with the user + interface description and the uic did put this code into the + generated source files. + Now, if code of custom slots is edited directly in the Qt Designer, + additionally to the .ui of a form, a .ui.h file + is created. The code is written into this source file now instead + of the .ui file. + This way the code of custom slots can be also easily edited outside + the Qt Designer without subclassing, and it is possible to edit it + both, in the Qt Designer and outside the Qt Designer without + conflicts, as this is a plain text C++ file. + Uic now automatically includes this source file into the generated + sources (if it exists) and, in this case, does not create empty + stubs for the custom slots in the generated sources anymore. So + this code file has not to be added to the project Makefile. If the + source file does not exist, uic falls back to the old behavior and + creates the empty stubs in the generated source. + If a user does not want to subclass to implement the custom slots, + but also does not want to edit the code of the custom slots in the + Qt Designer, it is possible to always create the .ui.h + for a form (even if it was not edited in the Qt Designer) and edit + that file in a seperate editor. This feature can be configured in + the project settings dialog. + This way, the old approach of subclassing keeps working (and all + old .ui files keep working without any change). Also, for users of + the previous Qt 3.0 Beta versions, Qt Designer can still read the + .ui files which contain code. So also .ui files created with Qt 3.0 + Beta versions of the Qt Designer keep working without any change. + Details about the possible concepts which can be used to add code + to a form created by the Qt Designer (subclassing and uic + + .ui.h) and related information about project management + can be found in the chapter about new features in Qt Designer 3.0 + in the Qt Designer manual. + + +Qt Functions +======================================== + +QApplication +------------ + + - flush() no longer calls sendPostedEvents(), as this might be unsafe + under certain circumstances. + +QDataTable +---------- + + - Now uses the new row selection mode of QTable. + +QDomDocument +------------ + + - Fixed the toString() function to work properly with namespaces. + - In Qt 3.0.0 Beta2, there was a workaround for Microsoft's XML parser, + so that the toString() function did not output a doctype that consists + only of the name. This workaround is semantically wrong; it was + reverted. + +QDateEdit +--------- + + - Fixed wrong default size policy and missing size hint. + - Improved focus and tab handling. + +QEffects +-------- + + - Tooltips and popup menus scroll and fade again + +QTable +------ + + - Fixed right mouse button handling. + - Implemented row selection modes. This implied adding the new enum values + SingleRow and MultiRow to the enum SelectionMode. + - Doubleclick clears selections completely now. + - Allow different focus styles, namely FollowStyle (draw it as the style + tells you) and SpreadSheet (draw it as it is done in common spreadsheet + programs). + +New functions: + virtual void setFocusStyle( FocusStyle fs ); + FocusStyle focusStyle() const; + virtual QRect cellRect( int row, int col ) const; + +QTimeEdit +--------- + + - Fixed wrong default size policy and missing size hint. + - Improved focus and tab handling. + +QTextEdit +--------- + + - QTextCursor is an internal class, so the signal + cursorPositionChanged(QTextCursor*) is only of limited use. Added a + more useful signal in addition. + + - Overrides accelerators for all shortcuts used to edit text. + +New signal: + void cursorPositionChanged( int para, int pos ); + +QLineEdit +--------- + + - Overrides accelerators for all shortcuts used to edit text. + +QLibrary +-------- + + - Static overload for resolve as a convenience function. + +New function: + static void *resolve( const QString &filename, const char * ); + +QListView +--------- + + - A bug that was introduced in Qt 3.0.0 beta 2 made listviews with + lots of items very slow. This problem has been fixed. + +QProcess +-------- + + - exitStatus() did not work for negative values on Unix. This is fixed + now. + - Fixed problems on Unixware. + +QRichtext +--------- + + - Fixed searching backwards. + - Fixed some BIDI text-rendering problems. + +QSound +------ + + - Simplified the API to allow easier extension. + +New functions: + bool isAvailable(); + int loops() const; + int loopsRemaining() const; + void setLoops(int); + QString fileName() const; + bool isFinished() const; + +New slot: + void stop(); + +Removed function: + bool available(); + +QSpinBox +-------- + + - Spin box arrows were not updated correctly when the widget was + disabled/enabled. This problem is fixed now. + - Improved handling of the case when a spinbox accepts a value: now it + also accepts it if the spinbox loses focus or is hidden. + +QSqlCursor +---------- + + - Add functions to set the generated flag. This is used to avoid the + generation of malformed SQL statements. + +New functions: + void setGenerated( const QString& name, bool generated ); + void setGenerated( int i, bool generated ); + +QSqlDriver +---------- + + - Add new function hasFeature( QSqlDriver::DriverFeature ) const which + allows you to query whether the driver supports features like SQL + transactions or Binary Large Object fields. The functions + hasQuerySizeSupport(), canEditBinaryFields() and hasTransactionSupport() + are therefore obsolete and have been removed. + +New function: + bool hasFeature( QSqlDriver::DriverFeature ) const; + +Removed functions: + bool hasQuerySizeSupport() const; + bool canEditBinaryFields() const; + bool hasTransactionSupport() const; + +QSqlField +--------- + + - The bool argument of setNull() was removed since it does not make sense + to set a field to non null. + +QTabWidget +---------- + + - Use the functions below to add tool tips to the individual tabs in a + QTabWidget. + +New functions: + void removeTabToolTip( QWidget * w ); + void setTabToolTip( QWidget * w, const QString & tip ); + QString tabToolTip( QWidget * w ) const; + +QTabBar +------- + + - Use the functions below to add tool tips to the individual tabs in a + QTabBar. + +New functions: + void removeToolTip( int id ); + void setToolTip( int id, const QString & tip ); + QString toolTip( int id ) const; + +QTextStream +----------- + + - The global functions setw(), setfill() and setprecison() were deleted + since they conflict with the std classes. If you need the functionality, + use qSetW(), qSetFill() and qSetPrecision() instead. + +Removed functions: + QTSManip setw( int w ) + QTSManip setfill( int f ) + QTSManip setprecision( int p ) diff --git a/dist/changes-3.0.0-beta4 b/dist/changes-3.0.0-beta4 new file mode 100644 index 0000000..a3f44a5 --- /dev/null +++ b/dist/changes-3.0.0-beta4 @@ -0,0 +1,688 @@ +Qt 3.0 Beta4 is not binary compatible with Beta3; any programs linked +against Beta3 must be recompiled. + +Below you will find a description of general changes in the Qt +Library and Qt Designer followed by a detailed list of changes in the +API. + + +The Qt Library +======================================== + +Documentation +------------- + +The extensive revision of the documentation is almost complete. +We have added new navigation options, including a shorter list +of classes entitled Main Classes. + +Translations +------------ + +Qt now includes French and German translations of the Qt library, as +well as a template for translating Qt. These files are found in the +translations directory of Qt, in both .ts and .qm formats. + +Style Fixes +----------- + +Qt 3.0.0 beta2 introduced a new QStyle API. This new API has changed +between beta3 and beta4. These changes will affect both widget +writers and style writers. The QStyle entry below explains what has +changed. + +Beta4 also introduces some fixes for bugs introduced during the port +to the new API in various widgets, notably QComboBox and QSlider. + +LiveConnect Plugin +------------------ + +A few bugs were fixed in the LiveConnect Plugin so that the grapher +example works again on Windows. + + +Qt Designer +======================================== + + - General usability improvements and bug fixes, and improved file + and project handling. + - Updated designer manual to cover the .ui.h mechanism. + - New auto-indentation algorithm in the code editor. + + +Qt Assistant +======================================== + + - Added a Settings dialog and made more features customizable. + - Sessions are now saved and restored. + - A brief introduction to using Qt Assistant is now included. + + +Qt Linguist +======================================== + + - Phrase books are now provided in tools/linguist/phrasebooks. + - Added support for Qt Designer's .ui.h mechanism to lupdate. + - Support for a larger subset of .pro file syntax in lupdate and + lrelease. + + +Qt Functions +======================================== + +QApplication +------------ + + - Ignore drag-and-drop events for disabled widgets. + - Always send ChildRemoved events, even if no ChildInserted event + was sent. + - Mouse events for popup menus are now sent to event filters. + +QCanvasItem +----------- + + - The functions visible(), selected() and active() have been renamed + setVisible(), setSelected() and setActive(). + +New functions: + bool isVisible() const; + bool isSelected() const; + bool isActive() const; + +Removed functions: + bool visible() const; + bool selected() const; + bool active() const; + +QCanvasText +----------- + + - Fixed alignment flags. + +QChar +----- + +New function: + bool isSymbol() const; + +QCheckBox +--------- + + - Fixed a bug in pixmap caching which could result in using the + wrong pixmap. + +QCheckListItem +-------------- + + - After a mouse click, the list view ignores the following double + click as in Windows XP. + +QClipboard +---------- + + - Made clipboard operations faster on X11. + +QColorDialog +------------ + + - Never show scrollbars in the color array. + +QComboBox +--------- + + - Comboboxes are now drawn correctly in all styles. + - Fixed bug with auto completion. There was undefined behavior with + non-editable comboboxes when changing focus. + +New function: + virtual void setCurrentText( const QString& ); + +New property: + QString currentText + +QDataBrowser +------------ + + - The setCursor() function is obsolete and will be removed for Qt 3 + release due to the incompatibility with some compilers. Use + setSqlCursor() instead. + +QDataTable +---------- + + - Dates and times in tables can now be displayed in different + display formats. + - The setCursor() function is obsolete and will be removed for Qt 3 + release due to the incompatibility with some compilers. Use + setSqlCursor() instead. + +QDateEdit +--------- + + - The default separator and the day-month-year order respect the + user's settings. + - Pressing the separator key now skips to the next section. + - Fixed a usability flaw related to some months being longer than + others. + +New functions: + QString separator() const; + virtual void setSeparator( const QString& s ); + +QDateTime +--------- + + - Always initialize the tm struct completely. This fixes a problem + on some versions of Unix. + +QDir +---- + + - QDir::homeDirectory() now always returns an existing directory on + Windows. + +QDockWindows +------------ + + - Fixed dockwindows created in non-dock areas. + - Fixed constructor if InDock and the parent is a QMainWindow. + +QDom... +------- + + - Fixes in the conversion of the DOM tree to a string. + +QDomNodeList +------------ + + - Fixed a crash. + +QFileDialog +----------- + + - Select contents of the line edit at startup (if any) so that the + user can overwrite the provided file name right away. + +QFileInfo +--------- + + - In adition to lastModified() and lastRead(), provide created(). + +New function: + QDateTime created() const; + +QFont +----- + + - Provide more correct font metrics under X11. + - Worked around X11 limits on length of strings to draw and on + coordinate sizes. + - Fixed sone point vs. pixel size issues under X11. + - Added PreferAntialias and NoAntialias flags to StyleStrategy enum + type. + +QFtp +---- + + - Fixed a QSocket bug that made QFtp crash if the connection was + refused. + - Fixed operationRename() and operationRemove(). + - Set the right state when finished. + +QGIFFormat +---------- + + - Support GIF files with broken logical screen size. + +QHeader +------- + + - Added support for '\n' in header labels. + - Improved placement of icon. + +QHttp +----- + + - If the status code of the reply is an error code, it is now also + reflected in the status of the network operation. The error + handling in general was improved. + +QImageIO +-------- + + - Allow gamma correction to be set programmatically. + +New functions: + void setGamma( float gamma ); + float gamma() const; + +QKeyEvent +--------- + + - Worked around an X11 bug in isAutoRepeat(). + +QKeySequence +------------ + +A new class that encapsulates a key sequence as used by accelerators. + +QLabel +------ + + - Made the WordBreak alignment property work with rich text labels + in addition to plain text labels. + +QLayout +------- + + - Fixed crashes with deleting widgets managed by the layout. + - Fixed problems with reparenting widgets managed by the layout. + - Respect maximumHeight() of items in heightForWidth(). + +QLibrary +-------- + + - Plugins now return the version number, threading model and debug + vs. release mode of the Qt library used in ucm_initialize(). If + there is any kind of incompatibility, cancel the loading. + +QLineEdit +--------- + + - Update the "edited" flag and the accessibility data better than + before. + - Fixed setMaxLength(). + - Fixed context menu problem on Windows. + +New functions: + bool isUndoAvailable() const; + bool isRedoAvailable() const; + +QListViewItem +------------- + + - Fixed setVisible(TRUE) which triggered an update too soon. + +QMenuBar +-------- + + - Cancel alt-activation of menubar on mouse press/release. + - On wheel events, all popup menus are now closed instead of hidden. + Hiding popup menus confused QMenuBar. + +QObject +------- + + - Have QObject dispatch events to customEvents(). + +QPainter +-------- + + - Renamed the enum type ClipMode to CoordinateMode. The enum values + ClipDevice and ClipPainter are now called CoordDevice and + CoordPainter. + - Fixed escaping of ampersand character, so "&&", "&&&", etc., now + work as they did in Qt 2.x. + +New functions: + void drawPixmap( const QRect& r, const QPixmap& pm ); + void drawImage( const QRect& r, const QImage& img ); + +QPicture +-------- + + - Respect the size of a loaded SVG document. + - Solved a replay-transformed-picture problem. + - Fixed format version number. + +QPluginManager +-------------- + + - Fixed crash when loading a plugin fails. + +QPopupMenu +---------- + + - Custom menu items that are separators now see their size hint + respected. + - Fixed crash when drawing an empty popup menu. + +QPrinter +-------- + + - Better printing in different resolutions under both Windows and + X11. + - Support for collation under Windows and X11. + - Correct bounding rectangles for texts in all printer modes. + - Fixed pixmap printing on Windows. + - Fixed PostScript font names for fonts with foundries. + - Support for PostScript printing of scaled images. + +New functions: + bool collateCopiesEnabled() const; + void setCollateCopiesEnabled( bool enable ) const; + bool collateCopies() const; + void setCollateCopies( bool on ); + int winPageSize() const; /* Windows only */ + +QProcess +-------- + + - The function hangUp() was renamed to tryTerminate() to make the + purpose more clear. Furthermore, under Unix, the signal that is + sent was changed from SIGHUP to SIGTERM. + - The function kill() and the function tryTerminate() (formerly + hangUp()) were made slots. + +New slots: + void tryTerminate(); + void kill(); + +Removed functions: + void hangUp(); + void kill(); + +QProgressBar +------------ + + - Draw the progress bar correctly with respect to the properties + "percentageVisible", "indicatorFollowsStyle" and + "centerIndicator". + +QPtrVector +---------- + + - Support null items without triggering an assert. + +QPushButton +----------- + + - Fixed the sizeHint() of buttons with an icon. + +QRegExp +------- + + - Fixed a subtle bug in regular expressions mixing anchors and + alternation. + +QRegion +------- + + - Don't crash when creating a QRegion from an empty point array. + +QRichText +--------- + + - Improved alignment support, including nested alignments. + - Improved table margin support. + - Improved page break algorithm. + - Do not eat '\n' in preformatted items. + - Do not draw the internal trailing space at the end of a paragraph. + - Fixed link underlining in table cells and other subdocuments. + - Use larger vertical margin between paragraphs. + - Display paragraph spacing even when printing. + - Support vertical table cell alignment. + - Fix for floating items and table cell size calculation. + - Improved allignment handling. + - Offset fixes for tabs. + - Better
support. + - Fixed
tag. + - Fix for the tag and centering tables. + - Fixed   and . + - Fixed off-by-one bug in gotoWordLeft() and gotoWordRight(). + - Better positioning of super- and subscripts. + - Faster printing of large tables by using a clipping rectangle. + - Improved high-resolution printing. + - Correct sizes for images when printing. + - Fixed list painting when printing. + - Use right background for printing. + +QScrollBar +---------- + + - Made setValue() a slot. + +New slot: + void setValue( int ); + +Removed function: + void setValue( int ); + +QSettings +--------- + + - Added support for QStringLists without requiring a distinct + separator. + - Added support for null strings, empty lists and null strings in + lists. + - Fixed bug with values ending with a backslash. + - On Unix, don't overwrite files if the user doesn't have permission. + +QSimpleRichText +--------------- + + - Implemented vertical breaks and floating elememts. + - Fixed bug with borders and clipping in printing. + - Fixed bug in adjustSize() cache. + +QSizePolicy +----------- + + - Stretch factors were added to QSizePolicy. + - Added a new size policy: Ignored. + +New functions: + uint horStretch() const; + uint verStretch() const; + void setHorStretch( uchar sf ); + void setVerStretch( uchar sf ); + +QSpinBox +-------- + +New slot: + virtual void selectAll(); + +QSqlDatabase +------------ + + - QSqlDatabase now provides access to meta-data. Meta-data is stored + in two new classes, QSqlFieldInfo and QSqlRecordInfo. See the + class documentation for details. + +New Functions: + QSqlRecordInfo recordInfo ( const QString & tablename ) const + QSqlRecordInfo recordInfo ( const QSqlQuery & query ) const + + +QSqlFieldInfo +------------- + +A new class that stores meta data associated with a SQL field. + +QSqlRecordInfo +-------------- + +A new class that is keeping a set of QSqlFieldInfo objects. + +QStatusBar +---------- + + - Don't cut off the bottom line of the border of the status bar. + - Respect maximumHeight() of items in the status bar. + +QString +------- + + - QString now provides section(), a function that parses simple + fields. + - The function similarityWith() has been removed from the API. If + you need it, write to qt-bugs@trolltech.com. + +New functions: + QString section( QChar sep, int start, int end, + int flags = SectionDefault ) const; + QString section( char sep, int start, int end = 0xffffffff, + int flags = SectionDefault ) const; + QString section( const char *substr, int start, int end = 0xffffffff, + int flags = SectionDefault ) const; + QString section( QString substr, int start, int end = 0xffffffff, + int flags = SectionDefault ) const; + QString section( const QRegExp ®xp, int start, int end = 0xffffffff, + int flags = SectionDefault ) const; + +Removed function: + int similarityWith( const QString& target ) const; + +QStyle +------ + + - Changed "void **" technique to QStyleOption technique. This + affects the interface of most of the QStyle member functions. + Please read the QStyle class documentation for details. + +QStyleOption +------------ + +A new class that encapsulates extra data sent to the style API. + +QTabBar +------- + + - The accelerators are now working correctly after changing a tab. + +QTable +------ + + - Fixed crash related to popup menu and cell edition. + - Fixed not-drawing hidden cells. + +QTextCodec +---------- + + - Added MIME names for codecs. + - Improved locale detection. + - Fixed the ISO 8859-6.8x (Arabic) font encoding. + +New function: + const char *mimeName() const; + +QTextStream +----------- + + - Fixed bug with stateful QTextEncoders. + +QTextEdit +--------- + + - Respect disabling updates. + - Fixed link underlining in table cells and other subdocuments. + - Draw cursor on focus in. + - Emit cursorPositionChanged() where it previously was missing. + - Fixed sync(). + +New functions: + bool isUndoAvailable() const; + bool isRedoAvailable() const; + bool isUndoRedoEnabled() const; + virtual void setUndoRedoEnabled( bool enabled ) const; + +New property: + bool undoRedoEnabled + +QThread +------- + + - Fixed QThread::sleep() on Unix. + +QTime +----- + + - fromString() with format Qt::ISODate now recognizes milliseconds + if they are specified. + - Make elapsed() a const function. + +QTimeEdit +--------- + + - The default time separator respects the user's settings. + - Pressing the separator key now skips to the next section. + +New functions: + QString separator() const; + virtual void setSeparator( const QString& s ); + +QTooltip +-------- + + - Hide active tooltips when the user switches to another application. + - Fixed tooltips with Windows effects enabled. + +QUrl +---- + + - Fixed password encoding. + +New function: + bool hasPort() const; + +QValidator +---------- + + - Let QValidator, QIntValidator, QDoubleValidator and + QRegExpValidator have QObject parents rather than only QWidget + parents. + +QVariant +-------- + + - Added QBitArray support. + - The QDateTime type now supports asDate() and asTime(). + - The QByteArray type now supports toString(). + +New functions: + QVariant( const QBitArray& ); + const QBitArray toBitArray() const; + QBitArray& asBitArray(); + +QWhatsThis +---------- + + - Added support for hyperlinks in "What's This?" help windows. + +QWidget +------- + + - Fixed crashes related to LayoutHint events. + +QWizard +------- + + - Made removePage() behave as documented. + - Fixed back() so that it skips irrelevant pages like next(). + +QWorkspace +---------- + + - Make sure that the widget state is set before the first titlebar + painting is triggered. + - Use the right pixmap for titlebar. + - Respects widget flags better for titlebars in QCommonStyle. + - Fixed move and resize in the system menu bar of workspace + children. + +QXml +---- + + - Made the "prefix" xmlns map to the namespace name + http://www.w3.org/2000/xmlns/. + - Fixed default namespaces. + +QXmlAttributes +-------------- + + - Added count() as equivalent to length() to be consistent with Qt + conventions. + +New function: + int count() const; diff --git a/dist/changes-3.0.0-beta5 b/dist/changes-3.0.0-beta5 new file mode 100644 index 0000000..174a1b3 --- /dev/null +++ b/dist/changes-3.0.0-beta5 @@ -0,0 +1,316 @@ +Qt 3.0 beta 5 is not binary compatible with beta 4; any programs +linked against beta 4 must be recompiled. + +Below you will find a description of general changes in the Qt +Library and Qt Designer followed by a detailed list of changes in the +API. + + +The Qt Library +======================================== + +Documentation +------------- + +The extensive revision of Qt classes' documentation is complete. The +front page of the Qt documentation (index.html) has been redesigned +to provide better access to other documentation than class +documentation. + +OpenGL Module +------------- + +Qt beta 5 provides some fixes which will make rendering GL widgets to +pixmaps work on a wider range of X servers. + +QDateTimeEdit +------------- + +The QDateTimeEdit, QDateEdit and QTimeEdit widgets have been moved +from the SQL module to the Qt core widget set. All users of Qt can +now use these widgets. + + +Qt Designer +======================================== + + - Some bugs related to the .ui.h feature were fixed. + + - The generation of code related to QSqlCursor has been fixed. + + - When removing a slot implementation from the Qt Designer + interface, do not accidentally remove a preceding comment. + + - Improved the C++ code indenter in the editor for some C++ + constructs, including try-catch blocks. + + +Qt Linguist +======================================== + + - Fixed problem with loading phrase books containing non-ASCII + characters. + + +Qt Classes +======================================== + +QApplication +------------ + + - Fixed a clipboard bug related to drag-and-drop on X11. + +QColorDialog +------------ + + - Fixed repaint problem. + +QComboBox +--------- + + - Never inserts empty strings in the list. + - Use the drop-down listbox's size hint in the combobox if the + listbox has been set manually. + +QComponentInterface +------------------- + + - This class has been renamed QComponentInformationInterface. + +QComponentServerInterface +------------------------- + + - This class has been renamed QComponentRegistrationInterface. + +QDataBrowser +------------ + + - The setCursor() function is obsolete and has been removed due to + problems with some compilers. Use setSqlCursor() instead. + +QDataTable +---------- + + - Fixed a rare crash when the database is deleted while its popup is + still open. + - Made setColumnWidth() a public slot like in the base class. + - The setCursor() function is obsolete and has been removed due to + problems with some compilers. Use setSqlCursor() instead. + +QDateTimeEdit +------------- + + - Fixed the minimumSizeHint() for better behavior in a layout. + +QDom +---- + + - Added a sanity check. + +QFileDialog +----------- + + - Fixed a crash in MotifPlus style. + - Use the existing file-icon provider rather than the default + Windows one if one is set. + +QFont +----- + + - Fixed background color for more than 8 bits per channel. + - Added the font's pixel size to the value returned by key(). + +QFtp +---- + + - Correcty sets the default password to "anonymous". + +QGL +--- + + - Added robustness on X11 for invalid pixmap parameters. + +QImage +------ + + - Fixed loading of BGR BMP files. + - Changed the signature of the constructor to accept "const char * + const *" objects without a cast. + +QLatin1Codec +------------ + + - Provide the missing mimeName(). + +QLibrary +-------- + + - Construct Unix-specific filenames correctly. + +QLineEdit +--------- + + - Fixed offset for right-aligned text. + +QListView +--------- + + - Fixed a bug with in-place renaming. + +QMime +----- + + - Fixed infinite loop when searching for a mime-source. + +QMutex +------ + + - Unlock the Qt library mutex when enter_loop() is called the first + time, rather than when exec() is called. A programmer might call + QDialog::exec() and never QApplication::exec(), and then she will + wait for the mutex. + +QPixmap +------- + + - Do transformations correctly on big-endian systems. + +QPrinter +-------- + + - Respect the PRINTER environment variable on X11, as stated in the + documentation. + - Work around a display-context bug on Windows 95 and 98. + +QProcess +-------- + +New functions: + void clearArguments(); + int communication() const; + void setCommunication( int c ); + +QProgressBar +------------ + + - Fixed bug in repainting when a background pixmap is set. + +QPtrList +-------- + + - Reverted a semantics change introduced in beta 4 when deleting the + current item. + +QRegExp +------- + + - Fixed matchedLength() when used with exactMatch(). This bug + affected QRegExpValidator. + +QRichText +--------- + + - Added support for "color" attribute in
---
tag. + - Fixed selectedText(). + +QSqlCursor +---------- + + - Don't generate calculated fields. + +QStatusBar +---------- + + - Made addWidget() and removeWidget() virtual. + +QSpinBox +-------- + + - Fixed the minimumSizeHint() for better behavior in a layout. + +QStyle +------ + + - Allow separator custom menu items to use a different size than + specified by the style. + +Qt +-- + + - Renamed Qt::Top, Qt::Bottom, Qt::Left, Qt::Right to Qt::DockTop, + Qt::DockBottom, Qt::DockLeft, Qt::DockRight. + +QTable +------ + + - Fixed currentChanged() and valueChanged() emits. + +QTextEdit +--------- + + - Moved eventFilter() from the public slots section to the public + section of the class definition. + - Reformat after changing tab-stop size. + - Implemented undo for clear(). + +New function: + void zoomTo( int size ); + +QTextIStream +------------ + + - Fixed QTextIStream with a QString. + +QToolBar +-------- + + - Fall back to text property in extension popup if no pixmap label + has been set. + - Made mainWindow() const. + +QToolButton +----------- + + - Fixed the minimumSizeHint() for better behavior in a layout. + +QToolTip +-------- + + - Fixed the transparent tooltip effect a la Windows 2000. + +QUrl +---- + + - Fixed the return value of QUrl::dirPath() on Windows. + - Set ref to nothing when merging URLs. + +QUrlOperator +------------ + + - Added a default parameter for single copy to specify the "to" file + name and not just the file path. + +New function: + QPtrList copy( const QString& from, + const QString& to, bool move, bool toPath ); + +QValueList +---------- + + - Added a return value to remove(), as stated in the documentation. + +QWidget +------- + + - Fixed a bug in QPainter on X11 that caused a crash when paint + events were dispatched from other paint events. + - Fixed showMaximized() and deferred map handling. + - When specifying WDestructiveClose as a widget flag, + QWidget::close() does not immediately delete the widget anymore, but + calles QObject::deferredDelete() + + +QWorkspace +---------- + + - Fixed cascade(). diff --git a/dist/changes-3.0.0-beta6 b/dist/changes-3.0.0-beta6 new file mode 100644 index 0000000..dbed175 --- /dev/null +++ b/dist/changes-3.0.0-beta6 @@ -0,0 +1,272 @@ +Qt 3.0 Beta6 is not binary compatible with Beta5; any programs linked +against Beta5 must be recompiled. + +Below you will find a description of general changes in the Qt +Library, Qt Designer and Qt Assistant. Followed by a detailed list of +changes in the API. + + +The Qt Library +======================================== + +QCom postponed +-------------- + +Previous Qt 3.0 betas introduced a module called QCom that provides a +COM-like component system. The feedback we received on this module +during the 3.0 beta phase has been mixed. Many users think this module +lacks the intuitiveness and compactness that they have learned to +expect from a Qt API. Therefore, we have made the difficult decision +to withdraw the QCom API from the Qt 3.0 release. We will continue to +develop this API until it is evolved enough for our customers, and +will include the improved version in a later release. + +We apologize for any inconvenience the QCom API change has +caused. This decision was made as part of our ongoing efforts to +maintain the soundness and quality of Qt. + +Please note that the new plugin functionality in 3.0 will still be +provided. This includes using custom widgets in Qt Designer, as well +as runtime addition of styles, codecs, SQL drivers, and image format +handlers. This functionality is now available through a substantially +simplified API. + +Also also note that it will still be convenient to add custom plugin +capabilities to Qt 3.0 applications, since the new QLibrary class will +still be available. This class takes care of the low-level, +platform-dependent issues regarding loading of DLLs and obtaining +pointers to the functions exported by the DLLs. + + +Qt Designer +======================================== + + - Improvements to the Designer reference manual. + + - Improved the C++ code indenter in the editor for numbers and + handling of parenthesis. + + +Qt Assistant +======================================== + + - Added a context menu with common commands. + + - Allow multiple windows to be opened and added the common shortcut + that Shift+Click on a link opens the link in a new window. + + +Qt Functions +======================================== + +QAccel +------ + + - Try harder to ensure that accelerators continue to work when a top + level widget is reparented into another window. + +QColor +----- + + - X11 only: better heuristic to decide if you use black or white when a + color could not be allocated. + - win32 only: improve color allocation on 8bit displays, e.g. when + using a terminal server. + +QComboBox +--------- + + - Added a new function to be able to set a custom line edit. + +New function: + virtual void setLineEdit( QLineEdit *edit ); + +QCString +-------- + + - Implemented a dummy out-of-line destructor for QCString to help the + compiler to optimize the number of conflicts as the location of a vtable + is now known. + +QCursor +------- + + - win32 only: Added a constructor that takes a platform specific handle. + +New function: + QCursor( HCURSOR ); (win32 only) + +QDateTime and QDateTimeEdit +--------------------------- + + - win32 only: better handling of localization settings. + +QDockWindow +----------- + + - Remeber last size of an undocked window, so when it is docked and + undocked again, use this size again. + +QDom +---- + + - Fixed an infinite loop in QDomDocument::toString(). + +QFileDialog +----------- + + - Improved handling of "~" to make it work as a directory. + +QFileInfo +--------- + + - win32 only: permissions respects the read-only attribute now. + +QIconView +--------- + + - Added a function to find out whether an item in a view is currently + being renamed. + - Fixed a crash. + +New function: + bool isRenaming() const; + +QInputDialog +------------ + + - Improved the handling of double input formats. + +QListView +--------- + + - Added a function to find out whether an item in a view is currently + being renamed. + - Fixed a possible infinite loop. + - Improved spacing handling for columns that can show a sort indicator. + +New function: + bool isRenaming() const; + +QMainWindow +----------- + + - Make menuAboutToShow() protected to allow customized dock menus. + - Fixed spacing problem for menu bars. + +QMap +---- + + - Fixed infinite looping in count( const Key& k ). + +QObject +------- + + - The slot deferredDelete() was renamed to deleteLater() to be more + intuitive. Code that used deferredDelete() has to be adjusted for the + new name. + +New function: + void deleteLater(); + +QPainter +-------- + + - Fixed bounding rectangle when printing richtext. + - Restore brush origin in QPainter::restore(). + +QPixmap +------- + + - X11 with render extension only: better support for alpha blending: + - QPixmap::xForm() keeps now the alpha channel information + - alpha channel information is kept when copying QPixamps + - alpha blending works with QMovie + - tiling pixmaps with alpha channel works now + +QPrinter +-------- + + - Unix only: fixed dashed line drawing when using high resolution + printing. + - Better printing detection on Irix. + +QRadioButton +------------ + + - Fixed focus problem for radio buttons in a button group. + +QSqlCursor +---------- + + - Fixed primeInsert() to work if the primary key of the edit buffer has + changed. + - Changing primary index keys now also works if the cursor's position + moved in the meantime. + +QStyle +------ + + - Added a base value (CC_CustomBase) for custom defined primitives, + controls, etc. -- this allows custom widgets to use the new style + engine. + - Fixed spacing problem for custom menu items. + - Improved the look of the Motif plus and the SGI style. + +QTable +------ + + - Fixed a crash when drag source is the current table editor widget. + - Fixed a bug that prevented having different colors in different cells. + +QTabletEvent +------------ + + - Improved Watcom tablet support to allow multiple devices to be used. + +QTextEdit +--------- + + - Better handling for font sizes in the font tag. + - Parse the qt tag again. + - Fixed text() for read-only documents. + - Improved right mouse button menu handling. + - New function to pass the position to the createPopupMenu() function for + improved flexibility. + +New function: + virtual QPopupMenu *createPopupMenu( const QPoint& pos ); + +QThread +------- + + - Unix only: Make sure that the seconds and nano-seconds in the sleep + functions are within the limits. + +QUrlInfo +-------- + + - Added the concept of invalid QUrlInfo objects. This is useful in + conjunction with QUrlOperator::info(). + +New function: + bool isValid() const; + +QWizard +------- + + - Set the previous pages nextEnabled to TRUE if we add a page to the end + of a wizard. + +QWMatrix +-------- + + - mapRect() returns always a valid QRect now. + +QWorkspace +---------- + + - Update the titlebar when toggling shaded/non-shaded. + - Update the titlebar to be deactivated when the application's activation + status changes. + - Improve placement of document windows. diff --git a/dist/changes-3.0.1 b/dist/changes-3.0.1 new file mode 100644 index 0000000..26fb022 --- /dev/null +++ b/dist/changes-3.0.1 @@ -0,0 +1,540 @@ +Qt 3.0.1 is a bugfix release. It maintains both forward and backward +compatibility (source and binary) with Qt 3.0.0 + + +**************************************************************************** +* General * +**************************************************************************** + +- Style Engine fixes + Qt 3.0 introduced a new and more flexibile style engine. This + release should fix most of the small visual flaws that the new + styles introduced. It also greatly improves appearance in + right-to-left mode. + +- MS-Windows XP + This is the first release to fully support Windows XP, + including the new themable GUI styles. + The Windows XP style can only be built as a plugin, which requires + Qt to be configured as a shared library. To build the plugin + you must install a Microsoft Platform SDK for October 2001 + or later. Your INCLUDE and LIB environment variables must + point to the respective directories in the SDK installation. + +- Reverse (right-to-left) layouts + Many classes have improved support for right-to-left layouts. + +- Compile fixes + Solaris 7 Intel, g++ version 2.8.1. + +- Documentation updates + Some new and improved diagrams and minor textual revisions. + +- Mac only: Drag'n'drop + Mac only: QDropEvents can decode HFS flavors. + +- X11 only: Multi-head (multi-screen) improvements + Support for different TrueColor depths on each head (screen). + Drag'n'drop support across multiple screens. Tooltips always + stay on the correct screen. Improved OpenGL support on + multiple screens. Qt 3.1 will support different color depths + on every screen (e.g. one TrueColor screen, one 8-bit + PseudoColor and one 8-bit GreyScale). + + +**************************************************************************** +* Library * +**************************************************************************** + +- QAction + Fixed a memory leak in conjunction with action accelerators. + Turn toggle actions off when toggling is turned off with + setToggleAction(FALSE); + +- QApplication + Shared double buffers are cleaned up on destruction. + Creating and using multiple QApplications in the same process + is supported. + - Solaris only: Default to the Interface System font (which is + the default for the CDE) + - Win32 only: When WM_QUERYENDSESSION is received, _flushall + is called to ensure that all open streams and buffers are + flushed to disk (or to OS's buffers). + Better support for more input methods (e.g. Chinese). + Enter events are not propagated to modally blocked widgets. + Key_BackTab events are generated rather than Shift+Key_Tab. + Floating toolbars are blocked when the application is modal. + Move and Resize are disabled in the system menu for + maximized toplevel windows + - WinXP only: WM_THEMECHANGED messages are handled; widgets + are repolished with the appropriate style. + - X11 only: Removed misleading warning message for main + widgets on heads (screens) other than the default head. + Input context: Solved a memory leak in Xlib, and saved a + server round trip when updating the microfocushint. + Worked around some broken XmbLookupString implementations + that do not report buffer overflows correctly. + Key events are never given to a widget after clearFocus() + has been called for that widget; this is the same behavior + as Windows. + +- QAquaStyle (MacOS X only) + More optimizations and several minor visual bugs fixed. + +- QCanvas + Erase any exposed empty space when shrinking the canvas. + +- QCanvasPixmapArray + Initialize the framecount to 0. + +- QCanvasView + Optimize background pixmaps: potentially they were drawn + twice, first untranslated then translated. + +- QClipboard (X11 only) + The race conditions that cause KDE to lock-up occasionally + should now be fixed. + +- QComboBox + Fixed behavior with non-selectable items. Fixed a crash when + calling setCurrentItem(-1). Fixed autoscrolling when dragging + the mouse directly after opening the dropdown. + +- QColor + Make invalid named colors return a non-valid QColor (as + documented). + +- QColorDialog (Win32 only) + Use WStyle_DialogBorder, since resizing this dialog does not + make much sense. + +- QCommonStyle + Respect QApplication::globalStrut() in scroll bars. Support + reverse layout in QTitleBar. + +- QCursor + Safer cleanup of cursor shapes (avoids possible free'd memory + read) + - Win32 only: fixed application override cursor with mouse + grabbing. + +- QDate + Fixed some possible overflows. + - Win32 only: Improve locale support for short day and month + names etc. Initialize milliseconds correctly. + +- QDateTimeEdit + Display AM/PM if set by locale. Improved sizeHint(). + +- QDockAarea + More reliable sizeHint(). Better support for reverse layouts. + +- QDockWindow + Emit the placeChange() signal more reliably. Avoid floating + docks popping up everywhere before they have been positioned + and laid out. + +- QDesktopWidget + - X11 only: When using normal dualhead (not Xinerama), make + sure we report the correct screen number. + - Win32 only: refresh on WM_DISPLAYCHANGE. + +- QFrame + New panel styles LineEditPanel and TabWidgetPanel. This was + required by the new for Windows XP support. + +- QFileDialog + Show unicode filenames to the user rather than encoded ASCII + (e.g. previously latin1 characters were shown as "%XX" + escapes). + Fixed multiple-selection of FTP files. + Emit signal fileHighlighted in existingfile mode. + - Mac only: Fixed existingFolder(). Fixed window position so + that it will never fall outside the screen. + - Win32 only: since files, directories and drives are not case + sensitive, we don't add an extra entry in the paths box if + the path already exists but with different case. + +- QFileInfo (Unix only) + Make sure that symlinks pointing to invalid/non-existing + targets are reported as symlinks. + +- QFont + Ensure a rounded-off value is returned from pointSize(). + - x11 only: improved line width calculation. Fixed off by one + error in interpreting Xft font extents. Allow the use of + both Xft and non Xft fonts in the same application. Make + sure fonts are antialiased by default when using + xftfreetype. + +- QFontDialog + Prevent re-laying out when the size of the preview label + changes. + +- QFtp + In parseDir(), do not compare English month names to + shortMonthName(), since the latter is localized. + +- QGList + Make self-assignments work. + +- QGLWidget + Fixed ARGB to RGBA conversion on BigEndian systems. + - Win32 only: fixed colormap for 8-bit RGBA GL mode. + - X11 only: multiple heads with different color depths fixes. + +- QHebrewCodec + Assume the bidi algorithm is a reversible operation for the + visual 8859-8 codec. This is not true for very complex strings + but should hold in most cases. + +- QIconSet + Fixed detach() to really detach the internal pixmaps. In case + no image formats are installed, show black pixmaps rather than + ASSERT. + +- QImage + Allow 16-bit DIBs. Allow > 32767 level PNMs. + Fixed smoothscale() for the following bug: whenever + (new_width / original_width * 4096) is not an integer the last + column of the scaled image is black. + +- QImageIO + Fixed plugin loading in cases where the image format is + explicitly defined. + +- QInputDialog + Disable the OK button when input is not Acceptable. + (See QValidator.) + +- QLabel + When showing rich text with tables (via QSimpleRichtext), + avoid drawing the table background. + +- QLayout + In reverse layout mode: fix off by one error when laying out + right to left or bottom to top. + +- QLineEdit + Fixed offset calculation for horizontal scrolling. Invoke + validator when the user presses Backspace or + Delete. Compression of the undo/redo stack fixed. Security: do + not reveal the position of spaces with Ctrl+RightArrow or + Ctrl+LeftArrow in password mode. + +- QListBox + Append items at the proper position even after sorting the + content. Made QWidget::setBackgroundMode() work correctly. + +- QListBoxPixmap + Use the function pixmap() when drawing the pixmap, so users + can reimplement QListBoxPixmap::pixmap(). + +- QListView + Fix misalignment of checkbox click zone. Make the selected and + focus rectangles cover the entire column for QCheckListItems + if the listview root is not decorated. Make + QWidget::setBackgroundMode() on the viewport work correctly. + Comply with user interface guidelines: clear the selection + when a click is in an empty area unless the Ctrl key is down. + Fixed possible crash when starting a rename with a double + click. Smarter ensureItemVisible(). Draw listview background + in paintEmptyArea() with the current style. Ensure the + listview always has a current item. + +- QMainWindow + Better laying out of dockareas when they are all empty. + Otherwise an empty QMainWindow looks unappealing in a + workspace. Maintain the toplevel layout's resize mode. + +- QMessageBox + Avoid double deletion if the parent is destroyed while the + messagebox is open. Support y/n/c shortcuts without needing + the Alt key modifier. + +- QMovie + Allow pause() and restart() with MNG. + +- QMultiLineEdit + Remove internal trailing space when returning a textline with + textLine(int) and querying lineLength(int). + +- QPainter + The boundingRect() should now work properly for the + combination richtext, right-aligned and an empty initial rect. + Handle DontClip-flag in the painter's complex drawText() + function. Reset the cached composition matrix (and inverse) + when reinitialising a painter. + +- QPicture + Fixed the loading of binaries from older Qt versions. + +- QPixmap + grabWidget(): when the widget sets WRepaintNoErase it might + erase itself with the non-redirected QWidget::erase(); restore + those areas. + - X11 only: (with XRENDER extension) when copying a pixmap, + bitBlt the entire data into the new pixmap instead of using + alpha composition. + +- QPopupMenu + Fixed strange side effects with the menu effects. Support + minimumSize() for popups. Fixed a navigation issue where + Key_Right under certain circumstances was not propagated to + the menu bar. Speedups when disabling/enabling menu items + before showing them. + - X11 only: Fixed mouse and keyboard grabbing side effects + with popup menu effects enabled. + +- QPrintDialog (built-in dialog) + Use the text in the lineedit for the file dialog. + +- QPrinter + Fixed crash when printing with incomplete combined unicode + fonts. + - Win32 only: fixed a very rare and mysterious crash. + + +- QPSPrinter + Make sure the fontPath is read correctly by the postscript + driver, and the qtconfig program. Small memory leaks closed. + Better support for Asian printing. Limit line length of + Postscript DSC comments to 255 chars (as per the postscript + specification). + +- QRichText + Fixed handling of  . Support both and + + + + +
Start report: 2008-12-16T13:43:49.65Z
+
Global variables with complex types:
+
+
1. + mutableComplex1 in globals.cpp at line 14
+
2. + mutableComplex2 in globals.cpp at line 15
+
3. + constComplex1 in globals.cpp at line 16
+
4. + constComplex2 in globals.cpp at line 17
+
+
Mutable global variables with primitives types:
+
+
1. + mutablePrimitive1 in globals.cpp at line 1
+
2. + mutablePrimitive2 in globals.cpp at line 2
+
+
End report: 2008-12-16T13:43:49.65Z
+ + + \endraw + + \section1 XQuery Code Walk-Through + + The XQuery source is in + \c{examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq} + It begins with two variable declarations that begin the XQuery: + + \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto declare variable + \printto (: + + The first variable, \c{$fileToOpen}, appears in the \c xmlpatterns + command shown earlier, as \c{-param fileToOpen=globals.gccxml}. + This binds the variable name to the file name. This variable is + then used in the declaration of the second variable, \c{$inDoc}, + as the parameter to the + \l{http://www.w3.org/TR/xpath-functions/#func-doc} {doc()} + function. The \c{doc()} function returns the document node of + \c{globals.gccxml}, which is assigned to \c{$inDoc} to be used + later in the XQuery as the root node of our searches for global + variables. + + Next skip to the end of the XQuery, where the \c{} element + is constructed. The \c{} will contain a \c{} element + to specify a heading for the html page, followed by some style + instructions for displaying the text, and then the \c{} + element. + + \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto } element contains a call to the \c{local:report()} + function, which is where the query does the "heavy lifting." Note + the two \c{return} clauses separated by the \e {comma operator} + about halfway down: + + \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto declare function local:report() + \printuntil }; + + The \c{return} clauses are like two separate queries. The comma + operator separating them means that both \c{return} clauses are + executed and both return their results, or, rather, both output + their results. The first \c{return} clause searches for global + variables with complex types, and the second searches for mutable + global variables with primitive types. + + Here is the html generated for the \c{} element. Compare + it with the XQuery code above: + + \quotefromfile examples/xmlpatterns/xquery/globalVariables/globals.html + \skipto + \printuntil + + The XQuery declares three more local functions that are called in + turn by the \c{local:report()} function. \c{isComplexType()} + returns true if the variable has a complex type. The variable can + be mutable or const. + + \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto declare function local:isComplexType + \printuntil }; + + \c{isPrimitive()} returns true if the variable has a primitive + type. The variable must be mutable. + + \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto declare function local:isPrimitive + \printuntil }; + + \c{location()} returns a text constructed from the variable's file + and line number attributes. + + \quotefromfile examples/xmlpatterns/xquery/globalVariables/reportGlobals.xq + \skipto declare function local:location + \printuntil }; + + */ diff --git a/doc/src/examples/grabber.qdoc b/doc/src/examples/grabber.qdoc new file mode 100644 index 0000000..efb5b6f --- /dev/null +++ b/doc/src/examples/grabber.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/grabber + \title Grabber Example + + The Grabber examples shows how to retrieve the contents of an OpenGL framebuffer. + + \image grabber-example.png +*/ diff --git a/doc/src/examples/groupbox.qdoc b/doc/src/examples/groupbox.qdoc new file mode 100644 index 0000000..c5f6a62 --- /dev/null +++ b/doc/src/examples/groupbox.qdoc @@ -0,0 +1,154 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/groupbox + \title Group Box Example + + The Group Box example shows how to use the different kinds of group + boxes in Qt. + + Group boxes are container widgets that organize buttons into groups, + both logically and on screen. They manage the interactions between + the user and the application so that you do not have to enforce + simple constraints. + + Group boxes are usually used to organize check boxes and radio + buttons into exclusive groups. + + \image groupbox-example.png + + The Group Boxes example consists of a single \c Window class that + is used to show four group boxes: an exclusive radio button group, + a non-exclusive checkbox group, an exclusive radio button group + with an enabling checkbox, and a group box with normal push buttons. + + \section1 Window Class Definition + + The \c Window class is a subclass of \c QWidget that is used to + display a number of group boxes. The class definition contains + functions to construct each group box and populate it with different + selections of button widgets: + + \snippet examples/widgets/groupbox/window.h 0 + + In the example, the widget will be used as a top-level window, so + the constructor is defined so that we do not have to specify a parent + widget. + + \section1 Window Class Implementation + + The constructor creates a grid layout and fills it with each of the + group boxes that are to be displayed: + + \snippet examples/widgets/groupbox/window.cpp 0 + + The functions used to create each group box each return a + QGroupBox to be inserted into the grid layout. + + \snippet examples/widgets/groupbox/window.cpp 1 + + The first group box contains and manages three radio buttons. Since + the group box contains only radio buttons, it is exclusive by + default, so only one radio button can be checked at any given time. + We check the first radio button to ensure that the button group + contains one checked button. + + \snippet examples/widgets/groupbox/window.cpp 3 + + We use a vertical layout within the group box to present the + buttons in the form of a vertical list, and return the group + box to the constructor. + + The second group box is itself checkable, providing a convenient + way to disable all the buttons inside it. Initially, it is + unchecked, so the group box itself must be checked before any of + the radio buttons inside can be checked. + + \snippet examples/widgets/groupbox/window.cpp 4 + + The group box contains three exclusive radio buttons, and an + independent checkbox. For consistency, one radio button must be + checked at all times, so we ensure that the first one is initially + checked. + + \snippet examples/widgets/groupbox/window.cpp 5 + + The buttons are arranged in the same way as those in the first + group box. + + \snippet examples/widgets/groupbox/window.cpp 6 + + The third group box is constructed with a "flat" style that is + better suited to certain types of dialog. + + \snippet examples/widgets/groupbox/window.cpp 7 + + This group box contains only checkboxes, so it is non-exclusive by + default. This means that each checkbox can be checked independently + of the others. + + \snippet examples/widgets/groupbox/window.cpp 8 + + Again, we use a vertical layout within the group box to present + the buttons in the form of a vertical list. + + \snippet examples/widgets/groupbox/window.cpp 9 + + The final group box contains only push buttons and, like the + second group box, it is checkable. + + \snippet examples/widgets/groupbox/window.cpp 10 + + We create a normal button, a toggle button, and a flat push button: + + \snippet examples/widgets/groupbox/window.cpp 11 + + Push buttons can be used to display popup menus. We create one, and + attach a simple menu to it: + + \snippet examples/widgets/groupbox/window.cpp 12 + + Finally, we lay out the widgets vertically, and return the group box + that we created: + + \snippet examples/widgets/groupbox/window.cpp 13 +*/ diff --git a/doc/src/examples/hellogl.qdoc b/doc/src/examples/hellogl.qdoc new file mode 100644 index 0000000..2fc51a3 --- /dev/null +++ b/doc/src/examples/hellogl.qdoc @@ -0,0 +1,272 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/hellogl + \title Hello GL Example + + The Hello GL example demonstrates the basic use of the OpenGL-related classes + provided with Qt. + + \image hellogl-example.png + + Qt provides the QGLWidget class to enable OpenGL graphics to be rendered within + a standard application user interface. By subclassing this class, and providing + reimplementations of event handler functions, 3D scenes can be displayed on + widgets that can be placed in layouts, connected to other objects using signals + and slots, and manipulated like any other widget. + + \tableofcontents + + \section1 GLWidget Class Definition + + The \c GLWidget class contains some standard public definitions for the + constructor, destructor, \l{QWidget::sizeHint()}{sizeHint()}, and + \l{QWidget::minimumSizeHint()}{minimumSizeHint()} functions: + + \snippet examples/opengl/hellogl/glwidget.h 0 + + We use a destructor to ensure that any OpenGL-specific data structures + are deleted when the widget is no longer needed. + + \snippet examples/opengl/hellogl/glwidget.h 1 + + The signals and slots are used to allow other objects to interact with the + 3D scene. + + \snippet examples/opengl/hellogl/glwidget.h 2 + + OpenGL initialization, viewport resizing, and painting are handled by + reimplementing the QGLWidget::initializeGL(), QGLWidget::resizeGL(), and + QGLWidget::paintGL() handler functions. To enable the user to interact + directly with the scene using the mouse, we reimplement + QWidget::mousePressEvent() and QWidget::mouseMoveEvent(). + + \snippet examples/opengl/hellogl/glwidget.h 3 + + The rest of the class contains utility functions and variables that are + used to construct and hold orientation information for the scene. The + \c object variable will be used to hold an identifier for an OpenGL + display list. + + \section1 GLWidget Class Implementation + + In this example, we split the class into groups of functions and describe + them separately. This helps to illustrate the differences between subclasses + of native widgets (such as QWidget and QFrame) and QGLWidget subclasses. + + \section2 Widget Construction and Sizing + + The constructor provides default rotation angles for the scene, initializes + the variable used for the display list, and sets up some colors for later use. + + \snippet examples/opengl/hellogl/glwidget.cpp 0 + + We also implement a destructor to release OpenGL-related resources when the + widget is deleted: + + \snippet examples/opengl/hellogl/glwidget.cpp 1 + + The destructor ensures that the display list is deleted properly. + + We provide size hint functions to ensure that the widget is shown at a + reasonable size: + + \snippet examples/opengl/hellogl/glwidget.cpp 2 + \codeline + \snippet examples/opengl/hellogl/glwidget.cpp 3 + \snippet examples/opengl/hellogl/glwidget.cpp 4 + + The widget provides three slots that enable other components in the + example to change the orientation of the scene: + + \snippet examples/opengl/hellogl/glwidget.cpp 5 + + In the above slot, the \c xRot variable is updated only if the new angle + is different to the old one, the \c xRotationChanged() signal is emitted to + allow other components to be updated, and the widget's + \l{QGLWidget::updateGL()}{updateGL()} handler function is called. + + The \c setYRotation() and \c setZRotation() slots perform the same task for + rotations measured by the \c yRot and \c zRot variables. + + \section2 OpenGL Initialization + + The \l{QGLWidget::initializeGL()}{initializeGL()} function is used to + perform useful initialization tasks that are needed to render the 3D scene. + These often involve defining colors and materials, enabling and disabling + certain rendering flags, and setting other properties used to customize the + rendering process. + + \snippet examples/opengl/hellogl/glwidget.cpp 6 + + In this example, we reimplement the function to set the background color, + create a display list containing information about the object we want to + display, and set up the rendering process to use a particular shading model + and rendering flags: + + \section2 Resizing the Viewport + + The \l{QGLWidget::resizeGL()}{resizeGL()} function is used to ensure that + the OpenGL implementation renders the scene onto a viewport that matches the + size of the widget, using the correct transformation from 3D coordinates to + 2D viewport coordinates. + + The function is called whenever the widget's dimensions change, and is + supplied with the new width and height. Here, we define a square viewport + based on the length of the smallest side of the widget to ensure that + the scene is not distorted if the widget has sides of unequal length: + + \snippet examples/opengl/hellogl/glwidget.cpp 8 + + A discussion of the projection transformation used is outside the scope of + this example. Please consult the OpenGL reference documentation for an + explanation of projection matrices. + + \section2 Painting the Scene + + The \l{QGLWidget::paintGL()}{paintGL()} function is used to paint the + contents of the scene onto the widget. For widgets that only need to be + decorated with pure OpenGL content, we reimplement QGLWidget::paintGL() + \e instead of reimplementing QWidget::paintEvent(): + + \snippet examples/opengl/hellogl/glwidget.cpp 7 + + In this example, we clear the widget using the background color that + we defined in the \l{QGLWidget::initializeGL()}{initializeGL()} function, + set up the frame of reference for the object we want to display, and call + the display list containing the rendering commands for the object. + + \section2 Mouse Handling + + Just as in subclasses of native widgets, mouse events are handled by + reimplementing functions such as QWidget::mousePressEvent() and + QWidget::mouseMoveEvent(). + + The \l{QWidget::mousePressEvent()}{mousePressEvent()} function simply + records the position of the mouse when a button is initially pressed: + + \snippet examples/opengl/hellogl/glwidget.cpp 9 + + The \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} function uses the + previous location of the mouse cursor to determine how much the object + in the scene should be rotated, and in which direction: + + \snippet examples/opengl/hellogl/glwidget.cpp 10 + + Since the user is expected to hold down the mouse button and drag the + cursor to rotate the object, the cursor's position is updated every time + a move event is received. + + \section2 Utility Functions + + We have omitted the utility functions, \c makeObject(), \c quad(), + \c extrude(), and \c normalizeAngle() from our discussion. These can be + viewed in the quoted source for \c glwidget.cpp via the link at the + start of this document. + + \section1 Window Class Definition + + The \c Window class is used as a container for the \c GLWidget used to + display the scene: + + \snippet examples/opengl/hellogl/window.h 0 + + In addition, it contains sliders that are used to change the orientation + of the object in the scene. + + \section1 Window Class Implementation + + The constructor constructs an instance of the \c GLWidget class and some + sliders to manipulate its contents. + + \snippet examples/opengl/hellogl/window.cpp 0 + + We connect the \l{QAbstractSlider::valueChanged()}{valueChanged()} signal + from each of the sliders to the appropriate slots in \c{glWidget}. + This allows the user to change the orientation of the object by dragging + the sliders. + + We also connect the \c xRotationChanged(), \c yRotationChanged(), and + \c zRotationChanged() signals from \c glWidget to the + \l{QAbstractSlider::setValue()}{setValue()} slots in the + corresponding sliders. + + \snippet examples/opengl/hellogl/window.cpp 1 + + The sliders are placed horizontally in a layout alongside the \c GLWidget, + and initialized with suitable default values. + + The \c createSlider() utility function constructs a QSlider, and ensures + that it is set up with a suitable range, step value, tick interval, and + page step value before returning it to the calling function: + + \snippet examples/opengl/hellogl/window.cpp 2 + + \section1 Summary + + The \c GLWidget class implementation shows how to subclass QGLWidget for + the purposes of rendering a 3D scene using OpenGL calls. Since QGLWidget + is a subclass of QWidget, subclasses of QGLWidget can be placed in layouts + and provided with interactive features just like normal custom widgets. + + We ensure that the widget is able to correctly render the scene using OpenGL + by reimplementing the following functions: + + \list + \o QGLWidget::initializeGL() sets up resources needed by the OpenGL implementation + to render the scene. + \o QGLWidget::resizeGL() resizes the viewport so that the rendered scene fits onto + the widget, and sets up a projection matrix to map 3D coordinates to 2D viewport + coordinates. + \o QGLWidget::paintGL() performs painting operations using OpenGL calls. + \endlist + + Since QGLWidget is a subclass of QWidget, it can also be used + as a normal paint device, allowing 2D graphics to be drawn with QPainter. + This use of QGLWidget is discussed in the \l{2D Painting Example}{2D Painting} + example. + + More advanced users may want to paint over parts of a scene rendered using + OpenGL. QGLWidget allows pure OpenGL rendering to be mixed with QPainter + calls, but care must be taken to maintain the state of the OpenGL implementation. + See the \l{Overpainting Example}{Overpainting} example for more information. +*/ diff --git a/doc/src/examples/hellogl_es.qdoc b/doc/src/examples/hellogl_es.qdoc new file mode 100644 index 0000000..0293584 --- /dev/null +++ b/doc/src/examples/hellogl_es.qdoc @@ -0,0 +1,124 @@ +/*! + \example opengl/hellogl_es + \title Hello GL ES Example + + The Hello GL ES example is the \l{Hello GL Example} ported to OpenGL ES. + It also included some effects from the OpenGL \l{Overpainting Example}. + + \image hellogl-es-example.png + + A complete introduction to OpenGL ES and a description of all differences + between OpenGL and OpenGL ES is out of the scope of this document; but + we will describe some of the major issues and differences. + + Since Hello GL ES is a direct port of standard OpenGL code, it is a fairly + good example for porting OpenGL code to OpenGL ES. + + \tableofcontents + + \section1 Using QGLWidget + + QGLWidget can be used for OpenGL ES similar to the way it is used with + standard OpenGL; but there are some differences. We use EGL 1.0 to embedd + the OpenGL ES window within the native window manager. In + QGLWidget::initializeGL() we initialize OpenGL ES. + + \section1 Using OpenGL ES rendering commands + + To update the scene, we reimplment QGLWidget::paintGL(). We use OpenGL ES + rendering commands just like we do with standard OpenGL. Since the OpenGL + ES common light profile only supports fixed point functions, we need to + abstract it somehow. Hence, we define an abstraction layer in + \c{cl_helper.h}. + + \snippet examples/opengl/hellogl_es/cl_helper.h 0 + + Instead of \c glFogxv() or \c glFogfv() we use \c q_glFogv() and to + convert the coordinates of a vertice we use the macro \c f2vt(). That way, + if QT_OPENGL_ES_CL is defined we use the fixed point functions and every + float is converted to fixed point. + + If QT_OPENGL_ES_CL is not defined we use the floating point functions. + + \snippet examples/opengl/hellogl_es/cl_helper.h 1 + + This way we support OpenGL ES Common and Common Light with the same code + and abstract the fact that we use either the floating point functions or + otherwise the fixed point functions. + + \section1 Porting OpenGL to OpenGL ES + + Since OpenGL ES is missing the immediate mode and does not support quads, + we have to create triangle arrays. + + We create a quad by adding vertices to a QList of vertices. We create both + sides of the quad and hardcode a distance of 0.05f. We also compute the + correct normal for each face and store them in another QList. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 0 + + And then we convert the complete list of vertexes and the list of normals + into the native OpenGL ES format that we can use with the OpenGL ES API. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 1 + + In \c paintQtLogo() we draw the triangle array using OpenGL ES. We use + q_vertexTypeEnum to abstract the fact that our vertex and normal arrays + are either in float or in fixed point format. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 2 + + \section1 Using QGLPainter + + Since the \c QGLPainter is slower for OpenGL ES we paint the bubbles with + the rasterizer and cache them in a QImage. This happends only once during + the initialiazation. + + \snippet examples/opengl/hellogl_es/bubble.cpp 0 + + For each bubble this QImage is then drawn to the QGLWidget by using the + according QPainter with transparency enabled. + + \snippet examples/opengl/hellogl_es/bubble.cpp 1 + + Another difference beetwen OpenGL and OpenGL ES is that OpenGL ES does not + support glPushAttrib(GL_ALL_ATTRIB_BITS). So we have to restore all the + OpenGL states ourselves, after we created the QPainter in + GLWidget::paintGL(). + + \snippet examples/opengl/hellogl_es/glwidget.cpp 3 + + Setting up up the model view matrix and setting the right OpenGL states is + done in the same way as for standard OpenGL. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 4 + + Now we have to restore the OpenGL state for the QPainter. This is not done + automatically for OpenGL ES. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 5 + + Now we use the QPainter to draw the transparent bubbles. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 6 + + In the end, we calculate the framerate and display it using the QPainter + again. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 7 + + After we finished all the drawing operations we swap the screen buffer. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 8 + + \section1 Summary + + Similar to the \l{Hello GL Example}, we subclass QGLWidget to render + a 3D scene using OpenGL ES calls. QGLWidget is a subclass of QWidget. + Hence, its \l{QGLWidget}'s subclasses can be placed in layouts and + provided with interactive features just like normal custom widgets. + + QGLWidget allows pure OpenGL ES rendering to be mixed with QPainter calls, + but care must be taken to maintain the state of the OpenGL ES + implementation. +*/ diff --git a/doc/src/examples/helloscript.qdoc b/doc/src/examples/helloscript.qdoc new file mode 100644 index 0000000..5662680 --- /dev/null +++ b/doc/src/examples/helloscript.qdoc @@ -0,0 +1,142 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example script/helloscript + \title Hello Script Example + + The Hello Script example shows the basic use of Qt Script: How to embed + a script engine into the application, how to evaluate a script, and how + to process the result of the evaluation. The example also shows how to + apply internationalization to scripts. + + \snippet examples/script/helloscript/main.cpp 0 + + The application will load the script file to evaluate from a resource, so + we first make sure that the resource is initialized. + + \snippet examples/script/helloscript/main.cpp 1 + + We attempt to load a translation, and install translation functions in the + script engine. How to produce a translation is explained later. + + \snippet examples/script/helloscript/main.cpp 2 + + A push button is created and exported to the script environment as a + global variable, \c button. Scripts will be able to access properties, + signals and slots of the button as properties of the \c button script + object; the script object acts as a proxy to the C++ button object. + + \snippet examples/script/helloscript/main.cpp 3 + + The contents of the script file are read. + + \snippet examples/script/helloscript/helloscript.qs 0 + + The script sets the \c text (note that the qTr() function is used to allow + for translation) and \c styleSheet properties of the button, and calls the + button's \c show() slot. + + \snippet examples/script/helloscript/main.cpp 4 + + The script is evaluated. Note that the file name is passed as the + (optional) second parameter; this makes it possible for the script engine + to produce a meaningful backtrace if something goes wrong, and makes the + qTr() function be able to resolve the translations that are associated + with this script. + + \snippet examples/script/helloscript/main.cpp 5 + + If the result is an Error object (e.g. the script contained a syntax + error, or tried to call a function that doesn't exist), we obtain + the line number and string representation of the error and display + it in a message box. + + \snippet examples/script/helloscript/main.cpp 6 + + If the evaluation went well, the application event loop is entered. + + \section1 Translating the Application + + The Qt Script internalization support builds on what Qt already provides + for C++; see the \l{Hello tr() Example} for an introduction. + + Since we haven't made the translation file \c helloscript_la.qm, the + source text is shown when we run the application ("Hello world!"). + + To generate the translation file, run \c lupdate as follows: + + \code + lupdate helloscript.qs -ts helloscript_la.ts + \endcode + + You should now have a file \c helloscript_la.ts in the current + directory. Run \c linguist to edit the translation: + + \code + linguist helloscript_la.ts + \endcode + + You should now see the text "helloscript.qs" in the top left pane. + Double-click it, then click on "Hello world!" and enter "Orbis, te + saluto!" in the \gui Translation pane (the middle right of the + window). Don't forget the exclamation mark! + + Click the \gui Done checkbox and choose \gui File|Save from the + menu bar. The \c .ts file will no longer contain + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3 + + but instead will have + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 4 + + To see the application running in Latin, we have to generate a \c .qm + file from the \c .ts file. Generating a \c .qm file can be achieved + either from within \e {Qt Linguist} (for a single \c .ts file), or + by using the command line program \c lrelease which will produce one \c + .qm file for each of the \c .ts files listed in the project file. + Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing + \gui File|Release from \e {Qt Linguist}'s menu bar and pressing + \gui Save in the file save dialog that pops up. Now run the \c helloscript + program again. This time the button will be labelled "Orbis, te + saluto!". +*/ diff --git a/doc/src/examples/hellotr.qdoc b/doc/src/examples/hellotr.qdoc new file mode 100644 index 0000000..72efd11 --- /dev/null +++ b/doc/src/examples/hellotr.qdoc @@ -0,0 +1,188 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example linguist/hellotr + \title Hello tr() Example + + This example is a small Hello World program with a Latin translation. The + screenshot below shows the English version. + + \image linguist-hellotr_en.png + + See the \l{Qt Linguist manual} for more information about + translating Qt application. + + \section1 Line by Line Walkthrough + + + \snippet examples/linguist/hellotr/main.cpp 0 + + This line includes the definition of the QTranslator class. + Objects of this class provide translations for user-visible text. + + \snippet examples/linguist/hellotr/main.cpp 5 + + Creates a QTranslator object without a parent. + + \snippet examples/linguist/hellotr/main.cpp 6 + + Tries to load a file called \c hellotr_la.qm (the \c .qm file extension is + implicit) that contains Latin translations for the source texts used in + the program. No error will occur if the file is not found. + + \snippet examples/linguist/hellotr/main.cpp 7 + + Adds the translations from \c hellotr_la.qm to the pool of translations used + by the program. + + \snippet examples/linguist/hellotr/main.cpp 8 + + Creates a push button that displays "Hello world!". If \c hellotr_la.qm + was found and contains a translation for "Hello world!", the + translation appears; if not, the source text appears. + + All classes that inherit QObject have a \c tr() function. Inside + a member function of a QObject class, we simply write \c tr("Hello + world!") instead of \c QPushButton::tr("Hello world!") or \c + QObject::tr("Hello world!"). + + \section1 Running the Application in English + + Since we haven't made the translation file \c hellotr_la.qm, the source text + is shown when we run the application: + + \image linguist-hellotr_en.png + + \section1 Creating a Latin Message File + + The first step is to create a project file, \c hellotr.pro, that lists + all the source files for the project. The project file can be a qmake + project file, or even an ordinary makefile. Any file that contains + + \snippet examples/linguist/hellotr/hellotr.pro 0 + \snippet examples/linguist/hellotr/hellotr.pro 1 + + will work. \c TRANSLATIONS specifies the message files we want to + maintain. In this example, we just maintain one set of translations, + namely Latin. + + Note that the file extension is \c .ts, not \c .qm. The \c .ts + translation source format is designed for use during the + application's development. Programmers or release managers run + the \c lupdate program to generate and update \c .ts files with + the source text that is extracted from the source code. + Translators read and update the \c .ts files using \e {Qt + Linguist} adding and editing their translations. + + The \c .ts format is human-readable XML that can be emailed directly + and is easy to put under version control. If you edit this file + manually, be aware that the default encoding for XML is UTF-8, not + Latin1 (ISO 8859-1). One way to type in a Latin1 character such as + '\oslash' (Norwegian o with slash) is to use an XML entity: + "\ø". This will work for any Unicode 4.0 character. + + Once the translations are complete the \c lrelease program is used to + convert the \c .ts files into the \c .qm Qt message file format. The + \c .qm format is a compact binary format designed to deliver very + fast lookup performance. Both \c lupdate and \c lrelease read all the + project's source and header files (as specified in the HEADERS and + SOURCES lines of the project file) and extract the strings that + appear in \c tr() function calls. + + \c lupdate is used to create and update the message files (\c hellotr_la.ts + in this case) to keep them in sync with the source code. It is safe to + run \c lupdate at any time, as \c lupdate does not remove any + information. For example, you can put it in the makefile, so the \c .ts + files are updated whenever the source changes. + + Try running \c lupdate right now, like this: + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 0 + + (The \c -verbose option instructs \c lupdate to display messages that + explain what it is doing.) You should now have a file \c hellotr_la.ts in + the current directory, containing this: + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 1 + + You don't need to understand the file format since it is read and + updated using tools (\c lupdate, \e {Qt Linguist}, \c lrelease). + + \section1 Translating to Latin with Qt Linguist + + We will use \e {Qt Linguist} to provide the translation, although + you can use any XML or plain text editor to enter a translation into a + \c .ts file. + + To start \e {Qt Linguist}, type + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 2 + + You should now see the text "QPushButton" in the top left pane. + Double-click it, then click on "Hello world!" and enter "Orbis, te + saluto!" in the \gui Translation pane (the middle right of the + window). Don't forget the exclamation mark! + + Click the \gui Done checkbox and choose \gui File|Save from the + menu bar. The \c .ts file will no longer contain + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3 + + but instead will have + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 4 + + \section1 Running the Application in Latin + + To see the application running in Latin, we have to generate a \c .qm + file from the \c .ts file. Generating a \c .qm file can be achieved + either from within \e {Qt Linguist} (for a single \c .ts file), or + by using the command line program \c lrelease which will produce one \c + .qm file for each of the \c .ts files listed in the project file. + Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing + \gui File|Release from \e {Qt Linguist}'s menu bar and pressing + \gui Save in the file save dialog that pops up. Now run the \c hellotr + program again. This time the button will be labelled "Orbis, te + saluto!". + + \image linguist-hellotr_la.png +*/ diff --git a/doc/src/examples/htmlinfo.qdoc b/doc/src/examples/htmlinfo.qdoc new file mode 100644 index 0000000..bf95486 --- /dev/null +++ b/doc/src/examples/htmlinfo.qdoc @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the $MODULE$ of the Qt Toolkit. +** +** $TROLLTECH_DUAL_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/htmlinfo + \title XML HTML Info Example + + The XML HTML Info example provides a simple command line utility that + scans the current directory for HTML files and prints statistics about + them to standard out. + + \note Standard out is redirected on some platforms. On Symbian using Open + C \c stdout is by default directed to the console window, but this window + may not always be visible. To redirect to a file instead, locate the \c + c:\\system\\data\\config.ini file (on either the emulator or the device) + and change \c STDOUT to point to \c MEDIA4. This will redirect the console + to \c c:\\system\\data\\out.txt. + + The files are parsed using a QXmlStreamReader object. If the file does + not contain a well-formed XML document, a description of the error is + printed to the standard error console. + + \section1 Basic Operation + + The main function of the example uses QDir to access files in the current + directory that match either "*.htm" or "*.html". For each file found, + the \c parseHtmlFile() function is called. + + Reading XML is handled by an instance of the QXmlStreamReader class, which + operates on the input file object: + + \snippet examples/xml/htmlinfo/main.cpp 0 + + The work of parsing and the XML and extracting statistics is done in a + while loop, and is driven by input from the reader: + + \snippet examples/xml/htmlinfo/main.cpp 1 + + If more input is available, the next token from the input file is read + and parsed. The program then looks for the specific element types, + "title", "a", and "p", and stores information about them. + + When there is no more input, the loop terminates. If an error occurred, + information is written to the standard out file via a stream, and the + example exits: + + \snippet examples/xml/htmlinfo/main.cpp 2 + + If no error occurred, the example prints some statistics from the data + gathered in the loop, and then exits. +*/ diff --git a/doc/src/examples/http.qdoc b/doc/src/examples/http.qdoc new file mode 100644 index 0000000..17404a8 --- /dev/null +++ b/doc/src/examples/http.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/http + \title HTTP Example + + The HTTP example demonstrates a simple HTTP client that shows how to fetch files + specified by URLs from remote hosts. + + \image http-example.png +*/ diff --git a/doc/src/examples/i18n.qdoc b/doc/src/examples/i18n.qdoc new file mode 100644 index 0000000..68d9153 --- /dev/null +++ b/doc/src/examples/i18n.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/i18n + \title I18N Example + + The Internationalization (I18N) example demonstrates Qt's support for translated + text. Developers can write the initial application text in one language, and + translations can be provided later without any modifications to the code. + + \image i18n-example.png +*/ diff --git a/doc/src/examples/icons.qdoc b/doc/src/examples/icons.qdoc new file mode 100644 index 0000000..750ef2e --- /dev/null +++ b/doc/src/examples/icons.qdoc @@ -0,0 +1,794 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/icons + \title Icons Example + + The Icons example shows how QIcon can generate pixmaps reflecting + an icon's state, mode and size. These pixmaps are generated from + the set of pixmaps made available to the icon, and are used by Qt + widgets to show an icon representing a particular action. + + \image icons-example.png Screenshot of the Icons example + + Contents: + + \tableofcontents + + \section1 QIcon Overview + + The QIcon class provides scalable icons in different modes and + states. An icon's state and mode are depending on the intended use + of the icon. Qt currently defines four modes: + + \table + \header \o Mode \o Description + \row + \o QIcon::Normal + \o Display the pixmap when the user is not interacting with the + icon, but the functionality represented by the icon is + available. + \row + \o QIcon::Active + \o Display the pixmap when the functionality represented by the + icon is available and the user is interacting with the icon, + for example, moving the mouse over it or clicking it. + \row + \o QIcon::Disabled + \o Display the pixmap when the functionality represented by + the icon is not available. + \row + \o QIcon::Selected + \o Display the pixmap when the icon is selected. + \endtable + + QIcon's states are QIcon::On and QIcon::Off, which will display + the pixmap when the widget is in the respective state. The most + common usage of QIcon's states are when displaying checkable tool + buttons or menu entries (see QAbstractButton::setCheckable() and + QAction::setCheckable()). When a tool button or menu entry is + checked, the QIcon's state is \l{QIcon::}{On}, otherwise it's + \l{QIcon::}{Off}. You can, for example, use the QIcon's states to + display differing pixmaps depending on whether the tool button or + menu entry is checked or not. + + A QIcon can generate smaller, larger, active, disabled, and + selected pixmaps from the set of pixmaps it is given. Such + pixmaps are used by Qt widgets to show an icon representing a + particular action. + + \section1 Overview of the Icons Application + + With the Icons application you get a preview of an icon's + generated pixmaps reflecting its different states, modes and size. + + When an image is loaded into the application, it is converted into + a pixmap and becomes a part of the set of pixmaps available to the + icon. An image can be excluded from this set by checking off the + related checkbox. The application provides a sub directory + containing sets of images explicitly designed to illustrate how Qt + renders an icon in different modes and states. + + The application allows you to manipulate the icon size with some + predefined sizes and a spin box. The predefined sizes are style + dependent, but most of the styles have the same values: Only the + Macintosh style differ by using 32 pixels, instead of 16 pixels, + for toolbar buttons. You can navigate between the available styles + using the \gui View menu. + + \image icons-view-menu.png Screenshot of the View menu + + The \gui View menu also provide the option to make the application + guess the icon state and mode from an image's file name. The \gui + File menu provide the options of adding an image and removing all + images. These last options are also available through a context + menu that appears if you press the right mouse button within the + table of image files. In addition, the \gui File menu provide an + \gui Exit option, and the \gui Help menu provide information about + the example and about Qt. + + \image icons_find_normal.png Screenshot of the Find Files + + The screenshot above shows the application with one image file + loaded. The \gui {Guess Image Mode/State} is enabled and the + style is Plastique. + + When QIcon is provided with only one available pixmap, that + pixmap is used for all the states and modes. In this case the + pixmap's icon mode is set to normal, and the generated pixmaps + for the normal and active modes will look the same. But in + disabled and selected mode, Qt will generate a slightly different + pixmap. + + The next screenshot shows the application with an additional file + loaded, providing QIcon with two available pixmaps. Note that the + new image file's mode is set to disabled. When rendering the \gui + Disabled mode pixmaps, Qt will now use the new image. We can see + the difference: The generated disabled pixmap in the first + screenshot is slightly darker than the pixmap with the originally + set disabled mode in the second screenshot. + + \image icons_find_normal_disabled.png Screenshot of the Find Files + + When Qt renders the icon's pixmaps it searches through the set of + available pixmaps following a particular algorithm. The algorithm + is documented in QIcon, but we will describe some particular cases + below. + + \image icons_monkey_active.png Screenshot of the Find Files + + In the screenshot above, we have set \c monkey_on_32x32 to be an + Active/On pixmap and \c monkey_off_64x64 to be Normal/Off. To + render the other six mode/state combinations, QIcon uses the + search algorithm described in the table below: + + \table + \header \o{2,1} Requested Pixmap \o{8,1} Preferred Alternatives (mode/state) + \header \o Mode \o State \o 1 \o 2 \o 3 \o 4 \o 5 \o 6 \o 7 \o 8 + \row \o{1,2} Normal \o Off \o \bold N0 \o A0 \o N1 \o A1 \o D0 \o S0 \o D1 \o S1 + \row \o On \o N1 \o \bold A1 \o N0 \o A0 \o D1 \o S1 \o D0 \o S0 + \row \o{1,2} Active \o Off \o A0 \o \bold N0 \o A1 \o N1 \o D0 \o S0 \o D1 \o S1 + \row \o On \o \bold A1 \o N1 \o A0 \o N0 \o D1 \o S1 \o D0 \o S0 + \row \o{1,2} Disabled \o Off \o D0 \o \bold {N0'} \o A0' \o D1 \o N1' \o A1' \o S0' \o S1' + \row \o On \o D1 \o N1' \o \bold {A1'} \o D0 \o N0' \o A0' \o S1' \o S0' + \row \o{1,2} Selected \o Off \o S0 \o \bold {N0''} \o A0'' \o S1 \o N1'' \o A1'' \o D0'' \o D1'' + \row \o On \o S1 \o N1'' \o \bold {A1''} \o S0 \o N0'' \o A0'' \o D1'' \o D0'' + \endtable + + In the table, "0" and "1" stand for Off" and "On", respectively. + Single quotes indicates that QIcon generates a disabled ("grayed + out") version of the pixmap; similarly, double quuote indicate + that QIcon generates a selected ("blued out") version of the + pixmap. + + The alternatives used in the screenshot above are shown in bold. + For example, the Disabled/Off pixmap is derived by graying out + the Normal/Off pixmap (\c monkey_off_64x64). + + In the next screenshots, we loaded the whole set of monkey + images. By checking or unchecking file names from the image list, + we get different results: + + \table + \row + \o \inlineimage icons_monkey.png Screenshot of the Monkey Files + \o \inlineimage icons_monkey_mess.png Screenshot of the Monkey Files + \endtable + + For any given mode/state combination, it is possible to specify + several images at different resolutions. When rendering an + icon, QIcon will automatically pick the most suitable image + and scale it down if necessary. (QIcon never scales up images, + because this rarely looks good.) + + The screenshots below shows what happens when we provide QIcon + with three images (\c qt_extended_16x16.png, \c qt_extended_32x32.png, \c + qt_extended_48x48.png) and try to render the QIcon at various + resolutions: + + \table + \row + \o + \o \inlineimage icons_qt_extended_8x8.png Qt Extended icon at 8 x 8 + \o \inlineimage icons_qt_extended_16x16.png Qt Extended icon at 16 x 16 + \o \inlineimage icons_qt_extended_17x17.png Qt Extended icon at 17 x 17 + \row + \o + \o 8 x 8 + \o \bold {16 x 16} + \o 17 x 17 + \row + \o \inlineimage icons_qt_extended_32x32.png Qt Extended icon at 32 x 32 + \o \inlineimage icons_qt_extended_33x33.png Qt Extended icon at 33 x 33 + \o \inlineimage icons_qt_extended_48x48.png Qt Extended icon at 48 x 48 + \o \inlineimage icons_qt_extended_64x64.png Qt Extended icon at 64 x 64 + \row + \o \bold {32 x 32} + \o 33 x 33 + \o \bold {48 x 48} + \o 64 x 64 + \endtable + + For sizes up to 16 x 16, QIcon uses \c qt_extended_16x16.png and + scales it down if necessary. For sizes between 17 x 17 and 32 x + 32, it uses \c qt_extended_32x32.png. For sizes above 32 x 32, it uses + \c qt_extended_48x48.png. + + \section1 Line-by-Line Walkthrough + + The Icons example consists of four classes: + + \list + \o \c MainWindow inherits QMainWindow and is the main application + window. + \o \c IconPreviewArea is a custom widget that displays all + combinations of states and modes for a given icon. + \o \c IconSizeSpinBox is a subclass of QSpinBox that lets the + user enter icon sizes (e.g., "48 x 48"). + \o \c ImageDelegate is a subclass of QItemDelegate that provides + comboboxes for letting the user set the mode and state + associated with an image. + \endlist + + We will start by reviewing the \c IconPreviewArea class before we + take a look at the \c MainWindow class. Finally, we will review the + \c IconSizeSpinBox and \c ImageDelegate classes. + + \section2 IconPreviewArea Class Definition + + An \c IconPreviewArea widget consists of a group box containing a grid of + QLabel widgets displaying headers and pixmaps. + + \image icons_preview_area.png Screenshot of IconPreviewArea. + + \snippet examples/widgets/icons/iconpreviewarea.h 0 + + The \c IconPreviewArea class inherits QWidget. It displays the + generated pixmaps corresponding to an icon's possible states and + modes at a given size. + + We need two public functions to set the current icon and the + icon's size. In addition the class has three private functions: We + use the \c createHeaderLabel() and \c createPixmapLabel() + functions when constructing the preview area, and we need the \c + updatePixmapLabels() function to update the preview area when + the icon or the icon's size has changed. + + The \c NumModes and \c NumStates constants reflect \l{QIcon}'s + number of currently defined modes and states. + + \section2 IconPreviewArea Class Implementation + + \snippet examples/widgets/icons/iconpreviewarea.cpp 0 + + In the constructor we create the labels displaying the headers and + the icon's generated pixmaps, and add them to a grid layout. + + When creating the header labels, we make sure the enums \c + NumModes and \c NumStates defined in the \c .h file, correspond + with the number of labels that we create. Then if the enums at + some point are changed, the \c Q_ASSERT() macro will alert that this + part of the \c .cpp file needs to be updated as well. + + If the application is built in debug mode, the \c Q_ASSERT() + macro will expand to + + \snippet doc/src/snippets/code/doc_src_examples_icons.qdoc 0 + + In release mode, the macro simply disappear. The mode can be set + in the application's \c .pro file. One way to do so is to add an + option to \c qmake when building the application: + + \snippet doc/src/snippets/code/doc_src_examples_icons.qdoc 1 + + or + + \snippet doc/src/snippets/code/doc_src_examples_icons.qdoc 2 + + Another approach is to add this line directly to the \c .pro + file. + + \snippet examples/widgets/icons/iconpreviewarea.cpp 1 + \codeline + \snippet examples/widgets/icons/iconpreviewarea.cpp 2 + + The public \c setIcon() and \c setSize() functions change the icon + or the icon size, and make sure that the generated pixmaps are + updated. + + \snippet examples/widgets/icons/iconpreviewarea.cpp 3 + \codeline + \snippet examples/widgets/icons/iconpreviewarea.cpp 4 + + We use the \c createHeaderLabel() and \c createPixmapLabel() + functions to create the preview area's labels displaying the + headers and the icon's generated pixmaps. Both functions return + the QLabel that is created. + + \snippet examples/widgets/icons/iconpreviewarea.cpp 5 + + We use the private \c updatePixmapLabel() function to update the + generated pixmaps displayed in the preview area. + + For each mode, and for each state, we retrieve a pixmap using the + QIcon::pixmap() function, which generates a pixmap corresponding + to the given state, mode and size. + + \section2 MainWindow Class Definition + + The \c MainWindow widget consists of three main elements: an + images group box, an icon size group box and a preview area. + + \image icons-example.png Screenshot of the Icons example + + \snippet examples/widgets/icons/mainwindow.h 0 + + The MainWindow class inherits from QMainWindow. We reimplement the + constructor, and declare several private slots: + + \list + \o The \c about() slot simply provides information about the example. + \o The \c changeStyle() slot changes the application's GUI style and + adjust the style dependent size options. + \o The \c changeSize() slot changes the size of the preview area's icon. + \o The \c changeIcon() slot updates the set of pixmaps available to the + icon displayed in the preview area. + \o The \c addImage() slot allows the user to load a new image into the + application. + \endlist + + In addition we declare several private functions to simplify the + constructor. + + \section2 MainWindow Class Implementation + + \snippet examples/widgets/icons/mainwindow.cpp 0 + + In the constructor we first create the main window's central + widget and its child widgets, and put them in a grid layout. Then + we create the menus with their associated entries and actions. + + Before we resize the application window to a suitable size, we set + the window title and determine the current style for the + application. We also enable the icon size spin box by clicking the + associated radio button, making the current value of the spin box + the icon's initial size. + + \snippet examples/widgets/icons/mainwindow.cpp 1 + + The \c about() slot displays a message box using the static + QMessageBox::about() function. In this example it displays a + simple box with information about the example. + + The \c about() function looks for a suitable icon in four + locations: It prefers its parent's icon if that exists. If it + doesn't, the function tries the top-level widget containing + parent, and if that fails, it tries the active window. As a last + resort it uses the QMessageBox's Information icon. + + \snippet examples/widgets/icons/mainwindow.cpp 2 + + In the \c changeStyle() slot we first check the slot's + parameter. If it is false we immediately return, otherwise we find + out which style to change to, i.e. which action that triggered the + slot, using the QObject::sender() function. + + This function returns the sender as a QObject pointer. Since we + know that the sender is a QAction object, we can safely cast the + QObject. We could have used a C-style cast or a C++ \c + static_cast(), but as a defensive programming technique we use a + \l qobject_cast(). The advantage is that if the object has the + wrong type, a null pointer is returned. Crashes due to null + pointers are much easier to diagnose than crashes due to unsafe + casts. + + \snippet examples/widgets/icons/mainwindow.cpp 3 + \snippet examples/widgets/icons/mainwindow.cpp 4 + + Once we have the action, we extract the style name using + QAction::data(). Then we create a QStyle object using the static + QStyleFactory::create() function. + + Although we can assume that the style is supported by the + QStyleFactory: To be on the safe side, we use the \c Q_ASSERT() + macro to check if the created style is valid before we use the + QApplication::setStyle() function to set the application's GUI + style to the new style. QApplication will automatically delete + the style object when a new style is set or when the application + exits. + + The predefined icon size options provided in the application are + style dependent, so we need to update the labels in the icon size + group box and in the end call the \c changeSize() slot to update + the icon's size. + + \snippet examples/widgets/icons/mainwindow.cpp 5 + + The \c changeSize() slot sets the size for the preview area's + icon. + + To determine the new size we first check if the spin box is + enabled. If it is, we extract the extent of the new size from the + box. If it's not, we search through the predefined size options, + extract the QStyle::PixelMetric and use the QStyle::pixelMetric() + function to determine the extent. Then we create a QSize object + based on the extent, and use that object to set the size of the + preview area's icon. + + \snippet examples/widgets/icons/mainwindow.cpp 12 + + The first thing we do when the \c addImage() slot is called, is to + show a file dialog to the user. The easiest way to create a file + dialog is to use QFileDialog's static functions. Here we use the + \l {QFileDialog::getOpenFileNames()}{getOpenFileNames()} function + that will return one or more existing files selected by the user. + + For each of the files the file dialog returns, we add a row to the + table widget. The table widget is listing the images the user has + loaded into the application. + + \snippet examples/widgets/icons/mainwindow.cpp 13 + \snippet examples/widgets/icons/mainwindow.cpp 14 + + We retrieve the image name using the QFileInfo::baseName() + function that returns the base name of the file without the path, + and create the first table widget item in the row. Then we add the + file's complete name to the item's data. Since an item can hold + several information pieces, we need to assign the file name a role + that will distinguish it from other data. This role can be Qt::UserRole + or any value above it. + + We also make sure that the item is not editable by removing the + Qt::ItemIsEditable flag. Table items are editable by default. + + \snippet examples/widgets/icons/mainwindow.cpp 15 + \snippet examples/widgets/icons/mainwindow.cpp 16 + \snippet examples/widgets/icons/mainwindow.cpp 17 + + Then we create the second and third items in the row making the + default mode Normal and the default state Off. But if the \gui + {Guess Image Mode/State} option is checked, and the file name + contains "_act", "_dis", or "_sel", the modes are changed to + Active, Disabled, or Selected. And if the file name contains + "_on", the state is changed to On. The sample files in the + example's \c images subdirectory respect this naming convension. + + \snippet examples/widgets/icons/mainwindow.cpp 18 + \snippet examples/widgets/icons/mainwindow.cpp 19 + + In the end we add the items to the associated row, and use the + QTableWidget::openPersistentEditor() function to create + comboboxes for the mode and state columns of the items. + + Due to the the connection between the table widget's \l + {QTableWidget::itemChanged()}{itemChanged()} signal and the \c + changeIcon() slot, the new image is automatically converted into a + pixmap and made part of the set of pixmaps available to the icon + in the preview area. So, corresponding to this fact, we need to + make sure that the new image's check box is enabled. + + \snippet examples/widgets/icons/mainwindow.cpp 6 + \snippet examples/widgets/icons/mainwindow.cpp 7 + + The \c changeIcon() slot is called when the user alters the set + of images listed in the QTableWidget, to update the QIcon object + rendered by the \c IconPreviewArea. + + We first create a QIcon object, and then we run through the + QTableWidget, which lists the images the user has loaded into the + application. + + \snippet examples/widgets/icons/mainwindow.cpp 8 + \snippet examples/widgets/icons/mainwindow.cpp 9 + \snippet examples/widgets/icons/mainwindow.cpp 10 + + We also extract the image file's name using the + QTableWidgetItem::data() function. This function takes a + Qt::DataItemRole as an argument to retrieve the right data + (remember that an item can hold several pieces of information) + and returns it as a QVariant. Then we use the + QVariant::toString() function to get the file name as a QString. + + To create a pixmap from the file, we need to first create an + image and then convert this image into a pixmap using + QPixmap::fromImage(). Once we have the final pixmap, we add it, + with its associated mode and state, to the QIcon's set of + available pixmaps. + + \snippet examples/widgets/icons/mainwindow.cpp 11 + + After running through the entire list of images, we change the + icon of the preview area to the one we just created. + + \snippet examples/widgets/icons/mainwindow.cpp 20 + + In the \c removeAllImages() slot, we simply set the table widget's + row count to zero, automatically removing all the images the user + has loaded into the application. Then we update the set of pixmaps + available to the preview area's icon using the \c changeIcon() + slot. + + \image icons_images_groupbox.png Screenshot of the images group box + + The \c createImagesGroupBox() function is implemented to simplify + the constructor. The main purpose of the function is to create a + QTableWidget that will keep track of the images the user has + loaded into the application. + + \snippet examples/widgets/icons/mainwindow.cpp 21 + + First we create a group box that will contain the table widget. + Then we create a QTableWidget and customize it to suit our + purposes. + + We call QAbstractItemView::setSelectionMode() to prevent the user + from selecting items. + + The QAbstractItemView::setItemDelegate() call sets the item + delegate for the table widget. We create a \c ImageDelegate that + we make the item delegate for our view. + + The QItemDelegate class can be used to provide an editor for an item view + class that is subclassed from QAbstractItemView. Using a delegate + for this purpose allows the editing mechanism to be customized and + developed independently from the model and view. + + In this example we derive \c ImageDelegate from QItemDelegate. + QItemDelegate usually provides line editors, while our subclass + \c ImageDelegate, provides comboboxes for the mode and state + fields. + + \snippet examples/widgets/icons/mainwindow.cpp 22 + \snippet examples/widgets/icons/mainwindow.cpp 23 + + Then we customize the QTableWidget's horizontal header, and hide + the vertical header. + + \snippet examples/widgets/icons/mainwindow.cpp 24 + \snippet examples/widgets/icons/mainwindow.cpp 25 + + At the end, we connect the QTableWidget::itemChanged() signal to + the \c changeIcon() slot to ensuret that the preview area is in + sync with the image table. + + \image icons_size_groupbox.png Screenshot of the icon size group box + + The \c createIconSizeGroupBox() function is called from the + constructor. It creates the widgets controlling the size of the + preview area's icon. + + \snippet examples/widgets/icons/mainwindow.cpp 26 + + First we create a group box that will contain all the widgets; + then we create the radio buttons and the spin box. + + The spin box is not a regular QSpinBox but an \c IconSizeSpinBox. + The \c IconSizeSpinBox class inherits QSpinBox and reimplements + two functions: QSpinBox::textFromValue() and + QSpinBox::valueFromText(). The \c IconSizeSpinBox is designed to + handle icon sizes, e.g., "32 x 32", instead of plain integer + values. + + \snippet examples/widgets/icons/mainwindow.cpp 27 + + Then we connect all of the radio buttons + \l{QRadioButton::toggled()}{toggled()} signals and the spin box's + \l {QSpinBox::valueChanged()}{valueChanged()} signal to the \c + changeSize() slot to make sure that the size of the preview + area's icon is updated whenever the user changes the icon size. + In the end we put the widgets in a layout that we install on the + group box. + + \snippet examples/widgets/icons/mainwindow.cpp 28 + + In the \c createActions() function we create and customize all the + actions needed to implement the functionality associated with the + menu entries in the application. + + In particular we create the \c styleActionGroup based on the + currently available GUI styles using + QStyleFactory. QStyleFactory::keys() returns a list of valid keys, + typically including "windows", "motif", "cde", and + "plastique". Depending on the platform, "windowsxp" and + "macintosh" may be available. + + We create one action for each key, and adds the action to the + action group. Also, for each action, we call QAction::setData() + with the style name. We will retrieve it later using + QAction::data(). + + \snippet examples/widgets/icons/mainwindow.cpp 29 + + In the \c createMenu() function, we add the previously created + actions to the \gui File, \gui View and \gui Help menus. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus. We put each menu in the + application's menu bar, which we retrieve using + QMainWindow::menuBar(). + + \snippet examples/widgets/icons/mainwindow.cpp 30 + + QWidgets have a \l{QWidget::contextMenuPolicy}{contextMenuPolicy} + property that controls how the widget should behave when the user + requests a context menu (e.g., by right-clicking). We set the + QTableWidget's context menu policy to Qt::ActionsContextMenu, + meaning that the \l{QAction}s associated with the widget should + appear in its context menu. + + Then we add the \gui{Add Image} and \gui{Remove All Images} + actions to the table widget. They will then appear in the table + widget's context menu. + + \snippet examples/widgets/icons/mainwindow.cpp 31 + + In the \c checkCurrentStyle() function we go through the group of + style actions, looking for the current GUI style. + + For each action, we first extract the style name using + QAction::data(). Since this is only a QStyleFactory key (e.g., + "macintosh"), we cannot compare it directly to the current + style's class name. We need to create a QStyle object using the + static QStyleFactory::create() function and compare the class + name of the created QStyle object with that of the current style. + As soon as we are done with a QStyle candidate, we delete it. + + For all QObject subclasses that use the \c Q_OBJECT macro, the + class name of an object is available through its + \l{QObject::metaObject()}{meta-object}. + + We can assume that the style is supported by + QStyleFactory, but to be on the safe side we use the \c + Q_ASSERT() macro to make sure that QStyleFactory::create() + returned a valid pointer. + + \section2 IconSizeSpinBox Class Definition + + \snippet examples/widgets/icons/iconsizespinbox.h 0 + + The \c IconSizeSpinBox class is a subclass of QSpinBox. A plain + QSpinBox can only handle integers. But since we want to display + the spin box's values in a more sophisticated way, we need to + subclass QSpinBox and reimplement the QSpinBox::textFromValue() + and QSpinBox::valueFromText() functions. + + \image icons_size_spinbox.png Screenshot of the icon size spinbox + + \section2 IconSizeSpinBox Class Implementation + + \snippet examples/widgets/icons/iconsizespinbox.cpp 0 + + The constructor is trivial. + + \snippet examples/widgets/icons/iconsizespinbox.cpp 2 + + QSpinBox::textFromValue() is used by the spin box whenever it + needs to display a value. The default implementation returns a + base 10 representation of the \c value parameter. + + Our reimplementation returns a QString of the form "32 x 32". + + \snippet examples/widgets/icons/iconsizespinbox.cpp 1 + + The QSpinBox::valueFromText() function is used by the spin box + whenever it needs to interpret text typed in by the user. Since + we reimplement the \c textFromValue() function we also need to + reimplement the \c valueFromText() function to interpret the + parameter text and return the associated int value. + + We parse the text using a regular expression (a QRegExp). We + define an expression that matches one or several digits, + optionally followed by whitespace, an "x" or the times symbol, + whitespace and one or several digits again. + + The first digits of the regular expression are captured using + parentheses. This enables us to use the QRegExp::cap() or + QRegExp::capturedTexts() functions to extract the matched + characters. If the first and second numbers of the spin box value + differ (e.g., "16 x 24"), we use the first number. + + When the user presses \key Enter, QSpinBox first calls + QSpinBox::valueFromText() to interpret the text typed by the + user, then QSpinBox::textFromValue() to present it in a canonical + format (e.g., "16 x 16"). + + \section2 ImageDelegate Class Definition + + \snippet examples/widgets/icons/imagedelegate.h 0 + + The \c ImageDelegate class is a subclass of QItemDelegate. The + QItemDelegate class provides display and editing facilities for + data items from a model. A single QItemDelegate object is + responsible for all items displayed in a item view (in our case, + a QTableWidget). + + A QItemDelegate can be used to provide an editor for an item view + class that is subclassed from QAbstractItemView. Using a delegate + for this purpose allows the editing mechanism to be customized and + developed independently from the model and view. + + \snippet examples/widgets/icons/imagedelegate.h 1 + + The default implementation of QItemDelegate creates a QLineEdit. + Since we want the editor to be a QComboBox, we need to subclass + QItemDelegate and reimplement the QItemDelegate::createEditor(), + QItemDelegate::setEditorData() and QItemDelegate::setModelData() + functions. + + \snippet examples/widgets/icons/imagedelegate.h 2 + + The \c emitCommitData() slot is used to emit the + QImageDelegate::commitData() signal with the appropriate + argument. + + \section2 ImageDelegate Class Implementation + + \snippet examples/widgets/icons/imagedelegate.cpp 0 + + The constructor is trivial. + + \snippet examples/widgets/icons/imagedelegate.cpp 1 + + The default QItemDelegate::createEditor() implementation returns + the widget used to edit the item specified by the model and item + index for editing. The parent widget and style option are used to + control the appearance of the editor widget. + + Our reimplementation create and populate a combobox instead of + the default line edit. The contents of the combobox depends on + the column in the table for which the editor is requested. Column + 1 contains the QIcon modes, whereas column 2 contains the QIcon + states. + + In addition, we connect the combobox's \l + {QComboBox::activated()}{activated()} signal to the \c + emitCommitData() slot to emit the + QAbstractItemDelegate::commitData() signal whenever the user + chooses an item using the combobox. This ensures that the rest of + the application notices the change and updates itself. + + \snippet examples/widgets/icons/imagedelegate.cpp 2 + + The QItemDelegate::setEditorData() function is used by + QTableWidget to transfer data from a QTableWidgetItem to the + editor. The data is stored as a string; we use + QComboBox::findText() to locate it in the combobox. + + Delegates work in terms of models, not items. This makes it + possible to use them with any item view class (e.g., QListView, + QListWidget, QTreeView, etc.). The transition between model and + items is done implicitly by QTableWidget; we don't need to worry + about it. + + \snippet examples/widgets/icons/imagedelegate.cpp 3 + + The QItemDelegate::setEditorData() function is used by QTableWidget + to transfer data back from the editor to the \l{QTableWidgetItem}. + + \snippet examples/widgets/icons/imagedelegate.cpp 4 + + The \c emitCommitData() slot simply emit the + QAbstractItemDelegate::commitData() signal for the editor that + triggered the slot. This signal must be emitted when the editor + widget has completed editing the data, and wants to write it back + into the model. +*/ diff --git a/doc/src/examples/imagecomposition.qdoc b/doc/src/examples/imagecomposition.qdoc new file mode 100644 index 0000000..8cba805 --- /dev/null +++ b/doc/src/examples/imagecomposition.qdoc @@ -0,0 +1,179 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/imagecomposition + \title Image Composition Example + + The Image Composition example lets the user combine images + together using any composition mode supported by QPainter, described + in detail in \l{QPainter#Composition Modes}{Composition Modes}. + + \image imagecomposition-example.png + + \section1 Setting Up The Resource File + + The Image Composition example requires two source images, + \e butterfly.png and \e checker.png that are embedded within + \e imagecomposition.qrc. The file contains the following code: + + \quotefile examples/painting/imagecomposition/imagecomposition.qrc + + For more information on resource files, see \l{The Qt Resource System}. + + \section1 ImageComposer Class Definition + + The \c ImageComposer class is a subclass of QWidget that implements three + private slots, \c chooseSource(), \c chooseDestination(), and + \c recalculateResult(). + + \snippet examples/painting/imagecomposition/imagecomposer.h 0 + + In addition, \c ImageComposer consists of five private functions, + \c addOp(), \c chooseImage(), \c loadImage(), \c currentMode(), and + \c imagePos(), as well as private instances of QToolButton, QComboBox, + QLabel, and QImage. + + \snippet examples/painting/imagecomposition/imagecomposer.h 1 + + \section1 ImageComposer Class Implementation + + We declare a QSize object, \c resultSize, as a static constant with width + and height equal to 200. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 0 + + Within the constructor, we instantiate a QToolButton object, + \c sourceButton and set its \l{QAbstractButton::setIconSize()}{iconSize} + property to \c resultSize. The \c operatorComboBox is instantiated and + then populated using the \c addOp() function. This function accepts a + QPainter::CompositionMode, \a mode, and a QString, \a name, representing + the name of the composition mode. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 1 + + The \c destinationButton is instantiated and its + \l{QAbstractButton::setIconSize()}{iconSize} property is set to + \c resultSize as well. The \l{QLabel}s \c equalLabel and \c resultLabel + are created and \c{resultLabel}'s \l{QWidget::setMinimumWidth()} + {minimumWidth} is set. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 2 + + We connect the following signals to their corresponding slots: + \list + \o \c{sourceButton}'s \l{QPushButton::clicked()}{clicked()} signal is + connected to \c chooseSource(), + \o \c{operatorComboBox}'s \l{QComboBox::activated()}{activated()} + signal is connected to \c recalculateResult(), and + \o \c{destinationButton}'s \l{QToolButton::clicked()}{clicked()} signal + is connected to \c chooseDestination(). + \endlist + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 3 + + A QGridLayout, \c mainLayout, is used to place all the widgets. Note + that \c{mainLayout}'s \l{QLayout::setSizeConstraint()}{sizeConstraint} + property is set to QLayout::SetFixedSize, which means that + \c{ImageComposer}'s size cannot be resized at all. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 4 + + We create a QImage, \c resultImage, and we invoke \c loadImage() twice + to load both the image files in our \e imagecomposition.qrc file. Then, + we set the \l{QWidget::setWindowTitle()}{windowTitle} property to + "Image Composition". + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 5 + + The \c chooseSource() and \c chooseDestination() functions are + convenience functions that invoke \c chooseImage() with specific + parameters. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 6 + \codeline + \snippet examples/painting/imagecomposition/imagecomposer.cpp 7 + + The \c chooseImage() function loads an image of the user's choice, + depending on the \a title, \a image, and \a button. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 10 + + The \c recalculateResult() function is used to calculate amd display the + result of combining the two images together with the user's choice of + composition mode. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 8 + + The \c addOp() function adds an item to the \c operatorComboBox using + \l{QComboBox}'s \l{QComboBox::addItem()}{addItem} function. This function + accepts a QPainter::CompositionMode, \a mode, and a QString, \a name. The + rectangle is filled with Qt::Transparent and both the \c sourceImage and + \c destinationImage are painted, before displaying it on \c resultLabel. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 9 + + The \c loadImage() function paints a transparent background using + \l{QPainter::fillRect()}{fillRect()} and draws \c image in a + centralized position using \l{QPainter::drawImage()}{drawImage()}. + This \c image is then set as the \c{button}'s icon. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 11 + + The \c currentMode() function returns the composition mode currently + selected in \c operatorComboBox. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 12 + + We use the \c imagePos() function to ensure that images loaded onto the + QToolButton objects, \c sourceButton and \c destinationButton, are + centralized. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 13 + + \section1 The \c main() Function + + The \c main() function instantiates QApplication and \c ImageComposer + and invokes its \l{QWidget::show()}{show()} function. + + \snippet examples/painting/imagecomposition/main.cpp 0 + + */ diff --git a/doc/src/examples/imageviewer.qdoc b/doc/src/examples/imageviewer.qdoc new file mode 100644 index 0000000..6881673 --- /dev/null +++ b/doc/src/examples/imageviewer.qdoc @@ -0,0 +1,340 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/imageviewer + \title Image Viewer Example + + The example shows how to combine QLabel and QScrollArea to + display an image. QLabel is typically used for displaying text, + but it can also display an image. QScrollArea provides a + scrolling view around another widget. If the child widget exceeds + the size of the frame, QScrollArea automatically provides scroll + bars. + + The example demonstrates how QLabel's ability to scale its + contents (QLabel::scaledContents), and QScrollArea's ability to + automatically resize its contents (QScrollArea::widgetResizable), + can be used to implement zooming and scaling features. In + addition the example shows how to use QPainter to print an image. + + \image imageviewer-example.png Screenshot of the Image Viewer example + + With the Image Viewer application, the users can view an image of + their choice. The \gui File menu gives the user the possibility + to: + + \list + \o \gui{Open...} - Open an image file + \o \gui{Print...} - Print an image + \o \gui{Exit} - Exit the application + \endlist + + Once an image is loaded, the \gui View menu allows the users to: + + \list + \o \gui{Zoom In} - Scale the image up by 25% + \o \gui{Zoom Out} - Scale the image down by 25% + \o \gui{Normal Size} - Show the image at its original size + \o \gui{Fit to Window} - Stretch the image to occupy the entire window + \endlist + + In addition the \gui Help menu provides the users with information + about the Image Viewer example in particular, and about Qt in + general. + + \section1 ImageViewer Class Definition + + \snippet examples/widgets/imageviewer/imageviewer.h 0 + + The \c ImageViewer class inherits from QMainWindow. We reimplement + the constructor, and create several private slots to facilitate + the menu entries. In addition we create four private functions. + + We use \c createActions() and \c createMenus() when constructing + the \c ImageViewer widget. We use the \c updateActions() function + to update the menu entries when a new image is loaded, or when + the \gui {Fit to Window} option is toggled. The zoom slots use \c + scaleImage() to perform the zooming. In turn, \c + scaleImage() uses \c adjustScrollBar() to preserve the focal point after + scaling an image. + + \section1 ImageViewer Class Implementation + + \snippet examples/widgets/imageviewer/imageviewer.cpp 0 + + In the constructor we first create the label and the scroll area. + + We set \c {imageLabel}'s size policy to \l + {QSizePolicy::Ignored}{ignored}, making the users able to scale + the image to whatever size they want when the \gui {Fit to Window} + option is turned on. Otherwise, the default size polizy (\l + {QSizePolicy::Preferred}{preferred}) will make scroll bars appear + when the scroll area becomes smaller than the label's minimum size + hint. + + We ensure that the label will scale its contents to fill all + available space, to enable the image to scale properly when + zooming. If we omitted to set the \c {imageLabel}'s \l + {QLabel::scaledContents}{scaledContents} property, zooming in + would enlarge the QLabel, but leave the pixmap at + its original size, exposing the QLabel's background. + + We make \c imageLabel the scroll area's child widget, and we make + \c scrollArea the central widget of the QMainWindow. At the end + we create the associated actions and menus, and customize the \c + {ImageViewer}'s appearance. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 1 + \snippet examples/widgets/imageviewer/imageviewer.cpp 2 + + In the \c open() slot, we show a file dialog to the user. The + easiest way to create a QFileDialog is to use the static + convenience functions. QFileDialog::getOpenFileName() returns an + existing file selected by the user. If the user presses \gui + Cancel, QFileDialog returns an empty string. + + Unless the file name is a empty string, we check if the file's + format is an image format by constructing a QImage which tries to + load the image from the file. If the constructor returns a null + image, we use a QMessageBox to alert the user. + + The QMessageBox class provides a modal dialog with a short + message, an icon, and some buttons. As with QFileDialog the + easiest way to create a QMessageBox is to use its static + convenience functions. QMessageBox provides a range of different + messages arranged along two axes: severity (question, + information, warning and critical) and complexity (the number of + necessary response buttons). In this particular example an + information message with an \gui OK button (the default) is + sufficient, since the message is part of a normal operation. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 3 + \snippet examples/widgets/imageviewer/imageviewer.cpp 4 + + If the format is supported, we display the image in \c imageLabel + by setting the label's \l {QLabel::pixmap}{pixmap}. Then we enable + the \gui Print and \gui {Fit to Window} menu entries and update + the rest of the view menu entries. The \gui Open and \gui Exit + entries are enabled by default. + + If the \gui {Fit to Window} option is turned off, the + QScrollArea::widgetResizable property is \c false and it is + our responsibility (not QScrollArea's) to give the QLabel a + reasonable size based on its contents. We call + \{QWidget::adjustSize()}{adjustSize()} to achieve this, which is + essentially the same as + + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.qdoc 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.qdoc 1 + + In release mode, the macro simply disappear. The mode can be set + in the application's \c .pro file. One way to do so is to add an + option to \gui qmake when building the appliction: + + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.qdoc 2 + + or + + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.qdoc 3 + + Another approach is to add this line directly to the \c .pro + file. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 7 + \snippet examples/widgets/imageviewer/imageviewer.cpp 8 + + Then we present a print dialog allowing the user to choose a + printer and to set a few options. We construct a painter with a + QPrinter as the paint device. We set the painter's window + and viewport in such a way that the image is as large as possible + on the paper, but without altering its + \l{Qt::KeepAspectRatio}{aspect ratio}. + + In the end we draw the pixmap at position (0, 0). + + \snippet examples/widgets/imageviewer/imageviewer.cpp 9 + \snippet examples/widgets/imageviewer/imageviewer.cpp 10 + + We implement the zooming slots using the private \c scaleImage() + function. We set the scaling factors to 1.25 and 0.8, + respectively. These factor values ensure that a \gui {Zoom In} + action and a \gui {Zoom Out} action will cancel each other (since + 1.25 * 0.8 == 1), and in that way the normal image size can be + restored using the zooming features. + + The screenshots below show an image in its normal size, and the + same image after zooming in: + + \table + \row + \o \inlineimage imageviewer-original_size.png + \o \inlineimage imageviewer-zoom_in_1.png + \o \inlineimage imageviewer-zoom_in_2.png + \endtable + + \snippet examples/widgets/imageviewer/imageviewer.cpp 11 + \snippet examples/widgets/imageviewer/imageviewer.cpp 12 + + When zooming, we use the QLabel's ability to scale its contents. + Such scaling doesn't change the actual size hint of the contents. + And since the \l {QLabel::adjustSize()}{adjustSize()} function + use those size hint, the only thing we need to do to restore the + normal size of the currently displayed image is to call \c + adjustSize() and reset the scale factor to 1.0. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 13 + \snippet examples/widgets/imageviewer/imageviewer.cpp 14 + + The \c fitToWindow() slot is called each time the user toggled + the \gui {Fit to Window} option. If the slot is called to turn on + the option, we tell the scroll area to resize its child widget + with the QScrollArea::setWidgetResizable() function. Then we + disable the \gui {Zoom In}, \gui {Zoom Out} and \gui {Normal + Size} menu entries using the private \c updateActions() function. + + If the \l {QScrollArea::widgetResizable} property is set to \c + false (the default), the scroll area honors the size of its child + widget. If this property is set to \c true, the scroll area will + automatically resize the widget in order to avoid scroll bars + where they can be avoided, or to take advantage of extra space. + But the scroll area will honor the minimum size hint of its child + widget independent of the widget resizable property. So in this + example we set \c {imageLabel}'s size policy to \l + {QSizePolicy::Ignored}{ignored} in the constructor, to avoid that + scroll bars appear when the scroll area becomes smaller than the + label's minimum size hint. + + The screenshots below shows an image in its normal size, and the + same image with the \gui {Fit to window} option turned on. + Enlarging the window will stretch the image further, as shown in + the third screenshot. + + \table + \row + \o \inlineimage imageviewer-original_size.png + \o \inlineimage imageviewer-fit_to_window_1.png + \o \inlineimage imageviewer-fit_to_window_2.png + \endtable + + If the slot is called to turn off the option, the + {QScrollArea::setWidgetResizable} property is set to \c false. We + also restore the image pixmap to its normal size by adjusting the + label's size to its content. And in the end we update the view + menu entries. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 15 + \snippet examples/widgets/imageviewer/imageviewer.cpp 16 + + We implement the \c about() slot to create a message box + describing what the example is designed to show. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 17 + \snippet examples/widgets/imageviewer/imageviewer.cpp 18 + + In the private \c createAction() function, we create the + actions providing the application features. + + We assign a short-cut key to each action and connect them to the + appropiate slots. We only enable the \c openAct and \c exitAxt at + the time of creation, the others are updated once an image has + been loaded into the application. In addition we make the \c + fitToWindowAct \l {QAction::checkable}{checkable}. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 19 + \snippet examples/widgets/imageviewer/imageviewer.cpp 20 + + In the private \c createMenu() function, we add the previously + created actions to the \gui File, \gui View and \gui Help menus. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus. The QMenuBar class provides + a horizontal menu bar that consists of a list of pull-down menu + items. So at the end we put the menus in the \c {ImageViewer}'s + menu bar which we retrieve with the QMainWindow::menuBar() + function. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 21 + \snippet examples/widgets/imageviewer/imageviewer.cpp 22 + + The private \c updateActions() function enables or disables the + \gui {Zoom In}, \gui {Zoom Out} and \gui {Normal Size} menu + entries depending on whether the \gui {Fit to Window} option is + turned on or off. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 23 + \snippet examples/widgets/imageviewer/imageviewer.cpp 24 + + In \c scaleImage(), we use the \c factor parameter to calculate + the new scaling factor for the displayed image, and resize \c + imageLabel. Since we set the + \l{QLabel::scaledContents}{scaledContents} property to \c true in + the constructor, the call to QWidget::resize() will scale the + image displayed in the label. We also adjust the scroll bars to + preserve the focal point of the image. + + At the end, if the scale factor is less than 33.3% or greater + than 300%, we disable the respective menu entry to prevent the + image pixmap from becoming too large, consuming too much + resources in the window system. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 25 + \snippet examples/widgets/imageviewer/imageviewer.cpp 26 + + Whenever we zoom in or out, we need to adjust the scroll bars in + consequence. It would have been tempting to simply call + + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.qdoc 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/itemviewspuzzle.qdoc b/doc/src/examples/itemviewspuzzle.qdoc new file mode 100644 index 0000000..99ef7d4 --- /dev/null +++ b/doc/src/examples/itemviewspuzzle.qdoc @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/puzzle + \title Item Views Puzzle Example + + The Puzzle example shows how to enable drag and drop with a custom model + to allow items to be transferred between a view and another widget. + + \image itemviewspuzzle-example.png + + This example is an implementation of a simple jigsaw puzzle game using the + built-in support for drag and drop provided by Qt's model/view framework. + The \l{Drag and Drop Puzzle Example}{Drag and Drop Puzzle} example shows + many of the same features, but takes an alternative approach that uses Qt's + drag and drop API at the application level to handle drag and drop + operations. +*/ diff --git a/doc/src/examples/licensewizard.qdoc b/doc/src/examples/licensewizard.qdoc new file mode 100644 index 0000000..a702c06 --- /dev/null +++ b/doc/src/examples/licensewizard.qdoc @@ -0,0 +1,232 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/licensewizard + \title License Wizard Example + + The License Wizard example shows how to implement complex wizards in + Qt. + + \image licensewizard-example.png Screenshot of the License Wizard example + + Most wizards have a linear structure, with page 1 followed by + page 2 and so on until the last page. The + \l{dialogs/classwizard}{Class Wizard} example shows how to create + such wizards. + + Some wizards are more complex in that they allow different + traversal paths based on the information provided by the user. + The License Wizard example illustrates this. It provides five + wizard pages; depending on which options are selected, the user + can reach different pages. + + \image licensewizard-flow.png The License Wizard pages + + The example consists of the following classes: + + \list + \o \c LicenseWizard inherits QWizard and implements a non-linear + five-page wizard that leads the user through the process of + choosing a license agreement. + \o \c IntroPage, \c EvaluatePage, \c RegisterPage, \c + DetailsPage, and \c ConclusionPage are QWizardPage subclasses + that implement the wizard pages. + \endlist + + \section1 The LicenseWizard Class + + The \c LicenseWizard class derives from QWizard and provides a + five-page wizard that guides the user through the process of + registering their copy of a fictitious software product. Here's + the class definition: + + \snippet examples/dialogs/licensewizard/licensewizard.h 1 + + The class's public API is limited to a constructor and an enum. + The enum defines the IDs associated with the various pages: + + \table + \header \o Class name \o Enum value \o Page ID + \row \o \c IntroPage \o \c Page_Intro \o 0 + \row \o \c EvaluatePage \o \c Page_Evaluate \o 1 + \row \o \c RegisterPage \o \c Page_Register \o 2 + \row \o \c DetailsPage \o \c Page_Details \o 3 + \row \o \c ConclusionPage \o \c Page_Conclusion \o 4 + \endtable + + For this example, the IDs are arbitrary. The only constraints are + that they must be unique and different from -1. IDs allow us to + refer to pages. + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 2 + + In the constructor, we create the five pages, insert them into + the wizard using QWizard::setPage(), and set \c Page_Intro to be + the first page. + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 3 + \snippet examples/dialogs/licensewizard/licensewizard.cpp 4 + + We set the style to \l{QWizard::}{ModernStyle} on all platforms + except Mac OS X, + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 5 + \snippet examples/dialogs/licensewizard/licensewizard.cpp 6 + + We configure the QWizard to show a \gui Help button, which is + connected to our \c showHelp() slot. We also set the + \l{QWizard::}{LogoPixmap} for all pages that have a header (i.e., + \c EvaluatePage, \c RegisterPage, and \c DetailsPage). + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 9 + \snippet examples/dialogs/licensewizard/licensewizard.cpp 11 + \dots + \snippet examples/dialogs/licensewizard/licensewizard.cpp 13 + + In \c showHelp(), we display help texts that are appropiate for + the current page. If the user clicks \gui Help twice for the same + page, we say, "Sorry, I already gave what help I could. Maybe you + should try asking a human?" + + \section1 The IntroPage Class + + The pages are defined in \c licensewizard.h and implemented in \c + licensewizard.cpp, together with \c LicenseWizard. + + Here's the definition and implementation of \c{IntroPage}: + + \snippet examples/dialogs/licensewizard/licensewizard.h 4 + \codeline + \snippet examples/dialogs/licensewizard/licensewizard.cpp 16 + + A page inherits from QWizardPage. We set a + \l{QWizardPage::}{title} and a + \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting + any \l{QWizardPage::}{subTitle}, we ensure that no header is + displayed for this page. (On Windows, it is customary for wizards + to display a watermark pixmap on the first and last pages, and to + have a header on the other pages.) + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 17 + \snippet examples/dialogs/licensewizard/licensewizard.cpp 19 + + The \c nextId() function returns the ID for \c EvaluatePage if + the \gui{Evaluate the product for 30 days} option is checked; + otherwise it returns the ID for \c RegisterPage. + + \section1 The EvaluatePage Class + + The \c EvaluatePage is slightly more involved: + + \snippet examples/dialogs/licensewizard/licensewizard.h 5 + \codeline + \snippet examples/dialogs/licensewizard/licensewizard.cpp 20 + \dots + \snippet examples/dialogs/licensewizard/licensewizard.cpp 21 + \dots + \snippet examples/dialogs/licensewizard/licensewizard.cpp 22 + + First, we set the page's \l{QWizardPage::}{title} + and \l{QWizardPage::}{subTitle}. + + Then we create the child widgets, create \l{Registering and Using + Fields}{wizard fields} associated with them, and put them into + layouts. The fields are created with an asterisk (\c + *) next to their name. This makes them \l{mandatory fields}, that + is, fields that must be filled before the user can press the + \gui Next button (\gui Continue on Mac OS X). The fields' values + can be accessed from any other page using QWizardPage::field(). + + Resetting the page amounts to clearing the two text fields. + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 23 + + The next page is always the \c ConclusionPage. + + \section1 The ConclusionPage Class + + The \c RegisterPage and \c DetailsPage are very similar to \c + EvaluatePage. Let's go directly to the \c ConclusionPage: + + \snippet examples/dialogs/licensewizard/licensewizard.h 6 + + This time, we reimplement QWizardPage::initializePage() and + QWidget::setVisible(), in addition to + \l{QWizardPage::}{nextId()}. We also declare a private slot: + \c printButtonClicked(). + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 18 + + The default implementation of QWizardPage::nextId() returns + the page with the next ID, or -1 if the current page has the + highest ID. This behavior would work here, because \c + Page_Conclusion equals 5 and there is no page with a higher ID, + but to avoid relying on such subtle behavior, we reimplement + \l{QWizardPage::}{nextId()} to return -1. + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 27 + + We use QWizard::hasVisitedPage() to determine the type of + license agreement the user has chosen. If the user filled the \c + EvaluatePage, the license text refers to an Evaluation License + Agreement. If the user filled the \c DetailsPage, the license + text is a First-Time License Agreement. If the user provided an + upgrade key and skipped the \c DetailsPage, the license text is + an Update License Agreement. + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 28 + + We want to display a \gui Print button in the wizard when the \c + ConclusionPage is up. One way to accomplish this is to reimplement + QWidget::setVisible(): + + \list + \o If the page is shown, we set the \l{QWizard::}{CustomButton1} button's + text to \gui{\underline{P}rint}, we enable the \l{QWizard::}{HaveCustomButton1} + option, and we connect the QWizard's \l{QWizard::}{customButtonClicked()} + signal to our \c printButtonClicked() slot. + \o If the page is hidden, we disable the \l{QWizard::}{HaveCustomButton1} + option and disconnect the \c printButtonClicked() slot. + \endlist + + \sa QWizard, {Class Wizard Example}, {Trivial Wizard Example} +*/ diff --git a/doc/src/examples/lineedits.qdoc b/doc/src/examples/lineedits.qdoc new file mode 100644 index 0000000..ee702ae --- /dev/null +++ b/doc/src/examples/lineedits.qdoc @@ -0,0 +1,175 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/lineedits + \title Line Edits Example + + The Line Edits example demonstrates the many ways that QLineEdit can be used, and + shows the effects of various properties and validators on the input and output + supplied by the user. + + \image lineedits-example.png + + The example consists of a single \c Window class, containing a selection of + line edits with different input constraints and display properties that can be + changed by selecting items from comboboxes. Presenting these together helps + developers choose suitable properties to use with line edits, and makes it easy + to compare the effects of each validator on user input. + + \section1 Window Class Definition + + The \c Window class inherits QWidget and contains a constructor and several + slots: + + \snippet examples/widgets/lineedits/window.h 0 + + The slots are used to update the type of validator used for a given line edit when + a new validator has been selected in the associated combobox. The line edits + are stored in the window for use in these slots. + + \section1 Window Class Implementation + + The \c Window constructor is used to set up the line edits, validators, + and comboboxes, connect signals from the comboboxes to slots in the \c Window + class, and arrange the child widgets in layouts. + + We begin by constructing a \l{QGroupBox}{group box} to hold a label, combobox, + and line edit so that we can demonstrate the QLineEdit::echoMode property: + + \snippet examples/widgets/lineedits/window.cpp 0 + + At this point, none of these widgets have been arranged in layouts. Eventually, + the \c echoLabel, \c echoComboBox, and \c echoLineEdit will be placed in a + vertical layout inside the \c echoGroup group box. + + Similarly, we construct group boxes and collections of widgets to show the + effects of QIntValidator and QDoubleValidator on a line edit's contents: + + \snippet examples/widgets/lineedits/window.cpp 1 + + Text alignment is demonstrated by another group of widgets: + + \snippet examples/widgets/lineedits/window.cpp 2 + + QLineEdit supports the use of \l{QLineEdit::inputMask}{input masks}. + These only allow the user to type characters into the line edit that + follow a simple specification. We construct a group of widgets to + demonstrate a selection of predefined masks: + + \snippet examples/widgets/lineedits/window.cpp 3 + + Another useful feature of QLineEdit is its ability to make its contents + read-only. This property is used to control access to a line edit in the + following group of widgets: + + \snippet examples/widgets/lineedits/window.cpp 4 + + Now that all the child widgets have been constructed, we connect signals + from the comboboxes to slots in the \c Window object: + + \snippet examples/widgets/lineedits/window.cpp 5 + + Each of these connections use the QComboBox::activated() signal that + supplies an integer to the slot. This will be used to efficiently + make changes to the appropriate line edit in each slot. + + We place each combobox, line edit, and label in a layout for each group + box, beginning with the layout for the \c echoGroup group box: + + \snippet examples/widgets/lineedits/window.cpp 6 + + The other layouts are constructed in the same way: + + \snippet examples/widgets/lineedits/window.cpp 7 + + Finally, we place each group box in a grid layout for the \c Window object + and set the window title: + + \snippet examples/widgets/lineedits/window.cpp 8 + + The slots respond to signals emitted when the comboboxes are changed by the + user. + + When the combobox for the \gui{Echo} group box is changed, the \c echoChanged() + slot is called: + + \snippet examples/widgets/lineedits/window.cpp 9 + + The slot updates the line edit in the same group box to use an echo mode that + corresponds to the entry described in the combobox. + + When the combobox for the \gui{Validator} group box is changed, the + \c validatorChanged() slot is called: + + \snippet examples/widgets/lineedits/window.cpp 10 + + The slot either creates a new validator for the line edit to use, or it removes + the validator in use by calling QLineEdit::setValidator() with a zero pointer. + We clear the line edit in this case to ensure that the new validator is + initially given valid input to work with. + + When the combobox for the \gui{Alignment} group box is changed, the + \c alignmentChanged() slot is called: + + \snippet examples/widgets/lineedits/window.cpp 11 + + This changes the way that text is displayed in the line edit to correspond with + the description selected in the combobox. + + The \c inputMaskChanged() slot handles changes to the combobox in the + \gui{Input Mask} group box: + + \snippet examples/widgets/lineedits/window.cpp 12 + + Each entry in the relevant combobox is associated with an input mask. We set + a new mask by calling the QLineEdit::setMask() function with a suitable string; + the mask is disabled if an empty string is used. + + The \c accessChanged() slot handles changes to the combobox in the + \gui{Access} group box: + + \snippet examples/widgets/lineedits/window.cpp 13 + + Here, we simply associate the \gui{False} and \gui{True} entries in the combobox + with \c false and \c true values to be passed to QLineEdit::setReadOnly(). This + allows the user to enable and disable input to the line edit. +*/ diff --git a/doc/src/examples/localfortuneclient.qdoc b/doc/src/examples/localfortuneclient.qdoc new file mode 100644 index 0000000..b4489b1 --- /dev/null +++ b/doc/src/examples/localfortuneclient.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example ipc/localfortuneclient + \title Local Fortune Client Example + + The Local Fortune Client example shows how to create a client for a simple + local service using QLocalSocket. It is intended to be run alongside the + \l{ipc/localfortuneserver}{Local Fortune Server} example. + + \image localfortuneclient-example.png Screenshot of the Local Fortune Client example + +*/ diff --git a/doc/src/examples/localfortuneserver.qdoc b/doc/src/examples/localfortuneserver.qdoc new file mode 100644 index 0000000..3b2395c --- /dev/null +++ b/doc/src/examples/localfortuneserver.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example ipc/localfortuneserver + \title Local Fortune Server Example + + The Local Fortune Server example shows how to create a server for a simple + local service. It is intended to be run alongside the + \l{ipc/localfortuneclient}{Local Fortune Client} example + + \image localfortuneserver-example.png Screenshot of the Local Fortune Server example + */ diff --git a/doc/src/examples/loopback.qdoc b/doc/src/examples/loopback.qdoc new file mode 100644 index 0000000..b100f71 --- /dev/null +++ b/doc/src/examples/loopback.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/loopback + \title Loopback Example + + The Loopback example shows how to communicate between simple clients and servers on a local + host. + + \image loopback-example.png +*/ diff --git a/doc/src/examples/mandelbrot.qdoc b/doc/src/examples/mandelbrot.qdoc new file mode 100644 index 0000000..d2a3ee1 --- /dev/null +++ b/doc/src/examples/mandelbrot.qdoc @@ -0,0 +1,382 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example threads/mandelbrot + \title Mandelbrot Example + + The Mandelbrot example shows how to use a worker thread to + perform heavy computations without blocking the main thread's + event loop. + + The heavy computation here is the Mandelbrot set, probably the + world's most famous fractal. These days, while sophisticated + programs such as \l{XaoS} that provide real-time zooming in the + Mandelbrot set, the standard Mandelbrot algorithm is just slow + enough for our purposes. + + \image mandelbrot-example.png Screenshot of the Mandelbrot example + + In real life, the approach described here is applicable to a + large set of problems, including synchronous network I/O and + database access, where the user interface must remain responsive + while some heavy operation is taking place. The \l + network/blockingfortuneclient example shows the same principle at + work in a TCP client. + + The Mandelbrot application supports zooming and scrolling using + the mouse or the keyboard. To avoid freezing the main thread's + event loop (and, as a consequence, the application's user + interface), we put all the fractal computation in a separate + worker thread. The thread emits a signal when it is done + rendering the fractal. + + During the time where the worker thread is recomputing the + fractal to reflect the new zoom factor position, the main thread + simply scales the previously rendered pixmap to provide immediate + feedback. The result doesn't look as good as what the worker + thread eventually ends up providing, but at least it makes the + application more responsive. The sequence of screenshots below + shows the original image, the scaled image, and the rerendered + image. + + \table + \row + \o \inlineimage mandelbrot_zoom1.png + \o \inlineimage mandelbrot_zoom2.png + \o \inlineimage mandelbrot_zoom3.png + \endtable + + Similarly, when the user scrolls, the previous pixmap is scrolled + immediately, revealing unpainted areas beyond the edge of the + pixmap, while the image is rendered by the worker thread. + + \table + \row + \o \inlineimage mandelbrot_scroll1.png + \o \inlineimage mandelbrot_scroll2.png + \o \inlineimage mandelbrot_scroll3.png + \endtable + + The application consists of two classes: + + \list + \o \c RenderThread is a QThread subclass that renders + the Mandelbrot set. + \o \c MandelbrotWidget is a QWidget subclass that shows the + Mandelbrot set on screen and lets the user zoom and scroll. + \endlist + + If you are not already familiar with Qt's thread support, we + recommend that you start by reading the \l{Thread Support in Qt} + overview. + + \section1 RenderThread Class Definition + + We'll start with the definition of the \c RenderThread class: + + \snippet examples/threads/mandelbrot/renderthread.h 0 + + The class inherits QThread so that it gains the ability to run in + a separate thread. Apart from the constructor and destructor, \c + render() is the only public function. Whenever the thread is done + rendering an image, it emits the \c renderedImage() signal. + + The protected \c run() function is reimplemented from QThread. It + is automatically called when the thread is started. + + In the \c private section, we have a QMutex, a QWaitCondition, + and a few other data members. The mutex protects the other data + member. + + \section1 RenderThread Class Implementation + + \snippet examples/threads/mandelbrot/renderthread.cpp 0 + + In the constructor, we initialize the \c restart and \c abort + variables to \c false. These variables control the flow of the \c + run() function. + + We also initialize the \c colormap array, which contains a series + of RGB colors. + + \snippet examples/threads/mandelbrot/renderthread.cpp 1 + + The destructor can be called at any point while the thread is + active. We set \c abort to \c true to tell \c run() to stop + running as soon as possible. We also call + QWaitCondition::wakeOne() to wake up the thread if it's sleeping. + (As we will see when we review \c run(), the thread is put to + sleep when it has nothing to do.) + + The important thing to notice here is that \c run() is executed + in its own thread (the worker thread), whereas the \c + RenderThread constructor and destructor (as well as the \c + render() function) are called by the thread that created the + worker thread. Therefore, we need a mutex to protect accesses to + the \c abort and \c condition variables, which might be accessed + at any time by \c run(). + + At the end of the destructor, we call QThread::wait() to wait + until \c run() has exited before the base class destructor is + invoked. + + \snippet examples/threads/mandelbrot/renderthread.cpp 2 + + The \c render() function is called by the \c MandelbrotWidget + whenever it needs to generate a new image of the Mandelbrot set. + The \c centerX, \c centerY, and \c scaleFactor parameters specify + the portion of the fractal to render; \c resultSize specifies the + size of the resulting QImage. + + The function stores the parameters in member variables. If the + thread isn't already running, it starts it; otherwise, it sets \c + restart to \c true (telling \c run() to stop any unfinished + computation and start again with the new parameters) and wakes up + the thread, which might be sleeping. + + \snippet examples/threads/mandelbrot/renderthread.cpp 3 + + \c run() is quite a big function, so we'll break it down into + parts. + + The function body is an infinite loop which starts by storing the + rendering parameters in local variables. As usual, we protect + accesses to the member variables using the class's mutex. Storing + the member variables in local variables allows us to minimize the + amout of code that needs to be protected by a mutex. This ensures + that the main thread will never have to block for too long when + it needs to access \c{RenderThread}'s member variables (e.g., in + \c render()). + + The \c forever keyword is, like \c foreach, a Qt pseudo-keyword. + + \snippet examples/threads/mandelbrot/renderthread.cpp 4 + \snippet examples/threads/mandelbrot/renderthread.cpp 5 + \snippet examples/threads/mandelbrot/renderthread.cpp 6 + \snippet examples/threads/mandelbrot/renderthread.cpp 7 + + Then comes the core of the algorithm. Instead of trying to create + a perfect Mandelbrot set image, we do multiple passes and + generate more and more precise (and computationally expensive) + approximations of the fractal. + + If we discover inside the loop that \c restart has been set to \c + true (by \c render()), we break out of the loop immediately, so + that the control quickly returns to the very top of the outer + loop (the \c forever loop) and we fetch the new rendering + parameters. Similarly, if we discover that \c abort has been set + to \c true (by the \c RenderThread destructor), we return from + the function immediately, terminating the thread. + + The core algorithm is beyond the scope of this tutorial. + + \snippet examples/threads/mandelbrot/renderthread.cpp 8 + \snippet examples/threads/mandelbrot/renderthread.cpp 9 + + Once we're done with all the iterations, we call + QWaitCondition::wait() to put the thread to sleep by calling, + unless \c restart is \c true. There's no use in keeping a worker + thread looping indefinitely while there's nothing to do. + + \snippet examples/threads/mandelbrot/renderthread.cpp 10 + + The \c rgbFromWaveLength() function is a helper function that + converts a wave length to a RGB value compatible with 32-bit + \l{QImage}s. It is called from the constructor to initialize the + \c colormap array with pleasing colors. + + \section1 MandelbrotWidget Class Defintion + + The \c MandelbrotWidget class uses \c RenderThread to draw the + Mandelbrot set on screen. Here's the class definition: + + \snippet examples/threads/mandelbrot/mandelbrotwidget.h 0 + + The widget reimplements many event handlers from QWidget. In + addition, it has an \c updatePixmap() slot that we'll connect to + the worker thread's \c renderedImage() signal to update the + display whenever we receive new data from the thread. + + Among the private variables, we have \c thread of type \c + RenderThread and \c pixmap, which contains the last rendered + image. + + \section1 MandelbrotWidget Class Implementation + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 0 + + The implementation starts with a few contants that we'll need + later on. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 1 + + The interesting part of the constructor is the + qRegisterMetaType() and QObject::connect() calls. Let's start + with the \l{QObject::connect()}{connect()} call. + + Although it looks like a standard signal-slot connection between + two \l{QObject}s, because the signal is emitted in a different + thread than the receiver lives in, the connection is effectively a + \l{Qt::QueuedConnection}{queued connection}. These connections are + asynchronous (i.e., non-blocking), meaning that the slot will be + called at some point after the \c emit statement. What's more, the + slot will be invoked in the thread in which the receiver lives. + Here, the signal is emitted in the worker thread, and the slot is + executed in the GUI thread when control returns to the event loop. + + With queued connections, Qt must store a copy of the arguments + that were passed to the signal so that it can pass them to the + slot later on. Qt knows how to take of copy of many C++ and Qt + types, but QImage isn't one of them. We must therefore call the + template function qRegisterMetaType() before we can use QImage + as parameter in queued connections. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 2 + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 3 + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 4 + + In \l{QWidget::paintEvent()}{paintEvent()}, we start by filling + the background with black. If we have nothing yet to paint (\c + pixmap is null), we print a message on the widget asking the user + to be patient and return from the function immediately. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 5 + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 6 + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 7 + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 8 + + If the pixmap has the right scale factor, we draw the pixmap directly onto + the widget. Otherwise, we scale and translate the \l{The Coordinate + System}{coordinate system} before we draw the pixmap. By reverse mapping + the widget's rectangle using the scaled painter matrix, we also make sure + that only the exposed areas of the pixmap are drawn. The calls to + QPainter::save() and QPainter::restore() make sure that any painting + performed afterwards uses the standard coordinate system. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 9 + + At the end of the paint event handler, we draw a text string and + a semi-transparent rectangle on top of the fractal. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 10 + + Whenever the user resizes the widget, we call \c render() to + start generating a new image, with the same \c centerX, \c + centerY, and \c curScale parameters but with the new widget size. + + Notice that we rely on \c resizeEvent() being automatically + called by Qt when the widget is shown the first time to generate + the image the very first time. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 11 + + The key press event handler provides a few keyboard bindings for + the benefit of users who don't have a mouse. The \c zoom() and \c + scroll() functions will be covered later. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 12 + + The wheel event handler is reimplemented to make the mouse wheel + control the zoom level. QWheelEvent::delta() returns the angle of + the wheel mouse movement, in eights of a degree. For most mice, + one wheel step corresponds to 15 degrees. We find out how many + mouse steps we have and determine the zoom factor in consequence. + For example, if we have two wheel steps in the positive direction + (i.e., +30 degrees), the zoom factor becomes \c ZoomInFactor + to the second power, i.e. 0.8 * 0.8 = 0.64. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 13 + + When the user presses the left mouse button, we store the mouse + pointer position in \c lastDragPos. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 14 + + When the user moves the mouse pointer while the left mouse button + is pressed, we adjust \c pixmapOffset to paint the pixmap at a + shifted position and call QWidget::update() to force a repaint. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 15 + + When the left mouse button is released, we update \c pixmapOffset + just like we did on a mouse move and we reset \c lastDragPos to a + default value. Then, we call \c scroll() to render a new image + for the new position. (Adjusting \c pixmapOffset isn't sufficient + because areas revealed when dragging the pixmap are drawn in + black.) + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 16 + + The \c updatePixmap() slot is invoked when the worker thread has + finished rendering an image. We start by checking whether a drag + is in effect and do nothing in that case. In the normal case, we + store the image in \c pixmap and reinitialize some of the other + members. At the end, we call QWidget::update() to refresh the + display. + + At this point, you might wonder why we use a QImage for the + parameter and a QPixmap for the data member. Why not stick to one + type? The reason is that QImage is the only class that supports + direct pixel manipulation, which we need in the worker thread. On + the other hand, before an image can be drawn on screen, it must + be converted into a pixmap. It's better to do the conversion once + and for all here, rather than in \c paintEvent(). + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 17 + + In \c zoom(), we recompute \c curScale. Then we call + QWidget::update() to draw a scaled pixmap, and we ask the worker + thread to render a new image corresponding to the new \c curScale + value. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 18 + + \c scroll() is similar to \c zoom(), except that the affected + parameters are \c centerX and \c centerY. + + \section1 The main() Function + + The application's multithreaded nature has no impact on its \c + main() function, which is as simple as usual: + + \snippet examples/threads/mandelbrot/main.cpp 0 +*/ diff --git a/doc/src/examples/masterdetail.qdoc b/doc/src/examples/masterdetail.qdoc new file mode 100644 index 0000000..d7dc0e2 --- /dev/null +++ b/doc/src/examples/masterdetail.qdoc @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/masterdetail + \title Master Detail Example + + The Master Detail Example shows how to present data from different + data sources in the same application. The album titles, and the + corresponding artists and release dates, are kept in a + database, while each album's tracks are stored in an XML + file. + + The example also shows how to add as well as remove data from both + the database and the associated XML file using the API provided by + the QtSql and QtXml modules, respectively. + + \image masterdetail-example.png +*/ diff --git a/doc/src/examples/mdi.qdoc b/doc/src/examples/mdi.qdoc new file mode 100644 index 0000000..f97db5e --- /dev/null +++ b/doc/src/examples/mdi.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example mainwindows/mdi + \title MDI Example + + The MDI example shows how to implement a Multiple Document Interface using Qt's + QMdiArea class. + + \image mdi-example.png + +*/ diff --git a/doc/src/examples/menus.qdoc b/doc/src/examples/menus.qdoc new file mode 100644 index 0000000..0500101 --- /dev/null +++ b/doc/src/examples/menus.qdoc @@ -0,0 +1,232 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example mainwindows/menus + \title Menus Example + + The Menus example demonstrates how menus can be used in a main + window application. + + A menu widget can be either a pull-down menu in a menu bar or a + standalone context menu. Pull-down menus are shown by the menu bar + when the user clicks on the respective item or presses the + specified shortcut key. Context menus are usually invoked by some + special keyboard key or by right-clicking. + + \image menus-example.png + + A menu consists of a list of \e action items. In applications, + many common commands can be invoked via menus, toolbar buttons as + well as keyboard shortcuts. Since the user expects the commands to + be performed in the same way, regardless of the user interface + used, it is useful to represent each command as an action. + + The Menus example consists of one single class, \c MainWindow, derived + from the QMainWindow class. When choosing one of the + action items in our application, it will display the item's path + in its central widget. + + \section1 MainWindow Class Definition + + QMainWindow provides a main application window, with a menu bar, + tool bars, dock widgets and a status bar around a large central + widget. + + \snippet examples/mainwindows/menus/mainwindow.h 0 + + In this example, we will see how to implement pull-down menus as + well as a context menu. In order to implement a custom context + menu we must reimplement QWidget's \l + {QWidget::}{contextMenuEvent()} function to receive the context + menu events for our main window. + + \snippet examples/mainwindows/menus/mainwindow.h 1 + + We must also implement a collection of private slots to respond to + the user activating any of our menu entries. Note that these + slots are left out of this documentation since they are trivial, + i.e., most of them are only displaying the action's path in the + main window's central widget. + + \snippet examples/mainwindows/menus/mainwindow.h 2 + + We have chosen to simplify the constructor by implementing two + private convenience functions to create the various actions, to + add them to menus and to insert the menus into our main window's + menu bar. + + \snippet examples/mainwindows/menus/mainwindow.h 3 + + Finally, we declare the various menus and actions as well as a + simple information label in the application wide scope. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus while the QAction class + provides an abstract user interface action that can be inserted + into widgets. + + In some situations it is useful to group actions together, e.g., + we have a \gui {Left Align} action, a \gui {Right Align} action, a + \gui {Justify} action, and a \gui {Center} action, and we want + only one of these actions to be active at any one time. One simple + way of achieving this is to group the actions together in an + action group using the QActionGroup class. + + \section1 MainWindow Class Implementation + + In the constructor, we start off by creating a regular QWidget and + make it our main window's central widget. Note that the main + window takes ownership of the widget pointer and deletes it at the + appropriate time. + + \snippet examples/mainwindows/menus/mainwindow.cpp 0 + \codeline + \snippet examples/mainwindows/menus/mainwindow.cpp 1 + + Then we create the information label as well as a top and bottom + filler that we add to a layout which we install on the central + widget. QMainWindow objects come with their own customized layout + and setting a layout on a the actual main window, or creating a + layout with a main window as a parent, is considered an error. You + should always set your own layout on the central widget instead. + + \snippet examples/mainwindows/menus/mainwindow.cpp 2 + + To create the actions and menus we call our two convenience + functions: \c createActions() and \c createMenus(). We will get + back to these shortly. + + QMainWindow's \l {QMainWindow::statusBar()}{statusBar()} function + returns the status bar for the main window (if the status bar does + not exist, this function will create and return an empty status + bar). We initialize the status bar and window title, resize the + window to an appropriate size as well as ensure that the main + window cannot be resized to a smaller size than the given + one. + + Now, let's take a closer look at the \c createActions() convenience + function that creates the various actions: + + \snippet examples/mainwindows/menus/mainwindow.cpp 4 + \dots + + A QAction object may contain an icon, a text, a shortcut, a status + tip, a "What's This?" text, and a tooltip. Most of these can be + set in the constructor, but they can also be set independently + using the provided convenience functions. + + In the \c createActions() function, we first create a \c newAct + action. We make \gui Ctrl+N its shortcut using the + QAction::setShortcut() function, and we set its status tip using the + QAction::setStatusTip() function (the status tip is displayed on all + status bars provided by the action's top-level parent widget). We + also connect its \l {QAction::}{triggered()} signal to the \c + newFile() slot. + + The rest of the actions are created in a similar manner. Please + see the source code for details. + + \snippet examples/mainwindows/menus/mainwindow.cpp 7 + + + Once we have created the \gui {Left Align}, \gui {Right Align}, + \gui {Justify}, and a \gui {Center} actions, we can also create + the previously mentioned action group. + + Each action is added to the group using QActionGroup's \l + {QActionGroup::}{addAction()} function. Note that an action also + can be added to a group by creating it with the group as its + parent. Since an action group is exclusive by default, only one of + the actions in the group is checked at any one time (this can be + altered using the QActionGroup::setExclusive() function). + + When all the actions are created, we use the \c createMenus() + function to add the actions to the menus and to insert the menus + into the menu bar: + + \snippet examples/mainwindows/menus/mainwindow.cpp 8 + + QMenuBar's \l {QMenuBar::addMenu()}{addMenu()} function appends a + new QMenu with the given title, to the menu bar (note that the + menu bar takes ownership of the menu). We use QWidget's \l + {QWidget::addAction()}{addAction()} function to add each action to + the corresponding menu. + + Alternatively, the QMenu class provides several \l + {QMenu::addAction()}{addAction()} convenience functions that create + and add new actions from given texts and/or icons. You can also + provide a member that will automatically connect to the new + action's \l {QAction::triggered()}{triggered()} signal, and a + shortcut represented by a QKeySequence instance. + + The QMenu::addSeparator() function creates and returns a new + separator action, i.e. an action for which QAction::isSeparator() + returns true, and adds the new action to the menu's list of + actions. + + \snippet examples/mainwindows/menus/mainwindow.cpp 12 + + Note the \gui Format menu. First of all, it is added as a submenu + to the \gui Edit Menu using QMenu's \l + {QMenu::addMenu()}{addMenu()} function. Secondly, take a look at the + alignment actions: In the \c createActions() function we added the + \c leftAlignAct, \c rightAlignAct, \c justifyAct and \c centerAct + actions to an action group. Nevertheless, we must add each action + to the menu separately while the action group does its magic + behind the scene. + + \snippet examples/mainwindows/menus/mainwindow.cpp 3 + + To provide a custom context menu, we must reimplement QWidget's \l + {QWidget::}{contextMenuEvent()} function to receive the widget's + context menu events (note that the default implementation simply + ignores these events). + + Whenever we receive such an event, we create a menu containing the + \gui Cut, \gui Copy and \gui Paste actions. Context menus can be + executed either asynchronously using the \l {QMenu::}{popup()} + function or synchronously using the \l {QMenu::}{exec()} + function. In this example, we have chosen to show the menu using + its \l {QMenu::}{exec()} function. By passing the event's position + as argument we ensure that the context menu appears at the + expected position. +*/ diff --git a/doc/src/examples/mousecalibration.qdoc b/doc/src/examples/mousecalibration.qdoc new file mode 100644 index 0000000..e271265 --- /dev/null +++ b/doc/src/examples/mousecalibration.qdoc @@ -0,0 +1,207 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example qws/mousecalibration + \title Mouse Calibration Example + + The Mouse Calibration example demonstrates how to write a simple + program using the mechanisms provided by the QWSMouseHandler class + to calibrate the mouse handler in \l{Qt for Embedded Linux}. + + Calibration is the process of mapping between physical + (i.e. device) coordinates and logical coordinates. + + The example consists of two classes in addition to the main program: + + \list + \o \c Calibration is a dialog widget that retrieves the device coordinates. + \o \c ScribbleWidget is a minimal drawing program used to let the user + test the new mouse settings. + \endlist + + First we will review the main program, then we will take a look at + the \c Calibration class. The \c ScribbleWidget class is only a + help tool in this context, and will not be covered here. + + \section1 The Main Program + + The program starts by presenting a message box informing the user + of what is going to happen: + + \snippet examples/qws/mousecalibration/main.cpp 0 + + The QMessageBox class provides a modal dialog with a range of + different messages, roughly arranged along two axes: severity and + complexity. The message box has a different icon for each of the + severity levels, but the icon must be specified explicitly. In our + case we use the default QMessageBox::NoIcon value. In addition we + use the default complexity, i.e. a message box showing the given + text and an \gui OK button. + + At this stage in the program, the mouse could be completely + uncalibrated, making the user unable to press the \gui OK button. For + that reason we use the static QTimer::singleShot() function to + make the message box disappear after 10 seconds. The QTimer class + provides repetitive and single-shot timers: The single shot + function calls the given slot after the specified interval. + + \snippet examples/qws/mousecalibration/main.cpp 1 + + Next, we create an instance of the \c Calibration class which is a + dialog widget retrieving the required sample coordinates: The + dialog sequentially presents five marks for the user to press, + storing the device coordinates for the mouse press events. + + \snippet examples/qws/mousecalibration/main.cpp 2 + + When the calibration dialog returns, we let the user test the new + mouse settings by drawing onto a \c ScribbleWidget object. Since + the mouse still can be uncalibrated, we continue to use the + QMessageBox and QTimer classes to inform the user about the + program's progress. + + An improved calibration tool would let the user choose between + accepting the new calibration, reverting to the old one, and + restarting the calibration. + + \section1 Calibration Class Definition + + The \c Calibration class inherits from QDialog and is responsible + for retrieving the device coordinates from the user. + + \snippet examples/qws/mousecalibration/calibration.h 0 + + We reimplement QDialog's \l {QDialog::exec()}{exec()} and \l + {QDialog::accept()}{accept()} slots, and QWidget's \l + {QWidget::paintEvent()}{paintEvent()} and \l + {QWidget::mouseReleaseEvent()}{mouseReleaseEvent()} functions. + + In addition, we declare a couple of private variables, \c data and + \c pressCount, holding the \c Calibration object's number of mouse + press events and current calibration data. The \c pressCount + variable is a convenience variable, while the \c data is a + QWSPointerCalibrationData object (storing the physical and logical + coordinates) that is passed to the mouse handler. The + QWSPointerCalibrationData class is simply a container for + calibration data. + + \section1 Calibration Class Implementation + + In the constructor we first ensure that the \c Calibration dialog + fills up the entire screen, has focus and will receive mouse + events (the latter by making the dialog modal): + + \snippet examples/qws/mousecalibration/calibration.cpp 0 + + Then we initialize the \l{QWSPointerCalibrationData::}{screenPoints} + array: + + \snippet examples/qws/mousecalibration/calibration.cpp 1 + + In order to specify the calibration, the + \l{QWSPointerCalibrationData::screenPoints}{screenPoints} array must + contain the screen coordinates for the logical positions + represented by the QWSPointerCalibrationData::Location enum + (e.g. QWSPointerCalibrationData::TopLeft). Since non-linearity is + expected to increase on the edge of the screen, all points are + kept 10 percent within the screen. The \c qt_screen pointer is a + reference to the screen device. There can only be one screen + device per application. + + \snippet examples/qws/mousecalibration/calibration.cpp 2 + + Finally, we initialize the variable which keeps track of the number of + mouse press events we have received. + + \snippet examples/qws/mousecalibration/calibration.cpp 3 + + The destructor is trivial. + + \snippet examples/qws/mousecalibration/calibration.cpp 4 + + The reimplementation of the QDialog::exec() slot is called from + the main program. + + First we clear the current calibration making the following mouse + event delivered in raw device coordinates. Then we call the + QWidget::grabMouse() function to make sure no mouse events are + lost, and the QWidget::activateWindow() function to make the + top-level widget containing this dialog, the active window. When + the call to the QDialog::exec() base function returns, we call + QWidget::releaseMouse() to release the mouse grab before the + function returns. + + \snippet examples/qws/mousecalibration/calibration.cpp 5 + + The QWidget::paintEvent() function is reimplemented to receive the + widget's paint events. A paint event is a request to repaint all + or parts of the widget. It can happen as a result of + QWidget::repaint() or QWidget::update(), or because the widget was + obscured and has now been uncovered, or for many other reasons. + In our reimplementation of the function we simply draw a cross at + the next point the user should press. + + \snippet examples/qws/mousecalibration/calibration.cpp 6 + + We then reimplement the QWidget::mouseReleaseEvent() function to + receive the widget's move events, using the QMouseEvent object + passed as parameter to find the coordinates the user pressed, and + update the QWSPointerCalibrationData::devPoints array. + + In order to complete the mapping between logical and physical + coordinates, the \l + {QWSPointerCalibrationData::devPoints}{devPoints} array must + contain the raw device coordinates for the logical positions + represented by the QWSPointerCalibrationData::Location enum + (e.g. QWSPointerCalibrationData::TopLeft) + + We continue by drawing the next cross, or close the dialog by + calling the QDialog::accept() slot if we have collected all the + required coordinate samples. + + \snippet examples/qws/mousecalibration/calibration.cpp 7 + + Our reimplementation of the QDialog::accept() slot simply activate + the new calibration data using the QWSMouseHandler::calibrate() + function. We also use the Q_ASSERT() macro to ensure that the number + of required samples are present. +*/ diff --git a/doc/src/examples/movie.qdoc b/doc/src/examples/movie.qdoc new file mode 100644 index 0000000..00e42c6 --- /dev/null +++ b/doc/src/examples/movie.qdoc @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/movie + \title Movie Example + + The Movie example demonstrates how to use QMovie and QLabel to + display animations. Now that Qt comes with \l{Phonon + Overview}{Phonon} (the 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/multipleinheritance.qdoc b/doc/src/examples/multipleinheritance.qdoc new file mode 100644 index 0000000..ff2f00f --- /dev/null +++ b/doc/src/examples/multipleinheritance.qdoc @@ -0,0 +1,108 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example uitools/multipleinheritance + \title Multiple Inheritance Example + + The Multiple Inheritance Example shows how to use a form created with \QD + in an application by subclassing both QWidget and the user interface + class, which is \c{Ui::CalculatorForm}. + + \image multipleinheritance-example.png + + To subclass the \c calculatorform.ui file and ensure that \c qmake + processes it with the \c uic, we have to include \c calculatorform.ui + in the \c .pro file, as shown below: + + \snippet examples/uitools/multipleinheritance/multipleinheritance.pro 0 + + When the project is compiled, the \c uic will generate a corresponding + \c ui_calculatorform.h. + + \section1 CalculatorForm Definition + + In the \c CalculatorForm definition, we include the \c ui_calculatorform.h + that was generated earlier. + + \snippet examples/uitools/multipleinheritance/calculatorform.h 0 + + As mentioned earlier, the class is a subclass of both QWidget and + \c{Ui::CalculatorForm}. + + \snippet examples/uitools/multipleinheritance/calculatorform.h 1 + + Two slots are defined according to the \l{Automatic Connections} + {automatic connection} naming convention required by \c uic. This is + to ensure that \l{QMetaObject}'s auto-connection facilities connect + all the signals and slots involved automatically. + + \section1 CalculatorForm Implementation + + In the constructor, we call \c setupUi() to load the user interface file. + Note that we do not need the \c{ui} prefix as \c CalculatorForm is a + subclass of the user interface class. + + \snippet examples/uitools/multipleinheritance/calculatorform.cpp 0 + + We include two slots, \c{on_inputSpinBox1_valueChanged()} and + \c{on_inputSpinBox2_valueChanged()}. These slots respond to the + \l{QSpinBox::valueChanged()}{valueChanged()} signal that both spin boxes + emit. Whenever there is a change in one spin box's value, we take that + value and add it to whatever value the other spin box has. + + \snippet examples/uitools/multipleinheritance/calculatorform.cpp 1 + \codeline + \snippet examples/uitools/multipleinheritance/calculatorform.cpp 2 + + \section1 \c main() Function + + The \c main() function instantiates QApplication and \c CalculatorForm. + The \c calculator object is displayed by invoking the \l{QWidget::show()} + {show()} function. + + \snippet examples/uitools/multipleinheritance/main.cpp 0 + + There are various approaches to include forms into applications. The + Multiple Inheritance approach is just one of them. See + \l{Using a Designer .ui File in Your Application} for more information on + the other approaches available. +*/ diff --git a/doc/src/examples/musicplayerexample.qdoc b/doc/src/examples/musicplayerexample.qdoc new file mode 100644 index 0000000..d23c1f1 --- /dev/null +++ b/doc/src/examples/musicplayerexample.qdoc @@ -0,0 +1,248 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example phonon/musicplayer + \title Music Player Example + + The Music Player Example shows how to use Phonon - the multimedia + framework that comes with Qt - to create a simple music player. + The player can play music files, and provides simple playback + control, such as pausing, stopping, and resuming the music. + + \image musicplayer.png + + The player has a button group with the play, pause, and stop + buttons familiar from most music players. The top-most slider + controls the position in the media stream, and the bottom slider + allows adjusting the sound volume. + + The user can use a file dialog to add music files to a table, + which displays meta information about the music - such as the + title, album, and artist. Each row contains information about a + single music file; to play it, the user selects that row and + presses the play button. Also, when a row is selected, the files + in the table are queued for playback. + + Phonon offers playback of sound using an available audio device, + e.g., a sound card or an USB headset. For the implementation, we + use two objects: a \l{Phonon::}{MediaObject}, which controls the + playback, and an \l{Phonon::}{AudioOutput}, which can output the + audio to a sound device. We will explain how they cooperate when + we encounter them in the code. For a high-level introduction to + Phonon, see its \l{Phonon Overview}{overview}. + + The API of Phonon is implemented through an intermediate + technology on each supported platform: DirectShow, QuickTime, and + GStreamer. The sound formats supported may therefore vary from + system to system. We do not in this example try to determine which + formats are supported, but let Phonon report an error if the user + tries to play an unsupported sound file. + + Our player consists of one class, \c MainWindow, which both + constructs the GUI and handles the playback. We will now go + through the parts of its definition and implementation that + concerns Phonon. + + \section1 MainWindow Class Definition + + Most of the API in \c MainWindow is private, as is often the case + for classes that represent self-contained windows. We list Phonon + objects and slots we connect to their signals; we take a closer + look at them when we walk through the \c MainWindow + implementation. + + \snippet examples/phonon/musicplayer/mainwindow.h 2 + + We use the \l{Phonon::}{SeekSlider} to move the current playback + position in the media stream, and the \l{Phonon::}{VolumeSlider} + controls the sound volume. Both of these widgets come ready made + with Phonon. We use another \l{Phonon::}{MediaObject}, + metaInformationProvider, to get the meta information from the + music files. More on this later. + + \snippet examples/phonon/musicplayer/mainwindow.h 1 + + The \l{Phonon::}{MediaObject} informs us of the state of the playback and + properties of the media it is playing back through a series of + signals. We connect the signals we need to slots in \c MainWindow. + The \c tableClicked() slot is connected to the table, so that we + know when the user requests playback of a new music file, by + clicking on the table. + + \section1 MainWindow Class Implementation + + The \c MainWindow class handles both the user interface and + Phonon. We will now take a look at the code relevant for Phonon. + The code required for setting up the GUI is explained elsewhere. + + We start with the constructor: + + \snippet examples/phonon/musicplayer/mainwindow.cpp 0 + + We start by instantiating our media and audio output objects. + As mentioned, the media object knows how to playback + multimedia (in our case sound files) while the audio output + can send it to a sound device. + + For the playback to work, the media and audio output objects need + to get in contact with each other, so that the media object can + send the sound to the audio output. Phonon is a graph based + framework, i.e., its objects are nodes that can be connected by + paths. Objects are connected using the \c createPath() function, + which is part of the Phonon namespace. + + \snippet examples/phonon/musicplayer/mainwindow.cpp 1 + + We also connect signals of the media object to slots in our \c + MainWindow. We will examine them shortly. + + \snippet examples/phonon/musicplayer/mainwindow.cpp 2 + + Finally, we call private helper functions to set up the GUI. + The \c setupUi() function contains code for setting up the seek + , and volume slider. We move on to \c setupUi(): + + \snippet examples/phonon/musicplayer/mainwindow.cpp 3 + \dots + \snippet examples/phonon/musicplayer/mainwindow.cpp 4 + + After creating the widgets, they must be supplied with the + \l{Phonon::}{MediaObject} and \l{Phonon::}{AudioOutput} objects + they should control. + + In the \c setupActions(), we connect the actions for the play, + pause, and stop tool buttons, to slots of the media object. + + \snippet examples/phonon/musicplayer/mainwindow.cpp 5 + + We move on to the the slots of \c MainWindow, starting with \c + addFiles(): + + \snippet examples/phonon/musicplayer/mainwindow.cpp 6 + + In the \c addFiles() slot, we add files selected by the user to + the \c sources list. We then set the first source selected on the + \c metaInformationProvider \l{Phonon::}{MediaObject}, which will + send a state changed signal when the meta information is resolved; + we have this signal connected to the \c metaStateChanged() slot. + + The media object informs us of state changes by sending the \c + stateChanged() signal. The \c stateChanged() slot is connected + to this signal. + + \snippet examples/phonon/musicplayer/mainwindow.cpp 9 + + The \l{Phonon::MediaObject::}{errorString()} function gives a + description of the error that is suitable for users of a Phonon + application. The two values of the \l{Phonon::}{ErrorState} enum + helps us determine whether it is possible to try to play the same + file again. + + \snippet examples/phonon/musicplayer/mainwindow.cpp 10 + + We update the GUI when the playback state changes, i.e., when it + starts, pauses, stops, or resumes. + + The media object will report other state changes, as defined by the + \l{Phonon::}{State} enum. + + The \c tick() slot is connected to a \l{Phonon::}{MediaObject} signal which is + emitted when the playback position changes: + + \snippet examples/phonon/musicplayer/mainwindow.cpp 11 + + The \c time is given in milliseconds. + + When the table is clicked on with the mouse, \c tableClick() + is invoked: + + \snippet examples/phonon/musicplayer/mainwindow.cpp 12 + + Since we stop the media object, we first check whether it is + currently playing. \c row contains the row in the table that was + clicked upon; the indices of \c sources follows the table, so we + can simply use \c row to find the new source. + + \snippet examples/phonon/musicplayer/mainwindow.cpp 13 + + When the media source changes, we simply need to select the + corresponding row in the table. + + \snippet examples/phonon/musicplayer/mainwindow.cpp 14 + + When \c metaStateChanged() is invoked, \c + metaInformationProvider has resolved the meta data for its current + source. A \l{Phonon::}{MediaObject} will do this before + entering \l{Phonon::}{StoppedState}. Note that we could also + have used the \l{Phonon::MediaObject::}{metaDataChanged()} signal for + this purpose. + + Some of the meta data is then chosen to be displayed in the + music table. A file might not contain the meta data requested, + in which case an empty string is returned. + + \snippet examples/phonon/musicplayer/mainwindow.cpp 15 + + If we have media sources in \c sources of which meta information + is not resolved, we set a new source on the \c + metaInformationProvider, which will invoke \c metaStateChanged() + again. + + We move on to the \c aboutToFinish() slot: + + \snippet examples/phonon/musicplayer/mainwindow.cpp 16 + + When a file is finished playing, the Music Player will move on and + play the next file in the table. This slot is connected to the + \l{Phonon::}{MediaObject}'s + \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is + guaranteed to be emitted while there is still time to enqueue + another file for playback. + + \section1 The main() function. + + Phonon requires that the application has a name; it is set with + \l{QCoreApplication::}{setApplicationName()}. This is because + D-Bus, which is used by Phonon on Linux systems, demands this. + + \snippet examples/phonon/musicplayer/main.cpp 1 +*/ diff --git a/doc/src/examples/network-chat.qdoc b/doc/src/examples/network-chat.qdoc new file mode 100644 index 0000000..3caeb9a --- /dev/null +++ b/doc/src/examples/network-chat.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/network-chat + \title Network Chat Example + + The Network Chat example demonstrates a stateful peer-to-peer Chat client + that uses broadcasting with QUdpSocket and QNetworkInterface to discover + its peers. + + \image network-chat-example.png +*/ diff --git a/doc/src/examples/orderform.qdoc b/doc/src/examples/orderform.qdoc new file mode 100644 index 0000000..f6f2607 --- /dev/null +++ b/doc/src/examples/orderform.qdoc @@ -0,0 +1,378 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example richtext/orderform + \title Order Form Example + + The Order Form example shows how to generate rich text documents by + combining a simple template with data input by the user in a dialog. Data + is extracted from a \c DetailsDialog object and displayed on a QTextEdit + with a QTextCursor, using various formats. Each form generated is added + to a QTabWidget for easy access. + + \image orderform-example.png + + \section1 DetailsDialog Definition + + The \c DetailsDialog class is a subclass of QDialog, implementing a slot + \c verify() to allow contents of the \c DetailsDialog to be verified later. + This is further explained in \c DetailsDialog Implementation. + + \snippet examples/richtext/orderform/detailsdialog.h 0 + + The constructor of \c DetailsDialog accepts parameters \a title and + \a parent. The class defines four \e{getter} functions: \c orderItems(), + \c senderName(), \c senderAddress(), and \c sendOffers() to allow data + to be accessed externally. + + The class definition includes input widgets for the required + fields, \c nameEdit and \c addressEdit. Also, a QCheckBox and a + QDialogButtonBox are defined; the former to provide the user with the + option to receive information on products and offers, and the latter + to ensure that buttons used are arranged according to the user's native + platform. In addition, a QTableWidget, \c itemsTable, is used to hold + order details. + + The screenshot below shows the \c DetailsDialog we intend to create. + + \image orderform-example-detailsdialog.png + + \section1 DetailsDialog Implementation + + The constructor of \c DetailsDialog instantiates the earlier defined fields + and their respective labels. The label for \c offersCheckBox is set and the + \c setupItemsTable() function is invoked to setup and populate + \c itemsTable. The QDialogButtonBox object, \c buttonBox, is instantiated + with \gui OK and \gui Cancel buttons. This \c buttonBox's \c accepted() and + \c rejected() signals are connected to the \c verify() and \c reject() + slots in \c DetailsDialog. + + \snippet examples/richtext/orderform/detailsdialog.cpp 0 + + A QGridLayout is used to place all the objects on the \c DetailsDialog. + + \snippet examples/richtext/orderform/detailsdialog.cpp 1 + + The \c setupItemsTable() function instantiates the QTableWidget object, + \c itemsTable, and sets the number of rows based on the QStringList + object, \c items, which holds the type of items ordered. The number of + columns is set to 2, providing a "name" and "quantity" layout. A \c for + loop is used to populate the \c itemsTable and the \c name item's flag + is set to Qt::ItemIsEnabled or Qt::ItemIsSelectable. For demonstration + purposes, the \c quantity item is set to a 1 and all items in the + \c itemsTable have this value for quantity; but this can be modified by + editing the contents of the cells at run time. + + \snippet examples/richtext/orderform/detailsdialog.cpp 2 + + The \c orderItems() function extracts data from the \c itemsTable and + returns it in the form of a QList> where each QPair + corresponds to an item and the quantity ordered. + + \snippet examples/richtext/orderform/detailsdialog.cpp 3 + + The \c senderName() function is used to return the value of the QLineEdit + used to store the name field for the order form. + + \snippet examples/richtext/orderform/detailsdialog.cpp 4 + + The \c senderAddress() function is used to return the value of the + QTextEdit containing the address for the order form. + + \snippet examples/richtext/orderform/detailsdialog.cpp 5 + + The \c sendOffers() function is used to return a \c true or \c false + value that is used to determine if the customer in the order form + wishes to receive more information on the company's offers and promotions. + + \snippet examples/richtext/orderform/detailsdialog.cpp 6 + + The \c verify() function is an additionally implemented slot used to + verify the details entered by the user into the \c DetailsDialog. If + the details entered are incomplete, a QMessageBox is displayed + providing the user the option to discard the \c DetailsDialog. Otherwise, + the details are accepted and the \c accept() function is invoked. + + \snippet examples/richtext/orderform/detailsdialog.cpp 7 + + \section1 MainWindow Definition + + The \c MainWindow class is a subclass of QMainWindow, implementing two + slots - \c openDialog() and \c printFile(). It also contains a private + instance of QTabWidget, \c letters. + + \snippet examples/richtext/orderform/mainwindow.h 0 + + \section1 MainWindow Implementation + + The \c MainWindow constructor sets up the \c fileMenu and the required + actions, \c newAction and \c printAction. These actions' \c triggered() + signals are connected to the additionally implemented openDialog() slot + and the default close() slot. The QTabWidget, \c letters, is + instantiated and set as the window's central widget. + + \snippet examples/richtext/orderform/mainwindow.cpp 0 + + The \c createLetter() function creates a new QTabWidget with a QTextEdit, + \c editor, as the parent. This function accepts four parameters that + correspond to we obtained through \c DetailsDialog, in order to "fill" + the \c editor. + + \snippet examples/richtext/orderform/mainwindow.cpp 1 + + We then obtain the cursor for the \c editor using QTextEdit::textCursor(). + The \c cursor is then moved to the start of the document using + QTextCursor::Start. + + \snippet examples/richtext/orderform/mainwindow.cpp 2 + + Recall the structure of a \l{Rich Text Document Structure} + {Rich Text Document}, where sequences of frames and + tables are always separated by text blocks, some of which may contain no + information. + + In the case of the Order Form Example, the document structure for this portion + is described by the table below: + + \table + \row + \o {1, 8} frame with \e{referenceFrameFormat} + \row + \o block \o \c{A company} + \row + \o block + \row + \o block \o \c{321 City Street} + \row + \o block + \row + \o block \o \c{Industry Park} + \row + \o block + \row + \o block \o \c{Another country} + \endtable + + This is accomplished with the following code: + + \snippet examples/richtext/orderform/mainwindow.cpp 3 + + Note that \c topFrame is the \c {editor}'s top-level frame and is not shown + in the document structure. + + We then set the \c{cursor}'s position back to its last position in + \c topFrame and fill in the customer's name (provided by the constructor) + and address - using a \c foreach loop to traverse the QString, \c address. + + \snippet examples/richtext/orderform/mainwindow.cpp 4 + + The \c cursor is now back in \c topFrame and the document structure for + the above portion of code is: + + \table + \row + \o block \o \c{Donald} + \row + \o block \o \c{47338 Park Avenue} + \row + \o block \o \c{Big City} + \endtable + + For spacing purposes, we invoke \l{QTextCursor::insertBlock()} + {insertBlock()} twice. The \l{QDate::currentDate()}{currentDate()} is + obtained and displayed. We use \l{QTextFrameFormat::setWidth()} + {setWidth()} to increase the width of \c bodyFrameFormat and we insert + a new frame with that width. + + \snippet examples/richtext/orderform/mainwindow.cpp 5 + + The following code inserts standard text into the order form. + + \snippet examples/richtext/orderform/mainwindow.cpp 6 + \snippet examples/richtext/orderform/mainwindow.cpp 7 + + This part of the document structure now contains the date, a frame with + \c bodyFrameFormat, as well as the standard text. + + \table + \row + \o block + \row + \o block + \row + \o block \o \c{Date: 25 May 2007} + \row + \o block + \row + \o {1, 4} frame with \e{bodyFrameFormat} + \row + \o block \o \c{I would like to place an order for the following items:} + \row + \o block + \row + \o block + \endtable + + A QTextTableFormat object, \c orderTableFormat, is used to hold the type + of item and the quantity ordered. + + \snippet examples/richtext/orderform/mainwindow.cpp 8 + + We use \l{QTextTable::cellAt()}{cellAt()} to set the headers for the + \c orderTable. + + \snippet examples/richtext/orderform/mainwindow.cpp 9 + + Then, we iterate through the QList of QPair objects to populate + \c orderTable. + + \snippet examples/richtext/orderform/mainwindow.cpp 10 + + The resulting document structure for this section is: + + \table + \row + \o {1, 11} \c{orderTable} with \e{orderTableFormat} + \row + \o block \o \c{Product} + \row + \o block \o \c{Quantity} + \row + \o block \o \c{T-shirt} + \row + \o block \o \c{4} + \row + \o block \o \c{Badge} + \row + \o block \o \c{3} + \row + \o block \o \c{Reference book} + \row + \o block \o \c{2} + \row + \o block \o \c{Coffee cup} + \row + \o block \o \c{5} + \endtable + + The \c cursor is then moved back to \c{topFrame}'s + \l{QTextFrame::lastPosition()}{lastPosition()} and more standard text + is inserted. + + \snippet examples/richtext/orderform/mainwindow.cpp 11 + \snippet examples/richtext/orderform/mainwindow.cpp 12 + + Another QTextTable is inserted, to display the customer's + preference regarding offers. + + \snippet examples/richtext/orderform/mainwindow.cpp 13 + + The document structure for this portion is: + + \table + \row + \o block + \row + \o block\o \c{Please update my...} + \row + \o {1, 5} block + \row + \o {1, 4} \c{offersTable} + \row + \o block \o \c{I want to receive...} + \row + \o block \o \c{I do not want to recieve...} + \row + \o block \o \c{X} + \endtable + + The \c cursor is moved to insert "Sincerely" along with the customer's + name. More blocks are inserted for spacing purposes. The \c printAction + is enabled to indicate that an order form can now be printed. + + \snippet examples/richtext/orderform/mainwindow.cpp 14 + + The bottom portion of the document structure is: + + \table + \row + \o block + \row + \o {1, 5} block\o \c{Sincerely,} + \row + \o block + \row + \o block + \row + \o block + \row + \o block \o \c{Donald} + \endtable + + The \c createSample() function is used for illustration purposes, to create + a sample order form. + + \snippet examples/richtext/orderform/mainwindow.cpp 15 + + The \c openDialog() function opens a \c DetailsDialog object. If the + details in \c dialog are accepted, the \c createLetter() function is + invoked using the parameters extracted from \c dialog. + + \snippet examples/richtext/orderform/mainwindow.cpp 16 + + In order to print out the order form, a \c printFile() function is + included, as shown below: + + \snippet examples/richtext/orderform/mainwindow.cpp 17 + + This function also allows the user to print a selected area with + QTextCursor::hasSelection(), instead of printing the entire document. + + \section1 \c main() Function + + The \c main() function instantiates \c MainWindow and sets its size to + 640x480 pixels before invoking the \c show() function and + \c createSample() function. + + \snippet examples/richtext/orderform/main.cpp 0 + +*/ diff --git a/doc/src/examples/overpainting.qdoc b/doc/src/examples/overpainting.qdoc new file mode 100644 index 0000000..e19f54b --- /dev/null +++ b/doc/src/examples/overpainting.qdoc @@ -0,0 +1,249 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/overpainting + \title Overpainting Example + + The Overpainting example shows how QPainter can be used + to overpaint a scene rendered using OpenGL in a QGLWidget. + + \image overpainting-example.png + + QGLWidget provides a widget with integrated OpenGL graphics support + that enables 3D graphics to be displayed using normal OpenGL calls, + yet also behaves like any other standard Qt widget with support for + signals and slots, properties, and Qt's action system. + + Usually, QGLWidget is subclassed to display a pure 3D scene; the + developer reimplements \l{QGLWidget::initializeGL()}{initializeGL()} + to initialize any required resources, \l{QGLWidget::resizeGL()}{resizeGL()} + to set up the projection and viewport, and + \l{QGLWidget::paintGL()}{paintGL()} to perform the OpenGL calls needed + to render the scene. However, it is possible to subclass QGLWidget + differently to allow 2D graphics, drawn using QPainter, to be + painted over a scene rendered using OpenGL. + + In this example, we demonstrate how this is done by reusing the code + from the \l{Hello GL Example}{Hello GL} example to provide a 3D scene, + and painting over it with some translucent 2D graphics. Instead of + examining each class in detail, we only cover the parts of the + \c GLWidget class that enable overpainting, and provide more detailed + discussion in the final section of this document. + + \section1 GLWidget Class Definition + + The \c GLWidget class is a subclass of QGLWidget, based on the one used + in the \l{Hello GL Example}{Hello GL} example. Rather than describe the + class as a whole, we show the first few lines of the class and only + discuss the changes we have made to the rest of it: + + \snippet examples/opengl/overpainting/glwidget.h 0 + \dots + \snippet examples/opengl/overpainting/glwidget.h 1 + \dots + \snippet examples/opengl/overpainting/glwidget.h 4 + + As usual, the widget uses \l{QGLWidget::initializeGL()}{initializeGL()} + to set up objects for our scene and perform other OpenGL initialization tasks. + The \l{QGLWidget::resizeGL()}{resizeGL()} function is used to ensure that + the 3D graphics in the scene are transformed correctly to the 2D viewport + displayed in the widget. + + Instead of implementing \l{QGLWidget::paintGL()}{paintGL()} to handle updates + to the widget, we implement a normal QWidget::paintEvent(). This + allows us to mix OpenGL calls and QPainter operations in a controlled way. + + In this example, we also implement QWidget::showEvent() to help with the + initialization of the 2D graphics used. + + The new private member functions and variables relate exclusively to the + 2D graphics and animation. The \c animate() slot is called periodically by the + \c animationTimer to update the widget; the \c createBubbles() function + initializes the \c bubbles list with instances of a helper class used to + draw the animation; the \c drawInstructions() function is responsible for + a semi-transparent messages that is also overpainted onto the OpenGL scene. + + \section1 GLWidget Class Implementation + + Again, we only show the parts of the \c GLWidget implementation that are + relevant to this example. In the constructor, we initialize a QTimer to + control the animation: + + \snippet examples/opengl/overpainting/glwidget.cpp 0 + + We turn off the widget's \l{QWidget::autoFillBackground}{autoFillBackground} property to + instruct OpenGL not to paint a background for the widget when + \l{QPainter::begin()}{QPainter::begin()} is called. + + As in the \l{Hello GL Example}{Hello GL} example, the destructor is responsible + for freeing any OpenGL-related resources: + + \snippet examples/opengl/overpainting/glwidget.cpp 1 + + The \c initializeGL() function is fairly minimal, only setting up the display + list used in the scene. + + \snippet examples/opengl/overpainting/glwidget.cpp 2 + + To cooperate fully with QPainter, we defer matrix stack operations and attribute + initialization until the widget needs to be updated. + + In this example, we implement \l{QWidget::paintEvent()}{paintEvent()} rather + than \l{QGLWidget::paintGL()}{paintGL()} to render + our scene. When drawing on a QGLWidget, the paint engine used by QPainter + performs certain operations that change the states of the OpenGL + implementation's matrix and property stacks. Therefore, it is necessary to + make all the OpenGL calls to display the 3D graphics before we construct + a QPainter to draw the 2D overlay. + + We render a 3D scene by setting up model and projection transformations + and other attributes. We use an OpenGL stack operation to preserve the + original matrix state, allowing us to recover it later: + + \snippet examples/opengl/overpainting/glwidget.cpp 4 + + We define a color to use for the widget's background, and set up various + attributes that define how the scene will be rendered. + + \snippet examples/opengl/overpainting/glwidget.cpp 6 + + We call the \c setupViewport() private function to set up the + projection used for the scene. This is unnecessary in OpenGL + examples that implement the \l{QGLWidget::paintGL()}{paintGL()} + function because the matrix stacks are usually unmodified between + calls to \l{QGLWidget::resizeGL()}{resizeGL()} and + \l{QGLWidget::paintGL()}{paintGL()}. + + Since the widget's background is not drawn by the system or by Qt, we use + an OpenGL call to paint it before positioning the object defined earlier + in the scene: + + \snippet examples/opengl/overpainting/glwidget.cpp 7 + + Once the list containing the object has been executed, the matrix stack + needs to be restored to its original state at the start of this function + before we can begin overpainting: + + \snippet examples/opengl/overpainting/glwidget.cpp 8 + + With the 3D graphics done, we construct a QPainter for use on the widget + and simply overpaint the widget with 2D graphics; in this case, using a + helper class to draw a number of translucent bubbles onto the widget, + and calling \c drawInstructions() to overlay some instructions: + + \snippet examples/opengl/overpainting/glwidget.cpp 10 + + When QPainter::end() is called, suitable OpenGL-specific calls are made to + write the scene, and its additional contents, onto the widget. + + The implementation of the \l{QGLWidget::resizeGL()}{resizeGL()} function + sets up the dimensions of the viewport and defines a projection + transformation: + + \snippet examples/opengl/overpainting/glwidget.cpp 11 + + Ideally, we want to arrange the 2D graphics to suit the widget's dimensions. + To achieve this, we implement the \l{QWidget::showEvent()}{showEvent()} handler, + creating new graphic elements (bubbles) if necessary at appropriate positions + in the widget. + + \snippet examples/opengl/overpainting/glwidget.cpp 12 + + This function only has an effect if less than 20 bubbles have already been + created. + + The \c animate() slot is called every time the widget's \c animationTimer emits + the \l{QTimer::timeout()}{timeout()} signal. This keeps the bubbles moving + around. + + \snippet examples/opengl/overpainting/glwidget.cpp 13 + + We simply iterate over the bubbles in the \c bubbles list, updating the + widget before and after each of them is moved. + + The \c setupViewport() function is called from \c paintEvent() + and \c resizeGL(). + + \snippet examples/opengl/overpainting/glwidget.cpp 14 + + The \c drawInstructions() function is used to prepare some basic + instructions that will be painted with the other 2D graphics over + the 3D scene. + + \snippet examples/opengl/overpainting/glwidget.cpp 15 + + \section1 Summary + + When overpainting 2D content onto 3D content, we need to use a QPainter + \e and make OpenGL calls to achieve the desired effect. Since QPainter + itself uses OpenGL calls when used on a QGLWidget subclass, we need to + preserve the state of various OpenGL stacks when we perform our own + calls, using the following approach: + + \list + \o Reimplement QGLWidget::initializeGL(), but only perform minimal + initialization. QPainter will perform its own initialization + routines, modifying the matrix and property stacks, so it is better + to defer certain initialization tasks until just before you render + the 3D scene. + \o Reimplement QGLWidget::resizeGL() as in the pure 3D case. + \o Reimplement QWidget::paintEvent() to draw both 2D and 3D graphics. + \endlist + + The \l{QWidget::paintEvent()}{paintEvent()} implementation performs the + following tasks: + + \list + \o Push the current OpenGL modelview matrix onto a stack. + \o Perform initialization tasks usually done in the + \l{QGLWidget::initializeGL()}{initializeGL()} function. + \o Perform code that would normally be located in the widget's + \l{QGLWidget::resizeGL()}{resizeGL()} function to set the correct + perspective transformation and set up the viewport. + \o Render the scene using OpenGL calls. + \o Pop the OpenGL modelview matrix off the stack. + \o Construct a QPainter object. + \o Initialize it for use on the widget with the QPainter::begin() function. + \o Draw primitives using QPainter's member functions. + \o Call QPainter::end() to finish painting. + \endlist +*/ diff --git a/doc/src/examples/padnavigator.qdoc b/doc/src/examples/padnavigator.qdoc new file mode 100644 index 0000000..f43725b --- /dev/null +++ b/doc/src/examples/padnavigator.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example graphicsview/padnavigator + \title Pad Navigator Example + + The Pad Navigator Example shows how you can use Graphics View + together with embedded widgets to create a simple but useful + dynamic user interface for embedded devices. + + \image padnavigator-example.png +*/ diff --git a/doc/src/examples/painterpaths.qdoc b/doc/src/examples/painterpaths.qdoc new file mode 100644 index 0000000..fd27566 --- /dev/null +++ b/doc/src/examples/painterpaths.qdoc @@ -0,0 +1,432 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/painterpaths + \title Painter Paths Example + + The Painter Paths example shows how painter paths can be used to + build complex shapes for rendering. + + \image painterpaths-example.png + + The QPainterPath class provides a container for painting + operations, enabling graphical shapes to be constructed and + reused. + + A painter path is an object composed of a number of graphical + building blocks (such as rectangles, ellipses, lines, and curves), + and can be used for filling, outlining, and clipping. The main + advantage of painter paths over normal drawing operations is that + complex shapes only need to be created once, but they can be drawn + many times using only calls to QPainter::drawPath(). + + The example consists of two classes: + + \list + \o The \c RenderArea class which is a custom widget displaying + a single painter path. + \o The \c Window class which is the applications main window + displaying several \c RenderArea widgets, and allowing the user + to manipulate the painter paths' filling, pen, color + and rotation angle. + \endlist + + First we will review the \c Window class, then we will take a look + at the \c RenderArea class. + + \section1 Window Class Definition + + The \c Window class inherits QWidget, and is the applications main + window displaying several \c RenderArea widgets, and allowing the + user to manipulate the painter paths' filling, pen, color and + rotation angle. + + \snippet examples/painting/painterpaths/window.h 0 + + We declare three private slots to respond to user input regarding + filling and color: \c fillRuleChanged(), \c fillGradientChanged() + and \c penColorChanged(). + + When the user changes the pen width and the rotation angle, the + new value is passed directly on to the \c RenderArea widgets using + the QSpinBox::valueChanged() signal. The reason why we must + implement slots to update the filling and color, is that QComboBox + doesn't provide a similar signal passing the new value as + argument; so we need to retrieve the new value, or values, before + we can update the \c RenderArea widgets. + + \snippet examples/painting/painterpaths/window.h 1 + + We also declare a couple of private convenience functions: \c + populateWithColors() populates a given QComboBox with items + corresponding to the color names Qt knows about, and \c + currentItemData() returns the current item for a given QComboBox. + + \snippet examples/painting/painterpaths/window.h 2 + + Then we declare the various components of the main window + widget. We also declare a convenience constant specifying the + number of \c RenderArea widgets. + + \section1 Window Class Implementation + + In the implementation of the \c Window class we first declare the + constant \c Pi with six significant figures: + + \snippet examples/painting/painterpaths/window.cpp 0 + + In the constructor, we then define the various painter paths and + create corresponding \c RenderArea widgets which will render the + graphical shapes: + + \snippet examples/painting/painterpaths/window.cpp 1 + + We construct a rectangle with sharp corners using the + QPainterPath::moveTo() and QPainterPath::lineTo() + functions. + + QPainterPath::moveTo() moves the current point to the point passed + as argument. A painter path is an object composed of a number of + graphical building blocks, i.e. subpaths. Moving the current point + will also start a new subpath (implicitly closing the previously + current path when the new one is started). The + QPainterPath::lineTo() function adds a straight line from the + current point to the given end point. After the line is drawn, the + current point is updated to be at the end point of the line. + + We first move the current point starting a new subpath, and we + draw three of the rectangle's sides. Then we call the + QPainterPath::closeSubpath() function which draws a line to the + beginning of the current subpath. A new subpath is automatically + begun when the current subpath is closed. The current point of the + new path is (0, 0). We could also have called + QPainterPath::lineTo() to draw the last line as well, and then + explicitly start a new subpath using the QPainterPath::moveTo() + function. + + QPainterPath also provide the QPainterPath::addRect() convenience + function, which adds a given rectangle to the path as a closed + subpath. The rectangle is added as a clockwise set of lines. The + painter path's current position after the rect has been added is + at the top-left corner of the rectangle. + + \snippet examples/painting/painterpaths/window.cpp 2 + + Then we construct a rectangle with rounded corners. As before, we + use the QPainterPath::moveTo() and QPainterPath::lineTo() + functions to draw the rectangle's sides. To create the rounded + corners we use the QPainterPath::arcTo() function. + + QPainterPath::arcTo() creates an arc that occupies the given + rectangle (specified by a QRect or the rectangle's coordinates), + beginning at the given start angle and extending the given degrees + counter-clockwise. Angles are specified in degrees. Clockwise arcs + can be specified using negative angles. The function connects the + current point to the starting point of the arc if they are not + already connected. + + \snippet examples/painting/painterpaths/window.cpp 3 + + We also use the QPainterPath::arcTo() function to construct the + ellipse path. First we move the current point starting a new + path. Then we call QPainterPath::arcTo() with starting angle 0.0 + and 360.0 degrees as the last argument, creating an ellipse. + + Again, QPainterPath provides a convenience function ( + QPainterPath::addEllipse()) which creates an ellipse within a + given bounding rectangle and adds it to the painter path. If the + current subpath is closed, a new subpath is started. The ellipse + is composed of a clockwise curve, starting and finishing at zero + degrees (the 3 o'clock position). + + \snippet examples/painting/painterpaths/window.cpp 4 + + When constructing the pie chart path we continue to use a + combination of the mentioned functions: First we move the current + point, starting a new subpath. Then we create a line from the + center of the chart to the arc, and the arc itself. When we close + the subpath, we implicitly construct the last line back to the + center of the chart. + + \snippet examples/painting/painterpaths/window.cpp 5 + + Constructing a polygon is equivalent to constructing a rectangle. + + QPainterPath also provide the QPainterPath::addPolygon() + convenience function which adds the given polygon to the path as a + new subpath. Current position after the polygon has been added is + the last point in polygon. + + \snippet examples/painting/painterpaths/window.cpp 6 + + Then we create a path consisting of a group of subpaths: First we + move the current point, and create a circle using the + QPainterPath::arcTo() function with starting angle 0.0, and 360 + degrees as the last argument, as we did when we created the + ellipse path. Then we move the current point again, starting a + new subpath, and construct three sides of a square using the + QPainterPath::lineTo() function. + + Now, when we call the QPainterPath::closeSubpath() fucntion the + last side is created. Remember that the + QPainterPath::closeSubpath() function draws a line to the + beginning of the \e current subpath, i.e the square. + + QPainterPath provide a convenience function, + QPainterPath::addPath() which adds a given path to the path that + calls the function. + + \snippet examples/painting/painterpaths/window.cpp 7 + + When creating the text path, we first create the font. Then we set + the font's style strategy which tells the font matching algorithm + what type of fonts should be used to find an appropriate default + family. QFont::ForceOutline forces the use of outline fonts. + + To construct the text, we use the QPainterPath::addText() function + which adds the given text to the path as a set of closed subpaths + created from the supplied font. The subpaths are positioned so + that the left end of the text's baseline lies at the specified + point. + + \snippet examples/painting/painterpaths/window.cpp 8 + + To create the Bezier path, we use the QPainterPath::cubicTo() + function which adds a Bezier curve between the current point and + the given end point with the given control point. After the curve + is added, the current point is updated to be at the end point of + the curve. + + In this case we omit to close the subpath so that we only have a + simple curve. But there is still a logical line from the curve's + endpoint back to the beginning of the subpath; it becomes visible + when filling the path as can be seen in the applications main + window. + + \snippet examples/painting/painterpaths/window.cpp 9 + + The final path that we construct shows that you can use + QPainterPath to construct rather complex shapes using only the + previous mentioned QPainterPath::moveTo(), QPainterPath::lineTo() + and QPainterPath::closeSubpath() functions. + + \snippet examples/painting/painterpaths/window.cpp 10 + + Now that we have created all the painter paths that we need, we + create a corresponding \c RenderArea widget for each. In the end, + we make sure that the number of render areas is correct using the + Q_ASSERT() macro. + + \snippet examples/painting/painterpaths/window.cpp 11 + + Then we create the widgets associated with the painter paths' fill + rule. + + There are two available fill rules in Qt: The Qt::OddEvenFill rule + determine whether a point is inside the shape by drawing a + horizontal line from the point to a location outside the shape, + and count the number of intersections. If the number of + intersections is an odd number, the point is inside the + shape. This rule is the default. + + The Qt::WindingFill rule determine whether a point is inside the + shape by drawing a horizontal line from the point to a location + outside the shape. Then it determines whether the direction of the + line at each intersection point is up or down. The winding number + is determined by summing the direction of each intersection. If + the number is non zero, the point is inside the shape. + + The Qt::WindingFill rule can in most cases be considered as the + intersection of closed shapes. + + \snippet examples/painting/painterpaths/window.cpp 12 + + We also create the other widgets associated with the filling, the + pen and the rotation angle. + + \snippet examples/painting/painterpaths/window.cpp 16 + + We connect the comboboxes \l {QComboBox::activated()}{activated()} + signals to the associated slots in the \c Window class, while we + connect the spin boxes \l + {QSpinBox::valueChanged()}{valueChanged()} signal directly to the + \c RenderArea widget's respective slots. + + \snippet examples/painting/painterpaths/window.cpp 17 + + We add the \c RenderArea widgets to a separate layout which we + then add to the main layout along with the rest of the widgets. + + \snippet examples/painting/painterpaths/window.cpp 18 + + Finally, we initialize the \c RenderArea widgets by calling the \c + fillRuleChanged(), \c fillGradientChanged() and \c + penColorChanged() slots, and we set the inital pen width and + window title. + + \snippet examples/painting/painterpaths/window.cpp 19 + \codeline + \snippet examples/painting/painterpaths/window.cpp 20 + \codeline + \snippet examples/painting/painterpaths/window.cpp 21 + + The private slots are implemented to retrieve the new value, or + values, from the associated comboboxes and update the RenderArea + widgets. + + First we determine the new value, or values, using the private \c + currentItemData() function and the qvariant_cast() template + function. Then we call the associated slot for each of the \c + RenderArea widgets to update the painter paths. + + \snippet examples/painting/painterpaths/window.cpp 22 + + The \c populateWithColors() function populates the given combobox + with items corresponding to the color names Qt knows about + provided by the static QColor::colorNames() function. + + \snippet examples/painting/painterpaths/window.cpp 23 + + The \c currentItemData() function simply return the current item + of the given combobox. + + \section1 RenderArea Class Definition + + The \c RenderArea class inherits QWidget, and is a custom widget + displaying a single painter path. + + \snippet examples/painting/painterpaths/renderarea.h 0 + + We declare several public slots updating the \c RenderArea + widget's associated painter path. In addition we reimplement the + QWidget::minimumSizeHint() and QWidget::sizeHint() functions to + give the \c RenderArea widget a reasonable size within our + application, and we reimplement the QWidget::paintEvent() event + handler to draw its painter path. + + \snippet examples/painting/painterpaths/renderarea.h 1 + + Each instance of the \c RenderArea class has a QPainterPath, a + couple of fill colors, a pen width, a pen color and a rotation + angle. + + \section1 RenderArea Class Implementation + + The constructor takes a QPainterPath as argument (in addition to + the optional QWidget parent): + + \snippet examples/painting/painterpaths/renderarea.cpp 0 + + In the constructor we initialize the \c RenderArea widget with the + QPainterPath parameter as well as initializing the pen width and + rotation angle. We also set the widgets \l + {QWidget::backgroundRole()}{background role}; QPalette::Base is + typically white. + + \snippet examples/painting/painterpaths/renderarea.cpp 1 + \codeline + \snippet examples/painting/painterpaths/renderarea.cpp 2 + + Then we reimplement the QWidget::minimumSizeHint() and + QWidget::sizeHint() functions to give the \c RenderArea widget a + reasonable size within our application. + + \snippet examples/painting/painterpaths/renderarea.cpp 3 + \codeline + \snippet examples/painting/painterpaths/renderarea.cpp 4 + \codeline + \snippet examples/painting/painterpaths/renderarea.cpp 5 + \codeline + \snippet examples/painting/painterpaths/renderarea.cpp 6 + \codeline + \snippet examples/painting/painterpaths/renderarea.cpp 7 + + The various public slots updates the \c RenderArea widget's + painter path by setting the associated property and make a call to + the QWidget::update() function, forcing a repaint of the widget + with the new rendering preferences. + + The QWidget::update() slot does not cause an immediate repaint; + instead it schedules a paint event for processing when Qt returns + to the main event loop. + + \snippet examples/painting/painterpaths/renderarea.cpp 8 + + A paint event is a request to repaint all or parts of the + widget. The paintEvent() function is an event handler that can be + reimplemented to receive the widget's paint events. We reimplement + the event handler to render the \c RenderArea widget's painter + path. + + First, we create a QPainter for the \c RenderArea instance, and + set the painter's render hints. The QPainter::RenderHints are used + to specify flags to QPainter that may, or may not, be respected by + any given engine. QPainter::Antialiasing indicates that the engine + should anti-alias the edges of primitives if possible, i.e. put + additional pixels around the original ones to smooth the edges. + + \snippet examples/painting/painterpaths/renderarea.cpp 9 + + Then we scale the QPainter's coordinate system to ensure that the + painter path is rendered in the right size, i.e that it grows with + the \c RenderArea widget when the application is resized. When we + constructed the various painter paths, they were all rnedered + within a square with a 100 pixel width wich is equivalent to \c + RenderArea::sizeHint(). The QPainter::scale() function scales the + coordinate system by the \c RenderArea widget's \e current width + and height divided by 100. + + Now, when we are sure that the painter path has the right size, we + can translate the coordinate system to make the painter path + rotate around the \c RenderArea widget's center. After we have + performed the rotation, we must remember to translate the + coordinate system back again. + + \snippet examples/painting/painterpaths/renderarea.cpp 10 + + Then we set the QPainter's pen with the instance's rendering + preferences. We create a QLinearGradient and set its colors + corresponding to the \c RenderArea widget's fill colors. Finally, + we set the QPainter's brush (the gradient is automatically + converted into a QBrush), and draw the \c RenderArea widget's + painter path using the QPainter::drawPath() function. +*/ diff --git a/doc/src/examples/pbuffers.qdoc b/doc/src/examples/pbuffers.qdoc new file mode 100644 index 0000000..347cf3d --- /dev/null +++ b/doc/src/examples/pbuffers.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/pbuffers + \title Pixel Buffers Example + + The Pixel Buffers example demonstrates how to use the + QGLPixelBuffer class to render into an off-screen buffer and use + the contents as a dynamic texture in a QGLWidget. + + \image pbuffers-example.png +*/ diff --git a/doc/src/examples/pbuffers2.qdoc b/doc/src/examples/pbuffers2.qdoc new file mode 100644 index 0000000..5426852 --- /dev/null +++ b/doc/src/examples/pbuffers2.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/pbuffers2 + \title Pixel Buffers 2 Example + + The Pixel Buffers 2 example demonstrates how to use the + QGLPixelBuffer class to render into an off-screen buffer and use + the contents as a dynamic texture in a QGLWidget. + + \image pbuffers2-example.png +*/ diff --git a/doc/src/examples/pixelator.qdoc b/doc/src/examples/pixelator.qdoc new file mode 100644 index 0000000..2a8b43d --- /dev/null +++ b/doc/src/examples/pixelator.qdoc @@ -0,0 +1,271 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/pixelator + \title Pixelator Example + + The Pixelator example shows how delegates can be used to customize the way that + items are rendered in standard item views. + + \image pixelator-example.png + + By default, QTreeView, QTableView, and QListView use a standard item delegate + to display and edit a set of common data types that are sufficient for many + applications. However, an application may need to represent items of data in a + particular way, or provide support for rendering more specialized data types, + and this often requires the use of a custom delegate. + + In this example, we show how to use custom delegates to modify the appearance + of standard views. To do this, we implement the following components: + + \list + \i A model which represents each pixel in an image as an item of data, where each + item contains a value for the brightness of the corresponding pixel. + \i A custom delegate that uses the information supplied by the model to represent + each pixel as a black circle on a white background, where the radius of the + circle corresponds to the darkness of the pixel. + \endlist + + This example may be useful for developers who want to implement their own table + models or custom delegates. The process of creating custom delegates for editing + item data is covered in the \l{Spin Box Delegate Example}{Spin Box Delegate} + example. + + \section1 ImageModel Class Definition + + The \c ImageModel class is defined as follows: + + \snippet examples/itemviews/pixelator/imagemodel.h 0 + + Since we only require a simple, read-only table model, we only need to implement + functions to indicate the dimensions of the image and supply data to other + components. + + For convenience, the image to be used is passed in the constructor. + + \section1 ImageModel Class Implementation + + The constructor is trivial: + + \snippet examples/itemviews/pixelator/imagemodel.cpp 0 + + The \c setImage() function sets the image that will be used by the model: + + \snippet examples/itemviews/pixelator/imagemodel.cpp 1 + + The QAbstractItemModel::reset() call tells the view(s) that the model + has changed. + + The \c rowCount() and \c columnCount() functions return the height and width of + the image respectively: + + \snippet examples/itemviews/pixelator/imagemodel.cpp 2 + \snippet examples/itemviews/pixelator/imagemodel.cpp 3 + + Since the image is a simple two-dimensional structure, the \c parent arguments + to these functions are unused. They both simply return the relevant size from + the underlying image object. + + The \c data() function returns data for the item that corresponds to a given + model index in a format that is suitable for a particular role: + + \snippet examples/itemviews/pixelator/imagemodel.cpp 4 + + In this implementation, we only check that the model index is valid, and that + the role requested is the \l{Qt::ItemDataRole}{DisplayRole}. If so, the function + returns the grayscale value of the relevant pixel in the image; otherwise, a null + model index is returned. + + This model can be used with QTableView to display the integer brightness values + for the pixels in the image. However, we will implement a custom delegate to + display this information in a more artistic way. + + The \c headerData() function is also reimplemented: + + \snippet examples/itemviews/pixelator/imagemodel.cpp 5 + + We return (1, 1) as the size hint for a header item. If we + didn't, the headers would default to a larger size, preventing + us from displaying really small items (which can be specified + using the \gui{Pixel size} combobox). + + \section1 PixelDelegate Class Definition + + The \c PixelDelegate class is defined as follows: + + \snippet examples/itemviews/pixelator/pixeldelegate.h 0 + + This class provides only basic features for a delegate so, unlike the + \l{Spin Box Delegate Example}{Spin Box Delegate} example, we subclass + QAbstractItemDelegate instead of QItemDelegate. + + We only need to reimplement \l{QAbstractItemDelegate::paint()}{paint()} and + \l{QAbstractItemDelegate::sizeHint()}{sizeHint()} in this class. + However, we also provide a delegate-specific \c setPixelSize() function so + that we can change the delegate's behavior via the signals and slots mechanism. + + \section1 PixelDelegate Class Implementation + + The \c PixelDelegate constructor is used to set up a default value for + the size of each "pixel" that it renders. The base class constructor is + also called to ensure that the delegate is set up with a parent object, + if one is supplied: + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 0 + + Each item is rendered by the delegate's + \l{QAbstractItemDelegate::paint()}{paint()} function. The view calls this + function with a ready-to-use QPainter object, style information that the + delegate should use to correctly draw the item, and an index to the item in + the model: + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 1 + + The first task the delegate has to perform is to draw the item's background + correctly. Usually, selected items appear differently to non-selected items, + so we begin by testing the state passed in the style option and filling the + background if necessary. + + The radius of each circle is calculated in the following lines of code: + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 3 + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 4 + + First, the largest possible radius of the circle is determined by taking the + smallest dimension of the style option's \c rect attribute. + Using the model index supplied, we obtain a value for the brightness of the + relevant pixel in the image. The radius of the circle is calculated by + scaling the brightness to fit within the item and subtracting it from the + largest possible radius. + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 5 + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 6 + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 7 + + We save the painter's state, turn on antialiasing (to obtain smoother + curves), and turn off the pen. + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 8 + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 9 + + The foreground of the item (the circle representing a pixel) must be + rendered using an appropriate brush. For unselected items, we will use a + solid black brush; selected items are drawn using a predefined brush from + the style option's palette. + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 10 + + Finally, we paint the circle within the rectangle specified by the style + option and we call \l{QPainter::}{restore()} on the painter. + + The \c paint() function does not have to be particularly complicated; it is + only necessary to ensure that the state of the painter when the function + returns is the same as it was when it was called. This usually + means that any transformations applied to the painter must be preceded by + a call to QPainter::save() and followed by a call to QPainter::restore(). + + The delegate's \l{QAbstractItemDelegate::}{sizeHint()} function + returns a size for the item based on the predefined pixel size, initially set + up in the constructor: + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 11 + + The delegate's size is updated whenever the pixel size is changed. + We provide a custom slot to do this: + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 12 + + \section1 Using The Custom Delegate + + In this example, we use a main window to display a table of data, using the + custom delegate to render each cell in a particular way. Much of the + \c MainWindow class performs tasks that are not related to item views. Here, + we only quote the parts that are relevant. You can look at the rest of the + implementation by following the links to the code at the top of this + document. + + In the constructor, we set up a table view, turn off its grid, and hide its + headers: + + \snippet examples/itemviews/pixelator/mainwindow.cpp 0 + \dots + \snippet examples/itemviews/pixelator/mainwindow.cpp 1 + + This enables the items to be drawn without any gaps between them. Removing + the headers also prevents the user from adjusting the sizes of individual + rows and columns. + + We also set the minimum section size to 1 on the headers. If we + didn't, the headers would default to a larger size, preventing + us from displaying really small items (which can be specified + using the \gui{Pixel size} combobox). + + The custom delegate is constructed with the main window as its parent, so + that it will be deleted correctly later, and we set it on the table view. + + \snippet examples/itemviews/pixelator/mainwindow.cpp 2 + + Each item in the table view will be rendered by the \c PixelDelegate + instance. + + We construct a spin box to allow the user to change the size of each "pixel" + drawn by the delegate: + + \snippet examples/itemviews/pixelator/mainwindow.cpp 3 + + This spin box is connected to the custom slot we implemented in the + \c PixelDelegate class. This ensures that the delegate always draws each + pixel at the currently specified size: + + \snippet examples/itemviews/pixelator/mainwindow.cpp 4 + \dots + \snippet examples/itemviews/pixelator/mainwindow.cpp 5 + + We also connect the spin box to a slot in the \c MainWindow class. This + forces the view to take into account the new size hints for each item; + these are provided by the delegate in its \c sizeHint() function. + + \snippet examples/itemviews/pixelator/mainwindow.cpp 6 + + We explicitly resize the columns and rows to match the + \gui{Pixel size} combobox. +*/ diff --git a/doc/src/examples/plugandpaint.qdoc b/doc/src/examples/plugandpaint.qdoc new file mode 100644 index 0000000..3cdd8a4 --- /dev/null +++ b/doc/src/examples/plugandpaint.qdoc @@ -0,0 +1,554 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/plugandpaint + \title Plug & Paint Example + + The Plug & Paint example demonstrates how to write Qt + applications that can be extended through plugins. + + \image plugandpaint.png Screenshot of the Plug & Paint example + + A plugin is a dynamic library that can be loaded at run-time to + extend an application. Qt makes it possible to create custom + plugins and to load them using QPluginLoader. To ensure that + plugins don't get lost, it is also possible to link them + statically to the executable. The Plug & Paint example uses + plugins to support custom brushes, shapes, and image filters. A + single plugin can provide multiple brushes, shapes, and/or + filters. + + If you want to learn how to make your own application extensible + through plugins, we recommend that you start by reading this + overview, which explains how to make an application use plugins. + Afterward, you can read the + \l{tools/plugandpaintplugins/basictools}{Basic Tools} and + \l{tools/plugandpaintplugins/extrafilters}{Extra Filters} + overviews, which show how to implement static and dynamic + plugins, respectively. + + Plug & Paint consists of the following classes: + + \list + \o \c MainWindow is a QMainWindow subclass that provides the menu + system and that contains a \c PaintArea as the central widget. + \o \c PaintArea is a QWidget that allows the user to draw using a + brush and to insert shapes. + \o \c PluginDialog is a dialog that shows information about the + plugins detected by the application. + \o \c BrushInterface, \c ShapeInterface, and \c FilterInterface are + abstract base classes that can be implemented by plugins to + provide custom brushes, shapes, and image filters. + \endlist + + \section1 The Plugin Interfaces + + We will start by reviewing the interfaces defined in \c + interfaces.h. These interfaces are used by the Plug & Paint + application to access extra functionality. They are implemented + in the plugins. + + + \snippet examples/tools/plugandpaint/interfaces.h 0 + + The \c BrushInterface class declares four pure virtual functions. + The first pure virtual function, \c brushes(), returns a list of + strings that identify the brushes provided by the plugin. By + returning a QStringList instead of a QString, we make it possible + for a single plugin to provide multiple brushes. The other + functions have a \c brush parameter to identify which brush + (among those returned by \c brushes()) is used. + + \c mousePress(), \c mouseMove(), and \c mouseRelease() take a + QPainter and one or two \l{QPoint}s, and return a QRect + identifying which portion of the image was altered by the brush. + + The class also has a virtual destructor. Interface classes + usually don't need such a destructor (because it would make + little sense to \c delete the object that implements the + interface through a pointer to the interface), but some compilers + emit a warning for classes that declare virtual functions but no + virtual destructor. We provide the destructor to keep these + compilers happy. + + \snippet examples/tools/plugandpaint/interfaces.h 1 + + The \c ShapeInterface class declares a \c shapes() function that + works the same as \c{BrushInterface}'s \c brushes() function, and + a \c generateShape() function that has a \c shape parameter. + Shapes are represented by a QPainterPath, a data type that can + represent arbitrary 2D shapes or combinations of shapes. The \c + parent parameter can be used by the plugin to pop up a dialog + asking the user to specify more information. + + \snippet examples/tools/plugandpaint/interfaces.h 2 + + The \c FilterInterface class declares a \c filters() function + that returns a list of filter names, and a \c filterImage() + function that applies a filter to an image. + + \snippet examples/tools/plugandpaint/interfaces.h 4 + + To make it possible to query at run-time whether a plugin + implements a given interface, we must use the \c + Q_DECLARE_INTERFACE() macro. The first argument is the name of + the interface. The second argument is a string identifying the + interface in a unique way. By convention, we use a "Java package + name" syntax to identify interfaces. If we later change the + interfaces, we must use a different string to identify the new + interface; otherwise, the application might crash. It is therefore + a good idea to include a version number in the string, as we did + above. + + The \l{tools/plugandpaintplugins/basictools}{Basic Tools} plugin + and the \l{tools/plugandpaintplugins/extrafilters}{Extra Filters} + plugin shows how to derive from \c BrushInterface, \c + ShapeInterface, and \c FilterInterface. + + A note on naming: It might have been tempting to give the \c + brushes(), \c shapes(), and \c filters() functions a more generic + name, such as \c keys() or \c features(). However, that would + have made multiple inheritance impractical. When creating + interfaces, we should always try to give unique names to the pure + virtual functions. + + \section1 The MainWindow Class + + The \c MainWindow class is a standard QMainWindow subclass, as + found in many of the other examples (e.g., + \l{mainwindows/application}{Application}). Here, we'll + concentrate on the parts of the code that are related to plugins. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 4 + + The \c loadPlugins() function is called from the \c MainWindow + constructor to detect plugins and update the \gui{Brush}, + \gui{Shapes}, and \gui{Filters} menus. We start by handling static + plugins (available through QPluginLoader::staticInstances()) + + To the application that uses the plugin, a Qt plugin is simply a + QObject. That QObject implements plugin interfaces using multiple + inheritance. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 5 + + The next step is to load dynamic plugins. We initialize the \c + pluginsDir member variable to refer to the \c plugins + subdirectory of the Plug & Paint example. On Unix, this is just a + matter of initializing the QDir variable with + QApplication::applicationDirPath(), the path of the executable + file, and to do a \l{QDir::cd()}{cd()}. On Windows and Mac OS X, + this file is usually located in a subdirectory, so we need to + take this into account. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 6 + \snippet examples/tools/plugandpaint/mainwindow.cpp 7 + \snippet examples/tools/plugandpaint/mainwindow.cpp 8 + + We use QDir::entryList() to get a list of all files in that + directory. Then we iterate over the result using \l foreach and + try to load the plugin using QPluginLoader. + + The QObject provided by the plugin is accessible through + QPluginLoader::instance(). If the dynamic library isn't a Qt + plugin, or if it was compiled against an incompatible version of + the Qt library, QPluginLoader::instance() returns a null pointer. + + If QPluginLoader::instance() is non-null, we add it to the menus. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 9 + + At the end, we enable or disable the \gui{Brush}, \gui{Shapes}, + and \gui{Filters} menus based on whether they contain any items. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 10 + + For each plugin (static or dynamic), we check which interfaces it + implements using \l qobject_cast(). First, we try to cast the + plugin instance to a \c BrushInterface; if it works, we call the + private function \c addToMenu() with the list of brushes returned + by \c brushes(). Then we do the same with the \c ShapeInterface + and the \c FilterInterface. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 3 + + The \c aboutPlugins() slot is called on startup and can be + invoked at any time through the \gui{About Plugins} action. It + pops up a \c PluginDialog, providing information about the loaded + plugins. + + \image plugandpaint-plugindialog.png Screenshot of the Plugin dialog + + + The \c addToMenu() function is called from \c loadPlugin() to + create \l{QAction}s for custom brushes, shapes, or filters and + add them to the relevant menu. The QAction is created with the + plugin from which it comes from as the parent; this makes it + convenient to get access to the plugin later. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 0 + + The \c changeBrush() slot is invoked when the user chooses one of + the brushes from the \gui{Brush} menu. We start by finding out + which action invoked the slot using QObject::sender(). Then we + get the \c BrushInterface out of the plugin (which we + conveniently passed as the QAction's parent) and we call \c + PaintArea::setBrush() with the \c BrushInterface and the string + identifying the brush. Next time the user draws on the paint + area, \c PaintArea will use this brush. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 1 + + The \c insertShape() is invoked when the use chooses one of the + shapes from the \gui{Shapes} menu. We retrieve the QAction that + invoked the slot, then the \c ShapeInterface associated with that + QAction, and finally we call \c ShapeInterface::generateShape() + to obtain a QPainterPath. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 2 + + The \c applyFilter() slot is similar: We retrieve the QAction + that invoked the slot, then the \c FilterInterface associated to + that QAction, and finally we call \c + FilterInterface::filterImage() to apply the filter onto the + current image. + + \section1 The PaintArea Class + + The \c PaintArea class contains some code that deals with \c + BrushInterface, so we'll review it briefly. + + \snippet examples/tools/plugandpaint/paintarea.cpp 0 + + In \c setBrush(), we simply store the \c BrushInterface and the + brush that are given to us by \c MainWindow. + + \snippet examples/tools/plugandpaint/paintarea.cpp 1 + + In the \l{QWidget::mouseMoveEvent()}{mouse move event handler}, + we call the \c BrushInterface::mouseMove() function on the + current \c BrushInterface, with the current brush. The mouse + press and mouse release handlers are very similar. + + \section1 The PluginDialog Class + + The \c PluginDialog class provides information about the loaded + plugins to the user. Its constructor takes a path to the plugins + and a list of plugin file names. It calls \c findPlugins() + to fill the QTreeWdiget with information about the plugins: + + \snippet examples/tools/plugandpaint/plugindialog.cpp 0 + + The \c findPlugins() is very similar to \c + MainWindow::loadPlugins(). It uses QPluginLoader to access the + static and dynamic plugins. Its helper function \c + populateTreeWidget() uses \l qobject_cast() to find out which + interfaces are implemented by the plugins: + + \snippet examples/tools/plugandpaint/plugindialog.cpp 1 + + \section1 Importing Static Plugins + + The \l{tools/plugandpaintplugins/basictools}{Basic Tools} plugin + is built as a static plugin, to ensure that it is always + available to the application. This requires using the + Q_IMPORT_PLUGIN() macro somewhere in the application (in a \c + .cpp file) and specifying the plugin in the \c .pro file. + + For Plug & Paint, we have chosen to put Q_IMPORT_PLUGIN() in \c + main.cpp: + + \snippet examples/tools/plugandpaint/main.cpp 0 + + The argument to Q_IMPORT_PLUGIN() is the plugin's name, as + specified with Q_EXPORT_PLUGIN2() in the \l{Exporting the + Plugin}{plugin}. + + In the \c .pro file, we need to specify the static library. + Here's the project file for building Plug & Paint: + + \snippet examples/tools/plugandpaint/plugandpaint.pro 0 + + The \c LIBS line variable specifies the library \c pnp_basictools + located in the \c ../plugandpaintplugins/basictools directory. + (Although the \c LIBS syntax has a distinct Unix flavor, \c qmake + supports it on all platforms.) + + The \c CONFIG() code at the end is necessary for this example + because the example is part of the Qt distribution and Qt can be + configured to be built simultaneously in debug and in release + modes. You don't need to for your own plugin applications. + + This completes our review of the Plug & Paint application. At + this point, you might want to take a look at the + \l{tools/plugandpaintplugins/basictools}{Basic Tools} example + plugin. +*/ + +/*! + \example tools/plugandpaintplugins/basictools + \title Plug & Paint Basic Tools Example + + The Basic Tools example is a static plugin for the + \l{tools/plugandpaint}{Plug & Paint} example. It provides a set + of basic brushes, shapes, and filters. Through the Basic Tools + example, we will review the four steps involved in writing a Qt + plugin: + + \list 1 + \o Declare a plugin class. + \o Implement the interfaces provided by the plugin. + \o Export the plugin using the Q_EXPORT_PLUGIN2() macro. + \o Build the plugin using an adequate \c .pro file. + \endlist + + \section1 Declaration of the Plugin Class + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.h 0 + + We start by including \c interfaces.h, which defines the plugin + interfaces for the \l{tools/plugandpaint}{Plug & Paint} + application. For the \c #include to work, we need to add an \c + INCLUDEPATH entry to the \c .pro file with the path to Qt's \c + examples/tools directory. + + The \c BasicToolsPlugin class is a QObject subclass that + implements the \c BrushInterface, the \c ShapeInterface, and the + \c FilterInterface. This is done through multiple inheritance. + The \c Q_INTERFACES() macro is necessary to tell \l{moc}, Qt's + meta-object compiler, that the base classes are plugin + interfaces. Without the \c Q_INTERFACES() macro, we couldn't use + \l qobject_cast() in the \l{tools/plugandpaint}{Plug & Paint} + application to detect interfaces. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.h 2 + + In the \c public section of the class, we declare all the + functions from the three interfaces. + + \section1 Implementation of the Brush Interface + + Let's now review the implementation of the \c BasicToolsPlugin + member functions inherited from \c BrushInterface. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 0 + + The \c brushes() function returns a list of brushes provided by + this plugin. We provide three brushes: \gui{Pencil}, \gui{Air + Brush}, and \gui{Random Letters}. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 1 + + On a mouse press event, we just call \c mouseMove() to draw the + spot where the event occurred. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 2 + + In \c mouseMove(), we start by saving the state of the QPainter + and we compute a few variables that we'll need later. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 3 + + Then comes the brush-dependent part of the code: + + \list + \o If the brush is \gui{Pencil}, we just call + QPainter::drawLine() with the current QPen. + + \o If the brush is \gui{Air Brush}, we start by setting the + painter's QBrush to Qt::Dense6Pattern to obtain a dotted + pattern. Then we draw a circle filled with that QBrush several + times, resulting in a thick line. + + \o If the brush is \gui{Random Letters}, we draw a random letter + at the new cursor position. Most of the code is for setting + the font to be bold and larger than the default font and for + computing an appropriate bounding rect. + \endlist + + At the end, we restore the painter state to what it was upon + entering the function and we return the bounding rectangle. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 4 + + When the user releases the mouse, we do nothing and return an + empty QRect. + + \section1 Implementation of the Shape Interface + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 5 + + The plugin provides three shapes: \gui{Circle}, \gui{Star}, and + \gui{Text...}. The three dots after \gui{Text} are there because + the shape pops up a dialog asking for more information. We know + that the shape names will end up in a menu, so we include the + three dots in the shape name. + + A cleaner but more complicated design would have been to + distinguish between the internal shape name and the name used in + the user interface. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 6 + + The \c generateShape() creates a QPainterPath for the specified + shape. If the shape is \gui{Text}, we pop up a QInputDialog to + let the user enter some text. + + \section1 Implementation of the Filter Interface + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 7 + + The plugin provides three filters: \gui{Invert Pixels}, \gui{Swap + RGB}, and \gui{Grayscale}. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 8 + + The \c filterImage() function takes a filter name and a QImage as + parameters and returns an altered QImage. The first thing we do + is to convert the image to a 32-bit RGB format, to ensure that + the algorithms will work as expected. For example, + QImage::invertPixels(), which is used to implement the + \gui{Invert Pixels} filter, gives counterintuitive results for + 8-bit images, because they invert the indices into the color + table instead of inverting the color table's entries. + + \section1 Exporting the Plugin + + Whereas applications have a \c main() function as their entry + point, plugins need to contain exactly one occurrence of the + Q_EXPORT_PLUGIN2() macro to specify which class provides the + plugin: + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 9 + + This line may appear in any \c .cpp file that is part of the + plugin's source code. + + \section1 The .pro File + + Here's the project file for building the Basic Tools plugin: + + \snippet examples/tools/plugandpaintplugins/basictools/basictools.pro 0 + + The \c .pro file differs from typical \c .pro files in many + respects. First, it starts with a \c TEMPLATE entry specifying \c + lib. (The default template is \c app.) It also adds \c plugin to + the \c CONFIG variable. This is necessary on some platforms to + avoid generating symbolic links with version numbers in the file + name, which is appropriate for most dynamic libraries but not for + plugins. + + To make the plugin a static plugin, all that is required is to + specify \c static in addition to \c plugin. The + \l{tools/plugandpaintplugins/extrafilters}{Extra Filters} plugin, + which is compiled as a dynamic plugin, doesn't specify \c static + in its \c .pro file. + + The \c INCLUDEPATH variable sets the search paths for global + headers (i.e., header files included using \c{#include <...>}). + We add Qt's \c examples/tools directory (strictly speaking, + \c{examples/tools/plugandpaintplugins/basictools/../..}) to the + list, so that we can include \c . + + The \c TARGET variable specifies which name we want to give the + target library. We use \c pnp_ as the prefix to show that the + plugin is designed to work with Plug & Paint. On Unix, \c lib is + also prepended to that name. On all platforms, a + platform-specific suffix is appended (e.g., \c .dll on Windows, + \c .a on Linux). + + The \c CONFIG() code at the end is necessary for this example + because the example is part of the Qt distribution and Qt can be + configured to be built simultaneously in debug and in release + modes. You don't need to for your own plugins. +*/ + +/*! + \example tools/plugandpaintplugins/extrafilters + \title Plug & Paint Extra Filters Example + + The Extra Filters example is a plugin for the + \l{tools/plugandpaint}{Plug & Paint} example. It provides a set + of filters in addition to those provided by the + \l{tools/plugandpaintplugins/basictools}{Basic Tools} plugin. + + Since the approach is identical to + \l{tools/plugandpaintplugins/basictools}{Basic Tools}, we won't + review the code here. The only part of interes is the + \c .pro file, since Extra Filters is a dynamic plugin + (\l{tools/plugandpaintplugins/basictools}{Basic Tools} is + linked statically into the Plug & Paint executable). + + Here's the project file for building the Extra Filters plugin: + + \snippet examples/tools/plugandpaintplugins/extrafilters/extrafilters.pro 0 + + The \c .pro file differs from typical \c .pro files in many + respects. First, it starts with a \c TEMPLATE entry specifying \c + lib. (The default template is \c app.) It also adds \c plugin to + the \c CONFIG variable. This is necessary on some platforms to + avoid generating symbolic links with version numbers in the file + name, which is appropriate for most dynamic libraries but not for + plugins. + + The \c INCLUDEPATH variable sets the search paths for global + headers (i.e., header files included using \c{#include <...>}). + We add Qt's \c examples/tools directory (strictly speaking, + \c{examples/tools/plugandpaintplugins/basictools/../..}) to the + list, so that we can include \c . + + The \c TARGET variable specifies which name we want to give the + target library. We use \c pnp_ as the prefix to show that the + plugin is designed to work with Plug & Paint. On Unix, \c lib is + also prepended to that name. On all platforms, a + platform-specific suffix is appended (e.g., \c .dll on Windows, + \c .so on Linux). + + The \c DESTDIR variable specifies where we want to install the + plugin. We put it in Plug & Paint's \c plugins subdirectory, + since that's where the application looks for dynamic plugins. + + The \c CONFIG() code at the end is necessary for this example + because the example is part of the Qt distribution and Qt can be + configured to be built simultaneously in debug and in release + modes. You don't need to for your own plugins. +*/ diff --git a/doc/src/examples/portedasteroids.qdoc b/doc/src/examples/portedasteroids.qdoc new file mode 100644 index 0000000..d32732f --- /dev/null +++ b/doc/src/examples/portedasteroids.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example graphicsview/portedasteroids + \title Ported Asteroids Example + + This GraphicsView example is a port of the + Asteroids game, which was based on QCanvas. + + \image portedasteroids-example.png +*/ diff --git a/doc/src/examples/portedcanvas.qdoc b/doc/src/examples/portedcanvas.qdoc new file mode 100644 index 0000000..76943df --- /dev/null +++ b/doc/src/examples/portedcanvas.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example graphicsview/portedcanvas + \title Ported Canvas Example + + This GraphicsView example is a port of the old + QCanvas example from Qt 3. + + \sa {Porting to Graphics View} + + \image portedcanvas-example.png +*/ diff --git a/doc/src/examples/previewer.qdoc b/doc/src/examples/previewer.qdoc new file mode 100644 index 0000000..9cbeec1 --- /dev/null +++ b/doc/src/examples/previewer.qdoc @@ -0,0 +1,181 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example webkit/previewer + \title Previewer Example + + The Previewer example shows how to use QtWebKit's QWebView to preview + HTML data written in a QPlainTextEdit. + + \image previewer-example.png + + \section1 The User Interface + + Before we begin, we create a user interface using \QD. Two QGroupBox + objects - the editor group box and the previewer group box are separated + by a QSplitter. In the editor group box, we have a QPlainTextEdit object, + \c plainTextEdit, and two QPushButton objects. In the previewer group box, + we have a QWebView object, \c webView. + + \image previewer-ui.png + + \section1 Previewer Class Definition + + The \c Previewer class is a subclass of both QWidget and Ui::Form. + We subclass Ui::Form in order to embed the \QD user interface form + created earlier. This method of embedding forms is known as the + \l{The Multiple Inheritance Approach}{multiple inheritance approach}. + + In our \c previewer.h file, we have a constructor and a slot, + \c on_previewButton_clicked(). + + \snippet examples/webkit/previewer/previewer.h 0 + + \section1 Previewer Class Implementation + + The \c{Previewer}'s constructor is only responsible for setting up the + user interface. + + \snippet examples/webkit/previewer/previewer.cpp 0 + + The \c on_previewButton_clicked() is a slot corresponding to the + \c{previewButton}'s \l{QPushButton::}{clicked()} signal. When the + \c previewButton is clicked, we extract the contents of \c plainTextEdit, + and then invoke the \l{QWebView::}{setHtml()} function to display our + contents as HTML. + + \snippet examples/webkit/previewer/previewer.cpp 1 + + \section1 MainWindow Class Definition + + The \c MainWindow class for the Previewer example is a subclass of + QMainWindow with a constructor and five private slots: \c open(), + \c openUrl(), \c save(), \c about() and \c updateTextEdit(). + + \snippet examples/webkit/previewer/mainwindow.h 0 + + The private objects in \c MainWindow are \c centralWidget, which is + a \c Previewer object, \c fileMenu, \c helpMenu and the QAction objects + \c openAct, \c openUrlAct, \c saveAct, \c exitAct, \c aboutAct and + \c aboutQtAct. + + \snippet examples/webkit/previewer/mainwindow.h 1 + + There are three private functions: \c createActions(), \c createMenus() + and \c setStartupText(). The \c createActions() and \c createMenus() + functions are necessary to set up the main window's actions and + assign them to the \gui File and \gui Help menus. The \c setStartupText() + function, on the other hand, displays a description about the example + in its HTML Previewer window. + + \section1 MainWindow Class Implementation + + The \c{MainWindow}'s constructor invokes \c createActions() and + \c createMenus() to set up the \gui File menu and \gui Help menu. Then, + the \c Previewer object, \c centralWidget, is set to the main window's + central widget. Also, we connect \c webView's + \l{QWebView::}{loadFinished()} signal to our \c updateTextEdit() slot. + Finally, we call the \c setStartupText() function to display the + description of the example. + + \snippet examples/webkit/previewer/mainwindow.cpp 0 + + Within the \c createActions() function, we instantiate all our private + QAction objects which we declared in \c{mainwindow.h}. We set the + short cut and status tip for these actions and connect their + \l{QAction::}{triggered()} signal to appropriate slots. + + \snippet examples/webkit/previewer/mainwindow.cpp 1 + \dots + + The \c createMenus() function instantiates the QMenu items, \c fileMenu + and \c helpMenu and adds them to the main window's + \l{QMainWindow::menuBar()}{menu bar}. + + \snippet examples/webkit/previewer/mainwindow.cpp 2 + + The example also provides an \c about() slot to describe its purpose. + + \snippet examples/webkit/previewer/mainwindow.cpp 3 + + The \c MainWindow class provides two types of \gui Open functions: + \c open() and \c openUrl(). The \c open() function opens an HTML file + with \c fileName, and reads it with QTextStream. The function then + displays the output on \c plainTextEdit. The file's name is obtained + using QFileDialog's \l{QFileDialog::}{getOpenFileName()} function. + + \snippet examples/webkit/previewer/mainwindow.cpp 4 + + The \c openUrl() function, on the other hand, displays a QInputDialog + to obtain a URL, and displays it on \c webView. + + \snippet examples/webkit/previewer/mainwindow.cpp 5 + + In order to save a HTML file, the \c save() function first extracts the + contents of \c plainTextEdit and displays a QFileDialog to obtain + \c fileName. Then, we use a QTextStream object, \c in, to write to + \c file. + + \snippet examples/webkit/previewer/mainwindow.cpp 6 + + Earlier, in \c{MainWindow}'s constructor, we connected \c{webView}'s + \l{QWebView::}{loadFinished()} signal to our private \c updateTextEdit() + slot. This slot updates the contents of \c plainTextEdit with the HTML + source of the web page's main frame, obtained using \l{QWebFrame}'s + \l{QWebFrame::}{toHtml()} function. + + \snippet examples/webkit/previewer/mainwindow.cpp 7 + + To provide a description about the Previewer example, when it starts up, + we use the \c setStartupText() function, as shown below: + + \snippet examples/webkit/previewer/mainwindow.cpp 8 + + + \section1 The \c{main()} Function + + The \c main() function instantiates a \c MainWindow object, \c mainWindow, + and displays it with the \l{QWidget::}{show()} function. + + \snippet examples/webkit/previewer/main.cpp 0 + +*/ \ No newline at end of file diff --git a/doc/src/examples/qobjectxmlmodel.qdoc b/doc/src/examples/qobjectxmlmodel.qdoc new file mode 100644 index 0000000..ce1dab6 --- /dev/null +++ b/doc/src/examples/qobjectxmlmodel.qdoc @@ -0,0 +1,353 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xmlpatterns/qobjectxmlmodel + \title QObject XML Model Example + + This example shows how to use QtXmlPatterns to query QObject trees + by modeling the non-XML data structure of a QObject tree to look + like XML. + + \tableofcontents + + \section1 Introduction + + This example illustrates two important points about using XQuery to + query non-XML data modeled to look like XML. The first point is that + a custom node model class doesn't always have to actually build the + node model. Sometimes the node model can be an already existing data + structure, like the QObject tree used in this example. The second + point is to explain what is required to make non-XML data look like + XML. + + In this example, we want to model a QObject tree to look like + XML. That is easy to do because a QObject tree maps to the XML tree + structure in a staightforward way. Each QObject node is modeled as + an XML element node. However, when we want to add the QMetaObject tree + to the QObject tree node model, we are trying to add a second tree to + the node model. The QMetaObject tree exists \e{behind} the QObject + tree. Adding the QMetaObject tree to the node model changes the two + dimensional tree into a three dimensional tree. + + The query engine can only traverse two dimensional trees, because an + XML document is always a two dimensional tree. If we want to add the + QMetaObject tree to the node model, we have to somehow flatten it + into the the same plane as the QObject tree. This requires that the + node model class must build an auxiliary data structure and make it + part of the two dimensional QObject node model. How to do this is + explained in \l{Including The QMetaObject Tree}. + + \section2 The User Interface + + The UI for this example was created using Qt Designer: + + \image qobjectxmlmodel-example.png + + \section1 Code Walk-Through + + The strategy for this example is different from the strategy for the + \l{File System Example}{file system example}. In the file system + example, the node model class had to actually build a node model + because the non-XML data to be traversed was the computer's file + system, a structure stored on disk in a form that the query engine + couldn't use. The node model class had to build an analog of the + computer's file system in memory. + + For this example, the data structure to be traversed already exists + in memory in a usable form. It is the QObject tree of the example + application itself. All we need is the pointer to the root of the + QObject tree. + + \note When we add the QMetaObject tree to the node model, the node + model class will have to build an auxiliary data structure to move + the QMetaObject tree into the same plane as the QObject tree. This + is explained later in \l{Including The QMetaObject Tree}. + + \section2 The Custom Node Model Class: QObjextXmlModel + + The node model class for this example is QObjextXmlModel, which is + derived from QSimpleXmlNodeModel. QObjextXmlModel implements the + callback interface functions that don't have implementations in + QSimpleXmlNodeModel: + + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 0 + + The node model class declares three data members: + + \target Three Data Members + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 2 + + The constructor sets \c m_baseURI to the QUrl constructed from the + \l{QCoreApplication::applicationFilePath()}{file path} of the + application executable. This is the value returned by + \l{QAbstractXmlNodeModel::documentUri()}{documentUri()}. The + constructor sets \c{m_root} to point to the QObject tree for the + example application. This is the node model that the query engine + will use. And the constructor calls a local function to build the + auxiliary data structure (\c{m_allMetaObjects}) for including the + QMetaObject tree in the node model. How this auxiliary data + structure is incorporated into the QObject node model is discussed + in \l{Including The QMetaObject Tree}. + + \section3 Accessing The Node Model + + Since the query engine knows nothing about QObject trees, it can + only access them by calling functions in the node model callback + interface. The query engine passes a QXmlNodeModelIndex to uniquely + identify a node in the node model. The QXmlNodeModelIndex is + constructed from a pointer to the QObject that represents the node. + \l{QAbstractXmlNodeModel::createIndex()}{createIndex()} creates the + QXmlNodeModelIndex, as in the local \c{root()} function, for example: + + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 0 + + A QObject represents an element node in the node model, but we also + need to represent attribute nodes. For example, the class name of a + QObject is an attribute of the QObject, so it should be an attribute + node in the node model. A QObject's class name is obtained from the + QObject. (Actually, it is in the QMetaObject, which is obtained from + the QObject). This means that a single QObject logically represents + multiple nodes in the node model: the element node and potentially + many attribute nodes. + + To uniquely identify an attribute node, we need the pointer to the + QObject containing the attribute, and an additional value that + identifies the attribute in the QObject. For this \e{additional + data} value, we use \c{enum QObjectNodeType}: + + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 3 + + Ignore the \c{MetaObjectXXX} values for now. They will be explained + in \l{Including The QMetaObject Tree}. Here we are interested in the + three node types for QObject nodes: \c{IsQObject}, which represents + the element node type for a QObject, and \c{QObjectProperty} and + \c{QObjectClassName}, which represent the attribute node types for + the attributes of a QObject. + + The \l{QAbstractXmlNodeModel::createIndex()}{createIndex()} + function called in the \c{root()} snippet above is the overload that + accepts a \c{void*} pointer and a second parameter, + \c{additionalData}, with default value 0 (\c{IsQObject}). Wherever + you see a call to \l{QAbstractXmlNodeModel::createIndex()} + {createIndex()} that only passes the QObject pointer, it is creating + the node index for a QObject element node. To create the node index + for the class name attribute, for example, the \l{QObject + attributes} {attributes()} function uses + \c{createIndex(object,QObjectClassName)}. + + \target QObject attributes + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 6 + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 8 + + \l{QObject attributes} {attributes()} is one of the callback + functions you have to implement in your custom node model class. It + returns a QVector of \l{QXmlNodeModelIndex} {node indexes} for all + the attribute nodes for QObject \c{n}. It calls + \l{QAbstractXmlNodeModel::createIndex()} {createIndex()} in two places. + Both calls use the QObject pointer from the current node \c{n} (the + element node), and just add a different value for the \e{additional data} + parameter. This makes sense because, in XML, the attributes of an + element are part of that element. + + \section3 Traversing The Node Model + + The query engine traverses the QObject tree by calling back to the + node model class's implementation of \l{QObject nextFromSimpleAxis} + {nextFromSimpleAxis()}. This function is the heart of the callback + interface, and it will probably be the most complex to implement in + your custom node model class. Below is a partial listing of the + implementation for this example. The full listing will be shown in + \l{Including The QMetaObject Tree}, where we discuss traversing the + QMetaObject tree. + + \target QObject nextFromSimpleAxis + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 2 + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 4 + + The main switch uses \c toNodeType(), which obtains the node + type from \l{QXmlNodeModelIndex::additionalData()}: + + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 1 + + \c{case IsObject} case is the most interesting. It switches again on + the value of the \c{axis} parameter, which specifies the direction + the query engine wants to take from the current node. It is one of + the four enum values of \l{QAbstractXmlNodeModel::SimpleAxis}. The + \l{QAbstractXmlNodeModel::Parent} {Parent} and + \l{QAbstractXmlNodeModel::FirstChild} {FirstChild} cases reduce to + calls to QObject::parent() and QObject::children() + respectively. Note that a default constructed QXmlNodeModelIndex is + returned in the \l{QAbstractXmlNodeModel::Parent} {Parent} case if + the current node is the root, and in the + \l{QAbstractXmlNodeModel::FirstChild} {FirstChild} case if the + current node has no children. + + For the \l{QAbstractXmlNodeModel::NextSibling} {NextSibling} and + \l{QAbstractXmlNodeModel::PreviousSibling} {PreviousSibling} axes, + the helper function \c{qObjectSibling()} is called, with +1 to + traverse to the \l{QAbstractXmlNodeModel::NextSibling} {NextSibling} + and -1 to traverse to the + \l{QAbstractXmlNodeModel::PreviousSibling} {PreviousSibling}. + + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 5 + + \c{qObjectSibling()} determines whether or not the node has any + siblings. It is called with \c{n}, the index of the current node. + If the current node is a child, then it has a parent with children + (the current node one of these). + So, we get the \l{QObject::parent()}{parent}, obtain the parent's + \l{QObject::children()} {child list}, find the current node in the + list, and construct the node index for the next or previous child + (sibling) and return it. + + \note In \l{QObject nextFromSimpleAxis} {nextFromSimpleAxis()}, the + special case of asking for the + \l{QAbstractXmlNodeModel::PreviousSibling} {PreviousSibling} of the + root node is discussed in \l{Including The QMetaObject Tree}. + + Traversing away from a \c{QObjectClassName} attribute node or a + \c{QObjectProperty} attribute node might seem a bit confusing at + first glance. The only move allowed from an attribute node is to the + \l{QAbstractXmlNodeModel::Parent} {Parent}, because attribute nodes + don't have children. But these two cases simply return the + \l{QXmlNodeModelIndex} {node index} of the current node. + + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 7 + + Since \c n is the QXmlNodeModelIndex of the current node, all this + does is create another QXmlNodeModelIndex for the current node and + return it. This was explained above in \l{Accessing The Node Model}, + where we saw that each QObject in the node model actually represents + an element node and potentially many attribute nodes. Traversing to + the parent node of an attribute simply creates a node index for the + same QObject, but with an \e{additional data} value of 0 + (\c{IsQObject}). + + If we only wanted to traverse the QObject tree with XQuery, we could + just implement the rest of the virtual callback functions listed + earlier and we would be done. The implementations for the remaining + functions are straightforward. But if we also want to use XQuery to + traverse the QMetaObject tree, we must include the QMetaObject tree + in the custom node model. + + \section3 Including The QMetaObject Tree + + The \l{Meta-Object System} {metaobject system} not only enables Qt's + \l{Signals and Slots} {signals and slots}, it also provides type + information that is useful at run-time; e.g., getting and setting + properties without knowing the property names at compile time. Each + QObject has an associated QMetaObject tree which contains all this + useful type information. Given a QObject, its QMetaObject is + obtained with QObject::metaObject(). Then QMetaObject::superClass() + can be called repeatedly to get the QMetaObject for each class in the + class hierarchy for the original QObject. + + However, the QMetaObject hierarchy is a second tree in a plan that + exists logically behind the plane of the QObject tree. The QtXmlPatterns + query engine can only traverse a two dimensional node model that + represents an XML tree. If we want to include the QMetaObject in the + same node model that represents the QObject tree, we must find a way + to flatten the QMetaObject tree into the same plane as the QObject + tree. + + The node model class declares \l{All MetaObjects}{m_allMetaObjects} + as a vector of pointers to QMetaObject: + + \target All MetaObjects + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 1 + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 4 + + This vector gets populated by the QObjectXmlModel constructor by + calling the private allMetaObjects() function: + + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 9 + + The first half of the function is an example of the standard code + pattern for using QtXmlPatterns to run an XQuery. First it creates an + instance of QXmlQuery. Then it \l{QXmlQuery::bindVariable()}{binds} + the XQuery variable \c{$root} to the root node of the of the node + model; i.e., the root of the QObject tree. Then it + \l{QXmlQuery::setQuery()} {sets the query} to be an XQuery that + returns all the QObjects in the node model. Finally, the query is + evaluated into a \l{QXmlResultItems} {result item list}. + + \note \l{QXmlQuery::bindVariable()} must be called before + \l{QXmlQuery::setQuery()}, because setting the query causes + QtXmlPatterns to \e compile the XQuery, which requires knowledge of + the variable bindings. + + The second half of the function traverses the \l{QXmlResultItems} + {result item list}, getting the QMetaObject hierarchy for each + QObject and appending it to \l{All MetaObjects} {m_allMetaObjects}, + if it isn't already there. But how do we include this vector of + pointers to QMetaObjects in the node model? The key insight is + shown in the full listing of \l{Full Listing of nextFromSimpleAxis} + {nextFromSimpleAxis()}, where we are interested now in the + \c{MetaObjectXXX} cases: + + \target Full Listing of nextFromSimpleAxis + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 2 + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 3 + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 4 + + But first, revisit the \c{PreviousSibling} case for the + \c{IsQObject} case: + + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 10 + + When asking for the previous sibling of the root of the QObject + tree, it creates a node model index with a null QObject pointer and + an \c{additionalData} value of \c{MetaObjects}. This effectively + allows the query engine to jump from the QObject tree to the + QMetaObject tree. + + The query engine can jump from the QMetaObject tree back to the + QObject tree in the \c{NextSibling} case of case \c{MetaObjects}, + where the \c{root()} function is called: + + \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 11 + + Having jumped from the QObject tree to the QMetaObject tree, the + query engine will use the \c{MetaObject}, \c{MetaObjectClassName}, + and \c{MetaObjectSuperClass} cases, which are similar to the cases + for \c{IsQObject}, \c{QObjectProperty}, and \c{QObjectClassName}. +*/ diff --git a/doc/src/examples/qtconcurrent-imagescaling.qdoc b/doc/src/examples/qtconcurrent-imagescaling.qdoc new file mode 100644 index 0000000..74b4be0 --- /dev/null +++ b/doc/src/examples/qtconcurrent-imagescaling.qdoc @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example qtconcurrent/imagescaling + \title QtConcurrent Image Scaling Example + + The QtConcurrent Map example shows how to use the asynchronous + QtConcurrent API to load and scale a collection of images. +*/ diff --git a/doc/src/examples/qtconcurrent-map.qdoc b/doc/src/examples/qtconcurrent-map.qdoc new file mode 100644 index 0000000..9f5295d --- /dev/null +++ b/doc/src/examples/qtconcurrent-map.qdoc @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example qtconcurrent/map + \title QtConcurrent Map Example + + The QtConcurrent Map example shows how to use the synchronous (blocking) + QtConcurrent API to scale a collection of images. +*/ diff --git a/doc/src/examples/qtconcurrent-progressdialog.qdoc b/doc/src/examples/qtconcurrent-progressdialog.qdoc new file mode 100644 index 0000000..41909fb --- /dev/null +++ b/doc/src/examples/qtconcurrent-progressdialog.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example qtconcurrent/progressdialog + \title QtConcurrent Progress Dialog Example + + The QtConcurrent Progress Dialog example shows how to use the + QFutureWatcher class to monitor the progress of a long-running operation. + + \image qtconcurrent-progressdialog.png +*/ diff --git a/doc/src/examples/qtconcurrent-runfunction.qdoc b/doc/src/examples/qtconcurrent-runfunction.qdoc new file mode 100644 index 0000000..5c40552 --- /dev/null +++ b/doc/src/examples/qtconcurrent-runfunction.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example qtconcurrent/runfunction + \title QtConcurrent Run Function Example + + The QtConcurrent Run Function example shows how to apply concurrency to + a standard function, using QFuture instances to retrieve return values + at a later time. +*/ diff --git a/doc/src/examples/qtconcurrent-wordcount.qdoc b/doc/src/examples/qtconcurrent-wordcount.qdoc new file mode 100644 index 0000000..d7d3227 --- /dev/null +++ b/doc/src/examples/qtconcurrent-wordcount.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example qtconcurrent/wordcount + \title QtConcurrent Word Count Example + + The QtConcurrent Word Count example demonstrates the use of the map-reduce + algorithm when applied to the problem of counting words in a collection + of files. +*/ diff --git a/doc/src/examples/qtscriptcalculator.qdoc b/doc/src/examples/qtscriptcalculator.qdoc new file mode 100644 index 0000000..1d713f8 --- /dev/null +++ b/doc/src/examples/qtscriptcalculator.qdoc @@ -0,0 +1,105 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example script/calculator + \title QtScript Calculator Example + \ingroup scripting + + In this simple QtScript example, we show how to implement the + functionality of a calculator widget. + + \image qtscript-calculator-example.png + + The program logic in this example is a fairly straight port of the logic in the C++ \l{Calculator Example}. + The graphical user interface is defined in a UI file. + + The C++ part of the example consists of four steps: + \list + \o Evaluate the script code that defines the \c{Calculator} class. + + \snippet examples/script/calculator/main.cpp 0a + \snippet examples/script/calculator/main.cpp 0b + + \o Create a widget from the UI file using QUiLoader. + + \snippet examples/script/calculator/main.cpp 1 + + \o Call the Calculator constructor function to create a new \c{Calculator} script object, passing the widget as argument. + + \snippet examples/script/calculator/main.cpp 2 + + \o Show the widget and start the application event loop. + + \snippet examples/script/calculator/main.cpp 3 + + \endlist + + On the script side, the \c{Calculator} constructor function + initializes the instance variables of the new \c{Calculator} + object, and connects the clicked() signal of the form's buttons + to corresponding functions defined in the \c{Calculator} prototype + object; the effect is that when a button is clicked, the proper + script function will be invoked to carry out the operation. + + \snippet examples/script/calculator/calculator.js 0 + + A \c{Calculator} object is just a plain script object; it is not + a widget. Instead, it stores a reference to the calculator form + (the widget) in an instance variable, \c{ui}. The calculator + script functions can access components of the form by referring + to the proper children of the \c{ui} member. + + \snippet examples/script/calculator/calculator.js 1 + + The digitClicked() function uses the special local variable + __qt_sender__ to access the object that triggered the signal; + this gives us a simple way to retrieve the value of the digit + that was clicked. + + \snippet examples/script/calculator/calculator.js 2 + + The changeSign() function shows how we retrieve the text property + of the calculator's display, change it appropriately, and write + back the new value. + + +*/ diff --git a/doc/src/examples/qtscriptcustomclass.qdoc b/doc/src/examples/qtscriptcustomclass.qdoc new file mode 100644 index 0000000..f8d85a2 --- /dev/null +++ b/doc/src/examples/qtscriptcustomclass.qdoc @@ -0,0 +1,198 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example script/customclass + \title Custom Script Class Example + + The Custom Script Class example shows how to use QScriptClass and QScriptClassPropertyIterator + to implement a custom script class. + + The script class we are going to implement is called \c{ByteArray}. It provides a wrapper around + the QByteArray class in Qt, with a simplified API. Why do we need such a class? Well, neither the + ECMAScript \c{Array} class or \c{String} class is appropriate to use when working with arrays of + bytes. Our \c{ByteArray} class will have the right semantics; objects will use only the amount of + memory that is really needed (a byte is stored as a byte, not as a floating-point number or a + Unicode character) and can be passed directly to C++ slots taking QByteArray arguments (no costly + conversion necessary). + + \section1 ByteArray Class In Use + + When the \c{ByteArray} class has been made available to the + scripting environment, \c{ByteArray} objects can be constructed like + so: + + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 0 + + \c{ByteArray} objects behave similar to normal \c{Array} objects. Every \c{ByteArray} object has + a \c{length} property, that holds the length of the array. If a new value is assigned to the \c{length} + property, the array is resized. If the array is enlarged, the new bytes are initialized to 0. + (This is a difference from normal \c{Array} objects; \c{ByteArray} objects are always dense arrays.) + Use normal array operations to read or write bytes in the array. The following code sets all the + bytes of an array to a certain value: + + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 1 + + When assigning a value to an array element, the value is truncated to eight bits: + + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 2 + + Like normal \c{Array} objects, if the array index is greater than the current length + of the array, the array is resized accordingly: + + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 3 + + Property names that aren't valid array indexes are treated + like normal object properties (again, the same is the case for normal \c{Array} objects); + in other words, it's perfectly fine to do something like this: + + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 4 + + The above assignment won't affect the contents of the array, but will rather assign a value + to the object property named "foo". + + \c{ByteArray} objects have a set of methods: chop(), equals(), left(), mid(), toBase64() and so on. + These map directly onto the corresponding methods in QByteArray. + + \snippet doc/src/snippets/code/doc_src_examples_qtscriptcustomclass.qdoc 5 + + \section1 ByteArray Class Implementation + + To implement the \c{ByteArray} script class in C++, we create a subclass of QScriptClass, + called ByteArrayClass, and reimplement the virtual functions from QScriptClass. We also provide + a Qt Script constructor function suitable for being added to a QScriptEngine's environment. + + The ByteArrayClass constructor prepares the script class: + + \snippet examples/script/customclass/bytearrayclass.cpp 0 + + First, the constructor registers a pair of conversion functions, so that C++ QByteArray objects + and Qt Script \c{ByteArray} objects can move seamlessly between the C++ side and the script side. + For example, if a \c{ByteArray} object is passed to a C++ slot that takes a QByteArray + argument, the actual QByteArray that the \c{ByteArray} object wraps will be passed correctly. + + Second, we store a handle to the string "length", so that we can quickly compare a given property name + to "length" later on. + + Third, we initialize the standard \c{ByteArray} prototype, to be returned by our prototype() + reimplementation later on. (The implementation of the prototype is discussed later.) + + Fourth, we initialize a constructor function for \c{ByteArray}, to be returned by the + constructor() function. We set the internal data of the constructor to be a pointer to + this ByteArrayClass object, so that the constructor, when it is invoked, can extract the + pointer and use it to create a new \c{ByteArray} object. + + \snippet examples/script/customclass/bytearrayclass.cpp 1 + + The newInstance() function isn't part of the QScriptClass API; its purpose is to offer + a convenient way to construct a \c{ByteArray} object from an existing QByteArray. We store the + QByteArray as the internal data of the new object, and return the new object. + QScriptEngine::newObject() will call the prototype() function of our class, ensuring that + the prototype of the new object will be the standard \c{ByteArray} prototype. + + \snippet examples/script/customclass/bytearrayclass.cpp 2 + + construct() is the native function that will act as a constructor for \c{ByteArray} + in scripts. We extract the pointer to the class, then call a newInstance() overload + that takes an initial size as argument, and return the new script object. + + \snippet examples/script/customclass/bytearrayclass.cpp 3 + + queryProperty() is the function that Qt Script will call whenever someone tries to access + a property of a \c{ByteArray} object. We first get a pointer to the underlying QByteArray. + We check if the property being accessed is the special \c{length} property; if so, we + return, indicating that we will handle every kind of access to this property (e.g. both + read and write). Otherwise, we attempt to convert the property name to an array index. If + this fails, we return, indicating that we don't want to handle this property. Otherwise, we + have a valid array index, and store it in the \c{id} argument, so that we don't have to + recompute it in e.g. property() or setProperty(). If the index is greater than or equal to + the QByteArray's size, we indicate that we don't want to handle read access (but we still want + to handle writes, if requested). + + \snippet examples/script/customclass/bytearrayclass.cpp 4 + + In the property() reimplementation, we do similar checks as in queryProperty() to find out + which property is being requested, and then return the value of that property. + + \snippet examples/script/customclass/bytearrayclass.cpp 5 + + The setProperty() reimplementation has a structure that is similar to property(). If the \c{length} property + is being set, we resize the underlying QByteArray to the given length. Otherwise, we grab the + array index that was calculated in the queryProperty() function, enlarge the array if necessary, + and write the given value to the array. + + \snippet examples/script/customclass/bytearrayclass.cpp 6 + + The propertyFlags() reimplementation specifies that the \c{length} property can't be deleted, + and that it is not enumerable. Array elements can't be deleted. + + \snippet examples/script/customclass/bytearrayclass.cpp 7 + + We want the array elements to show up when a \c{ByteArray} object is used in for-in + statements and together with QScriptValueIterator. Therefore, we reimplement the + newIterator() function and have it return a new iterator for a given \c{ByteArray}. + + \section1 ByteArray Iterator Implementation + + \snippet examples/script/customclass/bytearrayclass.cpp 8 + + The \c{ByteArrayClassPropertyIterator} class is simple. It maintains an index into the + underlying QByteArray, and checks and updates the index in hasNext(), next() and so on. + + \section1 ByteArray Prototype Implementation + + The prototype class, ByteArrayPrototype, implements the \c{ByteArray} functions as slots. + + \snippet examples/script/customclass/bytearrayprototype.h 0 + + There is a small helper function, thisByteArray(), that returns a pointer to the QByteArray + being operated upon: + + \snippet examples/script/customclass/bytearrayprototype.cpp 0 + + The slots simply forward the calls to the QByteArray. Examples: + + \snippet examples/script/customclass/bytearrayprototype.cpp 1 + + The remove() function is noteworthy; if we look at QByteArray::remove(), we see that it + should return a reference to the QByteArray itself (i.e. not a copy). To get the same + behavior in scripts, we return the script object (thisObject()). +*/ diff --git a/doc/src/examples/qtscripttetrix.qdoc b/doc/src/examples/qtscripttetrix.qdoc new file mode 100644 index 0000000..c96db6a --- /dev/null +++ b/doc/src/examples/qtscripttetrix.qdoc @@ -0,0 +1,92 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example script/qstetrix + \title Qt Script Tetrix Example + + The QSTetrix example is a Qt Script version of the classic Tetrix game. + + \image tetrix-example.png + + \section1 Overview + + The program logic in this example is a fairly straight port of the + logic in the C++ \l{Tetrix Example}. You may find it useful to compare + the implementations of the \c TetrixBoard, \c TetrixPiece and + \c TetrixWindow classes to see how Qt Script is used to implement + methods, call Qt functions, and emit signals. + + \section1 Setting up the GUI + + The graphical user interface is defined in a \c{.ui} file, creating + using Qt Designer, and is set up in the example's C++ \c{main.cpp} file. + + \snippet examples/script/qstetrix/main.cpp 0 + + We define a custom UI loader that handles our \c TetrixBoard widget; this + is the main component of the UI (where the pieces are drawn). + + \snippet examples/script/qstetrix/main.cpp 1 + + We initialize the script engine to have the Qt namespace, so that + e.g., \l{Qt::Key_Left}{Qt.Key_Left} will be available to script code. + We also make the application object available (for the + \l{QApplication::}{quit()} slot). + + \snippet examples/script/qstetrix/main.cpp 2 + + Several scripts are evaluated as part of the engine setup process. + The \c{tetrixpiece.js} file contains the definition of the \c TetrixPiece + class, which is used to populate the play field. The \c{tetrixboard.js} + file contains the definition of the \c TetrixBoard class, which contains + the main game logic. Finally, \c{tetrixwindow.js} contains the definition + of the \c TetrixWindow class, which wires up the top-level widget. + + \snippet examples/script/qstetrix/main.cpp 3 + + A form is created from the UI file. A new \c TetrixWindow script object + is then constructed, passing the form as its argument. + + \snippet examples/script/qstetrix/main.cpp 4 + + The form is shown, and the event loop is entered. +*/ diff --git a/doc/src/examples/querymodel.qdoc b/doc/src/examples/querymodel.qdoc new file mode 100644 index 0000000..296f609 --- /dev/null +++ b/doc/src/examples/querymodel.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/querymodel + \title Query Model Example + + The Query Model example shows how to make customized versions of + data obtained from a SQL query, using a model that encapsulates + the query and table views to display the results. + + \image querymodel-example.png +*/ diff --git a/doc/src/examples/queuedcustomtype.qdoc b/doc/src/examples/queuedcustomtype.qdoc new file mode 100644 index 0000000..bbd1427 --- /dev/null +++ b/doc/src/examples/queuedcustomtype.qdoc @@ -0,0 +1,177 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example threads/queuedcustomtype + \title Queued Custom Type Example + + The Queued Custom Type example shows how to send custom types between + threads with queued signals and slots. + + \image queuedcustomtype-example.png + + Contents: + + \tableofcontents + + \section1 Overview + + In the \l{Custom Type Sending Example}, we showed how to use a custom type + with signal-slot communication within the same thread. + + In this example, we create a new value class, \c Block, and register it + with the meta-object system to enable us to send instances of it between + threads using queued signals and slots. + + \section1 The Block Class + + The \c Block class is similar to the \c Message class described in the + \l{Custom Type Example}. It provides the default constructor, copy + constructor and destructor in the public section of the class that the + meta-object system requires. It describes a colored rectangle. + + \snippet examples/threads/queuedcustomtype/block.h custom type definition and meta-type declaration + + We will still need to register it with the meta-object system at + run-time by calling the qRegisterMetaType() template function before + we make any signal-slot connections that use this type. + Even though we do not intend to use the type with QVariant in this example, + it is good practice to also declare the new type with Q_DECLARE_METATYPE(). + + The implementation of the \c Block class is trivial, so we avoid quoting + it here. + + \section1 The Window Class + + We define a simple \c Window class with a public slot that accepts a + \c Block object. The rest of the class is concerned with managing the + user interface and handling images. + + \snippet examples/threads/queuedcustomtype/window.h Window class definition + + The \c Window class also contains a worker thread, provided by a + \c RenderThread object. This will emit signals to send \c Block objects + to the window's \c addBlock(Block) slot. + + The parts of the \c Window class that are most relevant are the constructor + and the \c addBlock(Block) slot. + + The constructor creates a thread for rendering images, sets up a user + interface containing a label and two push buttons that are connected to + slots in the same class. + + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor start + \snippet examples/threads/queuedcustomtype/window.cpp set up widgets and connections + \snippet examples/threads/queuedcustomtype/window.cpp connecting signal with custom type + + In the last of these connections, we connect a signal in the + \c RenderThread object to the \c addBlock(Block) slot in the window. + + \dots + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor finish + + The rest of the constructor simply sets up the layout of the window. + + The \c addBlock(Block) slot receives blocks from the rendering thread via + the signal-slot connection set up in the constructor: + + \snippet examples/threads/queuedcustomtype/window.cpp Adding blocks to the display + + We simply paint these onto the label as they arrive. + + \section1 The RenderThread Class + + The \c RenderThread class processes an image, creating \c Block objects + and using the \c sendBlock(Block) signal to send them to other components + in the example. + + \snippet examples/threads/queuedcustomtype/renderthread.h RenderThread class definition + + The constructor and destructor are not quoted here. These take care of + setting up the thread's internal state and cleaning up when it is destroyed. + + Processing is started with the \c processImage() function, which calls the + \c RenderThread class's reimplementation of the QThread::run() function: + + \snippet examples/threads/queuedcustomtype/renderthread.cpp processing the image (start) + + Ignoring the details of the way the image is processed, we see that the + signal containing a block is emitted in the usual way: + + \dots + \snippet examples/threads/queuedcustomtype/renderthread.cpp processing the image (finish) + + Each signal that is emitted will be queued and delivered later to the + window's \c addBlock(Block) slot. + + \section1 Registering the Type + + In the example's \c{main()} function, we perform the registration of the + \c Block class as a custom type with the meta-object system by calling the + qRegisterMetaType() template function: + + \snippet examples/threads/queuedcustomtype/main.cpp main function + + This call is placed here to ensure that the type is registered before any + signal-slot connections are made that use it. + + The rest of the \c{main()} function is concerned with setting a seed for + the pseudo-random number generator, creating and showing the window, and + setting a default image. See the source code for the implementation of the + \c createImage() function. + + \section1 Further Reading + + This example showed how a custom type can be registered with the + meta-object system so that it can be used with signal-slot connections + between threads. For ordinary communication involving direct signals and + slots, it is enough to simply declare the type in the way described in the + \l{Custom Type Sending Example}. + + In practice, both the Q_DECLARE_METATYPE() macro and the qRegisterMetaType() + template function can be used to register custom types, but + qRegisterMetaType() is only required if you need to perform signal-slot + communication or need to create and destroy objects of the custom type + at run-time. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ diff --git a/doc/src/examples/qxmlstreambookmarks.qdoc b/doc/src/examples/qxmlstreambookmarks.qdoc new file mode 100644 index 0000000..7059043 --- /dev/null +++ b/doc/src/examples/qxmlstreambookmarks.qdoc @@ -0,0 +1,200 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/streambookmarks + \title QXmlStream Bookmarks Example + + The QXmlStream Bookmarks example provides a reader for XML Bookmark + Exchange Language (XBEL) files using Qt's QXmlStreamReader class + for reading, and QXmlStreamWriter class for writing the files. + + \image xmlstreamexample-screenshot.png + + \section1 XbelWriter Class Definition + + The \c XbelWriter class is a subclass of QXmlStreamReader, which provides + an XML parser with a streaming API. \c XbelWriter also contains a private + instance of QTreeWidget in order to display the bookmarks according to + hierarchies. + + \snippet examples/xml/streambookmarks/xbelwriter.h 0 + + \section1 XbelWriter Class Implementation + + The \c XbelWriter constructor accepts a \a treeWidget to initialize within + its definition. We enable \l{QXmlStreamWriter}'s auto-formatting property + to ensure line-breaks and indentations are added automatically to empty + sections between elements, increasing readability as the data is split into + several lines. + + \snippet examples/xml/streambookmarks/xbelwriter.cpp 0 + + The \c writeFile() function accepts a QIODevice object and sets it using + \c setDevice(). This function then writes the document type + definition(DTD), the start element, the version, and \c{treeWidget}'s + top-level items. + + \snippet examples/xml/streambookmarks/xbelwriter.cpp 1 + + The \c writeItem() function accepts a QTreeWidget object and writes it + to the stream, depending on its \c tagName, which can either be a "folder", + "bookmark", or "separator". + + \snippet examples/xml/streambookmarks/xbelwriter.cpp 2 + + \section1 XbelReader Class Definition + + The \c XbelReader class is a subclass of QXmlStreamReader, the pendent + class for QXmlStreamWriter. \c XbelReader contains a private instance + of QTreeWidget to group bookmarks according to their hierarchies. + + \snippet examples/xml/streambookmarks/xbelreader.h 0 + + \section1 XbelReader Class Implementation + + The \c XbelReader constructor accepts a QTreeWidget to initialize the + \c treeWidget within its definition. A QStyle object is used to set + \c{treeWidget}'s style property. The \c folderIcon is set to QIcon::Normal + mode where the pixmap is only displayed when the user is not interacting + with the icon. The QStyle::SP_DirClosedIcon, QStyle::SP_DirOpenIcon, and + QStyle::SP_FileIcon correspond to standard pixmaps that follow the style + of your GUI. + + \snippet examples/xml/streambookmarks/xbelreader.cpp 0 + + The \c read() function accepts a QIODevice and sets it using + \l{QXmlStreamReader::setDevice()}{setDevice()}. The actual process + of reading only takes place in event the file is a valid XBEL 1.0 + file. Otherwise, the \l{QXmlStreamReader::raiseError()} + {raiseError()} function is used to display an error message. + + \snippet examples/xml/streambookmarks/xbelreader.cpp 1 + + The \c readUnknownElement() function reads an unknown element. The + Q_ASSERT() macro is used to provide a pre-condition for the function. + + \snippet examples/xml/streambookmarks/xbelreader.cpp 2 + + The \c readXBEL() function reads the name of a startElement and calls + the appropriate function to read it, depending on whether if its a + "folder", "bookmark" or "separator". Otherwise, it calls + \c readUnknownElement(). + + \snippet examples/xml/streambookmarks/xbelreader.cpp 3 + + The \c readTitle() function reads the bookmark's title. + + \snippet examples/xml/streambookmarks/xbelreader.cpp 4 + + The \c readSeparator() function creates a separator and sets its flags. + The text is set to 30 "0xB7", the HEX equivalent for period, and then + read using \c readElementText(). + + \snippet examples/xml/streambookmarks/xbelreader.cpp 5 + + \section1 MainWindow Class Definition + + The \c MainWindow class is a subclass of QMainWindow, with a + \c File menu and a \c Help menu. + + \snippet examples/xml/streambookmarks/mainwindow.h 0 + + \section1 MainWindow Class Implementation + + The \c MainWindow constructor instantiates the QTreeWidget object, \c + treeWidget and sets its header with a QStringList object, \c labels. + The constructor also invokes \c createActions() and \c createMenus() + to set up the menus and their corresponding actions. The \c statusBar() + is used to display the message "Ready" and the window's size is fixed + to 480x320 pixels. + + \snippet examples/xml/streambookmarks/mainwindow.cpp 0 + + The \c open() function enables the user to open an XBEL file using + QFileDialog::getOpenFileName(). A warning message is displayed along + with the \c fileName and \c errorString if the file cannot be read or + if there is a parse error. + + \snippet examples/xml/streambookmarks/mainwindow.cpp 1 + + The \c saveAs() function displays a QFileDialog, prompting the user for + a \c fileName using QFileDialog::getSaveFileName(). Similar to the + \c open() function, this function also displays a warning message if + the file cannot be written to. + + \snippet examples/xml/streambookmarks/mainwindow.cpp 2 + + The \c about() function displays a QMessageBox with a brief description + of the example. + + \snippet examples/xml/streambookmarks/mainwindow.cpp 3 + + In order to implement the \c open(), \c saveAs(), \c exit(), \c about() + and \c aboutQt() functions, we connect them to QAction objects and + add them to the \c fileMenu and \c helpMenu. The connections are as shown + below: + + \snippet examples/xml/streambookmarks/mainwindow.cpp 4 + + The \c createMenus() function creates the \c fileMenu and \c helpMenu + and adds the QAction objects to them in order to create the menu shown + in the screenshot below: + + \table + \row + \o \inlineimage xmlstreamexample-filemenu.png + \o \inlineimage xmlstreamexample-helpmenu.png + \endtable + + \snippet examples/xml/streambookmarks/mainwindow.cpp 5 + + \section1 \c{main()} Function + + The \c main() function instantiates \c MainWindow and invokes the \c show() + function. + + \snippet examples/xml/streambookmarks/main.cpp 0 + + See the \l{http://pyxml.sourceforge.net/topics/xbel/} + {XML Bookmark Exchange Language Resource Page} for more information + about XBEL files. +*/ diff --git a/doc/src/examples/recentfiles.qdoc b/doc/src/examples/recentfiles.qdoc new file mode 100644 index 0000000..185cbf1 --- /dev/null +++ b/doc/src/examples/recentfiles.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example mainwindows/recentfiles + \title Recent Files Example + + The Recent Files example shows how a standard File menu can be extended to show + the most recent files loaded by a main window application. + + \image recentfiles-example.png +*/ diff --git a/doc/src/examples/recipes.qdoc b/doc/src/examples/recipes.qdoc new file mode 100644 index 0000000..ba06b7e --- /dev/null +++ b/doc/src/examples/recipes.qdoc @@ -0,0 +1,164 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xmlpatterns/recipes + \title Recipes Example + + The recipes example shows how to use QtXmlPatterns to query XML data + loaded from a file. + + \tableofcontents + + \section1 Introduction + + In this case, the XML data represents a cookbook, \c{cookbook.xml}, + which contains \c{} as its document element, which in turn + contains a sequence of \c{} elements. This XML data is + searched using queries stored in XQuery files (\c{*.xq}). + + \section2 The User Interface + + The UI for this example was created using \l{Qt Designer Manual} {Qt + Designer}: + + \image recipes-example.png + + The UI consists of three \l{QGroupBox} {group boxes} arranged + vertically. The top one contains a \l{QTextEdit} {text viewer} that + displays the XML text from the cookbook file. The middle group box + contains a \l{QComboBox} {combo box} for choosing the \l{A Short + Path to XQuery} {XQuery} to run and a \l{QTextEdit} {text viewer} + for displaying the text of the selected XQuery. The \c{.xq} files in + the file list above are shown in the combo box menu. Choosing an + XQuery loads, parses, and runs the selected XQuery. The query result + is shown in the bottom group box's \l{QTextEdit} {text viewer}. + + \section2 Running your own XQueries + + You can write your own XQuery files and run them in the example + program. The file \c{xmlpatterns/recipes/recipes.qrc} is the \l{The + Qt Resource System} {resource file} for this example. It is used in + \c{main.cpp} (\c{Q_INIT_RESOURCE(recipes);}). It lists the XQuery + files (\c{.xq}) that can be selected in the combobox. + + \quotefromfile examples/xmlpatterns/recipes/recipes.qrc + \printuntil + + To add your own queries to the example's combobox, store your + \c{.xq} files in the \c{examples/xmlpatterns/recipes/files} + directory and add them to \c{recipes.qrc} as shown above. + + \section1 Code Walk-Through + + The example's main() function creates the standard instance of + QApplication. Then it creates an instance of the UI class, shows it, + and starts the Qt event loop: + + \snippet examples/xmlpatterns/recipes/main.cpp 0 + + \section2 The UI Class: QueryMainWindow + + The example's UI is a conventional Qt GUI application inheriting + QMainWindow and the class generated by \l{Qt Designer Manual} {Qt + Designer}: + + \snippet examples/xmlpatterns/recipes/querymainwindow.h 0 + + The constructor finds the window's \l{QComboBox} {combo box} child + widget and connects its \l{QComboBox::currentIndexChanged()} + {currentIndexChanged()} signal to the window's \c{displayQuery()} + slot. It then calls \c{loadInputFile()} to load \c{cookbook.xml} and + display its contents in the top group box's \l{QTextEdit} {text + viewer} . Finally, it finds the XQuery files (\c{.xq}) and adds each + one to the \l{QComboBox} {combo box} menu. + + \snippet examples/xmlpatterns/recipes/querymainwindow.cpp 0 + + The work is done in the \l{displayQuery() slot} {displayQuery()} + slot and the \l{evaluate() function} {evaluate()} function it + calls. \l{displayQuery() slot} {displayQuery()} loads and displays + the selected query file and passes the XQuery text to \l{evaluate() + function} {evaluate()}. + + \target displayQuery() slot + \snippet examples/xmlpatterns/recipes/querymainwindow.cpp 1 + + \l{evaluate() function} {evaluate()} demonstrates the standard + QtXmlPatterns usage pattern. First, an instance of QXmlQuery is + created (\c{query}). The \c{query's} \l{QXmlQuery::bindVariable()} + {bindVariable()} function is then called to bind the \c cookbook.xml + file to the XQuery variable \c inputDocument. \e{After} the variable + is bound, \l{QXmlQuery::setQuery()} {setQuery()} is called to pass + the XQuery text to the \c query. + + \note \l{QXmlQuery::setQuery()} {setQuery()} must be called + \e{after} \l{QXmlQuery::bindVariable()} {bindVariable()}. + + Passing the XQuery to \l{QXmlQuery::setQuery()} {setQuery()} causes + QtXmlPatterns to parse the XQuery. \l{QXmlQuery::isValid()} is + called to ensure that the XQuery was correctly parsed. + + \target evaluate() function + \snippet examples/xmlpatterns/recipes/querymainwindow.cpp 2 + + If the XQuery is valid, an instance of QXmlFormatter is created to + format the query result as XML into a QBuffer. To evaluate the + XQuery, an overload of \l{QXmlQuery::evaluateTo()} {evaluateTo()} is + called that takes a QAbstractXmlReceiver for its output + (QXmlFormatter inherits QAbstractXmlReceiver). Finally, the + formatted XML result is displayed in the UI's bottom text view. + + \note Each XQuery \c{.xq} file must declare the \c{$inputDocument} + variable to represent the \c cookbook.xml document: + + \code + (: All ingredients for Mushroom Soup. :) + declare variable $inputDocument external; + + doc($inputDocument)/cookbook/recipe[@xml:id = "MushroomSoup"]/ingredient/ +
{@name, @quantity}
+ \endcode + + \note If you add add your own query.xq files, you must declare the + \c{$inputDocument} and use it as shown above. + +*/ diff --git a/doc/src/examples/regexp.qdoc b/doc/src/examples/regexp.qdoc new file mode 100644 index 0000000..de6cbfc --- /dev/null +++ b/doc/src/examples/regexp.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/regexp + \title Regular Expressions Example + + The Regular Expressions (RegExp) example shows how regular expressions in Qt are + applied to text by providing an environment in which new regular expressions can be + created and tested on custom text strings. + + \image regexp-example.png +*/ diff --git a/doc/src/examples/relationaltablemodel.qdoc b/doc/src/examples/relationaltablemodel.qdoc new file mode 100644 index 0000000..5e944c2 --- /dev/null +++ b/doc/src/examples/relationaltablemodel.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/relationaltablemodel + \title Relational Table Model Example + + The Relational Table Model example shows how to use table views with a relational + model to visualize the relations between items in a database. + + \image relationaltablemodel-example.png +*/ diff --git a/doc/src/examples/remotecontrol.qdoc b/doc/src/examples/remotecontrol.qdoc new file mode 100644 index 0000000..698ad1f --- /dev/null +++ b/doc/src/examples/remotecontrol.qdoc @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example help/remotecontrol + \title Remote Control Example + + This example shows how to use and control Qt Assistant + as a help viewer. +*/ \ No newline at end of file diff --git a/doc/src/examples/rsslisting.qdoc b/doc/src/examples/rsslisting.qdoc new file mode 100644 index 0000000..73ff68c --- /dev/null +++ b/doc/src/examples/rsslisting.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/rsslisting + \title RSS-Listing Example + + This example shows how to create a widget that displays news items + from RDF news sources. + + \image rsslistingexample.png +*/ diff --git a/doc/src/examples/samplebuffers.qdoc b/doc/src/examples/samplebuffers.qdoc new file mode 100644 index 0000000..1c8202c --- /dev/null +++ b/doc/src/examples/samplebuffers.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/samplebuffers + \title Sample Buffers Example + + The Sample Buffers example demonstrates how to use and enable + sample buffers in a QGLWidget. + + \image samplebuffers-example.png +*/ diff --git a/doc/src/examples/saxbookmarks.qdoc b/doc/src/examples/saxbookmarks.qdoc new file mode 100644 index 0000000..3db87d6 --- /dev/null +++ b/doc/src/examples/saxbookmarks.qdoc @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/saxbookmarks + \title SAX Bookmarks Example + + The SAX Bookmarks example provides a reader for XML Bookmark Exchange Language (XBEL) + files that uses Qt's SAX-based API to read and parse the files. The DOM Bookmarks + example provides an alternative way to read this type of file. + + \image saxbookmarks-example.png + + See the \l{XML Bookmark Exchange Language Resource Page} for more + information about XBEL files. +*/ diff --git a/doc/src/examples/screenshot.qdoc b/doc/src/examples/screenshot.qdoc new file mode 100644 index 0000000..b989a32 --- /dev/null +++ b/doc/src/examples/screenshot.qdoc @@ -0,0 +1,262 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example desktop/screenshot + \title Screenshot Example + + The Screenshot example shows how to take a screenshot of the + desktop using QApplication and QDesktopWidget. It also shows how + to use QTimer to provide a single-shot timer, and how to + reimplement the QWidget::resizeEvent() event handler to make sure + that an application resizes smoothly and without data loss. + + \image screenshot-example.png + + With the application the users can take a screenshot of their + desktop. They are provided with a couple of options: + + \list + \o Delaying the screenshot, giving them time to rearrange + their desktop. + \o Hiding the application's window while the screenshot is taken. + \endlist + + In addition the application allows the users to save their + screenshot if they want to. + + \section1 Screenshot Class Definition + + \snippet examples/desktop/screenshot/screenshot.h 0 + + The \c Screenshot class inherits QWidget and is the application's + main widget. It displays the application options and a preview of + the screenshot. + + We reimplement the QWidget::resizeEvent() function to make sure + that the preview of the screenshot scales properly when the user + resizes the application widget. We also need several private slots + to facilitate the options: + + \list + \o The \c newScreenshot() slot prepares a new screenshot. + \o The \c saveScreenshot() slot saves the last screenshot. + \o The \c shootScreen() slot takes the screenshot. + \o The \c updateCheckBox() slot enables or disables the + \gui {Hide This Window} option. + \endlist + + We also declare some private functions: We use the \c + createOptionsGroupBox(), \c createButtonsLayout() and \c + createButton() functions when we construct the widget. And we call + the private \c updateScreenshotLabel() function whenever a new + screenshot is taken or when a resize event changes the size of the + screenshot preview label. + + In addition we need to store the screenshot's original pixmap. The + reason is that when we display the preview of the screenshot, we + need to scale its pixmap, storing the original we make sure that + no data are lost in that process. + + \section1 Screenshot Class Implementation + + \snippet examples/desktop/screenshot/screenshot.cpp 0 + + In the constructor we first create the QLabel displaying the + screenshot preview. + + We set the QLabel's size policy to be QSizePolicy::Expanding both + horizontally and vertically. This means that the QLabel's size + hint is a sensible size, but the widget can be shrunk and still be + useful. Also, the widget can make use of extra space, so it should + get as much space as possible. Then we make sure the QLabel is + aligned in the center of the \c Screenshot widget, and set its + minimum size. + + We create the applications's buttons and the group box containing + the application's options, and put it all into a main + layout. Finally we take the initial screenshot, and set the inital + delay and the window title, before we resize the widget to a + suitable size. + + \snippet examples/desktop/screenshot/screenshot.cpp 1 + + The \c resizeEvent() function is reimplemented to receive the + resize events dispatched to the widget. The purpose is to scale + the preview screenshot pixmap without deformation of its content, + and also make sure that the application can be resized smoothly. + + To achieve the first goal, we scale the screenshot pixmap using + Qt::KeepAspectRatio. We scale the pixmap to a rectangle as large + as possible inside the current size of the screenshot preview + label, preserving the aspect ratio. This means that if the user + resizes the application window in only one direction, the preview + screenshot keeps the same size. + + To reach our second goal, we make sure that the preview screenshot + only is repainted (using the private \c updateScreenshotLabel() + function) when it actually changes its size. + + \snippet examples/desktop/screenshot/screenshot.cpp 2 + + The private \c newScreenshot() slot is called when the user + requests a new screenshot; but the slot only prepares a new + screenshot. + + First we see if the \gui {Hide This Window} option is checked, if + it is we hide the \c Screenshot widget. Then we disable the \gui + {New Screenshot} button, to make sure the user only can request + one screenshot at a time. + + We create a timer using the QTimer class which provides repetitive + and single-shot timers. We set the timer to time out only once, + using the static QTimer::singleShot() function. This function + calls the private \c shootScreen() slot after the time interval + specified by the \gui {Screenshot Delay} option. It is \c + shootScreen() that actually performs the screenshot. + + \snippet examples/desktop/screenshot/screenshot.cpp 3 + + The \c saveScreenshot() slot is called when the user push the \gui + Save button, and it presents a file dialog using the QFileDialog + class. + + QFileDialog enables a user to traverse the file system in order to + select one or many files or a directory. The easiest way to create + a QFileDialog is to use the convenience static + functions. + + We define the default file format to be png, and we make the file + dialog's initial path the path the application is run from. We + create the file dialog using the static + QFileDialog::getSaveFileName() function which returns a file name + selected by the user. The file does not have to exist. If the file + name is valid, we use the QPixmap::save() function to save the + screenshot's original pixmap in that file. + + \snippet examples/desktop/screenshot/screenshot.cpp 4 + + The \c shootScreen() slot is called to take the screenshot. If the + user has chosen to delay the screenshot, we make the application + beep when the screenshot is taken using the static + QApplication::beep() function. + + The QApplication class manages the GUI application's control flow + and main settings. It contains the main event loop, where all + events from the window system and other sources are processed and + dispatched. + + \snippet examples/desktop/screenshot/screenshot.cpp 5 + + We take the screenshot using the static QPixmap::grabWindow() + function. The function grabs the contents of the window passed as + an argument, makes a pixmap out of it and returns that pixmap. + + We identify the argument window using the QWidget::winID() + function which returns the window system identifier. Here it + returns the identifier of the current QDesktopWidget retrieved by + the QApplication::desktop() function. The QDesktopWidget class + provides access to screen information, and inherits + QWidget::winID(). + + We update the screenshot preview label using the private \c + updateScreenshotLabel() function. Then we enable the \gui {New + Screenshot} button, and finally we make the \c Screenshot widget + visible if it was hidden during the screenshot. + + \snippet examples/desktop/screenshot/screenshot.cpp 6 + + The \gui {Hide This Window} option is enabled or disabled + depending on the delay of the screenshot. If there is no delay, + the application window cannot be hidden and the option's checkbox + is disabled. + + The \c updateCheckBox() slot is called whenever the user changes + the delay using the \gui {Screenshot Delay} option. + + \snippet examples/desktop/screenshot/screenshot.cpp 7 + + The private \c createOptionsGroupBox() function is called from the + constructor. + + First we create a group box that will contain all of the options' + widgets. Then we create a QSpinBox and a QLabel for the \gui + {Screenshot Delay} option, and connect the spinbox to the \c + updateCheckBox() slot. Finally, we create a QCheckBox for the \gui + {Hide This Window} option, add all the options' widgets to a + QGridLayout and install the layout on the group box. + + Note that we don't have to specify any parents for the widgets + when we create them. The reason is that when we add a widget to a + layout and install the layout on another widget, the layout's + widgets are automatically reparented to the widget the layout is + installed on. + + \snippet examples/desktop/screenshot/screenshot.cpp 8 + + The private \c createButtonsLayout() function is called from the + constructor. We create the application's buttons using the private + \c createButton() function, and add them to a QHBoxLayout. + + \snippet examples/desktop/screenshot/screenshot.cpp 9 + + The private \c createButton() function is called from the \c + createButtonsLayout() function. It simply creates a QPushButton + with the provided text, connects it to the provided receiver and + slot, and returns a pointer to the button. + + \snippet examples/desktop/screenshot/screenshot.cpp 10 + + The private \c updateScreenshotLabel() function is called whenever + the screenshot changes, or when a resize event changes the size of + the screenshot preview label. It updates the screenshot preview's + label using the QLabel::setPixmap() and QPixmap::scaled() + functions. + + QPixmap::scaled() returns a copy of the given pixmap scaled to a + rectangle of the given size according to the given + Qt::AspectRatioMode and Qt::TransformationMode. + + We scale the original pixmap to fit the current screenshot label's + size, preserving the aspect ratio and giving the resulting pixmap + smoothed edges. +*/ + diff --git a/doc/src/examples/scribble.qdoc b/doc/src/examples/scribble.qdoc new file mode 100644 index 0000000..4dc1783 --- /dev/null +++ b/doc/src/examples/scribble.qdoc @@ -0,0 +1,432 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/scribble + \title Scribble Example + + The Scribble example shows how to reimplement some of QWidget's + event handlers to receive the events generated for the + application's widgets. + + We reimplement the mouse event handlers to implement drawing, the + paint event handler to update the application and the resize event + handler to optimize the application's appearance. In addition we + reimplement the close event handler to intercept the close events + before terminating the application. + + The example also demonstrates how to use QPainter to draw an image + in real time, as well as to repaint widgets. + + \image scribble-example.png Screenshot of the Scribble example + + With the Scribble application the users can draw an image. The + \gui File menu gives the users the possibility to open and edit an + existing image file, save an image and exit the application. While + drawing, the \gui Options menu allows the users to to choose the + pen color and pen width, as well as clear the screen. In addition + the \gui Help menu provides the users with information about the + Scribble example in particular, and about Qt in general. + + The example consists of two classes: + + \list + \o \c ScribbleArea is a custom widget that displays a QImage and + allows to the user to draw on it. + \o \c MainWindow provides a menu above the \c ScribbleArea. + \endlist + + We will start by reviewing the \c ScribbleArea class, which + contains the interesting, then we will take a look at the \c + MainWindow class that uses it. + + \section1 ScribbleArea Class Definition + + \snippet examples/widgets/scribble/scribblearea.h 0 + + The \c ScribbleArea class inherits from QWidget. We reimplement + the \c mousePressEvent(), \c mouseMoveEvent() and \c + mouseReleaseEvent() functions to implement the drawing. We + reimplement the \c paintEvent() function to update the scribble + area, and the \c resizeEvent() function to ensure that the QImage + on which we draw is at least as large as the widget at any time. + + We need several public functions: \c openImage() loads an image + from a file into the scribble area, allowing the user to edit the + image; \c save() writes the currently displayed image to file; \c + clearImage() slot clears the image displayed in the scribble + area. We need the private \c drawLineTo() function to actually do + the drawing, and \c resizeImage() to change the size of a + QImage. The \c print() slot handles printing. + + We also need the following private variables: + + \list + \o \c modified is \c true if there are unsaved + changes to the image displayed in the scribble area. + \o \c scribbling is \c true while the user is pressing + the left mouse button within the scribble area. + \o \c penWidth and \c penColor hold the currently + set width and color for the pen used in the application. + \o \c image stores the image drawn by the user. + \o \c lastPoint holds the position of the cursor at the last + mouse press or mouse move event. + \endlist + + \section1 ScribbleArea Class Implementation + + \snippet examples/widgets/scribble/scribblearea.cpp 0 + + In the constructor, we set the Qt::WA_StaticContents + attribute for the widget, indicating that the widget contents are + rooted to the top-left corner and don't change when the widget is + resized. Qt uses this attribute to optimize paint events on + resizes. This is purely an optimization and should only be used + for widgets whose contents are static and rooted to the top-left + corner. + + \snippet examples/widgets/scribble/scribblearea.cpp 1 + \snippet examples/widgets/scribble/scribblearea.cpp 2 + + In the \c openImage() function, we load the given image. Then we + resize the loaded QImage to be at least as large as the widget in + both directions using the private \c resizeImage() function and + we set the \c image member variable to be the loaded image. At + the end, we call QWidget::update() to schedule a repaint. + + \snippet examples/widgets/scribble/scribblearea.cpp 3 + \snippet examples/widgets/scribble/scribblearea.cpp 4 + + The \c saveImage() function creates a QImage object that covers + only the visible section of the actual \c image and saves it using + QImage::save(). If the image is successfully saved, we set the + scribble area's \c modified variable to \c false, because there is + no unsaved data. + + \snippet examples/widgets/scribble/scribblearea.cpp 5 + \snippet examples/widgets/scribble/scribblearea.cpp 6 + \codeline + \snippet examples/widgets/scribble/scribblearea.cpp 7 + \snippet examples/widgets/scribble/scribblearea.cpp 8 + + The \c setPenColor() and \c setPenWidth() functions set the + current pen color and width. These values will be used for future + drawing operations. + + \snippet examples/widgets/scribble/scribblearea.cpp 9 + \snippet examples/widgets/scribble/scribblearea.cpp 10 + + The public \c clearImage() slot clears the image displayed in the + scribble area. We simply fill the entire image with white, which + corresponds to RGB value (255, 255, 255). As usual when we modify + the image, we set \c modified to \c true and schedule a repaint. + + \snippet examples/widgets/scribble/scribblearea.cpp 11 + \snippet examples/widgets/scribble/scribblearea.cpp 12 + + For mouse press and mouse release events, we use the + QMouseEvent::button() function to find out which button caused + the event. For mose move events, we use QMouseEvent::buttons() + to find which buttons are currently held down (as an OR-combination). + + If the users press the left mouse button, we store the position + of the mouse cursor in \c lastPoint. We also make a note that the + user is currently scribbling. (The \c scribbling variable is + necessary because we can't assume that a mouse move and mouse + release event is always preceded by a mouse press event on the + same widget.) + + If the user moves the mouse with the left button pressed down or + releases the button, we call the private \c drawLineTo() function + to draw. + + \snippet examples/widgets/scribble/scribblearea.cpp 13 + \snippet examples/widgets/scribble/scribblearea.cpp 14 + + In the reimplementation of the \l + {QWidget::paintEvent()}{paintEvent()} function, we simply create + a QPainter for the scribble area, and draw the image. + + At this point, you might wonder why we don't just draw directly + onto the widget instead of drawing in a QImage and copying the + QImage onto screen in \c paintEvent(). There are at least three + good reasons for this: + + \list + \o The window system requires us to be able to redraw the widget + \e{at any time}. For example, if the window is minimized and + restored, the window system might have forgotten the contents + of the widget and send us a paint event. In other words, we + can't rely on the window system to remember our image. + + \o Qt normally doesn't allow us to paint outside of \c + paintEvent(). In particular, we can't paint from the mouse + event handlers. (This behavior can be changed using the + Qt::WA_PaintOnScreen widget attribute, though.) + + \o If initialized properly, a QImage is guaranteed to use 8-bit + for each color channel (red, green, blue, and alpha), whereas + a QWidget might have a lower color depth, depending on the + monitor configuration. This means that if we load a 24-bit or + 32-bit image and paint it onto a QWidget, then copy the + QWidget into a QImage again, we might lose some information. + \endlist + + \snippet examples/widgets/scribble/scribblearea.cpp 15 + \snippet examples/widgets/scribble/scribblearea.cpp 16 + + When the user starts the Scribble application, a resize event is + generated and an image is created and displayed in the scribble + area. We make this initial image slightly larger than the + application's main window and scribble area, to avoid always + resizing the image when the user resizes the main window (which + would be very inefficient). But when the main window becomes + larger than this initial size, the image needs to be resized. + + \snippet examples/widgets/scribble/scribblearea.cpp 17 + \snippet examples/widgets/scribble/scribblearea.cpp 18 + + In \c drawLineTo(), we draw a line from the point where the mouse + was located when the last mouse press or mouse move occurred, we + set \c modified to true, we generate a repaint event, and we + update \c lastPoint so that next time \c drawLineTo() is called, + we continue drawing from where we left. + + We could call the \c update() function with no parameter, but as + an easy optimization we pass a QRect that specifies the rectangle + inside the scribble are needs updating, to avoid a complete + repaint of the widget. + + \snippet examples/widgets/scribble/scribblearea.cpp 19 + \snippet examples/widgets/scribble/scribblearea.cpp 20 + + QImage has no nice API for resizing an image. There's a + QImage::copy() function that could do the trick, but when used to + expand an image, it fills the new areas with black, whereas we + want white. + + So the trick is to create a brand new QImage with the right size, + to fill it with white, and to draw the old image onto it using + QPainter. The new image is given the QImage::Format_RGB32 + format, which means that each pixel is stored as 0xffRRGGBB + (where RR, GG, and BB are the red, green and blue + color channels, ff is the hexadecimal value 255). + + Printing is handled by the \c print() slot: + + \snippet examples/widgets/scribble/scribblearea.cpp 21 + + We construct a high resolution QPrinter object for the required + output format, using a QPrintDialog to ask the user to specify a + page size and indicate how the output should be formatted on the page. + + If the dialog is accepted, we perform the task of printing to the paint + device: + + \snippet examples/widgets/scribble/scribblearea.cpp 22 + + Printing an image to a file in this way is simply a matter of + painting onto the QPrinter. We scale the image to fit within the + available space on the page before painting it onto the paint + device. + + \section1 MainWindow Class Definition + + \snippet examples/widgets/scribble/mainwindow.h 0 + + The \c MainWindow class inherits from QMainWindow. We reimplement + the \l{QWidget::closeEvent()}{closeEvent()} handler from QWidget. + The \c open(), \c save(), \c penColor() and \c penWidth() + slots correspond to menu entries. In addition we create four + private functions. + + We use the boolean \c maybeSave() function to check if there are + any unsaved changes. If there are unsaved changes, we give the + user the opportunity to save these changes. The function returns + \c false if the user clicks \gui Cancel. We use the \c saveFile() + function to let the user save the image currently displayed in + the scribble area. + + \section1 MainWindow Class Implementation + + \snippet examples/widgets/scribble/mainwindow.cpp 0 + + In the constructor, we create a scribble area which we make the + central widget of the \c MainWindow widget. Then we create the + associated actions and menus. + + \snippet examples/widgets/scribble/mainwindow.cpp 1 + \snippet examples/widgets/scribble/mainwindow.cpp 2 + + Close events are sent to widgets that the users want to close, + usually by clicking \gui{File|Exit} or by clicking the \gui X + title bar button. By reimplementing the event handler, we can + intercept attempts to close the application. + + In this example, we use the close event to ask the user to save + any unsaved changes. The logic for that is located in the \c + maybeSave() function. If \c maybeSave() returns true, there are + no modifications or the users successfully saved them, and we + accept the event. The application can then terminate normally. If + \c maybeSave() returns false, the user clicked \gui Cancel, so we + "ignore" the event, leaving the application unaffected by it. + + \snippet examples/widgets/scribble/mainwindow.cpp 3 + \snippet examples/widgets/scribble/mainwindow.cpp 4 + + In the \c open() slot we first give the user the opportunity to + save any modifications to the currently displayed image, before a + new image is loaded into the scribble area. Then we ask the user + to choose a file and we load the file in the \c ScribbleArea. + + \snippet examples/widgets/scribble/mainwindow.cpp 5 + \snippet examples/widgets/scribble/mainwindow.cpp 6 + + The \c save() slot is called when the users choose the \gui {Save + As} menu entry, and then choose an entry from the format menu. The + first thing we need to do is to find out which action sent the + signal using QObject::sender(). This function returns the sender + as a QObject pointer. Since we know that the sender is an action + object, we can safely cast the QObject. We could have used a + C-style cast or a C++ \c static_cast<>(), but as a defensive + programming technique we use a qobject_cast(). The advantage is + that if the object has the wrong type, a null pointer is + returned. Crashes due to null pointers are much easier to diagnose + than crashes due to unsafe casts. + + Once we have the action, we extract the chosen format using + QAction::data(). (When the actions are created, we use + QAction::setData() to set our own custom data attached to the + action, as a QVariant. More on this when we review \c + createActions().) + + Now that we know the format, we call the private \c saveFile() + function to save the currently displayed image. + + \snippet examples/widgets/scribble/mainwindow.cpp 7 + \snippet examples/widgets/scribble/mainwindow.cpp 8 + + We use the \c penColor() slot to retrieve a new color from the + user with a QColorDialog. If the user chooses a new color, we + make it the scribble area's color. + + \snippet examples/widgets/scribble/mainwindow.cpp 9 + \snippet examples/widgets/scribble/mainwindow.cpp 10 + + To retrieve a new pen width in the \c penWidth() slot, we use + QInputDialog. The QInputDialog class provides a simple + convenience dialog to get a single value from the user. We use + the static QInputDialog::getInteger() function, which combines a + QLabel and a QSpinBox. The QSpinBox is initialized with the + scribble area's pen width, allows a range from 1 to 50, a step of + 1 (meaning that the up and down arrow increment or decrement the + value by 1). + + The boolean \c ok variable will be set to \c true if the user + clicked \gui OK and to \c false if the user pressed \gui Cancel. + + \snippet examples/widgets/scribble/mainwindow.cpp 11 + \snippet examples/widgets/scribble/mainwindow.cpp 12 + + We implement the \c about() slot to create a message box + describing what the example is designed to show. + + \snippet examples/widgets/scribble/mainwindow.cpp 13 + \snippet examples/widgets/scribble/mainwindow.cpp 14 + + In the \c createAction() function we create the actions + representing the menu entries and connect them to the appropiate + slots. In particular we create the actions found in the \gui + {Save As} sub-menu. We use QImageWriter::supportedImageFormats() + to get a list of the supported formats (as a QList). + + Then we iterate through the list, creating an action for each + format. We call QAction::setData() with the file format, so we + can retrieve it later as QAction::data(). We could also have + deduced the file format from the action's text, by truncating the + "...", but that would have been inelegant. + + \snippet examples/widgets/scribble/mainwindow.cpp 15 + \snippet examples/widgets/scribble/mainwindow.cpp 16 + + In the \c createMenu() function, we add the previously created + format actions to the \c saveAsMenu. Then we add the rest of the + actions as well as the \c saveAsMenu sub-menu to the \gui File, + \gui Options and \gui Help menus. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus. The QMenuBar class provides + a horizontal menu bar with a list of pull-down \l{QMenu}s. At the + end we put the \gui File and \gui Options menus in the \c + {MainWindow}'s menu bar, which we retrieve using the + QMainWindow::menuBar() function. + + \snippet examples/widgets/scribble/mainwindow.cpp 17 + \snippet examples/widgets/scribble/mainwindow.cpp 18 + + In \c mayBeSave(), we check if there are any unsaved changes. If + there are any, we use QMessageBox to give the user a warning that + the image has been modified and the opportunity to save the + modifications. + + As with QColorDialog and QFileDialog, the easiest way to create a + QMessageBox is to use its static functions. QMessageBox provides + a range of different messages arranged along two axes: severity + (question, information, warning and critical) and complexity (the + number of necessary response buttons). Here we use the \c + warning() function sice the message is rather important. + + If the user chooses to save, we call the private \c saveFile() + function. For simplicitly, we use PNG as the file format; the + user can always press \gui Cancel and save the file using another + format. + + The \c maybeSave() function returns \c false if the user clicks + \gui Cancel; otherwise it returns \c true. + + \snippet examples/widgets/scribble/mainwindow.cpp 19 + \snippet examples/widgets/scribble/mainwindow.cpp 20 + + In \c saveFile(), we pop up a file dialog with a file name + suggestion. The static QFileDialog::getSaveFileName() function + returns a file name selected by the user. The file does not have + to exist. +*/ diff --git a/doc/src/examples/sdi.qdoc b/doc/src/examples/sdi.qdoc new file mode 100644 index 0000000..cfe351c --- /dev/null +++ b/doc/src/examples/sdi.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example mainwindows/sdi + \title SDI Example + + The SDI example shows how to create a Single Document Interface. It uses a number of + top-level windows to display the contents of different text files. + + \image sdi-example.png +*/ diff --git a/doc/src/examples/securesocketclient.qdoc b/doc/src/examples/securesocketclient.qdoc new file mode 100644 index 0000000..e93bf20 --- /dev/null +++ b/doc/src/examples/securesocketclient.qdoc @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/securesocketclient + \title Secure Socket Client Example + + The Secure Socket Client example shows how to use QSslSocket to + communicate over an encrypted (SSL) connection. It also demonstrates how + to deal with authenticity problems, and how to display security and + certificate information. + + \image securesocketclient.png + \image securesocketclient2.png +*/ diff --git a/doc/src/examples/semaphores.qdoc b/doc/src/examples/semaphores.qdoc new file mode 100644 index 0000000..a387350 --- /dev/null +++ b/doc/src/examples/semaphores.qdoc @@ -0,0 +1,159 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example threads/semaphores + \title Semaphores Example + + The Semaphores example shows how to use QSemaphore to control + access to a circular buffer shared by a producer thread and a + consumer thread. + + The producer writes data to the buffer until it reaches the end + of the buffer, at which point it restarts from the beginning, + overwriting existing data. The consumer thread reads the data as + it is produced and writes it to standard error. + + Semaphores make it possible to have a higher level of concurrency + than mutexes. If accesses to the buffer were guarded by a QMutex, + the consumer thread couldn't access the buffer at the same time + as the producer thread. Yet, there is no harm in having both + threads working on \e{different parts} of the buffer at the same + time. + + The example comprises two classes: \c Producer and \c Consumer. + Both inherit from QThread. The circular buffer used for + communicating between these two classes and the semaphores that + protect it are global variables. + + An alternative to using QSemaphore to solve the producer-consumer + problem is to use QWaitCondition and QMutex. This is what the + \l{threads/waitconditions}{Wait Conditions} example does. + + \section1 Global Variables + + Let's start by reviewing the circular buffer and the associated + semaphores: + + \snippet examples/threads/semaphores/semaphores.cpp 0 + + \c DataSize is the amout of data that the producer will generate. + To keep the example as simple as possible, we make it a constant. + \c BufferSize is the size of the circular buffer. It is less than + \c DataSize, meaning that at some point the producer will reach + the end of the buffer and restart from the beginning. + + To synchronize the producer and the consumer, we need two + semaphores. The \c freeBytes semaphore controls the "free" area + of the buffer (the area that the producer hasn't filled with data + yet or that the consumer has already read). The \c usedBytes + semaphore controls the "used" area of the buffer (the area that + the producer has filled but that the consumer hasn't read yet). + + Together, the semaphores ensure that the producer is never more + than \c BufferSize bytes ahead of the consumer, and that the + consumer never reads data that the producer hasn't generated yet. + + The \c freeBytes semaphore is initialized with \c BufferSize, + because initially the entire buffer is empty. The \c usedBytes + semaphore is initialized to 0 (the default value if none is + specified). + + \section1 Producer Class + + Let's review the code for the \c Producer class: + + \snippet examples/threads/semaphores/semaphores.cpp 1 + \snippet examples/threads/semaphores/semaphores.cpp 2 + + The producer generates \c DataSize bytes of data. Before it + writes a byte to the circular buffer, it must acquire a "free" + byte using the \c freeBytes semaphore. The QSemaphore::acquire() + call might block if the consumer hasn't kept up the pace with the + producer. + + At the end, the producer releases a byte using the \c usedBytes + semaphore. The "free" byte has successfully been transformed into + a "used" byte, ready to be read by the consumer. + + \section1 Consumer Class + + Let's now turn to the \c Consumer class: + + \snippet examples/threads/semaphores/semaphores.cpp 3 + \snippet examples/threads/semaphores/semaphores.cpp 4 + + The code is very similar to the producer, except that this time + we acquire a "used" byte and release a "free" byte, instead of + the opposite. + + \section1 The main() Function + + In \c main(), we create the two threads and call QThread::wait() + to ensure that both threads get time to finish before we exit: + + \snippet examples/threads/semaphores/semaphores.cpp 5 + \snippet examples/threads/semaphores/semaphores.cpp 6 + + So what happens when we run the program? Initially, the producer + thread is the only one that can do anything; the consumer is + blocked waiting for the \c usedBytes semaphore to be released (its + initial \l{QSemaphore::available()}{available()} count is 0). + Once the producer has put one byte in the buffer, + \c{freeBytes.available()} is \c BufferSize - 1 and + \c{usedBytes.available()} is 1. At that point, two things can + happen: Either the consumer thread takes over and reads that + byte, or the consumer gets to produce a second byte. + + The producer-consumer model presented in this example makes it + possible to write highly concurrent multithreaded applications. + On a multiprocessor machine, the program is potentially up to + twice as fast as the equivalent mutex-based program, since the + two threads can be active at the same time on different parts of + the buffer. + + Be aware though that these benefits aren't always realized. + Acquiring and releasing a QSemaphore has a cost. In practice, it + would probably be worthwhile to divide the buffer into chunks and + to operate on chunks instead of individual bytes. The buffer size + is also a parameter that must be selected carefully, based on + experimentation. +*/ diff --git a/doc/src/examples/settingseditor.qdoc b/doc/src/examples/settingseditor.qdoc new file mode 100644 index 0000000..5ce1e49 --- /dev/null +++ b/doc/src/examples/settingseditor.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/settingseditor + \title Settings Editor Example + + The Settings Editor example shows how Qt's standard settings support is used in an + application by providing an editor that enables the user to view the settings for + installed applications, and modify those that can be edited. + + \image settingseditor-example.png +*/ diff --git a/doc/src/examples/shapedclock.qdoc b/doc/src/examples/shapedclock.qdoc new file mode 100644 index 0000000..369553b --- /dev/null +++ b/doc/src/examples/shapedclock.qdoc @@ -0,0 +1,145 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/shapedclock + \title Shaped Clock Example + + The Shaped Clock example shows how to apply a widget mask to a top-level + widget to produce a shaped window. + + \image shapedclock-example.png + + Widget masks are used to customize the shapes of top-level widgets by restricting + the available area for painting. On some window systems, setting certain window flags + will cause the window decoration (title bar, window frame, buttons) to be disabled, + allowing specially-shaped windows to be created. In this example, we use this feature + to create a circular window containing an analog clock. + + Since this example's window does not provide a \gui File menu or a close + button, we provide a context menu with an \gui Exit entry so that the example + can be closed. Click the right mouse button over the window to open this menu. + + \section1 ShapedClock Class Definition + + The \c ShapedClock class is based on the \c AnalogClock class defined in the + \l{Analog Clock Example}{Analog Clock} example. The whole class definition is + presented below: + + \snippet examples/widgets/shapedclock/shapedclock.h 0 + + The \l{QWidget::paintEvent()}{paintEvent()} implementation is the same as that found + in the \c AnalogClock class. We implement \l{QWidget::sizeHint()}{sizeHint()} + so that we don't have to resize the widget explicitly. We also provide an event + handler for resize events. This allows us to update the mask if the clock is resized. + + Since the window containing the clock widget will have no title bar, we provide + implementations for \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} and + \l{QWidget::mousePressEvent()}{mousePressEvent()} to allow the clock to be dragged + around the screen. The \c dragPosition variable lets us keep track of where the user + last clicked on the widget. + + \section1 ShapedClock Class Implementation + + The \c ShapedClock constructor performs many of the same tasks as the \c AnalogClock + constructor. We set up a timer and connect it to the widget's update() slot: + + \snippet examples/widgets/shapedclock/shapedclock.cpp 0 + + We inform the window manager that the widget is not to be decorated with a window + frame by setting the Qt::FramelessWindowHint flag on the widget. As a result, we need + to provide a way for the user to move the clock around the screen. + + Mouse button events are delivered to the \c mousePressEvent() handler: + + \snippet examples/widgets/shapedclock/shapedclock.cpp 1 + + If the left mouse button is pressed over the widget, we record the displacement in + global (screen) coordinates between the top-left position of the widget's frame (even + when hidden) and the point where the mouse click occurred. This displacement will be + used if the user moves the mouse while holding down the left button. Since we acted + on the event, we accept it by calling its \l{QEvent::accept()}{accept()} function. + + \image shapedclock-dragging.png + + The \c mouseMoveEvent() handler is called if the mouse is moved over the widget. + + \snippet examples/widgets/shapedclock/shapedclock.cpp 2 + + If the left button is held down while the mouse is moved, the top-left corner of the + widget is moved to the point given by subtracting the \c dragPosition from the current + cursor position in global coordinates. If we drag the widget, we also accept the event. + + The \c paintEvent() function is given for completeness. See the + \l{Analog Clock Example}{Analog Clock} example for a description of the process used + to render the clock. + + \snippet examples/widgets/shapedclock/shapedclock.cpp 3 + + In the \c resizeEvent() handler, we re-use some of the code from the \c paintEvent() + to determine the region of the widget that is visible to the user: + + \snippet examples/widgets/shapedclock/shapedclock.cpp 4 + + Since the clock face is a circle drawn in the center of the widget, this is the region + we use as the mask. + + Although the lack of a window frame may make it difficult for the user to resize the + widget on some platforms, it will not necessarily be impossible. The \c resizeEvent() + function ensures that the widget mask will always be updated if the widget's dimensions + change, and additionally ensures that it will be set up correctly when the widget is + first displayed. + + Finally, we implement the \c sizeHint() for the widget so that it is given a reasonable + default size when it is first shown: + + \snippet examples/widgets/shapedclock/shapedclock.cpp 5 + + \section1 Notes on Widget Masks + + Since QRegion allows arbitrarily complex regions to be created, widget masks can be + made to suit the most unconventionally-shaped windows, and even allow widgets to be + displayed with holes in them. + + Widget masks can also be constructed by using the contents of pixmap to define the + opaque part of the widget. For a pixmap with an alpha channel, a suitable mask can be + obtained with QPixmap::mask(). +*/ diff --git a/doc/src/examples/sharedmemory.qdoc b/doc/src/examples/sharedmemory.qdoc new file mode 100644 index 0000000..f323977 --- /dev/null +++ b/doc/src/examples/sharedmemory.qdoc @@ -0,0 +1,142 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example ipc/sharedmemory + \title Shared Memory Example + + The Shared Memory example shows how to use the QSharedMemory class + to implement inter-process communication using shared memory. To + build the example, run make. To run the example, start two instances + of the executable. The main() function creates an \l {QApplication} + {application} and an instance of our example's Dialog class. The + dialog is displayed and then control is passed to the application in + the standard way. + + \snippet examples/ipc/sharedmemory/main.cpp 0 + + Two instances of class Dialog appear. + + \image sharedmemory-example_1.png Screenshot of the Shared Memory example + + Class Dialog inherits QDialog. It encapsulates the user interface + and an instance of QSharedMemory. It also has two public slots, + loadFromFile() and loadFromMemory() that correspond to the two + buttons on the dialog. + + \snippet examples/ipc/sharedmemory/dialog.h 0 + + The constructor builds the user interface widgets and connects the + clicked() signal of each button to the corresponding slot function. + + \snippet examples/ipc/sharedmemory/dialog.cpp 0 + + Note that "QSharedMemoryExample" is passed to the \l {QSharedMemory} + {QSharedMemory()} constructor to be used as the key. This will be + used by the system as the identifier of the underlying shared memory + segment. + + Click the \tt {Load Image From File...} button on one of the + dialogs. The loadFromFile() slot is invoked. First, it tests whether + a shared memory segment is already attached to the process. If so, + that segment is detached from the process, so we can be assured of + starting off the example correctly. + + \snippet examples/ipc/sharedmemory/dialog.cpp 1 + + The user is then asked to select an image file using + QFileDialog::getOpenFileName(). The selected file is loaded into a + QImage. Using a QImage lets us ensure that the selected file is a + valid image, and it also allows us to immediately display the image + in the dialog using setPixmap(). + + Next the image is streamed into a QBuffer using a QDataStream. This + gives us the size, which we then use to \l {QSharedMemory::} + {create()} our shared memory segment. Creating a shared memory + segment automatically \l {QSharedMemory::attach()} {attaches} the + segment to the process. Using a QBuffer here lets us get a pointer + to the image data, which we then use to do a memcopy() from the + QBuffer into the shared memory segment. + + \snippet examples/ipc/sharedmemory/dialog.cpp 2 + + Note that we \l {QSharedMemory::} {lock()} the shared memory segment + before we copy into it, and we \l {QSharedMemory::} {unlock()} it + again immediately after the copy. This ensures we have exclusive + access to the shared memory segment to do our memcopy(). If some + other process has the segment lock, then our process will block + until the lock becomes available. + + Note also that the function does not \l {QSharedMemory::} {detach()} + from the shared memory segment after the memcopy() and + unlock(). Recall that when the last process detaches from a shared + memory segment, the segment is released by the operating + system. Since this process only one that is attached to the shared + memory segment at the moment, if loadFromFile() detached from the + shared memory segment, the segment would be destroyed before we get + to the next step. + + When the function returns, if the file you selected was qt.png, your + first dialog looks like this. + + \image sharedmemory-example_2.png Screenshot of the Shared Memory example + + In the second dialog, click the \tt {Display Image From Shared + Memory} button. The loadFromMemory() slot is invoked. It first \l + {QSharedMemory::attach()} {attaches} the process to the same shared + memory segment created by the first process. Then it \l + {QSharedMemory::lock()} {locks} the segment for exclusive access and + links a QBuffer to the image data in the shared memory segment. It + then streams the data into a QImage and \l {QSharedMemory::unlock()} + {unlocks} the segment. + + \snippet examples/ipc/sharedmemory/dialog.cpp 3 + + In this case, the function does \l {QSharedMemory::} {detach()} from + the segment, because now we are effectively finished using + it. Finally, the QImage is displayed. At this point, both dialogs + should be showing the same image. When you close the first dialog, + the Dialog destructor calls the QSharedMemory destructor, which + detaches from the shared memory segment. Since this is the last + process to be detached from the segment, the operating system will + now release the shared memory. + + */ diff --git a/doc/src/examples/simpledecoration.qdoc b/doc/src/examples/simpledecoration.qdoc new file mode 100644 index 0000000..fe8700a --- /dev/null +++ b/doc/src/examples/simpledecoration.qdoc @@ -0,0 +1,266 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example qws/simpledecoration + \title Simple Decoration Example + \ingroup qt-embedded + + The Simple Decoration example shows how to create a custom window decoration + for embedded applications. + + \image embedded-simpledecoration-example.png + + By default, Qt for Embedded Linux applications display windows with one of + the standard window decorations provided by Qt which are perfectly suitable + for many situations. Nonetheless, for certain applications and devices, it + is necessary to provide custom window decorations. + + In this document, we examine the fundamental features of custom window + decorations, and create a simple decoration as an example. + + \section1 Styles and Window Decorations + + On many platforms, the style used for the contents of a window (including + scroll bars) and the style used for the window decorations (the title bar, + window borders, close, maximize and other buttons) are handled differently. + This is usually because each application is responsible for rendering the + contents of its own windows and the window manager renders the window + decorations. + + Although the situation is not quite like this on Qt for Embedded Linux + because QApplication automatically handles window decorations as well, + there are still two style mechanisms at work: QStyle and its associated + classes are responsible for rendering widgets and subclasses of QDecoration + are responsible for rendering window decorations. + + \image embedded-simpledecoration-example-styles.png + + Three decorations are provided with Qt for Embedded Linux: \e default is + a basic style, \e windows resembles the classic Windows look and feel, + and \e styled uses the QStyle classes for QMdiSubWindow to draw window + decorations. Of these, \e styled is the most useful if you want to impose + a consistent look and feel, but the window decorations may be too large + for some use cases. + + If none of these built-in decorations are suitable, a custom style can + easily be created and used. To do this, we simply need to create a + subclass of QDecorationDefault and apply it to a QApplication instance + in a running application. + + \section1 MyDecoration Class Definition + + The \c MyDecoration class is a subclass of QDecorationDefault, a subclass + of QDecoration that provides reasonable default behavior for a decoration: + + \snippet examples/qws/simpledecoration/mydecoration.h decoration class definition + + We only need to implement a constructor and reimplement the + \l{QDecorationDefault::}{region()} and \l{QDecorationDefault::}{paint()} + functions to provide our own custom appearance for window decorations. + + To make things fairly general, we provide a number of private variables + to hold parameters which control certain aspects of the decoration's + appearance. We also define some data structures that we will use to + relate buttons in the window decorations to regions. + + \section1 MyDecoration Class Implementation + + In the constructor of the \c MyDecoration class, we set up some default + values for the decoration, specifying a thin window border, a title + bar that is just taller than the buttons it will hold, and we create a + list of buttons that we support: + + \snippet examples/qws/simpledecoration/mydecoration.cpp constructor start + + We map each of these Qt::WindowFlags to QDecoration::DecorationRegion + enum values to help with the implementation of the + \l{#Finding Regions}{region() function implementation}. + + \snippet examples/qws/simpledecoration/mydecoration.cpp map window flags to decoration regions + + In this decoration, we implement the buttons used in the decoration as + pixmaps. To help us relate regions of the window to these, we define + mappings between each \l{QDecoration::}{DecorationRegion} and its + corresponding pixmap for two situations: when a window is shown normally + and when it has been maximized. This is purely for cosmetic purposes. + + \snippet examples/qws/simpledecoration/mydecoration.cpp map decoration regions to pixmaps + + We finish the constructor by defining the regions for buttons that we + understand. This will be useful when we are asked to give regions for + window decoration buttons. + + \snippet examples/qws/simpledecoration/mydecoration.cpp constructor end + + \section2 Finding Regions + + Each decoration needs to be able to describe the regions used for parts + of the window furniture, such as the close button, window borders and + title bar. We reimplement the \l{QDecorationDefault::}{region()} function + to do this for our decoration. This function returns a QRegion object + that describes an arbitrarily-shaped region of the screen that can itself + be made up of several distinct areas. + + \snippet examples/qws/simpledecoration/mydecoration.cpp region start + + The function is called for a given \e widget, occupying a region specified + by \e insideRect, and is expected to return a region for the collection of + \l{QDecoration::}{DecorationRegion} enum values supplied in the + \e decorationRegion parameter. + + We begin by figuring out how much space in the decoration we will need to + allocate for buttons, and where to place them: + + \snippet examples/qws/simpledecoration/mydecoration.cpp calculate the positions of buttons based on the window flags used + + In a more sophisticated implementation, we might test the \e decorationRegion + supplied for regions related to buttons and the title bar, and only perform + this space allocation if asked for regions related to these. + + We also use the information about the area occupied by buttons to determine + how large an area we can use for the window title: + + \snippet examples/qws/simpledecoration/mydecoration.cpp calculate the extent of the title + + With these basic calculations done, we can start to compose a region, first + checking whether we have been asked for all of the window, and we return + immediately if so. + + \snippet examples/qws/simpledecoration/mydecoration.cpp check for all regions + + We examine each decoration region in turn, adding the corresponding region + to the \c region object created earlier. We take care to avoid "off by one" + errors in the coordinate calculations. + + \snippet examples/qws/simpledecoration/mydecoration.cpp compose a region based on the decorations specified + + Unlike the window borders and title bar, the regions occupied by buttons + many of the window decorations do not occupy fixed places in the window. + Instead, their locations depend on which other buttons are present. + We only add regions for buttons we can handle (defined in the \c stateRegions) + member variable, and only for those that are present (defined in the + \c buttons hash). + + \snippet examples/qws/simpledecoration/mydecoration.cpp add a region for each button only if it is present + + The fully composed region can then be returned: + + \snippet examples/qws/simpledecoration/mydecoration.cpp region end + + The information returned by this function is used when the decoration is + painted. Ideally, this function should be implemented to perform all the + calculations necessary to place elements of the decoration; this makes + the implementation of the \c paint() function much easier. + + \section2 Painting the Decoration + + The \c paint() function is responsible for drawing each window element + for a given widget. Information about the decoration region, its state + and the widget itself is provided along with a QPainter object to use. + + The first check we make is for a call with no regions: + + \snippet examples/qws/simpledecoration/mydecoration.cpp paint start + + We return false to indicate that we have not painted anything. If we paint + something, we must return true so that the window can be composed, if + necessary. + + Just as with the \c region() function, we test the decoration region to + determine which elements need to be drawn. If we paint anything, we set + the \c handled variable to true so that we can return the correct value + when we have finished. + + \snippet examples/qws/simpledecoration/mydecoration.cpp paint different regions + + Note that we use our own \c region() implementation to determine where + to draw decorations. + + Since the \c region() function performs calculations to place buttons, we + can simply test the window flags against the buttons we support (using the + \c buttonHintMap defined in the constructor), and draw each button in the + relevant region: + + \snippet examples/qws/simpledecoration/mydecoration.cpp paint buttons + + Finally, we return the value of \c handled to indicate whether any painting + was performed: + + \snippet examples/qws/simpledecoration/mydecoration.cpp paint end + + We now have a decoration class that we can use in an application. + + \section1 Using the Decoration + + In the \c main.cpp file, we set up the application as usual, but we also + create an instance of our decoration and set it as the standard decoration + for the application: + + \snippet examples/qws/simpledecoration/main.cpp create application + + This causes all windows opened by this application to use our decoration. + To demonstrate this, we show the analog clock widget from the + \l{Analog Clock Example}, which we build into the application: + + \snippet examples/qws/simpledecoration/main.cpp start application + + The application can be run either + \l{Running Qt for Embedded Linux Applications}{as a server or a client + application}. In both cases, it will use our decoration rather than the + default one provided with Qt. + + \section1 Notes + + This example does not cache any information about the state or buttons + used for each window. This means that the \c region() function calculates + the locations and regions of buttons in cases where it could re-use + existing information. + + If you run the application as a window server, you may expect client + applications to use our decoration in preference to the default Qt + decoration. However, it is up to each application to draw its own + decoration, so this will not happen automatically. One way to achieve + this is to compile the decoration with each application that needs it; + another way is to build the decoration as a plugin, using the + QDecorationPlugin class, and load it into the server and client + applications. +*/ diff --git a/doc/src/examples/simpledommodel.qdoc b/doc/src/examples/simpledommodel.qdoc new file mode 100644 index 0000000..8d2d102 --- /dev/null +++ b/doc/src/examples/simpledommodel.qdoc @@ -0,0 +1,294 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/simpledommodel + \title Simple DOM Model Example + + The Simple DOM Model example shows how an existing class can be adapted for use with + the model/view framework. + + \image simpledommodel-example.png + + Qt provides two complementary sets of classes for reading XML files: The classes based + around QXmlReader provide a SAX-style API for incremental reading of large files, and + the classes based around QDomDocument enable developers to access the contents of XML + files using a Document Object Model (DOM) API. + + In this example, we create a model that uses the DOM API to expose the structure and + contents of XML documents to views via the standard QAbstractModel interface. + + \section1 Design and Concepts + + Reading an XML document with Qt's DOM classes is a straightforward process. Typically, + the contents of a file are supplied to QDomDocument, and nodes are accessed using the + functions provided by QDomNode and its subclasses. + + \omit + For example, the following code + snippet reads the contents of a file into a QDomDocument object and traverses the + document, reading all the plain text that can be found: + + \snippet doc/src/snippets/code/doc_src_examples_simpledommodel.qdoc 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/simpletextviewer.qdoc b/doc/src/examples/simpletextviewer.qdoc new file mode 100644 index 0000000..2a5e45c0 --- /dev/null +++ b/doc/src/examples/simpletextviewer.qdoc @@ -0,0 +1,466 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example help/simpletextviewer + \title Simple Text Viewer Example + + The Simple Text Viewer example shows how to use \QA as a customized + help viewer for your application. + + This is done in two stages. Firstly, documentation is created and \QA + is customized; secondly, the functionality to launch and control + \QA is added to the application. + + \image simpletextviewer-example.png + + The Simple Text Viewer application lets the user select and view + existing files. + + The application provides its own custom documentation that is + available from the \gui Help menu in the main window's menu bar + or by clicking the \gui Help button in the application's find file + dialog. + + The example consists of four classes: + + \list + \o \c Assistant provides functionality to launch \QA. + \o \c MainWindow is the main application window. + \o \c FindFileDialog allows the user to search for + files using wildcard matching. + \o \c TextEdit provides a rich text browser that makes + sure that images referenced in HTML documents are + displayed properly. + \endlist + + Note that we will only comment on the parts of the implementation + that are relevant to the main issue, that is making Qt Assistant + act as a customized help viewer for our Simple Text Viewer + application. + + \section1 Creating Documentation and Customizing \QA + + How to create the actual documentation in the form of HTML pages is + not in the scope of this example. In general, HTML pages can either + be written by hand or generated with the help of documentation tools + like qdoc or Doxygen. For the purposes of this example we assume that + the HTML files have already been created. So, the only thing that + remains to be done is to tell \QA how to structure and display the + help information. + + \section2 Organizing Documentation for \QA + + Plain HTML files only contain text or documentation about specific topics, + but they usually include no information about how several HTML documents + relate to each other or in which order they are supposed to be read. + What is missing is a table of contents along with an index to access + certain help contents quickly, without having to browse through a lot + of documents in order to find a piece of information. + + To organize the documentation and make it available for \QA, we have + to create a Qt help project (.qhp) file. The first and most important + part of the project file is the definition of the namespace. The namespace + has to be unique and will be the first part of the page URL in \QA. + In addition, we have to set a virtual folder which acts as a common + folder for documentation sets. This means, that two documentation sets + identified by two different namespaces can cross reference HTML files + since those files are in one big virtual folder. However, for this + example, we'll only have one documentation set available, so the + virtual folder name and functionality are not important. + + \code + + + com.trolltech.examples.simpletextviewer + doc + \endcode + + The next step is to define the filter section. A filter section + contains the table of contents, indices and a complete list of + all documentation files, and can have any number of filter attributes + assigned to it. A filter attribute is an ordinary string which can + be freely chosen. Later in \QA, users can then define a custom + filter referencing those attributes. If the attributes of a filter + section match the attributes of the custom filter the documentation + will be shown, otherwise \QA will hide the documentation. + + Again, since we'll only have one documentation set, we do not need + the filtering functionality of \QA and can therefore skip the + filter attributes. + + Now, we build up the table of contents. An item in the table is + defined by the \c section tag which contains the attributes for the + item title as well as link to the actual page. Section tags can be + nested infinitely, but for practical reasons it is not recommended + to nest them deeper than three or four levels. For our example we + want to use the following outline for the table of contents: + + \list + \o Simple Text Viewer + \list + \o Find File + \list + \o File Dialog + \o Wildcard Matching + \o Browse + \endlist + \o Open File + \endlist + \endlist + + In the help project file, the outline is represented by: + + \code + + +
+
+
+
+
+
+
+
+ + \endcode + + After the table of contents is defined, we will list all index keywords: + + \code + + + + + + + + + + + + + + + + + \endcode + + As the last step, we have to list all files making up the documentation. + An important point to note here is that all files have to listed, including + image files, and even stylesheets if they are used. + + \code + + browse.html + filedialog.html + findfile.html + index.html + intro.html + openfile.html + wildcardmatching.html + images/browse.png + images/fadedfilemenu.png + images/filedialog.png + images/handbook.png + images/mainwindow.png + images/open.png + images/wildcard.png + + + + \endcode + + The help project file is now finished. If you want to see the resulting + documentation in \QA, you have to generate a Qt compressed help file + out of it and register it with the default help collection of \QA. + + \code + qhelpgenerator simpletextviewer.qhp -o simpletextviewer.qch + assistant -register simpletextviewer.qch + \endcode + + If you start \QA now, you'll see the Simple Text Viewer documentation + beside the Qt documentation. This is OK for testing purposes, but + for the final version we want to only have the Simple Text Viewer + documentation in \QA. + + \section2 Customizing \QA + + The easiest way to make \QA only display the Simple Text Viewer + documentation is to create our own help collection file. A collection + file is stored in a binary format, similar to the compressed help file, + and generated from a help collection project file (*.qhcp). With + the help of a collection file, we can customize the appearance and even + some functionality offered by \QA. + + At first, we change the window title and icon. Instead of showing "\QA" + it will show "Simple Text Viewer", so it is much clearer for the user + that the help viewer actually belongs to our application. + + \code + + + + + images/handbook.png + Trolltech/SimpleTextViewer + \endcode + + The \c cacheDirectory tag specifies a subdirectory of the users + data directory (see the + \l{Using Qt Assistant as a Custom Help Viewer#Qt Help Collection Files}{Qt Help Collection Files}) + where the cache file for the full text search or the settings file will + be stored. + + After this, we set the page displayed by \QA when launched for the very + first time in its new configuration. The URL consists of the namespace + and virtual folder defined in the Qt help project file, followed by the + actual page file name. + + \code + qthelp://com.trolltech.examples.simpletextviewer/doc/index.html + \endcode + + Next, we alter the name of the "About" menu item to "About Simple + Text Viewer". The contents of the \gui{About} dialog are also changed + by specifying a file where the about text or icon is taken from. + + \code + + About Simple Text Viewer + + + about.txt + images/icon.png + + \endcode + + \QA offers the possibility to add or remove documentation via its + preferences dialog. This functionality is helpful when using \QA + as the central help viewer for more applications, but in our case + we want to actually prevent the user from removing the documentation. + So, we disable the documentation manager. + + Since the address bar is not really relevant in such a small + documentation set we switch it off as well. By having just one filter + section, without any filter attributes, we can also disable the filter + functionality of \QA, which means that the filter page and the filter + toolbar will not be available. + + \code + false + false + false + + \endcode + + For testing purposes, we already generated the compressed help file + and registered it with \QA's default help collection. With the + following lines we achieve the same result. The only and important + difference is that we register the compressed help file, not in + the default collection, but in our own collection file. + + \code + + + + simpletextviewer.qhp +
simpletextviewer.qch
+ + + + simpletextviewer.qch + + + + \endcode + + As the last step, we have to generate the binary collection file + out of the help collection project file. This is done by running the + \c qcollectiongenerator tool. + + \code + qcollectiongenerator simpletextviewer.qhcp -o simpletextviewer.qhc + \endcode + + To test all our customizations made to \QA, we add the collection + file name to the command line: + + \code + assistant -collectionFile simpletextviewer.qhc + \endcode + + \section1 Controlling \QA via the Assistant Class + + We will first take a look at how to start and operate \QA from a + remote application. For that purpose, we create a class called + \c Assistant. + + This class provides a public function that is used to show pages + of the documentation, and one private helper function to make sure + that \QA is up and running. + + Launching \QA is done in the function \c startAssistant() by simply + creating and starting a QProcess. If the process is already running, + the function returns immediately. Otherwise, the process has + to be set up and started. + + \snippet examples/help/simpletextviewer/assistant.cpp 2 + + To start the process we need the executable name of \QA as well as the + command line arguments for running \QA in a customized mode. The + executable name is a little bit tricky since it depends on the + platform, but fortunately it is only different on Mac OS X. + + The displayed documentation can be altered using the \c -collectionFile + command line argument when launching \QA. When started without any options, + \QA displays a default set of documentation. When Qt is installed, + the default documentation set in \QA contains the Qt reference + documentation as well as the tools that come with Qt, such as Qt + Designer and \c qmake. + + In our example, we replace the default documentation set with our + custom documentation by passing our application-specific collection + file to the process's command line options. + + As the last argument, we add \c -enableRemoteControl, which makes \QA + listen to its \c stdin channel for commands, such as those to display + a certain page in the documentation. + Then we start the process and wait until it is actually running. If, + for some reason \QA cannot be started, \c startAssistant() will return + false. + + The implementation for \c showDocumentation() is now straightforward. + Firstly, we ensure that \QA is running, then we send the request to + display the \a page via the \c stdin channel of the process. It is very + important here that the command is terminated by the '\\0' character + followed by an end of line token to flush the channel. + + \snippet examples/help/simpletextviewer/assistant.cpp 1 + + Finally, we make sure that \QA is terminated properly in the case that + the application is shut down. The destructor of QProcess kills the + process, meaning that the application has no possibility to do things + like save user settings, which would result in corrupted settings files. + To avoid this, we ask \QA to terminate in the destructor of the + \c Assistant class. + + \snippet examples/help/simpletextviewer/assistant.cpp 0 + + \section1 MainWindow Class + + \image simpletextviewer-mainwindow.png + + The \c MainWindow class provides the main application window with + two menus: the \gui File menu lets the user open and view an + existing file, while the \gui Help menu provides information about + the application and about Qt, and lets the user open \QA to + display the application's documentation. + + To be able to access the help functionality, we initialize the + \c Assistant object in the \c MainWindow's constructor. + + \snippet examples/help/simpletextviewer/mainwindow.cpp 0 + \dots + \snippet examples/help/simpletextviewer/mainwindow.cpp 1 + + Then we create all the actions for the Simple Text Viewer application. + Of special interest is the \c assistantAct action accessible + via the \key{F1} shortcut or the \menu{Help|Help Contents} menu item. + This action is connected to the \c showDocumentation() slot of + the \c MainWindow class. + + \snippet examples/help/simpletextviewer/mainwindow.cpp 4 + \dots + \snippet examples/help/simpletextviewer/mainwindow.cpp 5 + + In the \c showDocumentation() slot, we call the \c showDocumentation() + function of the \c Assistant class with the URL of home page of the + documentation. + + \snippet examples/help/simpletextviewer/mainwindow.cpp 3 + + Finally, we must reimplement the protected QWidget::closeEvent() + event handler to ensure that the application's \QA instance is + properly closed before we terminate the application. + + \snippet examples/help/simpletextviewer/mainwindow.cpp 2 + + \section1 FindFileDialog Class + + \image simpletextviewer-findfiledialog.png + + The Simple Text Viewer application provides a find file dialog + allowing the user to search for files using wildcard matching. The + search is performed within the specified directory, and the user + is given an option to browse the existing file system to find the + relevant directory. + + In the constructor we save the references to the \c Assistant + and \c QTextEdit objects passed as arguments. The \c Assistant + object will be used in the \c FindFileDialog's \c help() slot, + as we will see shortly, while the QTextEdit will be used in the + dialog's \c openFile() slot to display the chosen file. + + \snippet examples/help/simpletextviewer/findfiledialog.cpp 0 + \dots + \snippet examples/help/simpletextviewer/findfiledialog.cpp 1 + + The most relevant member to observe in the \c FindFileDialog + class is the private \c help() slot. The slot is connected to the + dialog's \gui Help button, and brings the current \QA instance + to the foreground with the documentation for the dialog by + calling \c Assistant's \c showDocumentation() function. + + \snippet examples/help/simpletextviewer/findfiledialog.cpp 2 + + \section1 Summary + + In order to make \QA act as a customized help tool for + your application, you must provide your application with a + process that controls \QA in addition to a custom help collection + file including Qt compressed help files. + + The \l{Using Qt Assistant as a Custom Help Viewer} document contains + more information about the options and settings available to + applications that use \QA as a custom help viewer. +*/ diff --git a/doc/src/examples/simpletreemodel.qdoc b/doc/src/examples/simpletreemodel.qdoc new file mode 100644 index 0000000..5ddeb46 --- /dev/null +++ b/doc/src/examples/simpletreemodel.qdoc @@ -0,0 +1,346 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/simpletreemodel + \title Simple Tree Model Example + + The Simple Tree Model example shows how to create a basic, read-only + hierarchical model to use with Qt's standard view classes. For a + description of simple non-hierarchical list and table models, see the + \l{model-view-programming.html}{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-model.html}{index-based} system. More generally, models can + be used to represent data in the form of a tree structure by allowing each + item to act as a parent to a table of child items. + + Before attempting to implement a tree model, it is worth considering whether + the data is supplied by an external source, or whether it is going to be + maintained within the model itself. In this example, we will implement an + internal structure to hold data rather than discuss how to package data from + an external source. + + \section1 Design and Concepts + + The data structure that we use to represent the structure of the data takes + the form of a tree built from \c TreeItem objects. Each \c TreeItem + represents an item in a tree view, and contains several columns of data. + + \target SimpleTreeModelStructure + \table + \row \i \inlineimage treemodel-structure.png + \i \bold{Simple Tree Model Structure} + + The data is stored internally in the model using \c TreeItem objects that + are linked together in a pointer-based tree structure. Generally, each + \c TreeItem has a parent item, and can have a number of child items. + However, the root item in the tree structure has no parent item and it + is never referenced outside the model. + + Each \c TreeItem contains information about its place in the tree + structure; it can return its parent item and its row number. Having + this information readily available makes implementing the model easier. + + Since each item in a tree view usually contains several columns of data + (a title and a summary in this example), it is natural to store this + information in each item. For simplicity, we will use a list of QVariant + objects to store the data for each column in the item. + \endtable + + The use of a pointer-based tree structure means that, when passing a + model index to a view, we can record the address of the corresponding + item in the index (see QAbstractItemModel::createIndex()) and retrieve + it later with QModelIndex::internalPointer(). This makes writing the + model easier and ensures that all model indexes that refer to the same + item have the same internal data pointer. + + With the appropriate data structure in place, we can create a tree model + with a minimal amount of extra code to supply model indexes and data to + other components. + + \section1 TreeItem Class Definition + + The \c TreeItem class is defined as follows: + + \snippet examples/itemviews/simpletreemodel/treeitem.h 0 + + The class is a basic C++ class. It does not inherit from QObject or + provide signals and slots. It is used to hold a list of QVariants, + containing column data, and information about its position in the tree + structure. The functions provide the following features: + + \list + \o The \c appendChildItem() is used to add data when the model is first + constructed and is not used during normal use. + \o The \c child() and \c childCount() functions allow the model to obtain + information about any child items. + \o Information about the number of columns associated with the item is + provided by \c columnCount(), and the data in each column can be + obtained with the data() function. + \o The \c row() and \c parent() functions are used to obtain the item's + row number and parent item. + \endlist + + The parent item and column data are stored in the \c parentItem and + \c itemData private member variables. The \c childItems variable contains + a list of pointers to the item's own child items. + + \section1 TreeItem Class Implementation + + The constructor is only used to record the item's parent and the data + associated with each column. + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 0 + + A pointer to each of the child items belonging to this item will be + stored in the \c childItems private member variable. When the class's + destructor is called, it must delete each of these to ensure that + their memory is reused: + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 1 + + Since each of the child items are constructed when the model is initially + populated with data, the function to add child items is straightforward: + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 2 + + Each item is able to return any of its child items when given a suitable + row number. For example, in the \l{#SimpleTreeModelStructure}{above diagram}, + the item marked with the letter "A" corresponds to the child of the root item + with \c{row = 0}, the "B" item is a child of the "A" item with \c{row = 1}, + and the "C" item is a child of the root item with \c{row = 1}. + + The \c child() function returns the child that corresponds to + the specified row number in the item's list of child items: + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 3 + + The number of child items held can be found with \c childCount(): + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 4 + + The \c TreeModel uses this function to determine the number of rows that + exist for a given parent item. + + The \c row() function reports the item's location within its parent's + list of items: + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 8 + + Note that, although the root item (with no parent item) is automatically + assigned a row number of 0, this information is never used by the model. + + The number of columns of data in the item is trivially returned by the + \c columnCount() function. + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 5 + + Column data is returned by the \c data() function, taking advantage of + QList's ability to provide sensible default values if the column number + is out of range: + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 6 + + The item's parent is found with \c parent(): + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 7 + + Note that, since the root item in the model will not have a parent, this + function will return zero in that case. We need to ensure that the model + handles this case correctly when we implement the \c TreeModel::parent() + function. + + \section1 TreeModel Class Definition + + The \c TreeModel class is defined as follows: + + \snippet examples/itemviews/simpletreemodel/treemodel.h 0 + + This class is similar to most other subclasses of QAbstractItemModel that + provide read-only models. Only the form of the constructor and the + \c setupModelData() function are specific to this model. In addition, we + provide a destructor to clean up when the model is destroyed. + + \section1 TreeModel Class Implementation + + For simplicity, the model does not allow its data to be edited. As a + result, the constructor takes an argument containing the data that the + model will share with views and delegates: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 0 + + It is up to the constructor to create a root item for the model. This + item only contains vertical header data for convenience. We also use it + to reference the internal data structure that contains the model data, + and it is used to represent an imaginary parent of top-level items in + the model. + + The model's internal data structure is populated with items by the + \c setupModelData() function. We will examine this function separately + at the end of this document. + + The destructor ensures that the root item and all of its descendants + are deleted when the model is destroyed: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 1 + + Since we cannot add data to the model after it is constructed and set + up, this simplifies the way that the internal tree of items is managed. + + Models must implement an \c index() function to provide indexes for + views and delegates to use when accessing data. Indexes are created + for other components when they are referenced by their row and column + numbers, and their parent model index. If an invalid model + index is specified as the parent, it is up to the model to return an + index that corresponds to a top-level item in the model. + + When supplied with a model index, we first check whether it is valid. + If it is not, we assume that a top-level item is being referred to; + otherwise, we obtain the data pointer from the model index with its + \l{QModelIndex::internalPointer()}{internalPointer()} function and use + it to reference a \c TreeItem object. Note that all the model indexes + that we construct will contain a pointer to an existing \c TreeItem, + so we can guarantee that any valid model indexes that we receive will + contain a valid data pointer. + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 6 + + Since the row and column arguments to this function refer to a + child item of the corresponding parent item, we obtain the item using + the \c TreeItem::child() function. The + \l{QAbstractItemModel::createIndex()}{createIndex()} function is used + to create a model index to be returned. We specify the row and column + numbers, and a pointer to the item itself. The model index can be used + later to obtain the item's data. + + The way that the \c TreeItem objects are defined makes writing the + \c parent() function easy: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 7 + + We only need to ensure that we never return a model index corresponding + to the root item. To be consistent with the way that the \c index() + function is implemented, we return an invalid model index for the + parent of any top-level items in the model. + + When creating a model index to return, we must specify the row and + column numbers of the parent item within its own parent. We can + easily discover the row number with the \c TreeItem::row() function, + but we follow a convention of specifying 0 as the column number of + the parent. The model index is created with + \l{QAbstractItemModel::createIndex()}{createIndex()} in the same way + as in the \c index() function. + + The \c rowCount() function simply returns the number of child items + for the \c TreeItem that corresponds to a given model index, or the + number of top-level items if an invalid index is specified: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 8 + + Since each item manages its own column data, the \c columnCount() + function has to call the item's own \c columnCount() function to + determine how many columns are present for a given model index. + As with the \c rowCount() function, if an invalid model index is + specified, the number of columns returned is determined from the + root item: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 2 + + Data is obtained from the model via \c data(). Since the item manages + its own columns, we need to use the column number to retrieve the data + with the \c TreeItem::data() function: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 3 + + Note that we only support the \l{Qt::ItemDataRole}{DisplayRole} + in this implementation, and we also return invalid QVariant objects for + invalid model indexes. + + We use the \c flags() function to ensure that views know that the + model is read-only: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 4 + + The \c headerData() function returns data that we conveniently stored + in the root item: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 5 + + This information could have been supplied in a different way: either + specified in the constructor, or hard coded into the \c headerData() + function. + + \section1 Setting Up the Data in the Model + + We use the \c setupModelData() function to set up the initial data in + the model. This function parses a text file, extracting strings of + text to use in the model, and creates item objects that record both + the data and the overall model structure. + Naturally, this function works in a way that is very specific to + this model. We provide the following description of its behavior, + and refer the reader to the example code itself for more information. + + We begin with a text file in the following format: + + \snippet doc/src/snippets/code/doc_src_examples_simpletreemodel.qdoc 0 + \dots + \snippet doc/src/snippets/code/doc_src_examples_simpletreemodel.qdoc 1 + + We process the text file with the following two rules: + + \list + \o For each pair of strings on each line, create an item (or node) + in a tree structure, and place each string in a column of data + in the item. + \o When the first string on a line is indented with respect to the + first string on the previous line, make the item a child of the + previous item created. + \endlist + + To ensure that the model works correctly, it is only necessary to + create instances of \c TreeItem with the correct data and parent item. +*/ diff --git a/doc/src/examples/simplewidgetmapper.qdoc b/doc/src/examples/simplewidgetmapper.qdoc new file mode 100644 index 0000000..2fdbf25 --- /dev/null +++ b/doc/src/examples/simplewidgetmapper.qdoc @@ -0,0 +1,139 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/simplewidgetmapper + \title Simple Widget Mapper Example + + The Simple Widget Mapper example shows how to use a widget mapper to display + data from a model in a collection of widgets. + + \image simplewidgetmapper-example.png + + The QDataWidgetMapper class allows information obtained from a + \l{Model Classes}{model} to be viewed and edited in a collection of + widgets instead of in an \l{View Classes}{item view}. + Any model derived from QAbstractItemModel can be used as the source of + data and almost any input widget can be used to display it. + + The example itself is very simple: we create \c Window, a QWidget subclass + that we use to hold the widgets used to present the data, and show it. The + \c Window class will provide buttons that the user can click to show + different records from the model. + + \section1 Window Class Definition + + The class provides a constructor, a slot to keep the buttons up to date, + and a private function to set up the model: + + \snippet examples/itemviews/simplewidgetmapper/window.h Window definition + + In addition to the QDataWidgetMapper object and the controls used to make + up the user interface, we use a QStandardItemModel to hold our data. + We could use a custom model, but this standard implementation is sufficient + for our purposes. + + \section1 Window Class Implementation + + The constructor of the \c Window class can be explained in three parts. + In the first part, we set up the widgets used for the user interface: + + \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up widgets + + We also set up the buddy relationships between various labels and the + corresponding input widgets. + + Next, we set up the widget mapper, relating each input widget to a column + in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}: + + \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the mapper + + We also connect the mapper to the \gui{Next} and \gui{Previous} buttons + via its \l{QDataWidgetMapper::}{toNext()} and + \l{QDataWidgetMapper::}{toPrevious()} slots. The mapper's + \l{QDataWidgetMapper::}{currentIndexChanged()} signal is connected to the + \c{updateButtons()} slot in the window which we'll show later. + + In the final part of the constructor, we set up the layout, placing each + of the widgets in a grid (we could also use a QFormLayout for this): + + \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the layout + + Lastly, we set the window title and initialize the mapper by setting it to + refer to the first row in the model. + + The model is initialized in the window's \c{setupModel()} function. Here, + we create a standard model with 5 rows and 3 columns, and we insert some + sample names, addresses and ages into each row: + + \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the model + + As a result, each row can be treated like a record in a database, and the + widget mapper will read the data from each row, using the column numbers + specified earlier to access the correct data for each widget. This is + shown in the following diagram: + + \image widgetmapper-simple-mapping.png + + Since the user can navigate using the buttons in the user interface, the + example is fully-functional at this point, but to make it a bit more + user-friendly, we implement the \c{updateButtons()} slot to show when the + user is viewing the first or last records: + + \snippet examples/itemviews/simplewidgetmapper/window.cpp Slot for updating the buttons + + If the mapper is referring to the first row in the model, the \gui{Previous} + button is disabled. Similarly, the \gui{Next} button is disabled if the + mapper reaches the last row in the model. + + \section1 More Complex Mappings + + The QDataWidgetMapper class makes it easy to relate information from a + model to widgets in a user interface. However, it is sometimes necessary + to use input widgets which offer choices to the user, such as QComboBox, + in conjunction with a widget mapper. + + In these situations, although the mapping to input widgets remains simple, + more work needs to be done to expose additional data to the widget mapper. + This is covered by the \l{Combo Widget Mapper Example}{Combo Widget Mapper} + and \l{SQL Widget Mapper Example}{SQL Widget Mapper} + examples. +*/ diff --git a/doc/src/examples/sipdialog.qdoc b/doc/src/examples/sipdialog.qdoc new file mode 100644 index 0000000..817f5e2 --- /dev/null +++ b/doc/src/examples/sipdialog.qdoc @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/sipdialog + \title SIP Dialog Example + \ingroup qtce + + The SIP Dialog example shows how to create a dialog that is aware of + the Windows Mobile SIP (Software Input Panel) and reacts to it. + + \table + \row \o \inlineimage sipdialog-closed.png + \o \inlineimage sipdialog-opened.png + \endtable + + Sometimes it is necessary for a dialog to take the SIP into account, + as the SIP may hide important input widgets. The SIP Dialog Example + shows how a \c Dialog object, \c dialog, can be resized accordingly + if the SIP is opened, by embedding the contents of \c dialog in a + QScrollArea. + + \section1 Dialog Class Definition + + The \c Dialog class is a subclass of QDialog that implements a public + slot, \c desktopResized(), and a public function, \c reactToSIP(). Also, + it holds a private instance of QRect, \c desktopGeometry. + + \snippet dialogs/sipdialog/dialog.h Dialog header + + \section1 Dialog Class Implementation + + In the constructor of \c Dialog, we start by obtaining the + available geometry of the screen with + \l{QDesktopWidget::availableGeometry()}{availableGeometry()}. The + parameter used is \c 0 to indicate that we require the primary screen. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part1 + + We set the window's title to "SIP Dialog Example" and declare a QScrollArea + object, \c scrollArea. Next we instantiate a QGroupBox, \c groupBox, with + \c scrollArea as its parent. The title of \c groupBox is also set to + "SIP Dialog Example". A QGridLayout object, \c gridLayout, is then used + as \c{groupBox}'s layout. + + We create a QLineEdit, a QLabel and a QPushButton and we set the + \l{QWidget::setMinimumWidth()}{minimumWidth} property to 220 pixels, + respectively. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part2 + + Also, all three widgets' text are set accordingly. The + \l{QGridLayout::setVerticalSpacing()}{verticalSpacing} property of + \c gridLayout is set based on the height of \c desktopGeometry. This + is to adapt to the different form factors of Windows Mobile. Then, we + add our widgets to the layout. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part3 + + The \c{scrollArea}'s widget is set to \c groupBox. We use a QHBoxLayout + object, \c layout, to contain \c scrollArea. The \c{Dialog}'s layout + is set to \c layout and the scroll area's horizontal scroll bar is turned + off. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part4 + + The following signals are connected to their respective slots: + \list + \o \c{button}'s \l{QPushButton::pressed()}{pressed()} signal to + \l{QApplication}'s \l{QApplication::closeAllWindows()} + {closeAllWindows()} slot, + \o \l{QDesktopWidget}'s \l{QDesktopWidget::workAreaResized()} + {workAreaResized()} signal to \c{dialog}'s \c desktopResized() slot. + \endlist + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part5 + + The \c desktopResized() function accepts an integer, \a screen, + corresponding to the screen's index. We only invoke \c reactToSIP() + if \a screen is the primary screen (e.g. index = 0). + + \snippet dialogs/sipdialog/dialog.cpp desktopResized() function + + The \c reactToSIP() function resizes \c dialog accordingly if the + desktop's available geometry changed vertically, as this change signifies + that the SIP may have been opened or closed. + + \snippet dialogs/sipdialog/dialog.cpp reactToSIP() function + + If the height has decreased, we unset the maximized window state. + Otherwise, we set the maximized window state. Lastly, we update + \c desktopGeometry to the desktop's available geometry. + + \section1 The \c main() function + + The \c main() function for the SIP Dialog example instantiates \c Dialog + and invokes its \l{QDialog::exec()}{exec()} function. + + \snippet dialogs/sipdialog/main.cpp main() function + + \note Although this example uses a dialog, the techniques used here apply to + all top-level widgets respectively. +*/ diff --git a/doc/src/examples/sliders.qdoc b/doc/src/examples/sliders.qdoc new file mode 100644 index 0000000..650fdcb --- /dev/null +++ b/doc/src/examples/sliders.qdoc @@ -0,0 +1,269 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/sliders + \title Sliders Example + + Qt provides three types of slider-like widgets: QSlider, + QScrollBar and QDial. They all inherit most of their + functionality from QAbstractSlider, and can in theory replace + each other in an application since the differences only concern + their look and feel. This example shows what they look like, how + they work and how their behavior and appearance can be + manipulated through their properties. + + The example also demonstrates how signals and slots can be used to + synchronize the behavior of two or more widgets. + + \image sliders-example.png Screenshot of the Sliders example + + The Sliders example consists of two classes: + + \list + + \o \c SlidersGroup is a custom widget. It combines a QSlider, a + QScrollBar and a QDial. + + \o \c Window is the main widget combining a QGroupBox and a + QStackedWidget. In this example, the QStackedWidget provides a + stack of two \c SlidersGroup widgets. The QGroupBox contain + several widgets that control the behavior of the slider-like + widgets. + + \endlist + + First we will review the \c Window class, then we + will take a look at the \c SlidersGroup class. + + \section1 Window Class Definition + + \snippet examples/widgets/sliders/window.h 0 + + The \c Window class inherits from QWidget. It displays the slider + widgets and allows the user to set their minimum, maximum and + current values and to customize their appearance, key bindings + and orientation. We use a private \c createControls() function to + create the widgets that provide these controlling mechanisms and + to connect them to the slider widgets. + + \section1 Window Class Implementation + + \snippet examples/widgets/sliders/window.cpp 0 + + In the constructor we first create the two \c SlidersGroup + widgets that display the slider widgets horizontally and + vertically, and add them to the QStackedWidget. QStackedWidget + provides a stack of widgets where only the top widget is visible. + With \c createControls() we create a connection from a + controlling widget to the QStackedWidget, making the user able to + choose between horizontal and vertical orientation of the slider + widgets. The rest of the controlling mechanisms is implemented by + the same function call. + + \snippet examples/widgets/sliders/window.cpp 1 + \snippet examples/widgets/sliders/window.cpp 2 + + Then we connect the \c horizontalSliders, \c verticalSliders and + \c valueSpinBox to each other, so that the slider widgets and the + control widget will behave synchronized when the current value of + one of them changes. The \c valueChanged() signal is emitted with + the new value as argument. The \c setValue() slot sets the + current value of the widget to the new value, and emits \c + valueChanged() if the new value is different from the old one. + + We put the group of control widgets and the stacked widget in a + horizontal layout before we initialize the minimum, maximum and + current values. The initialization of the current value will + propagate to the slider widgets through the connection we made + between \c valueSpinBox and the \c SlidersGroup widgets. The + minimum and maximum values propagate through the connections we + created with \c createControls(). + + \snippet examples/widgets/sliders/window.cpp 3 + \snippet examples/widgets/sliders/window.cpp 4 + + In the private \c createControls() function, we let a QGroupBox + (\c controlsGroup) display the control widgets. A group box can + provide a frame, a title and a keyboard shortcut, and displays + various other widgets inside itself. The group of control widgets + is composed by two checkboxes, three spin boxes (with labels) and + one combobox. + + After creating the labels, we create the two checkboxes. + Checkboxes are typically used to represent features in an + application that can be enabled or disabled. When \c + invertedAppearance is enabled, the slider values are inverted. + The table below shows the appearance for the different + slider-like widgets: + + \table + \header \o \o{2,1} QSlider \o{2,1} QScrollBar \o{2,1} QDial + \header \o \o Normal \o Inverted \o Normal \o Inverted \o Normal \o Inverted + \row \o Qt::Horizontal \o Left to right \o Right to left \o Left to right \o Right to left \o Clockwise \o Counterclockwise + \row \o Qt::Vertical \o Bottom to top \o Top to bottom \o Top to bottom \o Bottom to top \o Clockwise \o Counterclockwise + \endtable + + It is common to invert the appearance of a vertical QSlider. A + vertical slider that controls volume, for example, will typically + go from bottom to top (the non-inverted appearance), whereas a + vertical slider that controls the position of an object on screen + might go from top to bottom, because screen coordinates go from + top to bottom. + + When the \c invertedKeyBindings option is enabled (corresponding + to the QAbstractSlider::invertedControls property), the slider's + wheel and key events are inverted. The normal key bindings mean + that scrolling the mouse wheel "up" or using keys like page up + will increase the slider's current value towards its maximum. + Inverted, the same wheel and key events will move the value + toward the slider's minimum. This can be useful if the \e + appearance of a slider is inverted: Some users might expect the + keys to still work the same way on the value, whereas others + might expect \key PageUp to mean "up" on the screen. + + Note that for horizontal and vertical scroll bars, the key + bindings are inverted by default: \key PageDown increases the + current value, and \key PageUp decreases it. + + \snippet examples/widgets/sliders/window.cpp 5 + \snippet examples/widgets/sliders/window.cpp 6 + + Then we create the spin boxes. QSpinBox allows the user to choose + a value by clicking the up and down buttons or pressing the \key + Up and \key Down keys on the keyboard to modify the value + currently displayed. The user can also type in the value + manually. The spin boxes control the minimum, maximum and current + values for the QSlider, QScrollBar, and QDial widgets. + + We create a QComboBox that allows the user to choose the + orientation of the slider widgets. The QComboBox widget is a + combined button and popup list. It provides a means of presenting + a list of options to the user in a way that takes up the minimum + amount of screen space. + + \snippet examples/widgets/sliders/window.cpp 7 + \snippet examples/widgets/sliders/window.cpp 8 + + We synchronize the behavior of the control widgets and the slider + widgets through their signals and slots. We connect each control + widget to both the horizontal and vertical group of slider + widgets. We also connect \c orientationCombo to the + QStackedWidget, so that the correct "page" is shown. Finally, we + lay out the control widgets in a QGridLayout within the \c + controlsGroup group box. + + \section1 SlidersGroup Class Definition + + \snippet examples/widgets/sliders/slidersgroup.h 0 + + The \c SlidersGroup class inherits from QGroupBox. It provides a + frame and a title, and contains a QSlider, a QScrollBar and a + QDial. + + We provide a \c valueChanged() signal and a public \c setValue() + slot with equivalent functionality to the ones in QAbstractSlider + and QSpinBox. In addition, we implement several other public + slots to set the minimum and maximum value, and invert the slider + widgets' appearance as well as key bindings. + + \section1 SlidersGroup Class Implementation + + \snippet examples/widgets/sliders/slidersgroup.cpp 0 + + First we create the slider-like widgets with the appropiate + properties. In particular we set the focus policy for each + widget. Qt::FocusPolicy is an enum type that defines the various + policies a widget can have with respect to acquiring keyboard + focus. The Qt::StrongFocus policy means that the widget accepts + focus by both tabbing and clicking. + + Then we connect the widgets with each other, so that they will + stay synchronized when the current value of one of them changes. + + \snippet examples/widgets/sliders/slidersgroup.cpp 1 + \snippet examples/widgets/sliders/slidersgroup.cpp 2 + + We connect \c {dial}'s \c valueChanged() signal to the + \c{SlidersGroup}'s \c valueChanged() signal, to notify the other + widgets in the application (i.e., the control widgets) of the + changed value. + + \snippet examples/widgets/sliders/slidersgroup.cpp 3 + \codeline + \snippet examples/widgets/sliders/slidersgroup.cpp 4 + + Finally, depending on the \l {Qt::Orientation}{orientation} given + at the time of construction, we choose and create the layout for + the slider widgets within the group box. + + \snippet examples/widgets/sliders/slidersgroup.cpp 5 + \snippet examples/widgets/sliders/slidersgroup.cpp 6 + + The \c setValue() slot sets the value of the QSlider. We don't + need to explicitly call + \l{QAbstractSlider::setValue()}{setValue()} on the QScrollBar and + QDial widgets, since QSlider will emit the + \l{QAbstractSlider::valueChanged()}{valueChanged()} signal when + its value changes, triggering a domino effect. + + \snippet examples/widgets/sliders/slidersgroup.cpp 7 + \snippet examples/widgets/sliders/slidersgroup.cpp 8 + \codeline + \snippet examples/widgets/sliders/slidersgroup.cpp 9 + \snippet examples/widgets/sliders/slidersgroup.cpp 10 + + The \c setMinimum() and \c setMaximum() slots are used by the \c + Window class to set the range of the QSlider, QScrollBar, and + QDial widgets. + + \snippet examples/widgets/sliders/slidersgroup.cpp 11 + \snippet examples/widgets/sliders/slidersgroup.cpp 12 + \codeline + \snippet examples/widgets/sliders/slidersgroup.cpp 13 + \snippet examples/widgets/sliders/slidersgroup.cpp 14 + + The \c invertAppearance() and \c invertKeyBindings() slots + control the child widgets' + \l{QAbstractSlider::invertedAppearance}{invertedAppearance} and + \l{QAbstractSlider::invertedControls}{invertedControls} + properties. +*/ diff --git a/doc/src/examples/spinboxdelegate.qdoc b/doc/src/examples/spinboxdelegate.qdoc new file mode 100644 index 0000000..542eebd --- /dev/null +++ b/doc/src/examples/spinboxdelegate.qdoc @@ -0,0 +1,151 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/spinboxdelegate + \title Spin Box Delegate Example + + The Spin Box Delegate example shows how to create an editor for a custom delegate in + the model/view framework by reusing a standard Qt editor widget. + + The model/view framework provides a standard delegate that is used by default + with the standard view classes. For most purposes, the selection of editor + widgets available through this delegate is sufficient for editing text, boolean + values, and other simple data types. However, for specific data types, it is + sometimes necessary to use a custom delegate to either display the data in a + specific way, or allow the user to edit it with a custom control. + + \image spinboxdelegate-example.png + + This concepts behind this example are covered in the + \l{model-view-delegate.html}{Delegate Classes} chapter of the + \l{model-view-programming.html}{Model/View Programming} overview. + + \section1 SpinBoxDelegate Class Definition + + The definition of the delegate is as follows: + + \snippet examples/itemviews/spinboxdelegate/delegate.h 0 + + The delegate class declares only those functions that are needed to + create an editor widget, display it at the correct location in a view, + and communicate with a model. Custom delegates can also provide their + own painting code by reimplementing the \c paintEvent() function. + + \section1 SpinBoxDelegate Class Implementation + + Since the delegate is stateless, the constructor only needs to + call the base class's constructor with the parent QObject as its + argument: + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 0 + + Since the delegate is a subclass of QItemDelegate, the data it retrieves + from the model is displayed in a default style, and we do not need to + provide a custom \c paintEvent(). + + The \c createEditor() function returns an editor widget, in this case a + spin box that restricts values from the model to integers from 0 to 100 + inclusive. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 1 + + We install an event filter on the spin box to ensure that it behaves in + a way that is consistent with other delegates. The implementation for + the event filter is provided by the base class. + + The \c setEditorData() function reads data from the model, converts it + to an integer value, and writes it to the editor widget. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 2 + + Since the view treats delegates as ordinary QWidget instances, we have + to use a static cast before we can set the value in the spin box. + + The \c setModelData() function reads the contents of the spin box, and + writes it to the model. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 3 + + We call \l{QSpinBox::interpretText()}{interpretText()} to make sure that + we obtain the most up-to-date value in the spin box. + + The \c updateEditorGeometry() function updates the editor widget's + geometry using the information supplied in the style option. This is the + minimum that the delegate must do in this case. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 4 + + More complex editor widgets may divide the rectangle available in + \c{option.rect} between different child widgets if required. + + \section1 The Main Function + + This example is written in a slightly different way to many of the + other examples supplied with Qt. To demonstrate the use of a custom + editor widget in a standard view, it is necessary to set up a model + containing some arbitrary data and a view to display it. + + We set up the application in the normal way, construct a standard item + model to hold some data, set up a table view to use the data in the + model, and construct a custom delegate to use for editing: + + \snippet examples/itemviews/spinboxdelegate/main.cpp 0 + + The table view is informed about the delegate, and will use it to + display each of the items. Since the delegate is a subclass of + QItemDelegate, each cell in the table will be rendered using standard + painting operations. + + We insert some arbitrary data into the model for demonstration purposes: + + \snippet examples/itemviews/spinboxdelegate/main.cpp 1 + \snippet examples/itemviews/spinboxdelegate/main.cpp 2 + + Finally, the table view is displayed with a window title, and we start + the application's event loop: + + \snippet examples/itemviews/spinboxdelegate/main.cpp 3 + + Each of the cells in the table can now be edited in the usual way, but + the spin box ensures that the data returned to the model is always + constrained by the values allowed by the spin box delegate. +*/ diff --git a/doc/src/examples/spinboxes.qdoc b/doc/src/examples/spinboxes.qdoc new file mode 100644 index 0000000..d8b0daa --- /dev/null +++ b/doc/src/examples/spinboxes.qdoc @@ -0,0 +1,205 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/spinboxes + \title Spin Boxes Example + + The Spin Boxes example shows how to use the many different types of spin boxes + available in Qt, from a simple QSpinBox widget to more complex editors like + the QDateTimeEdit widget. + + \image spinboxes-example.png + + The example consists of a single \c Window class that is used to display the + different spin box-based widgets available with Qt. + + \section1 Window Class Definition + + The \c Window class inherits QWidget and contains two slots that are used + to provide interactive features: + + \snippet examples/widgets/spinboxes/window.h 0 + + The private functions are used to set up each type of spin box in the window. + We use member variables to keep track of various widgets so that they can + be reconfigured when required. + + \section1 Window Class Implementation + + The constructor simply calls private functions to set up the different types + of spin box used in the example, and places each group in a layout: + + \snippet examples/widgets/spinboxes/window.cpp 0 + + We use the layout to manage the arrangement of the window's child widgets, + and change the window title. + + The \c createSpinBoxes() function constructs a QGroupBox and places three + QSpinBox widgets inside it with descriptive labels to indicate the types of + input they expect. + + \snippet examples/widgets/spinboxes/window.cpp 1 + + The first spin box shows the simplest way to use QSpinBox. It accepts values + from -20 to 20, the current value can be increased or decreased by 1 with + either the arrow buttons or \key{Up} and \key{Down} keys, and the default + value is 0. + + The second spin box uses a larger step size and displays a suffix to + provide more information about the type of data the number represents: + + \snippet examples/widgets/spinboxes/window.cpp 2 + + This spin box also displays a + \l{QAbstractSpinBox::specialValueText}{special value} instead of the minimum + value defined for it. This means that it will never show \gui{0%}, but will + display \gui{Automatic} when the minimum value is selected. + + The third spin box shows how a prefix can be used: + + \snippet examples/widgets/spinboxes/window.cpp 4 + + For simplicity, we show a spin box with a prefix and no suffix. It is also + possible to use both at the same time. + + \snippet examples/widgets/spinboxes/window.cpp 5 + + The rest of the function sets up a layout for the group box and places each + of the widgets inside it. + + The \c createDateTimeEdits() function constructs another group box with a + selection of spin boxes used for editing dates and times. + + \snippet examples/widgets/spinboxes/window.cpp 6 + + The first spin box is a QDateEdit widget that is able to accept dates + within a given range specified using QDate values. The arrow buttons and + \key{Up} and \key{Down} keys can be used to increase and decrease the + values for year, month, and day when the cursor is in the relevant section. + + The second spin box is a QTimeEdit widget: + + \snippet examples/widgets/spinboxes/window.cpp 7 + + Acceptable values for the time are defined using QTime values. + + The third spin box is a QDateTimeEdit widget that can display both date and + time values, and we place a label above it to indicate the range of allowed + times for a meeting. These widgets will be updated when the user changes a + format string. + + \snippet examples/widgets/spinboxes/window.cpp 8 + + The format string used for the date time editor, which is also shown in the + string displayed by the label, is chosen from a set of strings in a combobox: + + \snippet examples/widgets/spinboxes/window.cpp 9 + \codeline + \snippet examples/widgets/spinboxes/window.cpp 10 + + A signal from this combobox is connected to a slot in the \c Window class + (shown later). + + \snippet examples/widgets/spinboxes/window.cpp 11 + + Each child widget of the group box in placed in a layout. + + The \c setFormatString() slot is called whenever the user selects a new + format string in the combobox. The display format for the QDateTimeEdit + widget is set using the raw string passed by the signal: + + \snippet examples/widgets/spinboxes/window.cpp 12 + + Depending on the visible sections in the widget, we set a new date or time + range, and update the associated label to provide relevant information for + the user: + + \snippet examples/widgets/spinboxes/window.cpp 13 + + When the format string is changed, there will be an appropriate label and + entry widget for dates, times, or both types of input. + + The \c createDoubleSpinBoxes() function constructs three spin boxes that are + used to input double-precision floating point numbers: + + \snippet examples/widgets/spinboxes/window.cpp 14 + + Before the QDoubleSpinBox widgets are constructed, we create a spin box to + control how many decimal places they show. By default, only two decimal places + are shown in the following spin boxes, each of which is the equivalent of a + spin box in the group created by the \c createSpinBoxes() function. + + The first double spin box shows a basic double-precision spin box with the + same range, step size, and default value as the first spin box in the + \c createSpinBoxes() function: + + \snippet examples/widgets/spinboxes/window.cpp 15 + + However, this spin box also allows non-integer values to be entered. + + The second spin box displays a suffix and shows a special value instead + of the minimum value: + + \snippet examples/widgets/spinboxes/window.cpp 16 + + The third spin box displays a prefix instead of a suffix: + + \snippet examples/widgets/spinboxes/window.cpp 17 + + We connect the QSpinBox widget that specifies the precision to a slot in + the \c Window class. + + \snippet examples/widgets/spinboxes/window.cpp 18 + + The rest of the function places each of the widgets into a layout for the + group box. + + The \c changePrecision() slot is called when the user changes the value in + the precision spin box: + + \snippet examples/widgets/spinboxes/window.cpp 19 + + This function simply uses the integer supplied by the signal to specify the + number of decimal places in each of the QDoubleSpinBox widgets. Each one + of these will be updated automatically when their + \l{QDoubleSpinBox::decimals}{decimals} property is changed. +*/ diff --git a/doc/src/examples/sqlwidgetmapper.qdoc b/doc/src/examples/sqlwidgetmapper.qdoc new file mode 100644 index 0000000..173aea4 --- /dev/null +++ b/doc/src/examples/sqlwidgetmapper.qdoc @@ -0,0 +1,199 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/sqlwidgetmapper + \title SQL Widget Mapper Example + + The SQL Widget Mapper example shows how to use a map information from a + database to widgets on a form. + + \image sql-widget-mapper.png + + In the \l{Combo Widget Mapper Example}, we showed how to use a named + mapping between a widget mapper and a QComboBox widget with a special + purpose model to relate values in the model to a list of choices. + + Again, we create a \c Window class with an almost identical user interface, + providing a combo box to allow their addresses to be classified as "Home", + "Work" or "Other". However, instead of using a separate model to hold these + address types, we use one database table to hold the example data and + another to hold the address types. In this way, we store all the + information in the same place. + + \section1 Window Class Definition + + The class provides a constructor, a slot to keep the buttons up to date, + and a private function to set up the model: + + \snippet examples/sql/sqlwidgetmapper/window.h Window definition + + In addition to the QDataWidgetMapper object and the controls used to make + up the user interface, we use a QStandardItemModel to hold our data and + a QStringListModel to hold information about the types of address that + can be applied to each person's data. + + \section1 Window Class Implementation + + The first act performed by the \c Window class constructor is to set up + the model used to hold the example data. Since this is a key part of the + example, we will look at this first. + + The model is initialized in the window's \c{setupModel()} function. Here, + we create a SQLite database containing a "person" table with primary key, + name, address and type fields. + + \snippet examples/sql/sqlwidgetmapper/window.cpp Set up the main table + + On each row of the table, we insert default values for these fields, + including values for the address types that correspond to the address + types are stored in a separate table. + + \image widgetmapper-sql-mapping-table.png + + We create an "addresstype" table containing the identifiers used in the + "person" table and the corresponding strings: + + \snippet examples/sql/sqlwidgetmapper/window.cpp Set up the address type table + + The "typeid" field in the "person" table is related to the contents of + the "addresstype" table via a relation in a QSqlRelationalTableModel. + This kind of model performs all the necessary work to store the data in + a database and also allows any relations to be used as models in their + own right. + + In this case, we have defined a relation for the "typeid" field in the + "person" table that relates it to the "id" field in the "addresstype" + table and which causes the contents of the "description" field to be + used wherever the "typeid" is presented to the user. (See the + QSqlRelationalTableModel::setRelation() documentation for details.) + + \image widgetmapper-sql-mapping.png + + The constructor of the \c Window class can be explained in three parts. + In the first part, we set up the model used to hold the data, then we set + up the widgets used for the user interface: + + \snippet examples/sql/sqlwidgetmapper/window.cpp Set up widgets + + We obtain a model for the combo box from the main model, based on the + relation we set up for the "typeid" field. The call to the combo box's + \l{QComboBox::}{setModelColumn()} selects the field in the field in the + model to display. + + Note that this approach is similar to the one used in the + \l{Combo Widget Mapper Example} in that we set up a model for the + combo box. However, in this case, we obtain a model based on a relation + in the QSqlRelationalTableModel rather than create a separate one. + + Next, we set up the widget mapper, relating each input widget to a field + in the model: + + \snippet examples/sql/sqlwidgetmapper/window.cpp Set up the mapper + + For the combo box, we already know the index of the field in the model + from the \c{setupModel()} function. We use a QSqlRelationalDelegate as + a proxy between the mapper and the input widgets to match up the "typeid" + values in the model with those in the combo box's model and populate the + combo box with descriptions rather than integer values. + + As a result, the user is able to select an item from the combo box, + and the associated value is written back to the model. + + The rest of the constructor is very similar to that of the + \l{Simple Widget Mapper Example}: + + \snippet examples/sql/sqlwidgetmapper/window.cpp Set up connections and layouts + + We show the implementation of the \c{updateButtons()} slot for + completeness: + + \snippet examples/sql/sqlwidgetmapper/window.cpp Slot for updating the buttons + + \omit + \section1 Delegate Class Definition and Implementation + + The delegate we use to mediate interaction between the widget mapper and + the input widgets is a small QItemDelegate subclass: + + \snippet examples/sql/sqlwidgetmapper/delegate.h Delegate class definition + + This provides implementations of the two standard functions used to pass + data between editor widgets and the model (see the \l{Delegate Classes} + documentation for a more general description of these functions). + + Since we only provide an empty implementation of the constructor, we + concentrate on the other two functions. + + The \l{QItemDelegate::}{setEditorData()} implementation takes the data + referred to by the model index supplied and processes it according to + the presence of a \c currentIndex property in the editor widget: + + \snippet examples/sql/sqlwidgetmapper/delegate.cpp setEditorData implementation + + If, like QComboBox, the editor widget has this property, it is set using + the value from the model. Since we are passing around QVariant values, + the strings stored in the model are automatically converted to the integer + values needed for the \c currentIndex property. + + As a result, instead of showing "0", "1" or "2" in the combo box, one of + its predefined set of items is shown. We call QItemDelegate::setEditorData() + for widgets without the \c currentIndex property. + + The \l{QItemDelegate::}{setModelData()} implementation performs the reverse + process, taking the value stored in the widget's \c currentIndex property + and storing it back in the model: + + \snippet examples/sql/sqlwidgetmapper/delegate.cpp setModelData implementation + \endomit + + \section1 Summary and Further Reading + + The use of a separate model for the combo box and a special delegate for the + widget mapper allows us to present a menu of choices to the user. Although + the choices are stored in the same database as the user's data, they are held + in a separate table. Using this approach, we can reconstructed complete records + at a later time while using database features appropriately. + + If SQL models are not being used, it is still possible to use more than + one model to present choices to the user. This is covered by the + \l{Combo Widget Mapper Example}. +*/ diff --git a/doc/src/examples/standarddialogs.qdoc b/doc/src/examples/standarddialogs.qdoc new file mode 100644 index 0000000..db533ed --- /dev/null +++ b/doc/src/examples/standarddialogs.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/standarddialogs + \title Standard Dialogs Example + + The Standard Dialogs example shows the standard dialogs that are provided by Qt. + + \image standarddialogs-example.png +*/ diff --git a/doc/src/examples/stardelegate.qdoc b/doc/src/examples/stardelegate.qdoc new file mode 100644 index 0000000..fde3316 --- /dev/null +++ b/doc/src/examples/stardelegate.qdoc @@ -0,0 +1,310 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/stardelegate + \title Star Delegate Example + + The Star Delegate example shows how to create a delegate that + can paint itself and that supports editing. + + \image stardelegate.png The Star Delegate Example + + When displaying data in a QListView, QTableView, or QTreeView, + the individual items are drawn by a + \l{Delegate Classes}{delegate}. Also, when the user starts + editing an item (e.g., by double-clicking the item), the delegate + provides an editor widget that is placed on top of the item while + editing takes place. + + Delegates are subclasses of QAbstractItemDelegate. Qt provides + QItemDelegate, which inherits QAbstractItemDelegate and handles + the most common data types (notably \c int and QString). If we + need to support custom data types, or want to customize the + rendering or the editing for existing data types, we can subclass + QAbstractItemDelegate or QItemDelegate. See \l{Delegate Classes} + for more information about delegates, and \l{Model/View + Programming} if you need a high-level introduction to Qt's + model/view architecture (including delegates). + + In this example, we will see how to implement a custom delegate + to render and edit a "star rating" data type, which can store + values such as "1 out of 5 stars". + + The example consists of the following classes: + + \list + \o \c StarRating is the custom data type. It stores a rating + expressed as stars, such as "2 out of 5 stars" or "5 out of + 6 stars". + + \o \c StarDelegate inherits QItemDelegate and provides support + for \c StarRating (in addition to the data types already + handled by QItemDelegate). + + \o \c StarEditor inherits QWidget and is used by \c StarDelegate + to let the user edit a star rating using the mouse. + \endlist + + To show the \c StarDelegate in action, we will fill a + QTableWidget with some data and install the delegate on it. + + \section1 StarDelegate Class Definition + + Here's the definition of the \c StarDelegate class: + + \snippet examples/itemviews/stardelegate/stardelegate.h 0 + + All public functions are reimplemented virtual functions from + QItemDelegate to provide custom rendering and editing. + + \section1 StarDelegate Class Implementation + + The \l{QAbstractItemDelegate::}{paint()} function is + reimplemented from QItemDelegate and is called whenever the view + needs to repaint an item: + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 0 + + The function is invoked once for each item, represented by a + QModelIndex object from the model. If the data stored in the item + is a \c StarRating, we paint it ourselves; otherwise, we let + QItemDelegate paint it for us. This ensures that the \c + StarDelegate can handle the most common data types. + + In the case where the item is a \c StarRating, we draw the + background if the item is selected, and we draw the item using \c + StarRating::paint(), which we will review later. + + \c{StartRating}s can be stored in a QVariant thanks to the + Q_DECLARE_METATYPE() macro appearing in \c starrating.h. More on + this later. + + The \l{QAbstractItemDelegate::}{createEditor()} function is + called when the user starts editing an item: + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 2 + + If the item is a \c StarRating, we create a \c StarEditor and + connect its \c editingFinished() signal to our \c + commitAndCloseEditor() slot, so we can update the model when the + editor closes. + + Here's the implementation of \c commitAndCloseEditor(): + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 5 + + When the user is done editing, we emit + \l{QAbstractItemDelegate::}{commitData()} and + \l{QAbstractItemDelegate::}{closeEditor()} (both declared in + QAbstractItemDelegate), to tell the model that there is edited + data and to inform the view that the editor is no longer needed. + + The \l{QAbstractItemDelegate::}{setEditorData()} function is + called when an editor is created to initialize it with data + from the model: + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 3 + + We simply call \c setStarRating() on the editor. + + The \l{QAbstractItemDelegate::}{setModelData()} function is + called when editing is finished, to commit data from the editor + to the model: + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 4 + + The \c sizeHint() function returns an item's preferred size: + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 1 + + We simply forward the call to \c StarRating. + + \section1 StarEditor Class Definition + + The \c StarEditor class was used when implementing \c + StarDelegate. Here's the class definition: + + \snippet examples/itemviews/stardelegate/stareditor.h 0 + + The class lets the user edit a \c StarRating by moving the mouse + over the editor. It emits the \c editingFinished() signal when + the user clicks on the editor. + + The protected functions are reimplemented from QWidget to handle + mouse and paint events. The private function \c starAtPosition() + is a helper function that returns the number of the star under + the mouse pointer. + + \section1 StarEditor Class Implementation + + Let's start with the constructor: + + \snippet examples/itemviews/stardelegate/stareditor.cpp 0 + + We enable \l{QWidget::setMouseTracking()}{mouse tracking} on the + widget so we can follow the cursor even when the user doesn't + hold down any mouse button. We also turn on QWidget's + \l{QWidget::autoFillBackground}{auto-fill background} feature to + obtain an opaque background. (Without the call, the view's + background would shine through the editor.) + + The \l{QWidget::}{paintEvent()} function is reimplemented from + QWidget: + + \snippet examples/itemviews/stardelegate/stareditor.cpp 1 + + We simply call \c StarRating::paint() to draw the stars, just + like we did when implementing \c StarDelegate. + + \snippet examples/itemviews/stardelegate/stareditor.cpp 2 + + In the mouse event handler, we call \c setStarCount() on the + private data member \c myStarRating to reflect the current cursor + position, and we call QWidget::update() to force a repaint. + + \snippet examples/itemviews/stardelegate/stareditor.cpp 3 + + When the user releases a mouse button, we simply emit the \c + editingFinished() signal. + + \snippet examples/itemviews/stardelegate/stareditor.cpp 4 + + The \c starAtPosition() function uses basic linear algebra to + find out which star is under the cursor. + + \section1 StarRating Class Definition + + \snippet examples/itemviews/stardelegate/starrating.h 0 + \codeline + \snippet examples/itemviews/stardelegate/starrating.h 1 + + The \c StarRating class represents a rating as a number of stars. + In addition to holding the data, it is also capable of painting + the stars on a QPaintDevice, which in this example is either a + view or an editor. The \c myStarCount member variable stores the + current rating, and \c myMaxStarCount stores the highest possible + rating (typically 5). + + The Q_DECLARE_METATYPE() macro makes the type \c StarRating known + to QVariant, making it possible to store \c StarRating values in + QVariant. + + \section1 StarRating Class Implementation + + The constructor initializes \c myStarCount and \c myMaxStarCount, + and sets up the polygons used to draw stars and diamonds: + + \snippet examples/itemviews/stardelegate/starrating.cpp 0 + + The \c paint() function paints the stars in this \c StarRating + object on a paint device: + + \snippet examples/itemviews/stardelegate/starrating.cpp 2 + + We first set the pen and brush we will use for painting. The \c + mode parameter can be either \c Editable or \c ReadOnly. If \c + mode is editable, we use the \l{QPalette::}{Highlight} color + instead of the \l{QPalette::}{Foreground} color to draw the + stars. + + Then we draw the stars. If we are in \c Edit mode, we paint + diamonds in place of stars if the rating is less than the highest + rating. + + The \c sizeHint() function returns the preferred size for an area + to paint the stars on: + + \snippet examples/itemviews/stardelegate/starrating.cpp 1 + + The preferred size is just enough to paint the maximum number of + stars. The function is called by both \c StarDelegate::sizeHint() + and \c StarEditor::sizeHint(). + + \section1 The \c main() Function + + Here's the program's \c main() function: + + \snippet examples/itemviews/stardelegate/main.cpp 5 + + The \c main() function creates a QTableWidget and sets a \c + StarDelegate on it. \l{QAbstractItemView::}{DoubleClicked} and + \l{QAbstractItemView::}{SelectedClicked} are set as + \l{QAbstractItemView::editTriggers()}{edit triggers}, so that the + editor is opened with a single click when the star rating item is + selected. + + The \c populateTableWidget() function fills the QTableWidget with + data: + + \snippet examples/itemviews/stardelegate/main.cpp 0 + \snippet examples/itemviews/stardelegate/main.cpp 1 + \dots + \snippet examples/itemviews/stardelegate/main.cpp 2 + \snippet examples/itemviews/stardelegate/main.cpp 3 + \codeline + \snippet examples/itemviews/stardelegate/main.cpp 4 + + Notice the call to qVariantFromValue to convert a \c + StarRating to a QVariant. + + \section1 Possible Extensions and Suggestions + + There are many ways to customize Qt's \l{Model/View + Programming}{model/view framework}. The approach used in this + example is appropriate for most custom delegates and editors. + Examples of possibilities not used by the star delegate and star + editor are: + + \list + \o It is possible to open editors programmatically by calling + QAbstractItemView::edit(), instead of relying on edit + triggers. This could be use to support other edit triggers + than those offered by the QAbstractItemView::EditTrigger enum. + For example, in the Star Delegate example, hovering over an + item with the mouse might make sense as a way to pop up an + editor. + + \o By reimplementing QAbstractItemDelegate::editorEvent(), it is + possible to implement the editor directly in the delegate, + instead of creating a separate QWidget subclass. + \endlist +*/ diff --git a/doc/src/examples/styleplugin.qdoc b/doc/src/examples/styleplugin.qdoc new file mode 100644 index 0000000..0dea7bf --- /dev/null +++ b/doc/src/examples/styleplugin.qdoc @@ -0,0 +1,147 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/styleplugin + \title Style Plugin Example + + This example shows how to create a plugin that extends Qt with a new + GUI look and feel. + + \image stylepluginexample.png + + On some platforms, the native style will prevent the button + from having a red background. In this case, try to run the example + in another style (e.g., plastique). + + A plugin in Qt is a class stored in a shared library that can be + loaded by a QPluginLoader at run-time. When you create plugins in + Qt, they either extend a Qt application or Qt itself. Writing a + plugin that extends Qt itself is achieved by inheriting one of the + plugin \l{Plugin Classes}{base classes}, reimplementing functions + from that class, and adding a macro. In this example we extend Qt + by adding a new GUI look and feel (i.e., making a new QStyle + available). A high-level introduction to plugins is given in the + plugin \l{How to Create Qt Plugins}{overview document}. + + Plugins that provide new styles inherit the QStylePlugin base + class. Style plugins are loaded by Qt and made available through + QStyleFactory; we will look at this later. We have implemented \c + SimpleStylePlugin, which provides \c SimpleStyle. The new style + inherits QWindowsStyle and contributes to widget styling by + drawing button backgrounds in red - not a major contribution, but + it still makes a new style. We test the plugin with \c + StyleWindow, in which we display a QPushButton. + + The \c SimpleStyle and \c StyleWindow classes do not contain any + plugin specific functionality and their implementations are + trivial; we will therefore leap past them and head on to the \c + SimpleStylePlugin and the \c main() function. After we have looked + at that, we examine the plugin's profile. + + + \section1 SimpleStylePlugin Class Definition + + \c SimpleStylePlugin inherits QStylePlugin and is the plugin + class. + + \snippet examples/tools/styleplugin/plugin/simplestyleplugin.h 0 + + \c keys() returns a list of style names that this plugin can + create, while \c create() takes such a string and returns the + QStyle corresponding to the key. Both functions are pure virtual + functions reimplemented from QStylePlugin. When an application + requests an instance of the \c SimpleStyle style, which this + plugin creates, Qt will create it with this plugin. + + + \section1 SimpleStylePlugin Class Implementation + + Here is the implementation of \c keys(): + + \snippet examples/tools/styleplugin/plugin/simplestyleplugin.cpp 0 + + Since this plugin only supports one style, we return a QStringList + with the class name of that style. + + Here is the \c create() function: + + \snippet examples/tools/styleplugin/plugin/simplestyleplugin.cpp 1 + + Note that the key for style plugins are case insensitive. + The case sensitivity varies from plugin to plugin, so you need to + check this when implementing new plugins. + + \section1 The \c main() function + + \snippet examples/tools/styleplugin/stylewindow/main.cpp 0 + + Qt loads the available style plugins when the QApplication object + is initialized. The QStyleFactory class knows about all styles and + produces them with \l{QStyleFactory::}{create()} (it is a + wrapper around all the style plugins). + + \section1 The Simple Style Plugin Profile + + The \c SimpleStylePlugin lives in its own directory and have + its own profile: + + \snippet examples/tools/styleplugin/plugin/plugin.pro 0 + + In the plugin profile we need to set the lib template as we are + building a shared library instead of an executable. We must also + set the config to plugin. We set the library to be stored in the + styles folder under stylewindow because this is a path in which Qt + will search for style plugins. + + \section1 Related articles and examples + + In addition to the plugin \l{How to Create Qt Plugins}{overview + document}, we have other examples and articles that concern + plugins. + + In the \l{Echo Plugin Example}{echo plugin example} we show how to + implement plugins that extends Qt applications rather than Qt + itself, which is the case with the style plugin of this example. + The \l{Plug & Paint Example}{plug & paint} example shows how to + implement a static plugin as well as being a more involved example + on plugins that extend applications. +*/ diff --git a/doc/src/examples/styles.qdoc b/doc/src/examples/styles.qdoc new file mode 100644 index 0000000..b68a310 --- /dev/null +++ b/doc/src/examples/styles.qdoc @@ -0,0 +1,486 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/styles + \title Styles Example + + The Styles example illustrates how to create custom widget + drawing styles using Qt, and demonstrates Qt's predefined styles. + + \image styles-enabledwood.png Screenshot of the Styles example + + A style in Qt is a subclass of QStyle or of one of its + subclasses. Styles perform drawing on behalf of widgets. Qt + provides a whole range of predefined styles, either built into + the \l QtGui library or found in plugins. Custom styles are + usually created by subclassing one of Qt's existing style and + reimplementing a few virtual functions. + + In this example, the custom style is called \c NorwegianWoodStyle + and derives from QMotifStyle. Its main features are the wooden + textures used for filling most of the widgets and its round + buttons and comboboxes. + + To implement the style, we use some advanced features provided by + QPainter, such as \l{QPainter::Antialiasing}{antialiasing} (to + obtain smoother button edges), \l{QColor::alpha()}{alpha blending} + (to make the buttons appeared raised or sunken), and + \l{QPainterPath}{painter paths} (to fill the buttons and draw the + outline). We also use many features of QBrush and QPalette. + + The example consists of the following classes: + + \list + \o \c NorwegianWoodStyle inherits from QMotifStyle and implements + the Norwegian Wood style. + \o \c WidgetGallery is a \c QDialog subclass that shows the most + common widgets and allows the user to switch style + dynamically. + \endlist + + \section1 NorwegianWoodStyle Class Definition + + Here's the definition of the \c NorwegianWoodStyle class: + + \snippet examples/widgets/styles/norwegianwoodstyle.h 0 + + The public functions are all declared in QStyle (QMotifStyle's + grandparent class) and reimplemented here to override the Motif + look and feel. The private functions are helper functions. + + \section1 NorwegianWoodStyle Class Implementation + + We will now review the implementation of the \c + NorwegianWoodStyle class. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 0 + + The \c polish() function is reimplemented from QStyle. It takes a + QPalette as a reference and adapts the palette to fit the style. + Most styles don't need to reimplement that function. The + Norwegian Wood style reimplements it to set a "wooden" palette. + + We start by defining a few \l{QColor}s that we'll need. Then we + load two PNG images. The \c : prefix in the file path indicates + that the PNG files are \l{The Qt Resource System}{embedded + resources}. + + \table + \row \o \inlineimage widgets/styles/images/woodbackground.png + + \o \bold{woodbackground.png} + + This texture is used as the background of most widgets. + The wood pattern is horizontal. + + \row \o \inlineimage widgets/styles/images/woodbutton.png + + \o \bold{woodbutton.png} + + This texture is used for filling push buttons and + comboboxes. The wood pattern is vertical and more reddish + than the texture used for the background. + \endtable + + The \c midImage variable is initialized to be the same as \c + buttonImage, but then we use a QPainter and fill it with a 25% + opaque black color (a black with an \l{QColor::alpha()}{alpha + channel} of 63). The result is a somewhat darker image than \c + buttonImage. This image will be used for filling buttons that the + user is holding down. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 1 + + We initialize the palette. Palettes have various + \l{QPalette::ColorRole}{color roles}, such as QPalette::Base + (used for filling text editors, item views, etc.), QPalette::Text + (used for foreground text), and QPalette::Background (used for + the background of most widgets). Each role has its own QBrush, + which usually is a plain color but can also be a brush pattern or + even a texture (a QPixmap). + + In addition to the roles, palettes have several + \l{QPalette::ColorGroup}{color groups}: active, disabled, and + inactive. The active color group is used for painting widgets in + the active window. The disabled group is used for disabled + widgets. The inactive group is used for all other widgets. Most + palettes have identical active and inactive groups, while the + disabled group uses darker shades. + + We initialize the QPalette object with a brown color. Qt + automatically derivates all color roles for all color groups from + that single color. We then override some of the default values. For + example, we use Qt::darkGreen instead of the default + (Qt::darkBlue) for the QPalette::Highlight role. The + QPalette::setBrush() overload that we use here sets the same + color or brush for all three color groups. + + The \c setTexture() function is a private function that sets the + texture for a certain color role, while preserving the existing + color in the QBrush. A QBrush can hold both a solid color and a + texture at the same time. The solid color is used for drawing + text and other graphical elements where textures don't look good. + + At the end, we set the brush for the disabled color group of the + palette. We use \c woodbackground.png as the texture for all + disabled widgets, including buttons, and use a darker color to + accompany the texture. + + \image styles-disabledwood.png The Norwegian Wood style with disabled widgets + + Let's move on to the other functions reimplemented from + QMotifStyle: + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 3 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 4 + + This QStyle::polish() overload is called once on every widget + drawn using the style. We reimplement it to set the Qt::WA_Hover + attribute on \l{QPushButton}s and \l{QComboBox}es. When this + attribute is set, Qt generates paint events when the mouse + pointer enters or leaves the widget. This makes it possible to + render push buttons and comboboxes differently when the mouse + pointer is over them. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 5 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 6 + + This QStyle::unpolish() overload is called to undo any + modification done to the widget in \c polish(). For simplicity, + we assume that the flag wasn't set before \c polish() was called. + In an ideal world, we would remember the original state for each + widgets (e.g., using a QMap) and restore it in + \c unpolish(). + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 7 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 8 + + The \l{QStyle::pixelMetric()}{pixelMetric()} function returns the + size in pixels for a certain user interface element. By + reimplementing this function, we can affect the way certain + widgets are drawn and their size hint. Here, we return 8 as the + width around a shown in a QComboBox, ensuring that there is + enough place around the text and the arrow for the Norwegian Wood + round corners. The default value for this setting in the Motif + style is 2. + + We also change the extent of \l{QScrollBar}s, i.e., the height + for a horizontal scroll bar and the width for a vertical scroll + bar, to be 4 pixels more than in the Motif style. This makes the + style a bit more distinctive. + + For all other QStyle::PixelMetric elements, we use the Motif + settings. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 9 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 10 + + The \l{QStyle::styleHint()}{styleHint()} function returns some + hints to widgets or to the base style (in our case QMotifStyle) + about how to draw the widgets. The Motif style returns \c true + for the QStyle::SH_DitherDisabledText hint, resulting in a most + unpleasing visual effect. We override this behavior and return \c + false instead. We also return \c true for the + QStyle::SH_EtchDisabledText hint, meaning that disabled text is + rendered with an embossed look (as QWindowsStyle does). + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 11 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 12 + + The \l{QStyle::drawPrimitive()}{drawPrimitive()} function is + called by Qt widgets to draw various fundamental graphical + elements. Here we reimplement it to draw QPushButton and + QComboBox with round corners. The button part of these widgets is + drawn using the QStyle::PE_PanelButtonCommand primitive element. + + The \c option parameter, of type QStyleOption, contains + everything we need to know about the widget we want to draw on. + In particular, \c option->rect gives the rectangle within which + to draw the primitive element. The \c painter parameter is a + QPainter object that we can use to draw on the widget. + + The \c widget parameter is the widget itself. Normally, all the + information we need is available in \c option and \c painter, so + we don't need \c widget. We can use it to perform special + effects; for example, QMacStyle uses it to animate default + buttons. If you use it, be aware that the caller is allowed to + pass a null pointer. + + We start by defining three \l{QColor}s that we'll need later on. + We also put the x, y, width, and height components of the + widget's rectangle in local variables. The value used for the \c + semiTransparentWhite and for the \c semiTransparentBlack color's + alpha channel depends on whether the mouse cursor is over the + widget or not. Since we set the Qt::WA_Hover attribute on + \l{QPushButton}s and \l{QComboBox}es, we can rely on the + QStyle::State_MouseOver flag to be set when the mouse is over the + widget. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 13 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 14 + + The \c roundRect variable is a QPainterPath. A QPainterPath is is + a vectorial specification of a shape. Any shape (rectangle, + ellipse, spline, etc.) or combination of shapes can be expressed + as a path. We will use \c roundRect both for filling the button + background with a wooden texture and for drawing the outline. The + \c roundRectPath() function is a private function; we will come + back to it later. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 15 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 16 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 17 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 18 + + We define two variables, \c brush and \c darker, and initialize + them based on the state of the button: + + \list + \o If the button is a \l{QPushButton::flat}{flat button}, we use + the \l{QPalette::Background}{Background} brush. We set \c + darker to \c true if the button is + \l{QAbstractButton::down}{down} or + \l{QAbstractButton::checked}{checked}. + \o If the button is currently held down by the user or in the + \l{QAbstractButton::checked}{checked} state, we use the + \l{QPalette::Mid}{Mid} component of the palette. We set + \c darker to \c true if the button is + \l{QAbstractButton::checked}{checked}. + \o Otherwise, we use the \l{QPalette::Button}{Button} component + of the palette. + \endlist + + The screenshot below illustrates how \l{QPushButton}s are + rendered based on their state: + + \image styles-woodbuttons.png Norwegian Wood buttons in different states + + To discover whether the button is flat or not, we need to cast + the \c option parameter to QStyleOptionButton and check if the + \l{QStyleOptionButton::features}{features} member specifies the + QStyleOptionButton::Flat flag. The qstyleoption_cast() function + performs a dynamic cast; if \c option is not a + QStyleOptionButton, qstyleoption_cast() returns a null pointer. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 19 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 20 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 21 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 22 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 23 + + We turn on antialiasing on QPainter. Antialiasing is a technique + that reduces the visual distortion that occurs when the edges of + a shape are converted into pixels. For the Norwegian Wood style, + we use it to obtain smoother edges for the round buttons. + + \image styles-aliasing.png Norwegian wood buttons with and without antialiasing + + The first call to QPainter::fillPath() draws the background of + the button with a wooden texture. The second call to + \l{QPainter::fillPath()}{fillPath()} paints the same area with a + semi-transparent black color (a black color with an alpha channel + of 63) to make the area darker if \c darker is true. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 24 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 25 + + Next, we draw the outline. The top-left half of the outline and + the bottom-right half of the outline are drawn using different + \l{QPen}s to produce a 3D effect. Normally, the top-left half of + the outline is drawn lighter whereas the bottom-right half is + drawn darker, but if the button is + \l{QAbstractButton::down}{down} or + \l{QAbstractButton::checked}{checked}, we invert the two + \l{QPen}s to give a sunken look to the button. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 26 + + We draw the top-left part of the outline by calling + QPainter::drawPath() with an appropriate + \l{QPainter::setClipRegion()}{clip region}. If the + \l{QStyleOption::direction}{layout direction} is right-to-left + instead of left-to-right, we swap the \c x1, \c x2, \c x3, and \c + x4 variables to obtain correct results. On right-to-left desktop, + the "light" comes from the top-right corner of the screen instead + of the top-left corner; raised and sunken widgets must be drawn + accordingly. + + The diagram below illustrates how 3D effects are drawn according + to the layout direction. The area in red on the diagram + corresponds to the \c topHalf polygon: + + \image styles-3d.png + + An easy way to test how a style looks in right-to-left mode is to + pass the \c -reverse command-line option to the application. This + option is recognized by the QApplication constructor. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 32 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 33 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 34 + + The bottom-right part of the outline is drawn in a similar + fashion. Then we draw a one-pixel wide outline around the entire + button, using the \l{QPalette::Foreground}{Foreground} component + of the QPalette. + + This completes the QStyle::PE_PanelButtonCommand case of the \c + switch statement. Other primitive elements are handled by the + base style. Let's now turn to the other \c NorwegianWoodStyle + member functions: + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 35 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 36 + + We reimplement QStyle::drawControl() to draw the text on a + QPushButton in a bright color when the button is + \l{QAbstractButton::down}{down} or + \l{QAbstractButton::checked}{checked}. + + If the \c option parameter points to a QStyleOptionButton object + (it normally should), we take a copy of the object and modify its + \l{QStyleOption::palette}{palette} member to make the + QPalette::ButtonText be the same as the QPalette::BrightText + component (unless the widget is disabled). + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 37 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 38 + + The \c setTexture() function is a private function that sets the + \l{QBrush::texture()}{texture} component of the \l{QBrush}es for + a certain \l{QPalette::ColorRole}{color role}, for all three + \l{QPalette::ColorGroup}{color groups} (active, disabled, + inactive). We used it to initialize the Norwegian Wood palette in + \c polish(QPalette &). + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 39 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 40 + + The \c roundRectPath() function is a private function that + constructs a QPainterPath object for round buttons. The path + consists of eight segments: four arc segments for the corners and + four lines for the sides. + + With around 250 lines of code, we have a fully functional custom + style based on one of the predefined styles. Custom styles can be + used to provide a distinct look to an application or family of + applications. + + \section1 WidgetGallery Class + + For completeness, we will quickly review the \c WidgetGallery + class, which contains the most common Qt widgets and allows the + user to change style dynamically. Here's the class definition: + + \snippet examples/widgets/styles/widgetgallery.h 0 + \dots + \snippet examples/widgets/styles/widgetgallery.h 1 + + Here's the \c WidgetGallery constructor: + + \snippet examples/widgets/styles/widgetgallery.cpp 0 + + We start by creating child widgets. The \gui Style combobox is + initialized with all the styles known to QStyleFactory, in + addition to \c NorwegianWood. The \c create...() functions are + private functions that set up the various parts of the \c + WidgetGallery. + + \snippet examples/widgets/styles/widgetgallery.cpp 1 + \snippet examples/widgets/styles/widgetgallery.cpp 2 + + We connect the \gui Style combobox to the \c changeStyle() + private slot, the \gui{Use style's standard palette} check box to + the \c changePalette() slot, and the \gui{Disable widgets} check + box to the child widgets' + \l{QWidget::setDisabled()}{setDisabled()} slot. + + \snippet examples/widgets/styles/widgetgallery.cpp 3 + \snippet examples/widgets/styles/widgetgallery.cpp 4 + + Finally, we put the child widgets in layouts. + + \snippet examples/widgets/styles/widgetgallery.cpp 5 + \snippet examples/widgets/styles/widgetgallery.cpp 6 + + When the user changes the style in the combobox, we call + QApplication::setStyle() to dynamically change the style of the + application. + + \snippet examples/widgets/styles/widgetgallery.cpp 7 + \snippet examples/widgets/styles/widgetgallery.cpp 8 + + If the user turns the \gui{Use style's standard palette} on, the + current style's \l{QStyle::standardPalette()}{standard palette} + is used; otherwise, the system's default palette is honored. + + For the Norwegian Wood style, this makes no difference because we + always override the palette with our own palette in \c + NorwegianWoodStyle::polish(). + + \snippet examples/widgets/styles/widgetgallery.cpp 9 + \snippet examples/widgets/styles/widgetgallery.cpp 10 + + The \c advanceProgressBar() slot is called at regular intervals + to advance the progress bar. Since we don't know how long the + user will keep the Styles application running, we use a + logarithmic formula: The closer the progress bar gets to 100%, + the slower it advances. + + We will review \c createProgressBar() in a moment. + + \snippet examples/widgets/styles/widgetgallery.cpp 11 + \snippet examples/widgets/styles/widgetgallery.cpp 12 + + The \c createTopLeftGroupBox() function creates the QGroupBox + that occupies the top-left corner of the \c WidgetGallery. We + skip the \c createTopRightGroupBox(), \c + createBottomLeftTabWidget(), and \c createBottomRightGroupBox() + functions, which are very similar. + + \snippet examples/widgets/styles/widgetgallery.cpp 13 + + In \c createProgressBar(), we create a QProgressBar at the bottom + of the \c WidgetGallery and connect its + \l{QTimer::timeout()}{timeout()} signal to the \c + advanceProgressBar() slot. +*/ diff --git a/doc/src/examples/stylesheet.qdoc b/doc/src/examples/stylesheet.qdoc new file mode 100644 index 0000000..811d65c --- /dev/null +++ b/doc/src/examples/stylesheet.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/stylesheet + \title Style Sheet Example + + The Style Sheet Example shows how to use style sheets. + + \image stylesheet-pagefold.png Screen Shot of the Pagefold style sheet +*/ + diff --git a/doc/src/examples/svgalib.qdoc b/doc/src/examples/svgalib.qdoc new file mode 100644 index 0000000..c94d408 --- /dev/null +++ b/doc/src/examples/svgalib.qdoc @@ -0,0 +1,360 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example qws/svgalib + \title Accelerated Graphics Driver Example + + The Accelerated Graphics Driver example shows how you can write + your own accelerated graphics driver and \l {add your graphics + driver to Qt for Embedded Linux}. In \l{Qt for Embedded Linux}, + painting is a pure software implementation and is normally performed + in two steps: + The clients render each window onto a corresponding surface + (stored in memory) using a paint engine, and then the server uses + the graphics driver to compose the surface images and copy them to + the screen. (See the \l{Qt for Embedded Linux Architecture} documentation + for details.) + + The rendering can be accelerated in two ways: Either by + accelerating the copying of pixels to the screen, or by + accelerating the explicit painting operations. The first is done + in the graphics driver implementation, the latter is performed by + the paint engine implementation. Typically, both the pixel copying + and the painting operations are accelerated using the following + approach: + + \list 1 + \o \l {Step 1: Creating a Custom Graphics Driver} + {Creating a Custom Graphics Driver} + + \o \l {Step 2: Implementing a Custom Raster Paint Engine} + {Implementing a Custom Paint Engine} + + \o \l {Step 3: Making the Widgets Aware of the Custom Paint + Engine}{Making the Widgets Aware of the Custom Paint Engine} + + \endlist + + After compiling the example code, install the graphics driver + plugin with the command \c {make install}. To start an application + using the graphics driver, you can either set the environment + variable \l QWS_DISPLAY and then run the application, or you can + just run the application using the \c -display switch: + + \snippet doc/src/snippets/code/doc_src_examples_svgalib.qdoc 0 + + \table + \header \o SVGAlib + \row \o + + Instead of interfacing the graphics hardware directly, this + example relies on \l {http://www.svgalib.org}{SVGAlib} being + installed on your system. \l {http://www.svgalib.org}{SVGAlib} is + a small graphics library which provides acceleration for many + common graphics cards used on desktop computers. It should work on + most workstations and has a small and simple API. + + \endtable + + \section1 Step 1: Creating a Custom Graphics Driver + + The custom graphics driver is created by deriving from the QScreen + class. QScreen is the base class for implementing screen/graphics + drivers in Qt for Embedded Linux. + + \snippet examples/qws/svgalib/svgalibscreen.h 0 + \codeline + \snippet examples/qws/svgalib/svgalibscreen.h 1 + + The \l {QScreen::}{connect()}, \l {QScreen::}{disconnect()}, \l + {QScreen::}{initDevice()} and \l {QScreen::}{shutdownDevice()} + functions are declared as pure virtual functions in QScreen and + must be implemented. They are used to configure the hardware, or + query its configuration: \l {QScreen::}{connect()} and \l + {QScreen::}{disconnect()} are called by both the server and client + processes, while the \l {QScreen::}{initDevice()} and \l + {QScreen::}{shutdownDevice()} functions are only called by the + server process. + + QScreen's \l {QScreen::}{setMode()} and \l {QScreen::}{blank()} + functions are also pure virtual, but our driver's implementations + are trivial. The last two functions (\l {QScreen::}{blit()} and \l + {QScreen::}{solidFill()}) are the ones involved in putting pixels + on the screen, i.e., we reimplement these functions to perform the + pixel copying acceleration. + + Finally, the \c context variable is a pointer to a \l + {http://www.svgalib.org}{SVGAlib} specific type. Note that the + details of using the \l {http://www.svgalib.org}{SVGAlib} library + is beyond the scope of this example. + + \section2 SvgalibScreen Class Implementation + + The \l {QScreen::}{connect()} function is the first function that + is called after the constructor returns. It queries \l + {http://www.svgalib.org}{SVGAlib} about the graphics mode and + initializes the variables. + + \snippet examples/qws/svgalib/svgalibscreen.cpp 0 + + It is important that the \l {QScreen::}{connect()} function + initializes the \c data, \c lstep, \c w, \c h, \c dw, \c dh, \c d, + \c physWidth and \c physHeight variables (inherited from QScreen) + to ensure that the driver is in a state consistent with the driver + configuration. + + In this particular example we do not have any information of the + real physical size of the screen, so we set these values with the + assumption of a screen with 72 DPI. + + \snippet examples/qws/svgalib/svgalibscreen.cpp 1 + + When the \l {QScreen::}{connect()} function returns, the server + process calls the \l {QScreen::}{initDevice()} function which is + expected to do the necessary hardware initialization, leaving the + hardware in a state consistent with the driver configuration. + + Note that we have chosen to use the software cursor. If you want + to use a hardware cursor, you should create a subclass of + QScreenCursor, create an instance of it, and make the global + variable \c qt_screencursor point to this instance. + + \snippet examples/qws/svgalib/svgalibscreen.cpp 2 + \codeline + \snippet examples/qws/svgalib/svgalibscreen.cpp 3 + + Before exiting, the server process will call the \l + {QScreen::}{shutdownDevice()} function to do the necessary + hardware cleanup. Again, it is important that the function leaves + the hardware in a state consistent with the driver + configuration. When \l {QScreen::}{shutdownDevice()} returns, the + \l {QScreen::}{disconnect()} function is called. Our + implementation of the latter function is trivial. + + Note that, provided that the \c QScreen::data variable points to a + valid linear framebuffer, the graphics driver is fully functional + as a simple screen driver at this point. The rest of this example + will show where to take advantage of the accelerated capabilities + available on the hardware. + + Whenever an area on the screen needs to be updated, the server will + call the \l {QScreen::}{exposeRegion()} function that paints the + given region on screen. The default implementation will do the + necessary composing of the top-level windows and call \l + {QScreen::}{solidFill()} and \l {QScreen::}{blit()} whenever it is + required. We do not want to change this behavior in the driver so + we do not reimplement \l {QScreen::}{exposeRegion()}. + + To control how the pixels are put onto the screen we need to + reimplement the \l {QScreen::}{solidFill()} and \l + {QScreen::}{blit()} functions. + + \snippet examples/qws/svgalib/svgalibscreen.cpp 4 + \codeline + \snippet examples/qws/svgalib/svgalibscreen.cpp 5 + + \section1 Step 2: Implementing a Custom Raster Paint Engine + + \l{Qt for Embedded Linux} uses QRasterPaintEngine (a raster-based + implementation of QPaintEngine) to implement the painting + operations. + + Acceleration of the painting operations is done by deriving from + QRasterPaintEngine class. This is a powerful mechanism for + accelerating graphic primitives while getting software fallbacks + for all the primitives you do not accelerate. + + \snippet examples/qws/svgalib/svgalibpaintengine.h 0 + + In this example, we will only accelerate one of the \l + {QRasterPaintEngine::}{drawRects()} functions, i.e., only + non-rotated, aliased and opaque rectangles will be rendered using + accelerated painting. All other primitives are rendered using the + base class's unaccelerated implementation. + + The paint engine's state is stored in the private member + variables, and we reimplement the \l + {QPaintEngine::}{updateState()} function to ensure that our + custom paint engine's state is updated properly whenever it is + required. The private \c setClip() and \c updateClip() functions + are only helper function used to simplify the \l + {QPaintEngine::}{updateState()} implementation. + + We also reimplement QRasterPaintEngine's \l + {QRasterPaintEngine::}{begin()} and \l + {QRasterPaintEngine::}{end()} functions to initialize the paint + engine and to do the cleanup when we are done rendering, + respectively. + + \table + \header \o Private Header Files + \row + \o + + Note the \c include statement used by this class. The files + prefixed with \c private/ are private headers file within + \l{Qt for Embedded Linux}. Private header files are not part of + the standard installation and are only present while + compiling Qt. To be able to compile using + private header files you need to use a \c qmake binary within a + compiled \l{Qt for Embedded Linux} package. + + \warning Private header files may change without notice between + releases. + + \endtable + + The \l {QRasterPaintEngine::}{begin()} function initializes the + internal state of the paint engine. Note that it also calls the + base class implementation to initialize the parts inherited from + QRasterPaintEngine: + + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 0 + \codeline + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 1 + + The implementation of the \l {QRasterPaintEngine::}{end()} + function removes the clipping constraints that might have been set + in \l {http://www.svgalib.org}{SVGAlib}, before calling the + corresponding base class implementation. + + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 2 + + The \l {QPaintEngine::}{updateState()} function updates our + custom paint engine's state. The QPaintEngineState class provides + information about the active paint engine's current state. + + Note that we only accept and save the current matrix if it doesn't + do any shearing. The pen is accepted if it is opaque and only one + pixel wide. The rest of the engine's properties are updated + following the same pattern. Again it is important that the + QPaintEngine::updateState() function is called to update the + parts inherited from the base class. + + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 3 + \codeline + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 4 + + The \c setClip() helper function is called from our custom + implementation of \l {QPaintEngine::}{updateState()}, and + enables clipping to the given region. An empty region means that + clipping is disabled. + + Our custom update function also makes use of the \c updateClip() + helper function that checks if the clip is "simple", i.e., that it + can be represented by only one rectangle, and updates the clip + region in \l {http://www.svgalib.org}{SVGAlib}. + + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 5 + + Finally, we accelerated that drawing of non-rotated, aliased and + opaque rectangles in our reimplementation of the \l + {QRasterPaintEngine::}{drawRects()} function. The + QRasterPaintEngine fallback is used whenever the rectangle is not + simple enough. + + \section1 Step 3: Making the Widgets Aware of the Custom Paint Engine + + To activate the custom paint engine, we also need to implement a + corresponding paint device and window surface and make some minor + adjustments of the graphics driver. + + \list + \o \l {Implementing a Custom Paint Device} + \o \l {Implementing a Custom Window Surface} + \o \l {Adjusting the Graphics Driver} + \endlist + + \section2 Implementing a Custom Paint Device + + The custom paint device can be derived from the + QCustomRasterPaintDevice class. Reimplement its \l + {QCustomRasterPaintDevice::}{paintEngine()} and \l + {QCustomRasterPaintDevice::}{memory()} functions to activate the + accelerated paint engine: + + \snippet examples/qws/svgalib/svgalibpaintdevice.h 0 + + The \l {QCustomRasterPaintDevice::}{paintEngine()} function should + return an instance of the \c SvgalibPaintEngine class. The \l + {QCustomRasterPaintDevice::}{memory()} function should return a + pointer to the buffer which should be used when drawing the + widget. + + Our example driver is rendering directly to the screen without any + buffering, i.e., our custom pain device's \l + {QCustomRasterPaintDevice::}{memory()} function returns a pointer + to the framebuffer. For this reason, we must also reimplement the + \l {QPaintDevice::}{metric()} function to reflect the metrics of + framebuffer. + + \section2 Implementing a Custom Window Surface + + The custom window surface can be derived from the QWSWindowSurface + class. QWSWindowSurface manages the memory used when drawing a + window. + + \snippet examples/qws/svgalib/svgalibsurface.h 0 + + We can implement most of the pure virtual functions inherited from + QWSWindowSurface as trivial inline functions, except the + \l {QWindowSurface::}{scroll()} function that actually makes use + of some hardware acceleration: + + \snippet examples/qws/svgalib/svgalibsurface.cpp 0 + + \section2 Adjusting the Graphics Driver + + Finally, we enable the graphics driver to recognize an instance of + our custom window surface: + + \snippet examples/qws/svgalib/svgalibscreen.cpp 7 + \codeline + \snippet examples/qws/svgalib/svgalibscreen.cpp 8 + + The \l {QScreen::}{createSurface()} functions are factory + functions that determines what kind of surface a top-level window + is using. In our example we only use the custom surface if the + given window has the Qt::WA_PaintOnScreen attribute or the + QT_ONSCREEN_PAINT environment variable is set. +*/ + diff --git a/doc/src/examples/svgviewer.qdoc b/doc/src/examples/svgviewer.qdoc new file mode 100644 index 0000000..affc85f --- /dev/null +++ b/doc/src/examples/svgviewer.qdoc @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/svgviewer + \title SVG Viewer Example + + The SVG Viewer example shows how to add SVG viewing support to applications. + + \image svgviewer-example.png + + Scalable Vector Graphics (SVG) is an XML-based language for describing two-dimensional + vector graphics. Qt provides classes for rendering and displaying SVG drawings in + widgets and on other paint devices. This example allows the user to load SVG files + and view them in a QGraphicsView using a QGraphicsSvgItem. Based on the selected + renderer the QGraphicsView uses either a QWidget or QGLWidget as its viewport. A + third render mode is also provided, where the QGraphicsView draws indirectly though + a QImage. This allows testing of drawing accuracy and performance for both the + native, raster, and OpenGL paint engines. + + See the QtSvg module documentation for more information about SVG and Qt's SVG classes. +*/ diff --git a/doc/src/examples/syntaxhighlighter.qdoc b/doc/src/examples/syntaxhighlighter.qdoc new file mode 100644 index 0000000..7cc9e61 --- /dev/null +++ b/doc/src/examples/syntaxhighlighter.qdoc @@ -0,0 +1,256 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example richtext/syntaxhighlighter + \title Syntax Highlighter Example + + The Syntax Highlighter example shows how to perform simple syntax + highlighting by subclassing the QSyntaxHighlighter class. + + \image syntaxhighlighter-example.png + + The Syntax Highlighter application displays C++ files with custom + syntax highlighting. + + The example consists of two classes: + + \list + \o The \c Highlighter class defines and applies the + highlighting rules. + \o The \c MainWindow widget is the application's main window. + \endlist + + We will first review the \c Highlighter class to see how you can + customize the QSyntaxHighlighter class to fit your preferences, + then we will take a look at the relevant parts of the \c + MainWindow class to see how you can use your custom highlighter + class in an application. + + \section1 Highlighter Class Definition + + \snippet examples/richtext/syntaxhighlighter/highlighter.h 0 + + To provide your own syntax highlighting, you must subclass + QSyntaxHighlighter, reimplement the \l + {QSyntaxHighlighter::highlightBlock()}{highlightBlock()} function, + and define your own highlighting rules. + + We have chosen to store our highlighting rules using a private + struct: A rule consists of a QRegExp pattern and a QTextCharFormat + instance. The various rules are then stored using a QVector. + + The QTextCharFormat class provides formatting information for + characters in a QTextDocument specifying the visual properties of + the text, as well as information about its role in a hypertext + document. In this example, we will only define the font weight and + color using the QTextCharFormat::setFontWeight() and + QTextCharFormat::setForeground() functions. + + \section1 Highlighter Class Implementation + + When subclassing the QSyntaxHighlighter class you must pass the + parent parameter to the base class constructor. The parent is the + text document upon which the syntax highligning will be + applied. In this example, we have also chosen to define our + highlighting rules in the constructor: + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 0 + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 1 + + First we define a keyword rule which recognizes the most common + C++ keywords. We give the \c keywordFormat a bold, dark blue + font. For each keyword, we assign the keyword and the specified + format to a HighlightingRule object and append the object to our + list of rules. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 2 + \codeline + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 4 + \codeline + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 5 + + Then we create a format that we will apply to Qt class names. The + class names will be rendered with a dark magenta color and a bold + style. We specify a string pattern that is actually a regular + expression capturing all Qt class names. Then we assign the + regular expression and the specified format to a HighlightingRule + object and append the object to our list of rules. + + We also define highlighting rules for quotations and functions + using the same approach: The patterns have the form of regular + expressions and are stored in HighlightingRule objects with the + associated format. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 3 + \codeline + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 6 + + The C++ language has two variations of comments: The single line + comment (\c //) and the multiline comment (\c{/*...}\starslash). The single + line comment can easily be defined through a highlighting rule + similar to the previous ones. But the multiline comment needs + special care due to the design of the QSyntaxHighlighter class. + + After a QSyntaxHighlighter object is created, its \l + {QSyntaxHighlighter::highlightBlock()}{highlightBlock()} function + will be called automatically whenever it is necessary by the rich + text engine, highlighting the given text block. The problem + appears when a comment spans several text blocks. We will take a + closer look at how this problem can be solved when reviewing the + implementation of the \c Highlighter::highlightBlock() + function. At this point we only specify the multiline comment's + color. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 7 + + The highlightBlock() function is called automatically whenever it + is necessary by the rich text engine, i.e. when there are text + blocks that have changed. + + First we apply the syntax highlighting rules that we stored in the + \c highlightingRules vector. For each rule (i.e. for each + HighlightingRule object) we search for the pattern in the given + textblock using the QString::indexOf() function. When the first + occurrence of the pattern is found, we use the + QRegExp::matchedLength() function to determine the string that + will be formatted. QRegExp::matchedLength() returns the length of + the last matched string, or -1 if there was no match. + + To perform the actual formatting the QSyntaxHighlighter class + provides the \l {QSyntaxHighlighter::setFormat()}{setFormat()} + function. This function operates on the text block that is passed + as argument to the \c highlightBlock() function. The specified + format is applied to the text from the given start position for + the given length. The formatting properties set in the given + format are merged at display time with the formatting information + stored directly in the document. Note that the document itself + remains unmodified by the format set through this function. + + This process is repeated until the last occurrence of the pattern + in the current text block is found. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 8 + + To deal with constructs that can span several text blocks (like + the C++ multiline comment), it is necessary to know the end state + of the previous text block (e.g. "in comment"). Inside your \c + highlightBlock() implementation you can query the end state of the + previous text block using the + QSyntaxHighlighter::previousBlockState() function. After parsing + the block you can save the last state using + QSyntaxHighlighter::setCurrentBlockState(). + + The \l + {QSyntaxHighlighter::previousBlockState()}{previousBlockState()} + function return an int value. If no state is set, the returned + value is -1. You can designate any other value to identify any + given state using the \l + {QSyntaxHighlighter::setCurrentBlockState()}{setCurrentBlockState()} + function. Once the state is set, the QTextBlock keeps that value + until it is set again or until the corresponding paragraph of text + is deleted. + + In this example we have chosen to use 0 to represent the "not in + comment" state, and 1 for the "in comment" state. When the stored + syntax highlighting rules are applied we initialize the current + block state to 0. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 9 + + If the previous block state was "in comment" (\c + {previousBlockState() == 1}), we start the search for an end + expression at the beginning of the text block. If the + previousBlockState() returns 0, we start the search at the + location of the first occurrence of a start expression. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 10 + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 11 + + When an end expression is found, we calculate the length of the + comment and apply the multiline comment format. Then we search for + the next occurrence of the start expression and repeat the + process. If no end expression can be found in the current text + block we set the current block state to 1, i.e. "in comment". + + This completes the \c Highlighter class implementation; it is now + ready for use. + + \section1 MainWindow Class Definition + + Using a QSyntaxHighlighter subclass is simple; just provide your + application with an instance of the class and pass it the document + upon which you want the highlighting to be applied. + + \snippet examples/richtext/syntaxhighlighter/mainwindow.h 0 + + In this example we declare a pointer to a \c Highlighter instance + which we later will initialize in the private \c setupEditor() + function. + + \section1 MainWindow Class Implementation + + The constructor of the main window is straight forward. We first + set up the menus, then we initialize the editor and make it the + central widget of the application. Finally we set the main + window's title. + + \snippet examples/richtext/syntaxhighlighter/mainwindow.cpp 0 + + We initialize and install the \c Highlighter object in the private + setupEditor() convenience function: + + \snippet examples/richtext/syntaxhighlighter/mainwindow.cpp 1 + + First we create the font we want to use in the editor, then we + create the editor itself which is an instance of the QTextEdit + class. Before we initialize the editor with the \c MainWindow + class definition file, we create a \c Highlighter instance passing + the editor's document as argument. This is the document that the + highlighting will be applied to. Then we are done. + + A QSyntaxHighlighter object can only be installed on one document + at the time, but you can easily reinstall the highlighter on + another document using the QSyntaxHighlighter::setDocument() + function. The QSyntaxHighlighter class also provides the \l + {QSyntaxHighlighter::document()}{document()} function which + returns the currently set document. +*/ diff --git a/doc/src/examples/systray.qdoc b/doc/src/examples/systray.qdoc new file mode 100644 index 0000000..62bc05c --- /dev/null +++ b/doc/src/examples/systray.qdoc @@ -0,0 +1,197 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example desktop/systray + \title System Tray Icon Example + + + The System Tray Icon example shows how to add an icon with a menu + and popup messages to a desktop environment's system tray. + + \image systemtray-example.png Screenshot of the System Tray Icon. + + Modern operating systems usually provide a special area on the + desktop, called the system tray or notification area, where + long-running applications can display icons and short messages. + + This example consists of one single class, \c Window, providing + the main application window (i.e., an editor for the system tray + icon) and the associated icon. + + \image systemtray-editor.png + + The editor allows the user to choose the preferred icon as well as + set the balloon message's type and duration. The user can also + edit the message's title and body. Finally, the editor provide a + checkbox controlling whether the icon is actually shown in the + system tray, or not. + + \section1 Window Class Definition + + The \c Window class inherits QWidget: + + \snippet examples/desktop/systray/window.h 0 + + We implement several private slots to respond to user + interaction. The other private functions are only convenience + functions provided to simplify the constructor. + + The tray icon is an instance of the QSystemTrayIcon class. To + check whether a system tray is present on the user's desktop, call + the static QSystemTrayIcon::isSystemTrayAvailable() + function. Associated with the icon, we provide a menu containing + the typical \gui minimize, \gui maximize, \gui restore and \gui + quit actions. We reimplement the QWidget::setVisible() function to + update the tray icon's menu whenever the editor's appearance + changes, e.g., when maximizing or minimizing the main application + window. + + Finally, we reimplement QWidget's \l {QWidget::}{closeEvent()} + function to be able to inform the user (when closing the editor + window) that the program will keep running in the system tray + until the user chooses the \gui Quit entry in the icon's context + menu. + + \section1 Window Class Implementation + + When constructing the editor widget, we first create the various + editor elements before we create the actual system tray icon: + + \snippet examples/desktop/systray/window.cpp 0 + + We ensure that the application responds to user input by + connecting most of the editor's input widgets (including the + system tray icon) to the application's private slots. But note the + visibility checkbox; its \l {QCheckBox::}{toggled()} signal is + connected to the \e {icon}'s \l {QSystemTrayIcon::}{setVisible()} + function instead. + + \snippet examples/desktop/systray/window.cpp 3 + + The \c setIcon() slot is triggered whenever the current index in + the icon combobox changes, i.e., whenever the user chooses another + icon in the editor. Note that it is also called when the user + activates the tray icon with the left mouse button, triggering the + icon's \l {QSystemTrayIcon::}{activated()} signal. We will come + back to this signal shortly. + + The QSystemTrayIcon::setIcon() function sets the \l + {QSystemTrayIcon::}{icon} property that holds the actual system + tray icon. On Windows, the system tray icon size is 16x16; on X11, + the preferred size is 22x22. The icon will be scaled to the + appropriate size as necessary. + + Note that on X11, due to a limitation in the system tray + specification, mouse clicks on transparent areas in the icon are + propagated to the system tray. If this behavior is unacceptable, + we suggest using an icon with no transparency. + + \snippet examples/desktop/systray/window.cpp 4 + + Whenever the user activates the system tray icon, it emits its \l + {QSystemTrayIcon::}{activated()} signal passing the triggering + reason as parameter. QSystemTrayIcon provides the \l + {QSystemTrayIcon::}{ActivationReason} enum to describe how the + icon was activated. + + In the constructor, we connected our icon's \l + {QSystemTrayIcon::}{activated()} signal to our custom \c + iconActivated() slot: If the user has clicked the icon using the + left mouse button, this function changes the icon image by + incrementing the icon combobox's current index, triggering the \c + setIcon() slot as mentioned above. If the user activates the icon + using the middle mouse button, it calls the custom \c + showMessage() slot: + + \snippet examples/desktop/systray/window.cpp 5 + + When the \e showMessage() slot is triggered, we first retrieve the + message icon depending on the currently chosen message type. The + QSystemTrayIcon::MessageIcon enum describes the icon that is shown + when a balloon message is displayed. Then we call + QSystemTrayIcon's \l {QSystemTrayIcon::}{showMessage()} function + to show the message with the title, body, and icon for the time + specified in milliseconds. + + Mac OS X users note: The Growl notification system must be + installed for QSystemTrayIcon::showMessage() to display messages. + + QSystemTrayIcon also has the corresponding, \l {QSystemTrayIcon::} + {messageClicked()} signal, which is emitted when the user clicks a + message displayed by \l {QSystemTrayIcon::}{showMessage()}. + + \snippet examples/desktop/systray/window.cpp 6 + + In the constructor, we connected the \l + {QSystemTrayIcon::}{messageClicked()} signal to our custom \c + messageClicked() slot that simply displays a message using the + QMessageBox class. + + QMessageBox provides a modal dialog with a short message, an icon, + and buttons laid out depending on the current style. It supports + four severity levels: "Question", "Information", "Warning" and + "Critical". The easiest way to pop up a message box in Qt is to + call one of the associated static functions, e.g., + QMessageBox::information(). + + As we mentioned earlier, we reimplement a couple of QWidget's + virtual functions: + + \snippet examples/desktop/systray/window.cpp 1 + + Our reimplementation of the QWidget::setVisible() function updates + the tray icon's menu whenever the editor's appearance changes, + e.g., when maximizing or minimizing the main application window, + before calling the base class implementation. + + \snippet examples/desktop/systray/window.cpp 2 + + We have reimplemented the QWidget::closeEvent() event handler to + receive widget close events, showing the above message to the + users when they are closing the editor window. + + In addition to the functions and slots discussed above, we have + also implemented several convenience functions to simplify the + constructor: \c createIconGroupBox(), \c createMessageGroupBox(), + \c createActions() and \c createTrayIcon(). See the \l + {desktop/systray/window.cpp}{window.cpp} file for details. +*/ diff --git a/doc/src/examples/tabdialog.qdoc b/doc/src/examples/tabdialog.qdoc new file mode 100644 index 0000000..c9500af --- /dev/null +++ b/doc/src/examples/tabdialog.qdoc @@ -0,0 +1,148 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/tabdialog + \title Tab Dialog Example + + The Tab Dialog example shows how to construct a tab dialog using the + QTabWidget class. + + Dialogs provide an efficient way for the application to communicate + with the user, but complex dialogs suffer from the problem that they + often take up too much screen area. By using a number of tabs in a + dialog, information can be split into different categories, while + remaining accessible. + + \image tabdialog-example.png + + The Tab Dialog example consists of a single \c TabDialog class that + provides three tabs, each containing information about a particular + file, and two standard push buttons that are used to accept or reject + the contents of the dialog. + + \section1 TabDialog Class Definition + + The \c TabDialog class is a subclass of QDialog that displays a + QTabWidget and two standard dialog buttons. The class definition + only contain the class constructor and a private data member for + the QTabWidget: + + \snippet examples/dialogs/tabdialog/tabdialog.h 3 + + In the example, the widget will be used as a top-level window, but + we define the constructor so that it can take a parent widget. This + allows the dialog to be centered on top of an application's main + window. + + \section1 TabDialog Class Implementation + + The constructor calls the QDialog constructor and creates a QFileInfo + object for the specified filename. + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 0 + + The tab widget is populated with three custom widgets that each + contain information about the file. We construct each of these + without a parent widget because the tab widget will reparent + them as they are added to it. + + We create two standard push buttons, and connect each of them to + the appropriate slots in the dialog: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 1 + \snippet examples/dialogs/tabdialog/tabdialog.cpp 3 + + We arrange the the tab widget above the buttons in the dialog: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 4 + + Finally, we set the dialog's title: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 5 + + Each of the tabs are subclassed from QWidget, and only provide + constructors. + + \section1 GeneralTab Class Definition + + The GeneralTab widget definition is simple because we are only interested + in displaying the contents of a widget within a tab: + + \snippet examples/dialogs/tabdialog/tabdialog.h 0 + + \section1 GeneralTab Class Implementation + + The GeneralTab widget simply displays some information about the file + passed by the TabDialog. Various widgets for this purpose, and these + are arranged within a vertical layout: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 6 + + \section1 PermissionsTab Class Definition + + Like the GeneralTab, the PermissionsTab is just used as a placeholder + widget for its children: + + \snippet examples/dialogs/tabdialog/tabdialog.h 1 + + \section1 PermissionsTab Class Implementation + + The PermissionsTab shows information about the file's access information, + displaying details of the file permissions and owner in widgets that are + arranged in nested layouts: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 7 + + \section1 ApplicationsTab Class Definition + + The ApplicationsTab is another placeholder widget that is mostly + cosmetic: + + \snippet examples/dialogs/tabdialog/tabdialog.h 2 + + \section1 ApplicationsTab Class Implementation + + The ApplicationsTab does not show any useful information, but could be + used as a template for a more complicated example: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 8 +*/ diff --git a/doc/src/examples/tablemodel.qdoc b/doc/src/examples/tablemodel.qdoc new file mode 100644 index 0000000..e3d4a22 --- /dev/null +++ b/doc/src/examples/tablemodel.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/tablemodel + \title Table Model Example + + The Table Model example shows how to use a specialized SQL table model with table + views to edit information in a database. + + \image tablemodel-example.png +*/ diff --git a/doc/src/examples/tablet.qdoc b/doc/src/examples/tablet.qdoc new file mode 100644 index 0000000..476bba1 --- /dev/null +++ b/doc/src/examples/tablet.qdoc @@ -0,0 +1,380 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/tablet + \title Tablet Example + + This example shows how to use a Wacom tablet in Qt applications. + + \image tabletexample.png + + When you use a tablet with Qt applications, \l{QTabletEvent}s are + genarated. You need to reimplement the + \l{QWidget::}{tabletEvent()} event handler if you want to handle + tablet events. Events are generated when the device used for + drawing enters and leaves the proximity of the tablet (i.e., when + it is close but not pressed down on it), when a device is pushed + down and released from it, and when a device is moved on the + tablet. + + The information available in QTabletEvent depends on the device + used. The tablet in this example has two different devices for + drawing: a stylus and an airbrush. For both devices the event + contains the position of the device, pressure on the tablet, + vertical tilt, and horizontal tilt (i.e, the angle between the + device and the perpendicular of the tablet). The airbrush has a + finger wheel; the position of this is also available in the tablet + event. + + In this example we implement a drawing program. You can use the + stylus to draw on the tablet as you use a pencil on paper. When + you draw with the airbrush you get a spray of paint; the finger + wheel is used to change the density of the spray. The pressure and + tilt can change the alpha and saturation values of the QColor and the + width of the QPen used for drawing. + + The example consists of the following: + + \list + \o The \c MainWindow class inherits QMainWindow and creates + the examples menus and connect their slots and signals. + \o The \c TabletCanvas class inherits QWidget and + receives tablet events. It uses the events to paint on a + QImage, which it draws onto itself. + \o The \c TabletApplication class inherits QApplication. This + class handles tablet events that are not sent to \c tabletEvent(). + We will look at this later. + \o The \c main() function creates a \c MainWindow and shows it + as a top level window. + \endlist + + + \section1 MainWindow Class Definition + + The \c MainWindow creates a \c TabletCanvas and sets it as its + center widget. + + \snippet examples/widgets/tablet/mainwindow.h 0 + + The QActions let the user select if the tablets pressure and + tilt should change the pen width, color alpha component and color + saturation. \c createActions() creates all actions, and \c + createMenus() sets up the menus with the actions. We have one + QActionGroup for the actions that alter the alpha channel, color + saturation and line width respectively. The action groups are + connected to the \c alphaActionTriggered(), \c + colorSaturationActiontriggered(), and \c + lineWidthActionTriggered() slots, which calls functions in \c + myCanvas. + + + \section1 MainWindow Class Implementation + + We start width a look at the constructor \c MainWindow(): + + \snippet examples/widgets/tablet/mainwindow.cpp 0 + + In the constructor we create the canvas, actions, and menus. + We set the canvas as the center widget. We also initialize the + canvas to match the state of our menus and start drawing with a + red color. + + Here is the implementation of \c brushColorAct(): + + \snippet examples/widgets/tablet/mainwindow.cpp 1 + + We let the user pick a color with a QColorDialog. If it is valid, + we set a new drawing color with \c setColor(). + + Here is the implementation of \c alphaActionTriggered(): + + \snippet examples/widgets/tablet/mainwindow.cpp 2 + + The \c TabletCanvas class supports two ways by which the alpha + channel of the drawing color can be changed: tablet pressure and + tilt. We have one action for each and an action if the alpha + channel should not be changed. + + Here is the implementation of \c lineWidthActionTriggered(): + + \snippet examples/widgets/tablet/mainwindow.cpp 3 + + We check which action is selected in \c lineWidthGroup, and set + how the canvas should change the drawing line width. + + Here is the implementation of \c saturationActionTriggered(): + + \snippet examples/widgets/tablet/mainwindow.cpp 4 + + We check which action is selected in \c colorSaturationGroup, and + set how the canvas should change the color saturation of the + drawing color. + + Here is the implementation of \c saveAct(): + + \snippet examples/widgets/tablet/mainwindow.cpp 5 + + We use the QFileDialog to let the user select a file to save the + drawing in. It is the \c TabletCanvas that save the drawing, so we + call its \c saveImage() function. + + Here is the implementation of \c loadAct(): + + \snippet examples/widgets/tablet/mainwindow.cpp 6 + + We let the user select the image file to be opened with + a QFileDialog; we then ask the canvas to load the image with \c + loadImage(). + + Here is the implementation of \c aboutAct(): + + \snippet examples/widgets/tablet/mainwindow.cpp 7 + + We show a message box with a short description of the example. + + \c createActions() creates all actions and action groups of + the example. We look at the creation of one action group and its + actions. See the \l{Application Example}{application example} if + you want a high-level introduction to QActions. + + Here is the implementation of \c createActions: + + \snippet examples/widgets/tablet/mainwindow.cpp 8 + \dots + \snippet examples/widgets/tablet/mainwindow.cpp 9 + + We want the user to be able to choose if the drawing color's + alpha component should be changed by the tablet pressure or tilt. + We have one action for each choice and an action if the alpha + channel is not to be changed, i.e, the color is opaque. We make + the actions checkable; the \c alphaChannelGroup will then ensure + that only one of the actions are checked at any time. The \c + triggered() signal is emitted when an action is checked. + + \dots + \snippet examples/widgets/tablet/mainwindow.cpp 10 + + Here is the implementation of \c createMenus(): + + \snippet examples/widgets/tablet/mainwindow.cpp 11 + + We create the menus of the example and add the actions to them. + + + \section1 TabletCanvas Class Definition + + The \c TabletCanvas class provides a surface on which the + user can draw with a tablet. + + \snippet examples/widgets/tablet/tabletcanvas.h 0 + + The canvas can change the alpha channel, color saturation, + and line width of the drawing. We have one enum for each of + these; their values decide if it is the tablet pressure or tilt + that will alter them. We keep a private variable for each, the \c + alphaChannelType, \c colorSturationType, and \c penWidthType, + which we provide access functions for. + + We draw on a QImage with \c myPen and \c myBrush using \c + myColor. The \c saveImage() and \c loadImage() saves and loads + the QImage to disk. The image 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 paintImage(), \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 image, as the default is gray. + + Here is the implementation of \c saveImage(): + + \snippet examples/widgets/tablet/tabletcanvas.cpp 1 + + QImage implements functionality to save itself to disk, so we + simply call \l{QImage::}{save()}. + + Here is the implementation of \c loadImage(): + + \snippet examples/widgets/tablet/tabletcanvas.cpp 2 + + We simply call \l{QImage::}{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 paintImage() 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 image to the top left of the widget. + + Here is the implementation of \c paintImage(): + + \snippet examples/widgets/tablet/tabletcanvas.cpp 5 + + In this function we draw on the image 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. + If it is an airbrush we want to draw a circle of points with a + point density based on the tangential pressure, which is the position + of the finger wheel on the airbrush. We use the Qt::BrushStyle to + draw the points as it has styles that draw points with different + density; we select the style based on the tangential pressure in + \c brushPattern(). + + \snippet examples/widgets/tablet/tabletcanvas.cpp 6 + + We return a brush style with a point density that increases with + the tangential pressure. + + In \c updateBrush() we set the pen and brush used for drawing + to match \c alphaChannelType, \c lineWidthType, \c + colorSaturationType, and \c myColor. We will examine the code to + set up \c myBrush and \c myPen for each of these variables: + + \snippet examples/widgets/tablet/tabletcanvas.cpp 7 + + We fetch the current drawingcolor's hue, saturation, value, + and alpha values. \c hValue and \c vValue are set to the + horizontal and vertical tilt as a number from 0 to 255. The + original values are in degrees from -60 to 60, i.e., 0 equals + -60, 127 equals 0, and 255 equals 60 degrees. The angle measured + is between the device and the perpendicular of the tablet (see + QTabletEvent for an illustration). + + \snippet examples/widgets/tablet/tabletcanvas.cpp 8 + + The alpha channel of QColor is given as a number between 0 + and 255 where 0 is transparent and 255 is opaque. + \l{QTabletEvent::}{pressure()} returns the pressure as a qreal + between 0.0 and 1.0. By subtracting 127 from the tilt values and + taking the absolute value we get the smallest alpha values (i.e., + the color is most transparent) when the pen is perpendicular to + the tablet. We select the largest of the vertical and horizontal + tilt value. + + \snippet examples/widgets/tablet/tabletcanvas.cpp 9 + + The colorsaturation is given as a number between 0 and 255. It is + set with \l{QColor::}{setHsv()}. We can set the tilt values + directly, but must multiply the pressure to a number between 0 and + 255. + + \snippet examples/widgets/tablet/tabletcanvas.cpp 10 + + The width of the pen increases with the pressure. When the pen + width is controlled with the tilt we let the width increse with + the angle between the device and the perpendicular of the tablet. + + \snippet examples/widgets/tablet/tabletcanvas.cpp 11 + + We finally check wether the pointer is the stylus or the eraser. + If it is the eraser, we set the color to the background color of + the image 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/taskmenuextension.qdoc b/doc/src/examples/taskmenuextension.qdoc new file mode 100644 index 0000000..b02da6c --- /dev/null +++ b/doc/src/examples/taskmenuextension.qdoc @@ -0,0 +1,457 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example designer/taskmenuextension + \title Task Menu Extension Example + + The Task Menu Extension example shows how to create a custom + widget plugin for \l {Qt Designer Manual}{\QD}, and how to to use + the QDesignerTaskMenuExtension class to provide custom task menu + entries associated with the plugin. + + \image taskmenuextension-example-faded.png + + To provide a custom widget that can be used with \QD, we need to + supply a self-contained implementation. In this example we use a + custom widget designed to show the task menu extension feature: + The TicTacToe widget. + + An extension is an object which modifies the behavior of \QD. The + QDesignerTaskMenuExtension can provide custom task menu entries + when a widget with this extension is selected. + + There are four available types of extensions in \QD: + + \list + \o QDesignerContainerExtension provides an extension that allows + you to add (and delete) pages to a multi-page container plugin + in \QD. + \o QDesignerMemberSheetExtension provides an extension that allows + you to manipulate a widget's member functions which is displayed + when configuring connections using Qt Designer's mode for editing + signals and slots. + \o QDesignerPropertySheetExtension provides an extension that + allows you to manipulate a widget's properties which is displayed + in Qt Designer's property editor. + \o QDesignerTaskMenuExtension provides an extension that allows + you to add custom menu entries to \QD's task menu. + \endlist + + You can use all the extensions following the same pattern as in + this example, only replacing the respective extension base + class. For more information, see the \l {QtDesigner Module}. + + The Task Menu Extension example consists of five classes: + + \list + \o \c TicTacToe is a custom widget that lets the user play + the Tic-Tac-Toe game. + \o \c TicTacToePlugin exposes the \c TicTacToe class to \QD. + \o \c TicTacToeTaskMenuFactory creates a \c TicTacToeTaskMenu object. + \o \c TicTacToeTaskMenu provides the task menu extension, i.e the + plugin's associated task menu entries. + \o \c TicTacToeDialog lets the user modify the state of a + Tic-Tac-Toe plugin loaded into \QD. + \endlist + + The project file for custom widget plugins needs some additional + information to ensure that they will work within \QD. For example, + custom widget plugins rely on components supplied with \QD, and + this must be specified in the project file that we use. We will + first take a look at the plugin's project file. + + Then we will continue by reviewing the \c TicTacToePlugin class, + and take a look at the \c TicTacToeTaskMenuFactory and \c + TicTacToeTaskMenu classes. Finally, we will review the \c + TicTacToeDialog class before we take a quick look at the \c + TicTacToe widget's class definition. + + \section1 The Project File: taskmenuextension.pro + + The project file must contain some additional information to + ensure that the plugin will work as expected: + + \snippet examples/designer/taskmenuextension/taskmenuextension.pro 0 + \snippet examples/designer/taskmenuextension/taskmenuextension.pro 1 + + The \c TEMPLATE variable's value makes \c qmake create the custom + widget as a library. Later, we will ensure that the widget will be + recognized as a plugin by Qt by using the Q_EXPORT_PLUGIN2() macro to + export the relevant widget information. + + The \c CONFIG variable contains two values, \c designer and \c + plugin: + + \list + \o \c designer: Since custom widgets plugins rely on components + supplied with \QD, this value ensures that our plugin links against + \QD's library (\c libQtDesigner.so). + + \o \c plugin: We also need to ensure that \c qmake considers the + custom widget a \e plugin library. + \endlist + + When Qt is configured to build in both debug and release modes, + \QD will be built in release mode. When this occurs, it is + necessary to ensure that plugins are also built in release + mode. For that reason we add the \c debug_and_release value to + the \c CONFIG variable. Otherwise, if a plugin is built in a mode + that is incompatible with \QD, it won't be loaded and + installed. + + The header and source files for the widget are declared in the + usual way: + + \snippet examples/designer/taskmenuextension/taskmenuextension.pro 2 + + We provide an implementation of the plugin interface so that \QD + can use the custom widget. In this particular example we also + provide implementations of the task menu extension and the + extension factory as well as a dialog implementation. + + It is important to ensure that the plugin is installed in a + location that is searched by \QD. We do this by specifying a + target path for the project and adding it to the list of items to + install: + + \snippet doc/src/snippets/code/doc_src_examples_taskmenuextension.qdoc 0 + + The task menu extension is created as a library, and will be + installed alongside the other \QD plugins when the project is + installed (using \c{make install} or an equivalent installation + procedure). + + Note that if you want the plugins to appear in a Visual Studio + integration, the plugins must be built in release mode and their + libraries must be copied into the plugin directory in the install + path of the integration (for an example, see \c {C:/program + files/trolltech as/visual studio integration/plugins}). + + For more information about plugins, see the \l {How to Create Qt + Plugins} documentation. + + \section1 TicTacToePlugin Class Definition + + The \c TicTacToePlugin class exposes \c the TicTacToe class to + \QD. Its definition is equivalent to the \l + {designer/customwidgetplugin}{Custom Widget Plugin} example's + plugin class which is explained in detail. The only part of the + class definition that is specific to this particular custom widget + is the class name: + + \snippet examples/designer/taskmenuextension/tictactoeplugin.h 0 + + The plugin class provides \QD with basic information about our + plugin, such as its class name and its include file. Furthermore + it knows how to create instances of the \c TicTacToe widget. + TicTacToePlugin also defines the \l + {QDesignerCustomWidgetInterface::initialize()}{initialize()} + function which is called after the plugin is loaded into \QD. The + function's QDesignerFormEditorInterface parameter provides the + plugin with a gateway to all of \QD's API's. + + The \c TicTacToePlugin class inherits from both QObject and + QDesignerCustomWidgetInterface. It is important to remember, when + using multiple inheritance, to ensure that all the interfaces + (i.e. the classes that doesn't inherit Q_OBJECT) are made known to + the meta object system using the Q_INTERFACES() macro. This + enables \QD to use \l qobject_cast() to query for supported + interfaces using nothing but a QObject pointer. + + \section1 TicTacToePlugin Class Implementation + + The TicTacToePlugin class implementation is in most parts + equivalent to the \l {designer/customwidgetplugin}{Custom Widget + Plugin} example's plugin class: + + \snippet examples/designer/taskmenuextension/tictactoeplugin.cpp 0 + + The only function that differs significantly is the initialize() + function: + + \snippet examples/designer/taskmenuextension/tictactoeplugin.cpp 1 + + The \c initialize() function takes a QDesignerFormEditorInterface + object as argument. The QDesignerFormEditorInterface class + provides access to Qt Designer's components. + + In \QD you can create two kinds of plugins: custom widget plugins + and tool plugins. QDesignerFormEditorInterface provides access to + all the \QD components that you normally need to create a tool + plugin: the extension manager, the object inspector, the property + editor and the widget box. Custom widget plugins have access to + the same components. + + \snippet examples/designer/taskmenuextension/tictactoeplugin.cpp 2 + + When creating extensions associated with custom widget plugins, we + need to access \QD's current extension manager which we retrieve + from the QDesignerFormEditorInterface parameter. + + \QD's QDesignerFormEditorInterface holds information about all Qt + Designer's components: The action editor, the object inspector, + the property editor, the widget box, and the extension and form + window managers. + + The QExtensionManager class provides extension management + facilities for \QD. Using \QD's current extension manager you can + retrieve the extension for a given object. You can also register + and unregister an extension for a given object. Remember that an + extension is an object which modifies the behavior of \QD. + + When registrering an extension, it is actually the associated + extension factory that is registered. In \QD, extension factories + are used to look up and create named extensions as they are + required. So, in this example, the task menu extension itself is + not created until a task menu is requested by the user. + + \snippet examples/designer/taskmenuextension/tictactoeplugin.cpp 3 + + We create a \c TicTacToeTaskMenuFactory object that we register + using \QD's current \l {QExtensionManager}{extension manager} + retrieved from the QDesignerFormEditorInterface parameter. The + first argument is the newly created factory and the second + argument is an extension identifier which is a string. The \c + Q_TYPEID() macro simply converts the string into a QLatin1String. + + The \c TicTacToeTaskMenuFactory class is a subclass of + QExtensionFactory. When the user request a task menu by clicking + the right mouse button over a widget with the specified task menu + extension, \QD's extension manager will run through all its + registered factories invoking the first one that is able to create + a task menu extension for the selected widget. This factory will + in turn create a \c TicTacToeTaskMenu object (the extension). + + We omit to reimplement the + QDesignerCustomWidgetInterface::domXml() function (which include + default settings for the widget in the standard XML format used by + Qt Designer), since no default values are necessary. + + \snippet examples/designer/taskmenuextension/tictactoeplugin.cpp 4 + + Finally, we use the Q_EXPORT_PLUGIN2() macro to export the + TicTacToePlugin class for use with Qt's plugin handling classes: + This macro ensures that \QD can access and construct the custom + widget. Without this macro, there is no way for \QD to use the + widget. + + \section1 TicTacToeTaskMenuFactory Class Definition + + The \c TicTacToeTaskMenuFactory class inherits QExtensionFactory + which provides a standard extension factory for \QD. + + \snippet examples/designer/taskmenuextension/tictactoetaskmenu.h 1 + + The subclass's purpose is to reimplement the + QExtensionFactory::createExtension() function, making it able to + create a \c TicTacToe task menu extension. + + \section1 TicTacToeTaskMenuFactory Class Implementation + + The class constructor simply calls the QExtensionFactory base + class constructor: + + \snippet examples/designer/taskmenuextension/tictactoetaskmenu.cpp 4 + + As described above, the factory is invoked when the user request a + task menu by clicking the right mouse button over a widget with + the specified task menu extension in \QD. + + \QD's behavior is the same whether the requested extension is + associated with a container, a member sheet, a property sheet or a + task menu: Its extension manager runs through all its registered + extension factories calling \c createExtension() for each until + one responds by creating the requested extension. + + \snippet examples/designer/taskmenuextension/tictactoetaskmenu.cpp 5 + + So the first thing we do in \c + TicTacToeTaskMenuFactory::createExtension() is to check if the + requested extension is a task menu extension. If it is, and the + widget requesting it is a \c TicTacToe widget, we create and + return a \c TicTacToeTaskMenu object. Otherwise, we simply return + a null pointer, allowing \QD's extension manager to continue its + search through the registered factories. + + + \section1 TicTacToeTaskMenu Class Definition + + \image taskmenuextension-menu.png + + The \c TicTacToeTaskMenu class inherits QDesignerTaskMenuExtension + which allows you to add custom entries (in the form of QActions) + to the task menu in \QD. + + \snippet examples/designer/taskmenuextension/tictactoetaskmenu.h 0 + + We reimplement the \c preferredEditAction() and \c taskActions() + functions. Note that we implement a constructor that takes \e two + arguments: the parent widget, and the \c TicTacToe widget for + which the task menu is requested. + + In addition we declare the private \c editState() slot, our custom + \c editStateAction and a private pointer to the \c TicTacToe + widget which state we want to modify. + + \section1 TicTacToeTaskMenu Class Implementation + + \snippet examples/designer/taskmenuextension/tictactoetaskmenu.cpp 0 + + In the constructor we first save the reference to the \c TicTacToe + widget sent as parameter, i.e the widget which state we want to + modify. We will need this later when our custom action is + invoked. We also create our custom \c editStateAction and connect + it to the \c editState() slot. + + \snippet examples/designer/taskmenuextension/tictactoetaskmenu.cpp 1 + + The \c editState() slot is called whenever the user chooses the + \gui {Edit State...} option in a \c TicTacToe widget's task menu. The + slot creates a \c TicTacToeDialog presenting the current state of + the widget, and allowing the user to edit its state by playing the + game. + + \snippet examples/designer/taskmenuextension/tictactoetaskmenu.cpp 2 + + We reimplement the \c preferredEditAction() function to return our + custom \c editStateAction as the action that should be invoked + when selecting a \c TicTacToe widget and pressing \key F2 . + + \snippet examples/designer/taskmenuextension/tictactoetaskmenu.cpp 3 + + We reimplement the \c taskActions() function to return a list of + our custom actions making these appear on top of the default menu + entries in a \c TicTacToe widget's task menu. + + \section1 TicTacToeDialog Class Definition + + \image taskmenuextension-dialog.png + + The \c TicTacToeDialog class inherits QDialog. The dialog lets the + user modify the state of the currently selected Tic-Tac-Toe + plugin. + + \snippet examples/designer/taskmenuextension/tictactoedialog.h 0 + + We reimplement the \c sizeHint() function. We also declare two + private slots: \c resetState() and \c saveState(). In addition to + the dialog's buttons and layouts we declare two \c TicTacToe + pointers, one to the widget the user can interact with and the + other to the original custom widget plugin which state the user + wants to edit. + + \section1 TicTacToeDialog Class Implementation + + \snippet examples/designer/taskmenuextension/tictactoedialog.cpp 0 + + In the constructor we first save the reference to the TicTacToe + widget sent as parameter, i.e the widget which state the user want + to modify. Then we create a new \c TicTacToe widget, and set its + state to be equivalent to the parameter widget's state. + + Finally, we create the dialog's buttons and layout. + + \snippet examples/designer/taskmenuextension/tictactoedialog.cpp 1 + + We reimplement the \c sizeHint() function to ensure that the + dialog is given a reasonable size. + + \snippet examples/designer/taskmenuextension/tictactoedialog.cpp 2 + + The \c resetState() slot is called whenever the user press the + \gui Reset button. The only thing we do is to call the \c + clearBoard() function for the editor widget, i.e. the \c TicTacToe + widget we created in the dialog's constructor. + + \snippet examples/designer/taskmenuextension/tictactoedialog.cpp 3 + + The \c saveState() slot is called whenever the user press the \gui + OK button, and transfers the state of the editor widget to the + widget which state we want to modify. In order to make the change + of state visible to \QD we need to set the latter widget's state + property using the QDesignerFormWindowInterface class. + + QDesignerFormWindowInterface provides you with information about + the associated form window as well as allowing you to alter its + properties. The interface is not intended to be instantiated + directly, but to provide access to Qt Designer's current form + windows controlled by Qt Designer's form window manager. + + If you are looking for the form window containing a specific + widget, you can use the static + QDesignerFormWindowInterface::findFormWindow() function: + + \snippet examples/designer/taskmenuextension/tictactoedialog.cpp 4 + + After retrieving the form window of the widget (which state we + want to modify), we use the QDesignerFormWindowInterface::cursor() + function to retrieve the form window's cursor. + + The QDesignerFormWindowCursorInterface class provides an interface + to the form window's text cursor. Once we have cursor, we can + finally set the state property using the + QDesignerFormWindowCursorInterface::setProperty() function. + + \snippet examples/designer/taskmenuextension/tictactoedialog.cpp 5 + + In the end we call the QEvent::accept() function which sets the + accept flag of the event object. Setting the \c accept parameter + indicates that the event receiver wants the event. Unwanted events + might be propagated to the parent widget. + + \section1 TicTacToe Class Definition + + The \c TicTacToe class is a custom widget that lets the user play + the Tic-Tac-Toe game. + + \snippet examples/designer/taskmenuextension/tictactoe.h 0 + + The main details to observe in the \c TicTacToe class defintion is + the declaration of the \c state property and its \c state() and \c + setState() functions. + + We need to declare the \c TicTacToe widget's state as a property + to make it visible to \QD; allowing \QD to manage it in the same + way it manages the properties the \c TicTacToe widget inherits + from QWidget and QObject, for example featuring the property + editor. +*/ diff --git a/doc/src/examples/tetrix.qdoc b/doc/src/examples/tetrix.qdoc new file mode 100644 index 0000000..b9adb98 --- /dev/null +++ b/doc/src/examples/tetrix.qdoc @@ -0,0 +1,445 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/tetrix + \title Tetrix Example + + The Tetrix example is a Qt version of the classic Tetrix game. + + \image tetrix-example.png + + The object of the game is to stack pieces dropped from the top of the + playing area so that they fill entire rows at the bottom of the playing area. + + When a row is filled, all the blocks on that row are removed, the player earns + a number of points, and the pieces above are moved down to occupy that row. + If more than one row is filled, the blocks on each row are removed, and the + player earns extra points. + + The \gui{Left} cursor key moves the current piece one space to the left, the + \gui{Right} cursor key moves it one space to the right, the \gui{Up} cursor + key rotates the piece counter-clockwise by 90 degrees, and the \gui{Down} + cursor key rotates the piece clockwise by 90 degrees. + + To avoid waiting for a piece to fall to the bottom of the board, press \gui{D} + to immediately move the piece down by one row, or press the \gui{Space} key to + drop it as close to the bottom of the board as possible. + + This example shows how a simple game can be created using only three classes: + + \list + \o The \c TetrixWindow class is used to display the player's score, number of + lives, and information about the next piece to appear. + \o The \c TetrixBoard class contains the game logic, handles keyboard input, and + displays the pieces on the playing area. + \o The \c TetrixPiece class contains information about each piece. + \endlist + + In this approach, the \c TetrixBoard class is the most complex class, since it + handles the game logic and rendering. One benefit of this is that the + \c TetrixWindow and \c TetrixPiece classes are very simple and contain only a + minimum of code. + + \section1 TetrixWindow Class Definition + + The \c TetrixWindow class is used to display the game information and contains + the playing area: + + \snippet examples/widgets/tetrix/tetrixwindow.h 0 + + We use private member variables for the board, various display widgets, and + buttons to allow the user to start a new game, pause the current game, and quit. + + Although the window inherits QWidget, the constructor does not provide an + argument to allow a parent widget to be specified. This is because the window + will always be used as a top-level widget. + + \section1 TetrixWindow Class Implementation + + The constructor sets up the user interface elements for the game: + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 0 + + We begin by constructing a \c TetrixBoard instance for the playing area and a + label that shows the next piece to be dropped into the playing area; the label + is initially empty. + + Three QLCDNumber objects are used to display the score, number of lives, and + lines removed. These initially show default values, and will be filled in + when a game begins: + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 1 + + Three buttons with shortcuts are constructed so that the user can start a + new game, pause the current game, and quit the application: + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 2 + \snippet examples/widgets/tetrix/tetrixwindow.cpp 3 + + These buttons are configured so that they never receive the keyboard focus; + we want the keyboard focus to remain with the \c TetrixBoard instance so that + it receives all the keyboard events. Nonetheless, the buttons will still respond + to \key{Alt} key shortcuts. + + We connect \l{QAbstractButton::}{clicked()} signals from the \gui{Start} + and \gui{Pause} buttons to the board, and from the \gui{Quit} button to the + application's \l{QApplication::}{quit()} slot. + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 4 + \snippet examples/widgets/tetrix/tetrixwindow.cpp 5 + + Signals from the board are also connected to the LCD widgets for the purpose of + updating the score, number of lives, and lines removed from the playing area. + + We place the label, LCD widgets, and the board into a QGridLayout + along with some labels that we create with the \c createLabel() convenience + function: + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 6 + + Finally, we set the grid layout on the widget, give the window a title, and + resize it to an appropriate size. + + The \c createLabel() convenience function simply creates a new label on the + heap, gives it an appropriate alignment, and returns it to the caller: + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 7 + + Since each label will be used in the widget's layout, it will become a child + of the \c TetrixWindow widget and, as a result, it will be deleted when the + window is deleted. + + \section1 TetrixPiece Class Definition + + The \c TetrixPiece class holds information about a piece in the game's + playing area, including its shape, position, and the range of positions it can + occupy on the board: + + \snippet examples/widgets/tetrix/tetrixpiece.h 0 + + Each shape contains four blocks, and these are defined by the \c coords private + member variable. Additionally, each piece has a high-level description that is + stored internally in the \c pieceShape variable. + + The constructor is written inline in the definition, and simply ensures that + each piece is initially created with no shape. The \c shape() function simply + returns the contents of the \c pieceShape variable, and the \c x() and \c y() + functions return the x and y-coordinates of any given block in the shape. + + \section1 TetrixPiece Class Implementation + + The \c setRandomShape() function is used to select a random shape for a piece: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 0 + + For convenience, it simply chooses a random shape from the \c TetrixShape enum + and calls the \c setShape() function to perform the task of positioning the + blocks. + + The \c setShape() function uses a look-up table of pieces to associate each + shape with an array of block positions: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 1 + \snippet examples/widgets/tetrix/tetrixpiece.cpp 2 + + These positions are read from the table into the piece's own array of positions, + and the piece's internal shape information is updated to use the new shape. + + The \c x() and \c y() functions are implemented inline in the class definition, + returning positions defined on a grid that extends horizontally and vertically + with coordinates from -2 to 2. Although the predefined coordinates for each + piece only vary horizontally from -1 to 1 and vertically from -1 to 2, each + piece can be rotated by 90, 180, and 270 degrees. + + The \c minX() and \c maxX() functions return the minimum and maximum horizontal + coordinates occupied by the blocks that make up the piece: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 3 + \snippet examples/widgets/tetrix/tetrixpiece.cpp 4 + + Similarly, the \c minY() and \c maxY() functions return the minimum and maximum + vertical coordinates occupied by the blocks: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 5 + \snippet examples/widgets/tetrix/tetrixpiece.cpp 6 + + The \c rotatedLeft() function returns a new piece with the same shape as an + existing piece, but rotated counter-clockwise by 90 degrees: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 7 + + Similarly, the \c rotatedRight() function returns a new piece with the same + shape as an existing piece, but rotated clockwise by 90 degrees: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 9 + + These last two functions enable each piece to create rotated copies of itself. + + \section1 TetrixBoard Class Definition + + The \c TetrixBoard class inherits from QFrame and contains the game logic and display features: + + \snippet examples/widgets/tetrix/tetrixboard.h 0 + + Apart from the \c setNextPieceLabel() function and the \c start() and \c pause() + public slots, we only provide public functions to reimplement QWidget::sizeHint() + and QWidget::minimumSizeHint(). The signals are used to communicate changes to + the player's information to the \c TetrixWindow instance. + + The rest of the functionality is provided by reimplementations of protected event + handlers and private functions: + + \snippet examples/widgets/tetrix/tetrixboard.h 1 + + The board is composed of a fixed-size array whose elements correspond to + spaces for individual blocks. Each element in the array contains a \c TetrixShape + value corresponding to the type of shape that occupies that element. + + Each shape on the board will occupy four elements in the array, and these will + all contain the enum value that corresponds to the type of the shape. + + We use a QBasicTimer to control the rate at which pieces fall toward the bottom + of the playing area. This allows us to provide an implementation of + \l{QObject::}{timerEvent()} that we can use to update the widget. + + \section1 TetrixBoard Class Implementation + + In the constructor, we customize the frame style of the widget, ensure that + keyboard input will be received by the widget by using Qt::StrongFocus for the + focus policy, and initialize the game state: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 0 + + The first (next) piece is also set up with a random shape. + + The \c setNextPieceLabel() function is used to pass in an externally-constructed + label to the board, so that it can be shown alongside the playing area: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 1 + + We provide a reasonable size hint and minimum size hint for the board, based on + the size of the space for each block in the playing area: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 2 + \snippet examples/widgets/tetrix/tetrixboard.cpp 3 + + By using a minimum size hint, we indicate to the layout in the parent widget + that the board should not shrink below a minimum size. + + A new game is started when the \c start() slot is called. This resets the + game's state, the player's score and level, and the contents of the board: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 4 + + We also emit signals to inform other components of these changes before creating + a new piece that is ready to be dropped into the playing area. We start the + timer that determines how often the piece drops down one row on the board. + + The \c pause() slot is used to temporarily stop the current game by stopping the + internal timer: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 5 + \snippet examples/widgets/tetrix/tetrixboard.cpp 6 + + We perform checks to ensure that the game can only be paused if it is already + running and not already paused. + + The \c paintEvent() function is straightforward to implement. We begin by + calling the base class's implementation of \l{QWidget::}{paintEvent()} before + constructing a QPainter for use on the board: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 7 + + Since the board is a subclass of QFrame, we obtain a QRect that covers the area + \e inside the frame decoration before drawing our own content. + + If the game is paused, we want to hide the existing state of the board and + show some text. We achieve this by painting text onto the widget and returning + early from the function. The rest of the painting is performed after this point. + + The position of the top of the board is found by subtracting the total height + of each space on the board from the bottom of the frame's internal rectangle. + For each space on the board that is occupied by a piece, we call the + \c drawSquare() function to draw a block at that position. + + \snippet examples/widgets/tetrix/tetrixboard.cpp 8 + \snippet examples/widgets/tetrix/tetrixboard.cpp 9 + + Spaces that are not occupied by blocks are left blank. + + Unlike the existing pieces on the board, the current piece is drawn + block-by-block at its current position: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 10 + \snippet examples/widgets/tetrix/tetrixboard.cpp 11 + \snippet examples/widgets/tetrix/tetrixboard.cpp 12 + + The \c keyPressEvent() handler is called whenever the player presses a key while + the \c TetrixBoard widget has the keyboard focus. + + \snippet examples/widgets/tetrix/tetrixboard.cpp 13 + + If there is no current game, the game is running but paused, or if there is no + current shape to control, we simply pass on the event to the base class. + + We check whether the event is about any of the keys that the player uses to + control the current piece and, if so, we call the relevant function to handle + the input: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 14 + + In the case where the player presses a key that we are not interested in, we + again pass on the event to the base class's implementation of + \l{QWidget::}{keyPressEvent()}. + + The \c timerEvent() handler is called every time the class's QBasicTimer + instance times out. We need to check that the event we receive corresponds to + our timer. If it does, we can update the board: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 15 + \snippet examples/widgets/tetrix/tetrixboard.cpp 16 + \snippet examples/widgets/tetrix/tetrixboard.cpp 17 + + If a row (or line) has just been filled, we create a new piece and reset the + timer; otherwise we move the current piece down by one row. We let the base + class handle other timer events that we receive. + + The \c clearBoard() function simply fills the board with the + \c TetrixShape::NoShape value: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 18 + + The \c dropDown() function moves the current piece down as far as possible on + the board, either until it is touching the bottom of the playing area or it is + stacked on top of another piece: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 19 + \snippet examples/widgets/tetrix/tetrixboard.cpp 20 + + The number of rows the piece has dropped is recorded and passed to the + \c pieceDropped() function so that the player's score can be updated. + + The \c oneLineDown() function is used to move the current piece down by one row + (line), either when the user presses the \gui{D} key or when the piece is + scheduled to move: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 21 + + If the piece cannot drop down by one line, we call the \c pieceDropped() function + with zero as the argument to indicate that it cannot fall any further, and that + the player should receive no extra points for the fall. + + The \c pieceDropped() function itself is responsible for awarding points to the + player for positioning the current piece, checking for full rows on the board + and, if no lines have been removed, creating a new piece to replace the current + one: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 22 + \snippet examples/widgets/tetrix/tetrixboard.cpp 23 + + We call \c removeFullLines() each time a piece has been dropped. This scans + the board from bottom to top, looking for blank spaces on each row. + + \snippet examples/widgets/tetrix/tetrixboard.cpp 24 + \snippet examples/widgets/tetrix/tetrixboard.cpp 25 + \snippet examples/widgets/tetrix/tetrixboard.cpp 26 + \snippet examples/widgets/tetrix/tetrixboard.cpp 27 + + If a row contains no blank spaces, the rows above it are copied down by one row + to compress the stack of pieces, the top row on the board is cleared, and the + number of full lines found is incremented. + + \snippet examples/widgets/tetrix/tetrixboard.cpp 28 + \snippet examples/widgets/tetrix/tetrixboard.cpp 29 + + If some lines have been removed, the player's score and the total number of lines + removed are updated. The \c linesRemoved() and \c scoreChanged() signals are + emitted to send these new values to other widgets in the window. + + Additionally, we set the timer to elapse after half a second, set the + \c isWaitingAfterLine flag to indicate that lines have been removed, unset + the piece's shape to ensure that it is not drawn, and update the widget. + The next time that the \c timerEvent() handler is called, a new piece will be + created and the game will continue. + + The \c newPiece() function places the next available piece at the top of the + board, and creates a new piece with a random shape: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 30 + \snippet examples/widgets/tetrix/tetrixboard.cpp 31 + + We place a new piece in the middle of the board at the top. The game is over if + the piece can't move, so we unset its shape to prevent it from being drawn, stop + the timer, and unset the \c isStarted flag. + + The \c showNextPiece() function updates the label that shows the next piece to + be dropped: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 32 + \snippet examples/widgets/tetrix/tetrixboard.cpp 33 + + We draw the piece's component blocks onto a pixmap that is then set on the label. + + The \c tryMove() function is used to determine whether a piece can be positioned + at the specified coordinates: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 34 + + We examine the spaces on the board that the piece needs to occupy and, if they + are already occupied by other pieces, we return \c false to indicate that the + move has failed. + + \snippet examples/widgets/tetrix/tetrixboard.cpp 35 + + If the piece could be placed on the board at the desired location, we update the + current piece and its position, update the widget, and return \c true to indicate + success. + + The \c drawSquare() function draws the blocks (normally squares) that make up + each piece using different colors for pieces with different shapes: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 36 + + We obtain the color to use from a look-up table that relates each shape to an + RGB value, and use the painter provided to draw the block at the specified + coordinates. +*/ diff --git a/doc/src/examples/textfinder.qdoc b/doc/src/examples/textfinder.qdoc new file mode 100644 index 0000000..2eea15d --- /dev/null +++ b/doc/src/examples/textfinder.qdoc @@ -0,0 +1,173 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example uitools/textfinder + \title Text Finder Example + + The Text Finder example demonstrates how to dynamically process forms + using the QtUiTools module. Dynamic form processing enables a form to + be processed at run-time only by changing the .ui file for the project. + The program allows the user to look up a particular word within the + contents of a text file. This text file is included in the project's + resource and is loaded into the display at startup. + + \table + \row \o \inlineimage textfinder-example-find.png + \o \inlineimage textfinder-example-find2.png + \endtable + + \section1 Setting Up The Resource File + + The resources required for Text Finder are: + \list + \o \e{textfinder.ui} - the user interface file created in QtDesigner + \o \e{input.txt} - a text file containing some text to be displayed + in the QTextEdit + \endlist + + \e{textfinder.ui} contains all the necessary QWidget objects for the + Text Finder. A QLineEdit is used for the user input, a QTextEdit is + used to display the contents of \e{input.txt}, a QLabel is used to + display the text "Keyword", and a QPushButton is used for the "Find" + button. The screenshot below shows the preview obtained in QtDesigner. + + \image textfinder-example-userinterface.png + + A \e{textfinder.qrc} file is used to store both the \e{textfinder.ui} + and \e{input.txt} in the application's executable. The file contains + the following code: + + \quotefile examples/uitools/textfinder/textfinder.qrc + + For more information on resource files, see \l{The Qt Resource System}. + + To generate a form at run-time, the example is linked against the + QtUiTools module library. This is done in the \c{textfinder.pro} file + that contains the following lines: + + \snippet doc/src/snippets/code/doc_src_examples_textfinder.qdoc 0 + + \section1 TextFinder Class Definition + + The \c TextFinder class is a subclass of QWidget and it hosts the + \l{QWidget}s we need to access in the user interface. The QLabel in the + user interface is not declared here as we do not need to access it. + + \snippet examples/uitools/textfinder/textfinder.h 0 + + The slot \c{on_find_Button_clicked()} is a slot named according to the + \l{Using a Designer .ui File in Your Application#Automatic Connections} + {Automatic Connection} naming convention required + by \c uic. + + \section1 TextFinder Class Implementation + + The \c TextFinder class's constructor calls the \c loadUiFile() function + and then uses \c qFindChild() to access the user interface's + \l{QWidget}s. + + \snippet examples/uitools/textfinder/textfinder.cpp 0 + + We then use QMetaObject's system to enable signal and slot connections. + + \snippet examples/uitools/textfinder/textfinder.cpp 2 + + The loadTextFile() function is called to load \c{input.txt} into + QTextEdit to displays its contents. + + \snippet examples/uitools/textfinder/textfinder.cpp 3a + + The \c{TextFinder}'s layout is set with \l{QWidget::}{setLayout()}. + + \snippet examples/uitools/textfinder/textfinder.cpp 3b + + Finally, the window title is set to \e {Text Finder} and \c isFirstTime is + set to true. + + \c isFirstTime is used as a flag to indicate whether the search operation + has been performed more than once. This is further explained with the + \c{on_findButton_clicked()} function. + + The \c{loadUiFile()} function is used to load the user interface file + previously created in QtDesigner. The QUiLoader class is instantiated + and its \c load() function is used to load the form into \c{formWidget} + that acts as a place holder for the user interface. The function then + returns \c{formWidget} to its caller. + + \snippet examples/uitools/textfinder/textfinder.cpp 4 + + As mentioned earlier, the loadTextFile() function loads \e{input.txt} + into QTextEdit to display its contents. Data is read using QTextStream + into a QString object, \c line with the QTextStream::readAll() function. + The contents of \c line are then appended to \c{ui_textEdit}. + + \snippet examples/uitools/textfinder/textfinder.cpp 5 + + The \c{on_findButton_clicked()} function is a slot that is connected to + \c{ui_findButton}'s \c clicked() signal. The \c searchString is extracted + from the \c ui_lineEdit and the \c document is extracted from \c textEdit. + In event there is an empty \c searchString, a QMessageBox is used, + requesting the user to enter a word. Otherwise, we traverse through the + words in \c ui_textEdit, and highlight all ocurrences of the + \c searchString . Two QTextCursor objects are used: One to traverse through + the words in \c line and another to keep track of the edit blocks. + + \snippet examples/uitools/textfinder/textfinder.cpp 7 + + The \c isFirstTime flag is set to false the moment \c findButton is + clicked. This is necessary to undo the previous text highlight before + highlighting the user's next search string. Also, the \c found flag + is used to indicate if the \c searchString was found within the contents + of \c ui_textEdit. If it was not found, a QMessageBox is used + to inform the user. + + \snippet examples/uitools/textfinder/textfinder.cpp 9 + + \section1 \c main() Function + + \snippet examples/uitools/textfinder/main.cpp 0 + + The \c main() function initialises the \e{textfinder.qrc} resource file + and instantiates as well as displays \c TextFinder. + + \sa{Calculator Builder Example}, {World Time Clock Builder Example} + */ diff --git a/doc/src/examples/textobject.qdoc b/doc/src/examples/textobject.qdoc new file mode 100644 index 0000000..cc5a6b6 --- /dev/null +++ b/doc/src/examples/textobject.qdoc @@ -0,0 +1,170 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example richtext/textobject + \title Text Object Example + + The Text Object example shows how to insert an SVG file into a + QTextDocument. + + \image textobject-example.png + + A QTextDocument consists of a hierarchy of elements, such as text blocks and + frames. A text object describes the structure or format of one or more of these + elements. For instance, images imported from HTML are implemented using text + objects. Text objects are used by the document's + \l{QAbstractTextDocumentLayout}{layout} to lay out and render (paint) the + document. Each object knows how to paint the elements they govern, and + calculates their size. + + To be able to insert an SVG image into a text document, we create + a text object, and implement painting for that object. This object + can then be \l{QTextCharFormat::setObjectType()}{set} on a + QTextCharFormat. We also register the text object with the layout + of the document, enabling it to draw \l{QTextCharFormat}s governed + by our text object. We can summarize the procedure with the + following steps: + + \list + \o Implement the text object. + \o Register the text object with the layout of the text + document. + \o Set the text object on a QTextCharFormat. + \o Insert a QChar::ObjectReplacementCharacter with that + text char format into the document. + \endlist + + The example consists of the following classes: + + \list + \o \c{SvgTextObject} implements the text object. + \o \c{Window} shows a QTextEdit into which SVG images can be + inserted. + \endlist + + \section1 SvgTextObject Class Definition + + Let's take a look at the header file of \c {SvgTextObject}: + + \snippet examples/richtext/textobject/svgtextobject.h 0 + + A text object is a QObject that implements QTextObjectInterface. + Note that the first class inherited must be QObject, and that + you must use Q_INTERFACES to let Qt know that your class + implements QTextObjectInterface. + + The document layout keeps a collection of text objects stored as + \l{QObject}s, each of which has an associated object type. The + layout casts the QObject for the associated object type into the + QTextObjectInterface. + + The \l{QTextObjectInterface::}{intrinsicSize()} and + \l{QTextObjectInterface::}{drawObject()} functions are then used + to calculate the size of the text object and draw it. + + \section1 SvgTextObject Class Implementation + + We start of by taking a look at the + \l{QTextObjectInterface::}{intrinsicSize()} function: + + \snippet examples/richtext/textobject/svgtextobject.cpp 0 + + \c intrinsicSize() is called by the layout to calculate the size + of the text object. Notice that we have drawn the SVG image on a + QImage. This is because SVG rendering is quite expensive. The + example would lag seriously for large images if we drew them + with a QSvgRenderer each time. + + \snippet examples/richtext/textobject/svgtextobject.cpp 1 + + In \c drawObject(), we paint the SVG image using the QPainter + provided by the layout. + + \section1 Window Class Definition + + The \c Window class is a self-contained window that has a + QTextEdit in which SVG images can be inserted. + + \snippet examples/richtext/textobject/window.h 0 + + The \c insertTextObject() slot inserts an SVG image at the current + cursor position, while \c setupTextObject() creates and registers + the SvgTextObject with the layout of the text edit's document. + + The constructor simply calls \c setupTextObject() and \c + setupGui(), which creates and lays out the widgets of the \c + Window. + + \section1 Window Class Implementation + + We will now take a closer look at the functions that are relevant + to our text object, starting with the \c setupTextObject() + function. + + \snippet examples/richtext/textobject/window.cpp 3 + + \c {SvgTextFormat}'s value is the number of our object type. It is + used to identify object types by the document layout. + + Note that we only create one SvgTextObject instance; it will be + used for all QTextCharFormat's with the \c SvgTextFormat object + type. + + Let's move on to the \c insertTextObject() function: + + \snippet examples/richtext/textobject/window.cpp 1 + + First, the \c .svg file is opened and its contents are read + into the \c svgData array. + + \snippet examples/richtext/textobject/window.cpp 2 + + To speed things up, we buffer the SVG image in a QImage. We use + \l{QTextFormat::}{setProperty()} to store the QImage in the in the + QTextCharFormat. We can retrieve it later with + \l{QTextCharFormat::}{property()}. + + We insert the char format in the standard way - using a + QTextCursor. Notice that we use the special QChar + \l{QChar::}{ObjectReplacementCharacter}. +*/ + diff --git a/doc/src/examples/textures.qdoc b/doc/src/examples/textures.qdoc new file mode 100644 index 0000000..2f0389c3 --- /dev/null +++ b/doc/src/examples/textures.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/textures + \title Textures Example + + The Textures example demonstrates the use of Qt's image classes as textures in + applications that use both OpenGL and Qt to display graphics. + + \image textures-example.png +*/ diff --git a/doc/src/examples/threadedfortuneserver.qdoc b/doc/src/examples/threadedfortuneserver.qdoc new file mode 100644 index 0000000..d5f2571 --- /dev/null +++ b/doc/src/examples/threadedfortuneserver.qdoc @@ -0,0 +1,121 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/threadedfortuneserver + \title Threaded Fortune Server Example + + The Threaded Fortune Server example shows how to create a server for a + simple network service that uses threads to handle requests from different + clients. It is intended to be run alongside the Fortune Client example. + + \image threadedfortuneserver-example.png + + The implementation of this example is similar to that of the + \l{network/fortuneserver}{Fortune Server} example, but here we will + implement a subclass of QTcpServer that starts each connection in a + different thread. + + For this we need two classes: FortuneServer, a QTcpServer subclass, and + FortuneThread, which inherits QThread. + + \snippet examples/network/threadedfortuneserver/fortuneserver.h 0 + + FortuneServer inherits QTcpServer and reimplements + QTcpServer::incomingConnection(). We also use it for storing the list of + random fortunes. + + \snippet examples/network/threadedfortuneserver/fortuneserver.cpp 0 + + We use FortuneServer's constructor to simply generate the list of + fortunes. + + \snippet examples/network/threadedfortuneserver/fortuneserver.cpp 1 + + Our implementation of QTcpServer::incomingConnection() creates a + FortuneThread object, passing the incoming socket descriptor and a random + fortune to FortuneThread's constructor. By connecting FortuneThread's + finished() signal to QObject::deleteLater(), we ensure that the thread + gets deleted once it has finished. We can then call QThread::start(), + which starts the thread. + + \snippet examples/network/threadedfortuneserver/fortunethread.h 0 + + Moving on to the FortuneThread class, this is a QThread subclass whose job + is to write the fortune to the connected socket. The class reimplements + QThread::run(), and it has a signal for reporting errors. + + \snippet examples/network/threadedfortuneserver/fortunethread.cpp 0 + + FortuneThread's constructor simply stores the socket descriptor and + fortune text, so that they are available for run() later on. + + \snippet examples/network/threadedfortuneserver/fortunethread.cpp 1 + + The first thing our run() function does is to create a QTcpSocket object + on the stack. What's worth noticing is that we are creating this object + inside the thread, which automatically associates the socket to the + thread's event loop. This ensures that Qt will not try to deliver events + to our socket from the main thread while we are accessing it from + FortuneThread::run(). + + \snippet examples/network/threadedfortuneserver/fortunethread.cpp 2 + + The socket is initialized by calling QTcpSocket::setSocketDescriptor(), + passing our socket descriptor as an argument. We expect this to succeed, + but just to be sure, (although unlikely, the system may run out of + resources,) we catch the return value and report any error. + + \snippet examples/network/threadedfortuneserver/fortunethread.cpp 3 + + As with the \l{network/fortuneserver}{Fortune Server} example, we encode + the fortune into a QByteArray using QDataStream. + + \snippet examples/network/threadedfortuneserver/fortunethread.cpp 4 + + But unlike the previous example, we finish off by calling + QTcpSocket::waitForDisconnected(), which blocks the calling thread until + the socket has disconnected. Because we are running in a separate thread, + the GUI will remain responsive. + + \sa {Fortune Server Example}, {Fortune Client Example}, {Blocking Fortune + Client Example} +*/ diff --git a/doc/src/examples/tooltips.qdoc b/doc/src/examples/tooltips.qdoc new file mode 100644 index 0000000..5daa2b2 --- /dev/null +++ b/doc/src/examples/tooltips.qdoc @@ -0,0 +1,408 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/tooltips + \title Tool Tips Example + + The Tool Tips example shows how to provide static and dynamic tool + tips for an application's widgets. + + The simplest and most common way to set a widget's tool tip is by + calling its QWidget::setToolTip() function (static tool + tips). Then the tool tip is shown whenever the cursor points at + the widget. We show how to do this with our application's tool + buttons. But it is also possible to show different tool tips + depending on the cursor's position (dynamic tooltips). This + approach uses mouse tracking and event handling to determine what + widgets are located under the cursor at any point in time, and + displays their tool tips. The tool tips for the shape items in our + application are implemented using the latter approach. + + \image tooltips-example.png + + With the \c Tooltips application the user can create new shape + items with the provided tool buttons, and move the items around + using the mouse. Tooltips are provided whenever the cursor is + pointing to a shape item or one of the buttons. + + The Tooltips example consists of two classes: + + \list + \o \c ShapeItem is a custom widget representing one single shape item. + \o \c SortingBox inherits from QWidget and is the application's main + widget. + \endlist + + First we will review the \c SortingBox class, then we will take a + look at the \c ShapeItem class. + + \section1 SortingBox Class Definition + + \snippet examples/widgets/tooltips/sortingbox.h 0 + + The \c SortingBox class inherits QWidget, and it is the Tooltips + application's main widget. We reimplement several of the event + handlers. + + The \c event() function provides tooltips, the \c resize() + function makes sure the application appears consistently when the + user resizes the main widget, and the \c paintEvent() function + displays the shape items within the \c SortingBox widget. The + mouse event handlers are reimplemented to make the user able to + move the items around. + + In addition we need three private slots to make the user able to + create new shape items. + + \snippet examples/widgets/tooltips/sortingbox.h 1 + + We also create several private functions: We use the \c + initialItemPosition(), \c initialItemColor() and \c + createToolButton() functions when we are constructing the widget, + and we use the \c updateButtonGeometry() function whenever the + user is resizing the application's main widget. + + The \c itemAt() function determines if there is a shape item at a + particular position, and the \c moveItemTo() function moves an + item to a new position. We use the \c createShapeItem(), \c + randomItemPosition() and \c randomItemColor() functions to create + new shape items. + + \snippet examples/widgets/tooltips/sortingbox.h 2 + + We keep all the shape items in a QList, and we keep three + QPainterPath objects holding the shapes of a circle, a square and + a triangle. We also need to have a pointer to an item when it is + moving, and we need to know its previous position. + + \section1 SortingBox Class Implementation + + \snippet examples/widgets/tooltips/sortingbox.cpp 0 + + In the constructor, we first set the Qt::WA_StaticContents + attribute on the widget. This attribute indicates that the widget + contents are north-west aligned and static. On resize, such a + widget will receive paint events only for the newly visible part + of itself. + + \snippet examples/widgets/tooltips/sortingbox.cpp 1 + + To be able to show the appropiate tooltips while the user is + moving the cursor around, we need to enable mouse tracking for the + widget. + + If mouse tracking is disabled (the default), the widget only + receives mouse move events when at least one mouse button is + pressed while the mouse is being moved. If mouse tracking is + enabled, the widget receives mouse move events even if no buttons + are pressed. + + \snippet examples/widgets/tooltips/sortingbox.cpp 2 + + A widget's background role defines the brush from the widget's + palette that is used to render the background, and QPalette::Base + is typically white. + + \snippet examples/widgets/tooltips/sortingbox.cpp 3 + + After creating the application's tool buttons using the private \c + createToolButton() function, we construct the shapes of a circle, + a square and a triangle using QPainterPath. + + The QPainterPath class provides a container for painting + operations, enabling graphical shapes to be constructed and + reused. The main advantage of painter paths over normal drawing + operations is that complex shapes only need to be created once, + but they can be drawn many times using only calls to + QPainter::drawPath(). + + \snippet examples/widgets/tooltips/sortingbox.cpp 4 + + Then we set the window title, resize the widget to a suitable + size, and finally create three initial shape items using the + private \c createShapeItem(), \c initialItemPosition() and \c + initialItemColor() functions. + + \snippet examples/widgets/tooltips/sortingbox.cpp 5 + + QWidget::event() is the main event handler and receives all the + widget's events. Normally, we recommend reimplementing one of the + specialized event handlers instead of this function. But here we + want to catch the QEvent::ToolTip events, and since these are + rather rare, there exists no specific event handler. For that + reason we reimplement the main event handler, and the first thing + we need to do is to determine the event's type: + + \snippet examples/widgets/tooltips/sortingbox.cpp 6 + + If the type is QEvent::ToolTip, we cast the event to a QHelpEvent, + otherwise we propagate the event using the QWidget::event() + function. + + The QHelpEvent class provides an event that is used to request + helpful information about a particular point in a widget. + + For example, the QHelpEvent::pos() function returns the event's + position relative to the widget to which the event is dispatched. + Here we use this information to determine if the position of the + event is contained within the area of any of the shape items. If + it is, we display the shape item's tooltip at the position of the + event. If not, we hide the tooltip and explicitly ignore the event. + This makes sure that the calling code does not start any tooltip + specific modes as a result of the event. Note that the + QToolTip::showText() function needs the event's position in global + coordinates provided by QHelpEvent::globalPos(). + + \snippet examples/widgets/tooltips/sortingbox.cpp 7 + + The \c resizeEvent() function is reimplemented to receive the + resize events dispatched to the widget. It makes sure that the + tool buttons keep their position relative to the main widget when + the widget is resized. We want the buttons to always be vertically + aligned in the application's bottom right corner, so each time the + main widget is resized we update the buttons geometry. + + \snippet examples/widgets/tooltips/sortingbox.cpp 8 + + The \c paintEvent() function is reimplemented to receive paint + events for the widget. We create a QPainter for the \c SortingBox + widget, and run through the list of created shape items, drawing + each item at its defined position. + + \snippet examples/widgets/tooltips/sortingbox.cpp 9 + + The painter will by default draw all the shape items at position + (0,0) in the \c SortingBox widget. The QPainter::translate() + function translates the coordinate system by the given offset, + making each shape item appear at its defined position. But + remember to translate the coordinate system back when the item is + drawn, otherwise the next shape item will appear at a position + relative to the item we drawed last. + + \snippet examples/widgets/tooltips/sortingbox.cpp 10 + + The QPainter::setBrush() function sets the current brush used by + the painter. When the provided argument is a QColor, the function + calls the appropiate QBrush constructor which creates a brush with + the specified color and Qt::SolidPattern style. The + QPainter::drawPath() function draws the given path using the + current pen for outline and the current brush for filling. + + \snippet examples/widgets/tooltips/sortingbox.cpp 11 + + The \c mousePressEvent() function is reimplemented to receive the + mouse press events dispatched to the widget. It determines if an + event's position is contained within the area of any of the shape + items, using the private \c itemAt() function. + + If an item covers the position, we store a pointer to that item + and the event's position. If several of the shape items cover the + position, we store the pointer to the uppermost item. Finally, we + move the shape item to the end of the list, and make a call to the + QWidget::update() function to make the item appear on top. + + The QWidget::update() function does not cause an immediate + repaint; instead it schedules a paint event for processing when Qt + returns to the main event loop. + + \snippet examples/widgets/tooltips/sortingbox.cpp 12 + + The \c mouseMoveEvent() function is reimplemented to receive mouse + move events for the widget. If the left mouse button is pressed + and there exists a shape item in motion, we use the private \c + moveItemTo() function to move the item with an offset + corresponding to the offset between the positions of the current + mouse event and the previous one. + + \snippet examples/widgets/tooltips/sortingbox.cpp 13 + + The \c mouseReleaseEvent() function is reimplemented to receive + the mouse release events dispatched to the widget. If the left + mouse button is pressed and there exists a shape item in motion, + we use the private \c moveItemTo() function to move the item like + we did in \c mouseMoveEvent(). But then we remove the pointer to + the item in motion, making the shape item's position final for + now. To move the item further, the user will need to press the + left mouse button again. + + \snippet examples/widgets/tooltips/sortingbox.cpp 14 + \codeline + \snippet examples/widgets/tooltips/sortingbox.cpp 15 + \codeline + \snippet examples/widgets/tooltips/sortingbox.cpp 16 + + The \c createNewCircle(), \c createNewSquare() and \c + createNewTriangle() slots simply create new shape items, using the + private \c createShapeItem(), \c randomItemPosition() and \c + randomItemColor() functions. + + \snippet examples/widgets/tooltips/sortingbox.cpp 17 + + In the \c itemAt() function, we run through the list of created + shape items to check if the given position is contained within the + area of any of the shape items. + + For each shape item we use the QPainterPath::contains() function + to find out if the item's painter path contains the position. If + it does we return the index of the item, otherwise we return + -1. We run through the list backwards to get the index of the + uppermost shape item in case several items cover the position. + + \snippet examples/widgets/tooltips/sortingbox.cpp 18 + + The \c moveItemTo() function moves the shape item in motion, and + the parameter \c pos is the position of a mouse event. First we + calculate the offset between the parameter \c pos and the previous + mouse event position. Then we add the offset to the current + position of the item in motion. + + It is tempting to simply set the position of the item to be the + parameter \c pos. But an item's position defines the top left + corner of the item's bounding rectangle, and the parameter \c pos + can be any point; The suggested shortcut would cause the item to + jump to a position where the cursor is pointing to the bounding + rectangle's top left corner, regardless of the item's previous + position. + + \snippet examples/widgets/tooltips/sortingbox.cpp 19 + + Finally, we update the previous mouse event position, and make a + call to the QWidget::update() function to make the item appear at + its new position. + + \snippet examples/widgets/tooltips/sortingbox.cpp 20 + + In the \c updateButtonGeometry() function we set the geometry for + the given button. The parameter coordinates define the bottom + right corner of the button. We use these coordinates and the + button's size hint to determine the position of the upper left + corner. This position, and the button's width and height, are the + arguments required by the QWidget::setGeometry() function. + + In the end, we calculate and return the y-coordinate of the bottom + right corner of the next button. We use the QWidget::style() + function to retrieve the widget's GUI style, and then + QStyle::pixelMetric() to determine the widget's preferred default + spacing between its child widgets. + + \snippet examples/widgets/tooltips/sortingbox.cpp 21 + + The \c createShapeItem() function creates a single shape item. It + sets the path, tooltip, position and color, using the item's own + functions. In the end, the function appends the new item to the + list of shape items, and calls the QWidget::update() function to + make it appear with the other items within the \c SortingBox + widget. + + \snippet examples/widgets/tooltips/sortingbox.cpp 22 + + The \c createToolButton() function is called from the \c + SortingBox constructor. We create a tool button with the given + tooltip and icon. The button's parent is the \c SortingBox widget, + and its size is 32 x 32 pixels. Before we return the button, we + connect it to the given slot. + + \snippet examples/widgets/tooltips/sortingbox.cpp 23 + + The \c initialItemPosition() function is also called from the + constructor. We want the three first items to initially be + centered in the middle of the \c SortingBox widget, and we use + this function to calculate their positions. + + \snippet examples/widgets/tooltips/sortingbox.cpp 24 + + Whenever the user creates a new shape item, we want the new item + to appear at a random position, and we use the \c + randomItemPosition() function to calculate such a position. We + make sure that the item appears within the the visible area of the + \c SortingBox widget, using the widget's current width and heigth + when calculating the random coordinates. + + \snippet examples/widgets/tooltips/sortingbox.cpp 25 + + As with \c initialItemPosition(), the \c initialItemColor() + function is called from the constructor. The purposes of both + functions are purely cosmetic: We want to control the inital + position and color of the three first items. + + \snippet examples/widgets/tooltips/sortingbox.cpp 26 + + Finally the \c randomItemColor() function is implemented to give + the shape items the user creates, a random color. + + \section1 ShapeItem Class Definition + + \snippet examples/widgets/tooltips/shapeitem.h 0 + + The \c ShapeItem class is a custom widget representing one single + shape item. The widget has a path, a position, a color and a + tooltip. We need functions to set or modify these objects, as well + as functions that return them. We make the latter functions \c + const to prohibit any modifications of the objects, + i.e. prohibiting unauthorized manipulation of the shape items + appearance. + + \section1 ShapeItem Class Implementation + + \snippet examples/widgets/tooltips/shapeitem.cpp 0 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 1 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 2 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 3 + + This first group of functions simply return the objects that are + requested. The objects are returned as constants, i.e. they cannot + be modified. + + \snippet examples/widgets/tooltips/shapeitem.cpp 4 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 5 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 6 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 7 + + The last group of functions set or modify the shape item's path, + position, color and tooltip, respectively. +*/ diff --git a/doc/src/examples/torrent.qdoc b/doc/src/examples/torrent.qdoc new file mode 100644 index 0000000..8805dad --- /dev/null +++ b/doc/src/examples/torrent.qdoc @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/torrent + \title Torrent Example + + The Torrent example is a functional BitTorrent client that + illustrates how to write a complex TCP/IP application using Qt. + + \image torrent-example.png + + \section1 License Information + + The implementation of the US Secure Hash Algorithm 1 (SHA1) in this example is + derived from the original description in \l{RFC 3174}. + + \legalese + Copyright (C) The Internet Society (2001). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + \endlegalese +*/ diff --git a/doc/src/examples/trafficinfo.qdoc b/doc/src/examples/trafficinfo.qdoc new file mode 100644 index 0000000..c9b6890 --- /dev/null +++ b/doc/src/examples/trafficinfo.qdoc @@ -0,0 +1,163 @@ +/**************************************************************************** +** +** Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xmlpatterns/trafficinfo + \title TrafficInfo Example + + Shows how XQuery can be used extract information from WML documents provided by a WAP service. + + \section1 Overview + + The WAP service used in this example is \l{Trafikanten}{wap.trafikanten.no} + that is run by the Norwegian governmental agency for public transport in + Oslo. The service provides real time information about the departure of + busses, trams and undergrounds for every station in the city area. + + This example application displays the departure information for a specific + station and provides the feature to filter for a special bus or tram line. + + \image trafficinfo-example.png + + \section1 Retrieving the Data + + Without the knowledge of XQuery, one would use QNetworkAccessManager to + query the WML document from the WAP service and then using the QDom + classes or QXmlStreamReader classes to iterate over the document and + extract the needed information. + However this approach results in a lot of glue code and consumes valuable + developer time, so we are looking for something that can access XML + documents locally or over the network and extract data according to given + filter rules. That's the point where XQuery enters the stage! + + If we want to know when the underground number 6 in direction + \Aring\c{}sjordet is passing the underground station in Nydalen on November + 14th 2008 after 1pm, we use the following URL: + + \c{http://wap.trafikanten.no/F.asp?f=03012130&t=13&m=00&d=14.11.2008&start=1} + + The parameters have the following meanings: + \list + \o \e{f} The unique station ID of Nydalen. + \o \e{t} The hour in 0-23 format. + \o \e{m} The minute in 0-59 format. + \o \e{d} The date in dd.mm.yyyy format. + \o \e{start} Not interesting for our use but should be passed. + \endlist + + As a result we get the following document: + + \quotefile examples/xmlpatterns/trafficinfo/time_example.wml + + So for every departure we have a \c tag that contains the time as a + text element, and the following text element contains the line number + and direction. + + To encapsulate the XQuery code in the example application, we create a + custom \c TimeQuery class. This provides the \c queryInternal() function + that takes a station ID and date/time as input and returns the list of + times and directions: + + \snippet examples/xmlpatterns/trafficinfo/timequery.cpp 1 + + The first lines of this function synthesize the XQuery strings that fetch + the document and extract the data. + For better readability, two separated queries are used here: the first one + fetches the times and the second fetches the line numbers and directions. + + The \c doc() XQuery method opens a local or remote XML document and returns + it, so the \c{/wml/card/p/small/} statement behind it selects all XML nodes + that can be reached by the path, \c wml \rarrow \c card \rarrow \c p \rarrow + \c small. + Now we are on the node that contains all the XML nodes we are interested in. + + In the first query we select all \c a nodes that have a \c href attribute + starting with the string "Rute" and return the text of these nodes. + + In the second query we select all text nodes that are children of the + \c small node which start with a number. + These two queries are passed to the QXmlQuery instance and are evaluated + to string lists. After some sanity checking, we have collected all the + information we need. + + In the section above we have seen that an unique station ID must be passed + as an argument to the URL for retrieving the time, so how to find out which + is the right station ID to use? The WAP service provides a page for that + as well, so the URL + + \c{http://wap.trafikanten.no/FromLink1.asp?fra=Nydalen} + + will return the following document: + + \snippet examples/xmlpatterns/trafficinfo/station_example.wml 0 + + The names of the available stations are listed as separate text elements + and the station ID is part of the \c href attribute of the parent \c a + (anchor) element. In our example, the \c StationQuery class encapsulates + the action of querying the stations that match the given name pattern with + the following code: + + \snippet examples/xmlpatterns/trafficinfo/stationquery.cpp 0 + + Just as in the \c TimeQuery implementation, the first step is to + synthesize the XQuery strings for selecting the station names and the + station IDs. As the station name that we pass in the URL will be input + from the user, we should protect the XQuery from code injection by using + the QXmlQuery::bindVariable() method to do proper quoting of the variable + content for us instead of concatenating the two strings manually. + + So, we define a XQuery \c $station variable that is bound to the user + input. This variable is concatenated inside the XQuery code with the + \c concat method. To extract the station IDs, we select all \c a elements + that have an \c title attribute with the content "Velg", and from these + elements we take the substring of the \c href attribute that starts at the + 18th character. + + The station name can be extracted a bit more easily by just taking the + text elements of the selected \a elements. + + After some sanity checks we have all the station IDs and the corresponding + names available. + + The rest of the code in this example is just for representing the time and + station information to the user, and uses techniques described in the + \l{Qt Examples#Widgets}{Widgets examples}. +*/ diff --git a/doc/src/examples/transformations.qdoc b/doc/src/examples/transformations.qdoc new file mode 100644 index 0000000..eabb803 --- /dev/null +++ b/doc/src/examples/transformations.qdoc @@ -0,0 +1,385 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/transformations + \title Transformations Example + + The Transformations example shows how transformations influence + the way that QPainter renders graphics primitives. In particular + it shows how the order of transformations affect the result. + + \image transformations-example.png + + The application allows the user to manipulate the rendering of a + shape by changing the translation, rotation and scale of + QPainter's coordinate system. + + The example consists of two classes and a global enum: + + \list + \o The \c RenderArea class controls the rendering of a given shape. + \o The \c Window class is the application's main window. + \o The \c Operation enum describes the various transformation + operations available in the application. + \endlist + + First we will take a quick look at the \c Operation enum, then we + will review the \c RenderArea class to see how a shape is + rendered. Finally, we will take a look at the Transformations + application's features implemented in the \c Window class. + + \section1 Transformation Operations + + Normally, the QPainter operates on the associated device's own + coordinate system, but it also has good support for coordinate + transformations. + + The default coordinate system of a paint device has its origin at + the top-left corner. The x values increase to the right and the y + values increase downwards. You can scale the coordinate system by + a given offset using the QPainter::scale() function, you can + rotate it clockwise using the QPainter::rotate() function and you + can translate it (i.e. adding a given offset to the points) using + the QPainter::translate() function. You can also twist the + coordinate system around the origin (called shearing) using the + QPainter::shear() function. + + All the tranformation operations operate on QPainter's + tranformation matrix that you can retrieve using the + QPainter::matrix() function. A matrix transforms a point in the + plane to another point. For more information about the + transformation matrix, see the \l {The Coordinate System} and + QMatrix documentation. + + \snippet examples/painting/transformations/renderarea.h 0 + + The global \c Operation enum is declared in the \c renderarea.h + file and describes the various transformation operations available + in the Transformations application. + + \section1 RenderArea Class Definition + + The \c RenderArea class inherits QWidget, and controls the + rendering of a given shape. + + \snippet examples/painting/transformations/renderarea.h 1 + + We declare two public functions, \c setOperations() and + \c setShape(), to be able to specify the \c RenderArea widget's shape + and to transform the coordinate system the shape is rendered + within. + + We reimplement the QWidget's \l + {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l + {QWidget::sizeHint()}{sizeHint()} functions to give the \c + RenderArea widget a reasonable size within our application, and we + reimplement the QWidget::paintEvent() event handler to draw the + render area's shape applying the user's transformation choices. + + \snippet examples/painting/transformations/renderarea.h 2 + + We also declare several convenience functions to draw the shape, + the coordinate system's outline and the coordinates, and to + transform the painter according to the chosen transformations. + + In addition, the \c RenderArea widget keeps a list of the + currently applied transformation operations, a reference to its + shape, and a couple of convenience variables that we will use when + rendering the coordinates. + + \section1 RenderArea Class Implementation + + The \c RenderArea widget controls the rendering of a given shape, + including the transformations of the coordinate system, by + reimplementing the QWidget::paintEvent() event handler. But first + we will take a quick look at the constructor and at the functions + that provides access to the \c RenderArea widget: + + \snippet examples/painting/transformations/renderarea.cpp 0 + + In the constructor we pass the parent parameter on to the base + class, and customize the font that we will use to render the + coordinates. The QWidget::font() funtion returns the font + currently set for the widget. As long as no special font has been + set, or after QWidget::setFont() is called, this is either a + special font for the widget class, the parent's font or (if this + widget is a top level widget) the default application font. + + After ensuring that the font's size is 12 points, we extract the + rectangles enclosing the coordinate letters, 'x' and 'y', using the + QFontMetrics class. + + QFontMetrics provides functions to access the individual metrics + of the font, its characters, and for strings rendered in the + font. The QFontMetrics::boundingRect() function returns the + bounding rectangle of the given character relative to the + left-most point on the base line. + + \snippet examples/painting/transformations/renderarea.cpp 1 + \codeline + \snippet examples/painting/transformations/renderarea.cpp 2 + + In the \c setShape() and \c setOperations() functions we update + the \c RenderArea widget by storing the new value or values + followed by a call to the QWidget::update() slot which schedules a + paint event for processing when Qt returns to the main event loop. + + \snippet examples/painting/transformations/renderarea.cpp 3 + \codeline + \snippet examples/painting/transformations/renderarea.cpp 4 + + We reimplement the QWidget's \l + {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l + {QWidget::sizeHint()}{sizeHint()} functions to give the \c + RenderArea widget a reasonable size within our application. The + default implementations of these functions returns an invalid size + if there is no layout for this widget, and returns the layout's + minimum size or preferred size, respectively, otherwise. + + \snippet examples/painting/transformations/renderarea.cpp 5 + + The \c paintEvent() event handler recieves the \c RenderArea + widget's paint events. A paint event is a request to repaint all + or part of the widget. It can happen as a result of + QWidget::repaint() or QWidget::update(), or because the widget was + obscured and has now been uncovered, or for many other reasons. + + First we create a QPainter for the \c RenderArea widget. The \l + {QPainter::RenderHint}{QPainter::Antialiasing} render hint + indicates that the engine should antialias edges of primitives if + possible. Then we erase the area that needs to be repainted using + the QPainter::fillRect() function. + + We also translate the coordinate system with an constant offset to + ensure that the original shape is renderend with a suitable + margin. + + \snippet examples/painting/transformations/renderarea.cpp 6 + + Before we start to render the shape, we call the QPainter::save() + function. + + QPainter::save() saves the current painter state (i.e. pushes the + state onto a stack) including the current coordinate system. The + rationale for saving the painter state is that the following call + to the \c transformPainter() function will transform the + coordinate system depending on the currently chosen transformation + operations, and we need a way to get back to the original state to + draw the outline. + + After transforming the coordinate system, we draw the \c + RenderArea's shape, and then we restore the painter state using + the the QPainter::restore() function (i.e. popping the saved state off + the stack). + + \snippet examples/painting/transformations/renderarea.cpp 7 + + Then we draw the square outline. + + \snippet examples/painting/transformations/renderarea.cpp 8 + + Since we want the coordinates to correspond with the coordinate + system the shape is rendered within, we must make another call to + the \c transformPainter() function. + + The order of the painting operations is essential with respect to + the shared pixels. The reason why we don't render the coordinates + when the coordinate system already is transformed to render the + shape, but instead defer their rendering to the end, is that we + want the coordinates to appear on top of the shape and its + outline. + + There is no need to save the QPainter state this time since + drawing the coordinates is the last painting operation. + + \snippet examples/painting/transformations/renderarea.cpp 9 + \codeline + \snippet examples/painting/transformations/renderarea.cpp 10 + \codeline + \snippet examples/painting/transformations/renderarea.cpp 11 + + The \c drawCoordinates(), \c drawOutline() and \c drawShape() are + convenience functions called from the \c paintEvent() event + handler. For more information about QPainter's basic drawing + operations and how to display basic graphics primitives, see the + \l {painting/basicdrawing}{Basic Drawing} example. + + \snippet examples/painting/transformations/renderarea.cpp 12 + + The \c transformPainter() convenience function is also called from + the \c paintEvent() event handler, and transforms the given + QPainter's coordinate system according to the user's + transformation choices. + + \section1 Window Class Definition + + The \c Window class is the Transformations application's main + window. + + The application displays four \c RenderArea widgets. The left-most + widget renders the shape in QPainter's default coordinate system, + the others render the shape with the chosen transformation in + addition to all the transformations applied to the \c RenderArea + widgets to their left. + + \snippet examples/painting/transformations/window.h 0 + + We declare two public slots to make the application able to + respond to user interaction, updating the displayed \c RenderArea + widgets according to the user's transformation choices. + + The \c operationChanged() slot updates each of the \c RenderArea + widgets applying the currently chosen transformation operations, and + is called whenever the user changes the selected operations. The + \c shapeSelected() slot updates the \c RenderArea widgets' shapes + whenever the user changes the preferred shape. + + \snippet examples/painting/transformations/window.h 1 + + We also declare a private convenience function, \c setupShapes(), + that is used when constructing the \c Window widget, and we + declare pointers to the various components of the widget. We + choose to keep the available shapes in a QList of \l + {QPainterPath}s. In addition we declare a private enum counting + the number of displayed \c RenderArea widgets except the widget + that renders the shape in QPainter's default coordinate system. + + \section1 Window Class Implementation + + In the constructor we create and initialize the application's + components: + + \snippet examples/painting/transformations/window.cpp 0 + + First we create the \c RenderArea widget that will render the + shape in the default coordinate system. We also create the + associated QComboBox that allows the user to choose among four + different shapes: A clock, a house, a text and a truck. The shapes + themselves are created at the end of the constructor, using the + \c setupShapes() convenience function. + + \snippet examples/painting/transformations/window.cpp 1 + + Then we create the \c RenderArea widgets that will render their + shapes with coordinate tranformations. By default the applied + operation is \gui {No Transformation}, i.e. the shapes are + rendered within the default coordinate system. We create and + initialize the associated \l {QComboBox}es with items + corresponding to the various transformation operations decribed by + the global \c Operation enum. + + We also connect the \l {QComboBox}es' \l + {QComboBox::activated()}{activated()} signal to the \c + operationChanged() slot to update the application whenever the + user changes the selected transformation operations. + + \snippet examples/painting/transformations/window.cpp 2 + + Finally, we set the layout for the application window using the + QWidget::setLayout() function, construct the available shapes + using the private \c setupShapes() convenience function, and make + the application show the clock shape on startup using the public + \c shapeSelected() slot before we set the window title. + + + \snippet examples/painting/transformations/window.cpp 3 + \snippet examples/painting/transformations/window.cpp 4 + \snippet examples/painting/transformations/window.cpp 5 + \snippet examples/painting/transformations/window.cpp 6 + \dots + + \snippet examples/painting/transformations/window.cpp 7 + + The \c setupShapes() function is called from the constructor and + create the QPainterPath objects representing the shapes that are + used in the application. For construction details, see the \l + {painting/transformations/window.cpp}{window.cpp} example + file. The shapes are stored in a QList. The QList::append() + function inserts the given shape at the end of the list. + + We also connect the associated QComboBox's \l + {QComboBox::activated()}{activated()} signal to the \c + shapeSelected() slot to update the application when the user + changes the preferred shape. + + \snippet examples/painting/transformations/window.cpp 8 + + The public \c operationChanged() slot is called whenever the user + changes the selected operations. + + We retrieve the chosen transformation operation for each of the + transformed \c RenderArea widgets by querying the associated \l + {QComboBox}{QComboBoxes}. The transformed \c RenderArea widgets + are supposed to render the shape with the transformation specified + by its associated combobox \e {in addition to} all the + transformations applied to the \c RenderArea widgets to its + left. For that reason, for each widget we query, we append the + associated operation to a QList of transformations which we apply + to the widget before proceeding to the next. + + \snippet examples/painting/transformations/window.cpp 9 + + The \c shapeSelected() slot is called whenever the user changes + the preferred shape, updating the \c RenderArea widgets using + their public \c setShape() function. + + \section1 Summary + + The Transformations example shows how transformations influence + the way that QPainter renders graphics primitives. Normally, the + QPainter operates on the device's own coordinate system, but it + also has good support for coordinate transformations. With the + Transformations application you can scale, rotate and translate + QPainter's coordinate system. The order in which these + tranformations are applied is essential for the result. + + All the tranformation operations operate on QPainter's + tranformation matrix. For more information about the + transformation matrix, see the \l {The Coordinate System} and + QMatrix documentation. + + The Qt reference documentation provides several painting + demos. Among these is the \l {demos/affine}{Affine + Transformations} demo that shows Qt's ability to perform + transformations on painting operations. The demo also allows the + user to experiment with the various transformation operations. +*/ diff --git a/doc/src/examples/treemodelcompleter.qdoc b/doc/src/examples/treemodelcompleter.qdoc new file mode 100644 index 0000000..82e9c24 --- /dev/null +++ b/doc/src/examples/treemodelcompleter.qdoc @@ -0,0 +1,185 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/treemodelcompleter + \title Tree Model Completer Example + + The Tree Model Completer example shows how to provide completion + facilities for a hierarchical model, using a period as the separator + to access Child, GrandChild and GrandGrandChild level objects. + + \image treemodelcompleter-example.png + + Similar to the \l{Completer Example}, we provide QComboBox objects to + enable selection for completion mode and case sensitivity, as well as + a QCheckBox for wrap completions. + + \section1 The Resource File + + The contents of the TreeModelCompleter is read from \e treemodel.txt. + This file is embedded within the \e treemodelcompleter.qrc resource file, + which contains the following: + + \quotefile examples/tools/treemodelcompleter/treemodelcompleter.qrc + + \section1 TreeModelCompleter Class Definition + + The \c TreeModelCompleter is a subclass of QCompleter with two + constructors - one with \a parent as an argument and another with + \a parent and \a model as arguments. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.h 0 + + The class reimplements the protected functions + \l{QCompleter::splitPath()}{splitPath()} and + \l{QCompleter::pathFromIndex()}{pathFromIndex()} to suit a tree model. + For more information on customizing QCompleter to suit tree models, refer + to \l{QCompleter#Handling Tree Models}{Handling Tree Models}. + + \c TreeModelCompleter also has a separator property which is declared + using the Q_PROPERTY() macro. The separator has READ and WRITE attributes + and the corresponding functions \c separator() and \c setSeparator(). For + more information on Q_PROPERTY(), refer to \l{Qt's Property System}. + + \section1 TreeModelCompleter Class Implementation + + The first constructor constructs a \c TreeModelCompleter object with a + parent while the second constructor constructs an object with a parent + and a QAbstractItemModel, \a model. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 0 + \codeline + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 1 + + The \c separator() function is a getter function that returns the + separator string. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 2 + + As mentioned earlier, the \c splitPath() function is reimplemented because + the default implementation is more suited to QDirModel or list models. In + order for QCompleter to split the path into a list of strings that are + matched at each level, we split it using QString::split() with \c sep as its + separator. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 3 + + The \c pathFromIndex() function returns data for the completionRole() for a + tree model. This function is reimplemented as its default implementation is + more suitable for list models. If there is no separator, we use + \l{QCompleter}'s default implementation, otherwise we use the + \l{QStringList::prepend()}{prepend()} function to navigate upwards and + accumulate the data. The function then returns a QStringList, \c dataList, + using a separator to join objects of different levels. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 4 + + \section1 MainWindow Class Definition + + The \c MainWindow class is a subclass of QMainWindow and implements five + custom slots: \c about(), \c changeCase(), \c changeMode(), + \c highlight(), and \c updateContentsLabel(). + + \snippet examples/tools/treemodelcompleter/mainwindow.h 0 + + In addition, the class has two private functions, \c createMenu() and + \c modelFromFile(), as well as private instances of QTreeView, QComboBox, + QLabel, \c TreeModelCompleter and QLineEdit. + + \snippet examples/tools/treemodelcompleter/mainwindow.h 1 + + \section1 MainWindow Class Implementation + + The \c{MainWindow}'s constructor creates a \c MainWindow object with a + parent and initializes the \c completer and \c lineEdit. The + \c createMenu() function is invoked to set up the "File" menu and "Help" + menu. The \c{completer}'s model is set to the QAbstractItemModel obtained + from \c modelFromFile(), and the \l{QCompleter::highlighted()} + {highlighted()} signal is connected to \c{MainWindow}'s \c highlight() + slot. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 0 + + The QLabel objects \c modelLabel, \c modeLabel and \c caseLabel are + instantiated. Also, the QComboBox objects, \c modeCombo and \c caseCombo, + are instantiated and populated. By default, the \c{completer}'s mode is + "Filtered Popup" and the case is insensitive. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 1 + \codeline + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 2 + + We use a QGridLayout to place all the objects in the \c MainWindow. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 3 + + The \c createMenu() function sets up the QAction objects required and + adds them to the "File" menu and "Help" menu. The + \l{QAction::triggered()}{triggered()} signals from these actions are + connected to their respective slots. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 4 + + The \c changeMode() function accepts an \a index corresponding to the + user's choice of completion mode and changes the \c{completer}'s mode + accordingly. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 5 + + The \c about() function provides a brief description on the Tree Model + Completer example. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 6 + + The \c changeCase() function alternates between \l{Qt::CaseSensitive} + {Case Sensitive} and \l{Qt::CaseInsensitive}{Case Insensitive} modes, + depending on the value of \a cs. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 7 + + \section1 \c main() Function + + The \c main() function instantiates \c MainWindow and invokes the + \l{QWidget::show()}{show()} function to display it. + + \snippet examples/tools/treemodelcompleter/main.cpp 0 +*/ diff --git a/doc/src/examples/trivialwizard.qdoc b/doc/src/examples/trivialwizard.qdoc new file mode 100644 index 0000000..360ea00 --- /dev/null +++ b/doc/src/examples/trivialwizard.qdoc @@ -0,0 +1,96 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/trivialwizard + \title Trivial Wizard Example + + The Trivial Wizard example illustrates how to create a linear three-page + registration wizard using three instances of QWizardPage and one instance + of QWizard. + + \image trivialwizard-example-flow.png + + \section1 Introduction Page + + \image trivialwizard-example-introduction.png + + The introduction page is created with the \c createIntroPage() + function where a QWizardPage is created and its title is set to + "Introduction". A QLabel is used to hold the description of \c page. + A QVBoxLayout is used to hold the \c label. This \c page is returned + when the \c createIntroPage() function is called. + + \snippet examples/dialogs/trivialwizard/trivialwizard.cpp 0 + + \section1 Registration Page + + \image trivialwizard-example-registration.png + + The registration page is created with the \c createRegistrationPage() + function. QLineEdit objects are used to allow the user to input a name + and an e-mail address. A QGridLayout is used to hold the QLabel and + QLineEdit objects. + + \snippet examples/dialogs/trivialwizard/trivialwizard.cpp 2 + + \section1 Conclusion Page + + \image trivialwizard-example-conclusion.png + + The conclusion page is created in the \c createConclusionPage() + function. This function's content is similar to \c createIntroPage(). A + QLabel is used to inform the user that the registration process has + completed successfully. + + \snippet examples/dialogs/trivialwizard/trivialwizard.cpp 6 + + \section1 \c main() Function + + The \c main() function instantiates a QWizard object, \c wizard, and + adds all three QWizardPage objects to it. The \c wizard window title is + set to "Trivial Wizard" and its \c show() function is invoked to display + it. + + \snippet examples/dialogs/trivialwizard/trivialwizard.cpp 10 + + \sa QWizard, {Class Wizard Example}, {License Wizard Example} +*/ diff --git a/doc/src/examples/trollprint.qdoc b/doc/src/examples/trollprint.qdoc new file mode 100644 index 0000000..38251ee --- /dev/null +++ b/doc/src/examples/trollprint.qdoc @@ -0,0 +1,275 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example linguist/trollprint + \title Troll Print Example + + Troll Print is an example application that lets the user choose + printer settings. It comes in two versions: English and + Portuguese. + + \image linguist-trollprint_10_en.png + + We've included a translation file, \c trollprint_pt.ts, which contains some + Portuguese translations for this example. + + We will consider two releases of the same application: Troll Print + 1.0 and 1.1. We will learn to reuse the translations created for one + release in a subsequent release. (In this tutorial, you need to edit + some source files. It's probably best to copy all the files to a new + temporary directory and work from there.) + + See the \l{Qt Linguist manual} for more information about + translating Qt application. + + \section1 Line by Line Walkthrough + + The \c PrintPanel class is defined in \c printpanel.h. + + \snippet examples/linguist/trollprint/printpanel.h 0 + + \c PrintPanel is a QWidget. It needs the \c Q_OBJECT macro for \c + tr() to work properly. + + The implementation file is \c printpanel.cpp. + + \snippet examples/linguist/trollprint/printpanel.cpp 0 + + Some of the code is commented out in Troll Print 1.0; you will + uncomment it later, for Troll Print 1.1. + + \snippet examples/linguist/trollprint/printpanel.cpp 1 + \snippet examples/linguist/trollprint/printpanel.cpp 2 + + Notice the two occurrences of \c tr("Enabled") and of \c + tr("Disabled") in PrintPanel. Since both "Enabled"s and "Disabled"s + appear in the same context \e {Qt Linguist} will only display one + occurrence of each and will use the same translations for the + duplicates that it doesn't display. Whilst this is a useful + timesaver, in some languages, such as Portuguese, the second + occurrence requires a separate translation. We will see how \e {Qt + Linguist} can be made to display all the occurrences for separate + translation shortly. + + The header file for \c MainWindow, \c mainwindow.h, contains no + surprises. In the implementation, \c mainwindow.cpp, we have some + user-visible source texts that must be marked for translation. + + \snippet examples/linguist/trollprint/mainwindow.cpp 0 + + We must translate the window title. + + \snippet examples/linguist/trollprint/mainwindow.cpp 1 + \snippet examples/linguist/trollprint/mainwindow.cpp 3 + + We also need to translate the actions and menus. Note that the + two argument form of \c tr() is used for the keyboard + accelerator, "Ctrl+Q", since the second argument is the only clue + the translator has to indicate what function that accelerator + will perform. + + \snippet examples/linguist/trollprint/main.cpp 0 + + The \c main() function in \c main.cpp is the same as the one in + the \l{linguist/arrowpad}{Arrow Pad} example. In particular, it + chooses a translation file based on the current locale. + + \section1 Running Troll Print 1.0 in English and in Portuguese + + We will use the translations in the \c trollprint_pt.ts file that is provided. + + Set the \c LANG environment variable to \c pt, and then run \c + trollprint. You should still see the English version. Now run \c + lrelease, e.g. \c {lrelease trollprint.pro}, and then run the + example again. Now you should see the Portuguese edition (Troll + Imprimir 1.0): + + \image linguist-trollprint_10_pt_bad.png + + Whilst the translation has appeared correctly, it is in fact wrong. In + good Portuguese, the second occurrence of "Enabled" should be + "Ativadas", not "Ativado" and the ending for the second translation of + "Disabled" must change similarly too. + + If you open \c trollprint_pt.ts using \e {Qt Linguist}, you will see that + there is just one occurrence of "Enabled" and of "Disabled" in the + translation source file, even though there are two of each in the + source code. This is because \e {Qt Linguist} tries to minimize the + translator's work by using the same translation for duplicate source + texts. In cases such as this where an identical translation is wrong, + the programmer must disambiguate the duplicate occurrences. This is + easily achieved by using the two argument form of \c tr(). + + We can easily determine which file must be changed because the + translator's "context" is in fact the class name for the class where + the texts that must be changed appears. In this case the file is \c + printpanel.cpp, where the there are four lines to change. Add the + second argument "two-sided" in the appropriate \c tr() calls to the + first pair of radio buttons: + + \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 0 + + and add the second argument "colors" in the appropriate \c tr() calls + for the second pair of radio buttons: + + \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 1 + + Now run \c lupdate and open \c trollprint_pt.ts with \e {Qt Linguist}. You + should now see two changes. + + First, the translation source file now contains \e three "Enabled", + "Disabled" pairs. The first pair is marked "(obs.)" signifying that they + are obsolete. This is because these texts appeared in \c tr() calls that + have been replaced by new calls with two arguments. The second pair has + "two-sided" as their comment, and the third pair has "colors" as their + comment. The comments are shown in the \gui {Source text and comments} + area in \e {Qt Linguist}. + + Second, the translation text "Ativado" and "Desativado" have been + automatically used as translations for the new "Enabled" and "Disabled" + texts, again to minimize the translator's work. Of course in this case + these are not correct for the second occurrence of each word, but they + provide a good starting point. + + Change the second "Ativado" into "Ativadas" and the second + "Desativado" into "Desativadas", then save and quit. Run \c lrelease + to obtain an up-to-date binary \c trollprint_pt.qm file, and run Troll Print + (or rather Troll Imprimir). + + \image linguist-trollprint_10_pt_good.png + + The second argument to \c tr() calls, called "comments" in \e {Qt + Linguist}, distinguish between identical source texts that occur in + the same context (class). They are also useful in other cases to give + clues to the translator, and in the case of Ctrl key accelerators are + the only means of conveying the function performed by the accelerator to + the translator. + + An additional way of helping the translator is to provide information on + how to navigate to the particular part of the application that contains + the source texts they must translate. This helps them see the context + in which the translation appears and also helps them to find and test + the translations. This can be achieved by using a \c TRANSLATOR comment + in the source code: + + \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 2 + + Try adding these comments to some source files, particularly to + dialog classes, describing the navigation necessary to reach the + dialogs. You could also add them to the example files, e.g. \c + mainwindow.cpp and \c printpanel.cpp are appropriate files. Run \c + lupdate and then start \e {Qt Linguist} and load in \c trollprint_pt.ts. + You should see the comments in the \gui {Source text and comments} area + as you browse through the list of source texts. + + Sometimes, particularly with large programs, it can be difficult for + the translator to find their translations and check that they're + correct. Comments that provide good navigation information can save + them time: + + \snippet doc/src/snippets/code/doc_src_examples_trollprint.qdoc 3 + + \section1 Troll Print 1.1 + + We'll now prepare release 1.1 of Troll Print. Start your favorite text + editor and follow these steps: + + \list + \o Uncomment the two lines that create a QLabel with the text + "\TROLL PRINT\" in \c printpanel.cpp. + \o Word-tidying: Replace "2-sided" by "Two-sided" in \c printpanel.cpp. + \o Replace "1.0" with "1.1" everywhere it occurs in \c mainwindow.cpp. + \o Update the copyright year to 1999-2000 in \c mainwindow.cpp. + \endlist + + (Of course the version number and copyright year would be consts or + #defines in a real application.) + + Once finished, run \c lupdate, then open \c trollprint_pt.ts in \e {Qt + Linguist}. The following items are of special interest: + + \list + \o \c MainWindow + \list + \o Troll Print 1.0 - marked "(obs.)", obsolete + \o About Troll Print 1.0 - marked "(obs.)", obsolete + \o Troll Print 1.0. Copyright 1999 Software, Inc. - + marked obsolete + \o Troll Print 1.1 - automatically translated as + "Troll Imprimir 1.1" + \o About Troll Print 1.1 - automatically translated as + "Troll Imprimir 1.1" + \o Troll Print 1.1. Copyright 1999-2000 Software, + Inc. - automatically translated as "Troll Imprimir 1.1. + Copyright 1999-2000 Software, Inc." + \endlist + \o \c PrintPanel + \list + \o 2-sided - marked "(obs.)", obsolete + \o \TROLL PRINT\ - unmarked, i.e. untranslated + \o Two-sided - unmarked, i.e. untranslated. + \endlist + \endlist + + Notice that \c lupdate works hard behind the scenes to make revisions + easier, and it's pretty smart with numbers. + + Go over the translations in \c MainWindow and mark these as "done". + Translate "\TROLL PRINT\" as "\TROLL IMPRIMIR\". + When you're translating "Two-sided", press the \gui {Guess Again} + button to translate "Two-sided", but change the "2" into "Dois". + + Save and quit, then run \c lrelease. The Portuguese version + should look like this: + + \image linguist-trollprint_11_pt.png + + Choose \gui{Ajuda|Sobre} (\gui{Help|About}) to see the about box. + + If you choose \gui {Ajuda|Sobre Qt} (\gui {Help|About Qt}), you'll get + an English dialog. Oops! Qt itself needs to be translated. See + \l{Internationalization with Qt} for details. + + Now set \c LANG=en to get the original English version: + + \image linguist-trollprint_11_en.png +*/ diff --git a/doc/src/examples/undoframework.qdoc b/doc/src/examples/undoframework.qdoc new file mode 100644 index 0000000..3d0965f --- /dev/null +++ b/doc/src/examples/undoframework.qdoc @@ -0,0 +1,306 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/undoframework + \title Undo Framework Example + + This example shows how to implement undo/redo functionality + with the Qt undo framework. + + \image undoframeworkexample.png The Undo Diagram Example + + In the Qt undo framework, all actions that the user performs are + implemented in classes that inherit QUndoCommand. An undo command + class knows how to both \l{QUndoCommand::}{redo()} - or just do + the first time - and \l{QUndoCommand::}{undo()} an action. For + each action the user performs, a command is placed on a + QUndoStack. Since the stack contains all commands executed + (stacked in chronological order) on the document, it can roll the + state of the document backwards and forwards by undoing and redoing + its commands. See the \l{Overview of Qt's Undo Framework}{overview + document} for a high-level introduction to the undo framework. + + The undo example implements a simple diagram application. It is + possible to add and delete items, which are either box or + rectangular shaped, and move the items by dragging them with the + mouse. The undo stack is shown in a QUndoView, which is a list in + which the commands are shown as list items. Undo and redo are + available through the edit menu. The user can also select a command + from the undo view. + + We use the \l{The Graphics View Framework}{graphics view + framework} to implement the diagram. We only treat the related + code briefly as the framework has examples of its own (e.g., the + \l{Diagram Scene Example}). + + The example consists of the following classes: + + \list + \o \c MainWindow is the main window and arranges the + example's widgets. It creates the commands based + on user input and keeps them on the command stack. + \o \c AddCommand adds an item to the scene. + \o \c DeleteCommand deletes an item from the scene. + \o \c MoveCommand when an item is moved the MoveCommand keeps record + of the start and stop positions of the move, and it + moves the item according to these when \c redo() and \c undo() + is called. + \o \c DiagramScene inherits QGraphicsScene and + emits signals for the \c MoveComands when an item is moved. + \o \c DiagramItem inherits QGraphicsPolygonItem and represents + an item in the diagram. + \endlist + + \section1 MainWindow Class Definition + + \snippet examples/tools/undoframework/mainwindow.h 0 + + The \c MainWindow class maintains the undo stack, i.e., it creates + \l{QUndoCommand}s and pushes and pops them from the stack when it + receives the \c triggered() signal from \c undoAction and \c + redoAction. + + \section1 MainWindow Class Implementation + + We will start with a look at the constructor: + + \snippet examples/tools/undoframework/mainwindow.cpp 0 + + In the constructor, we set up the DiagramScene and QGraphicsView. + + Here is the \c createUndoView() function: + + \snippet examples/tools/undoframework/mainwindow.cpp 1 + + The QUndoView is a widget that display the text, which is set with + the \l{QUndoCommand::}{setText()} function, for each QUndoCommand + in the undo stack in a list. + + Here is the \c createActions() function: + + \snippet examples/tools/undoframework/mainwindow.cpp 2 + \codeline + \snippet examples/tools/undoframework/mainwindow.cpp 3 + \dots + \snippet examples/tools/undoframework/mainwindow.cpp 5 + + The \c createActions() function sets up all the examples actions + in the manner shown above. The + \l{QUndoStack::}{createUndoAction()} and + \l{QUndoStack::}{createRedoAction()} helps us crate actions that + are disabled and enabled based on the state of the stack. Also, + the text of the action will be updated automatically based on the + \l{QUndoCommand::}{text()} of the undo commands. For the other + actions we have implemented slots in the \c MainWindow class. + + Here is the \c createMenus() function: + + \snippet examples/tools/undoframework/mainwindow.cpp 6 + + \dots + \snippet examples/tools/undoframework/mainwindow.cpp 7 + \dots + \snippet examples/tools/undoframework/mainwindow.cpp 8 + + We have to use the QMenu \c aboutToShow() and \c aboutToHide() + signals since we only want \c deleteAction to be enabled when we + have selected an item. + + Here is the \c itemMoved() slot: + + \snippet examples/tools/undoframework/mainwindow.cpp 9 + + We simply push a MoveCommand on the stack, which calls \c redo() + on it. + + Here is the \c deleteItem() slot: + + \snippet examples/tools/undoframework/mainwindow.cpp 10 + + An item must be selected to be deleted. We need to check if it is + selected as the \c deleteAction may be enabled even if an item is + not selected. This can happen as we do not catch a signal or event + when an item is selected. + + Here is the \c itemMenuAboutToShow() and itemMenuAboutToHide() slots: + + \snippet examples/tools/undoframework/mainwindow.cpp 11 + \codeline + \snippet examples/tools/undoframework/mainwindow.cpp 12 + + We implement \c itemMenuAboutToShow() and \c itemMenuAboutToHide() + to get a dynamic item menu. These slots are connected to the + \l{QMenu::}{aboutToShow()} and \l{QMenu::}{aboutToHide()} signals. + We need this to disable or enable the \c deleteAction. + + Here is the \c addBox() slot: + + \snippet examples/tools/undoframework/mainwindow.cpp 13 + + The \c addBox() function creates an AddCommand and pushes it on + the undo stack. + + Here is the \c addTriangle() sot: + + \snippet examples/tools/undoframework/mainwindow.cpp 14 + + The \c addTriangle() function creates an AddCommand and pushes it + on the undo stack. + + Here is the implementation of \c about(): + + \snippet examples/tools/undoframework/mainwindow.cpp 15 + + The about slot is triggered by the \c aboutAction and displays an + about box for the example. + + \section1 AddCommand Class Definition + + \snippet examples/tools/undoframework/commands.h 2 + + The \c AddCommand class adds DiagramItem graphics items to the + DiagramScene. + + \section1 AddCommand Class Implementation + + We start with the constructor: + + \snippet examples/tools/undoframework/commands.cpp 7 + + We first create the DiagramItem to add to the DiagramScene. The + \l{QUndoCommand::}{setText()} function let us set a QString that + describes the command. We use this to get custom messages in the + QUndoView and in the menu of the main window. + + \snippet examples/tools/undoframework/commands.cpp 8 + + \c undo() removes the item from the scene. We need to update the + scene as ...(ask Andreas) + + \snippet examples/tools/undoframework/commands.cpp 9 + + We set the position of the item as we do not do this in the + constructor. + + \section1 DeleteCommand Class Definition + + \snippet examples/tools/undoframework/commands.h 1 + + The DeleteCommand class implements the functionality to remove an + item from the scene. + + \section1 DeleteCommand Class Implementation + + \snippet examples/tools/undoframework/commands.cpp 4 + + We know that there must be one selected item as it is not possible + to create a DeleteCommand unless the item to be deleted is + selected and that only one item can be selected at any time. + The item must be unselected if it is inserted back into the + scene. + + \snippet examples/tools/undoframework/commands.cpp 5 + + The item is simply reinserted into the scene. + + \snippet examples/tools/undoframework/commands.cpp 6 + + The item is removed from the scene. + + \section1 MoveCommand Class Definition + + \snippet examples/tools/undoframework/commands.h 0 + + The \l{QUndoCommand::}{mergeWith()} is reimplemented to make + consecutive moves of an item one MoveCommand, i.e, the item will + be moved back to the start position of the first move. + + \section1 MoveCommand Class Implementation + + + The constructor of MoveCommand looks like this: + + \snippet examples/tools/undoframework/commands.cpp 0 + + We save both the old and new positions for undo and redo + respectively. + + \snippet examples/tools/undoframework/commands.cpp 2 + + We simply set the items old position and update the scene. + + \snippet examples/tools/undoframework/commands.cpp 3 + + We set the item to its new position. + + \snippet examples/tools/undoframework/commands.cpp 1 + + Whenever a MoveCommand is created, this function is called to + check if it should be merged with the previous command. It is the + previous command object that is kept on the stack. The function + returns true if the command is merged; otherwise false. + + We first check whether it is the same item that has been moved + twice, in which case we merge the commands. We update the position + of the item so that it will take the last position in the move + sequence when undone. + + \section1 DiagramScene Class Definition + + \snippet examples/tools/undoframework/diagramscene.h 0 + + The DiagramScene implements the functionality to move a + DiagramItem with the mouse. It emits a signal when a move is + completed. This is caught by the \c MainWindow, which makes + MoveCommands. We do not examine the implementation of DiagramScene + as it only deals with graphics framework issues. + + \section1 The \c main() Function + + The \c main() function of the program looks like this: + + \snippet examples/tools/undoframework/main.cpp 0 + + We draw a grid in the background of the DiagramScene, so we use a + resource file. The rest of the function creates the \c MainWindow and + shows it as a top level window. +*/ diff --git a/doc/src/examples/waitconditions.qdoc b/doc/src/examples/waitconditions.qdoc new file mode 100644 index 0000000..dce0411 --- /dev/null +++ b/doc/src/examples/waitconditions.qdoc @@ -0,0 +1,166 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example threads/waitconditions + \title Wait Conditions Example + + The Wait Conditions example shows how to use QWaitCondition and + QMutex to control access to a circular buffer shared by a + producer thread and a consumer thread. + + The producer writes data to the buffer until it reaches the end + of the buffer, at which point it restarts from the beginning, + overwriting existing data. The consumer thread reads the data as + it is produced and writes it to standard error. + + Wait conditions make it possible to have a higher level of + concurrency than what is possible with mutexes alone. If accesses + to the buffer were simply guarded by a QMutex, the consumer + thread couldn't access the buffer at the same time as the + producer thread. Yet, there is no harm in having both threads + working on \e{different parts} of the buffer at the same time. + + The example comprises two classes: \c Producer and \c Consumer. + Both inherit from QThread. The circular buffer used for + communicating between these two classes and the synchronization + tools that protect it are global variables. + + An alternative to using QWaitCondition and QMutex to solve the + producer-consumer problem is to use QSemaphore. This is what the + \l{threads/semaphores}{Semaphores} example does. + + \section1 Global Variables + + Let's start by reviewing the circular buffer and the associated + synchronization tools: + + \snippet examples/threads/waitconditions/waitconditions.cpp 0 + + \c DataSize is the amount of data that the producer will generate. + To keep the example as simple as possible, we make it a constant. + \c BufferSize is the size of the circular buffer. It is less than + \c DataSize, meaning that at some point the producer will reach + the end of the buffer and restart from the beginning. + + To synchronize the producer and the consumer, we need two wait + conditions and one mutex. The \c bufferNotEmpty condition is + signalled when the producer has generated some data, telling the + consumer that it can start reading it. The \c bufferNotFull + condition is signalled when the consumer has read some data, + telling the producer that it can generate more. The \c numUsedBytes + is the number of bytes in the buffer that contain data. + + Together, the wait conditions, the mutex, and the \c numUsedBytes + counter ensure that the producer is never more than \c BufferSize + bytes ahead of the consumer, and that the consumer never reads + data that the consumer hasn't generated yet. + + \section1 Producer Class + + Let's review the code for the \c Producer class: + + \snippet examples/threads/waitconditions/waitconditions.cpp 1 + \snippet examples/threads/waitconditions/waitconditions.cpp 2 + + The producer generates \c DataSize bytes of data. Before it + writes a byte to the circular buffer, it must first check whether + the buffer is full (i.e., \c numUsedBytes equals \c BufferSize). + If the buffer is full, the thread waits on the \c bufferNotFull + condition. + + At the end, the producer increments \c numUsedBytes and signalls + that the condition \c bufferNotEmpty is true, since \c + numUsedBytes is necessarily greater than 0. + + We guard all accesses to the \c numUsedBytes variable with a + mutex. In addition, the QWaitCondition::wait() function accepts a + mutex as its argument. This mutex is unlocked before the thread + is put to sleep and locked when the thread wakes up. Furthermore, + the transition from the locked state to the wait state is atomic, + to prevent race conditions from occurring. + + \section1 Consumer Class + + Let's turn to the \c Consumer class: + + \snippet examples/threads/waitconditions/waitconditions.cpp 3 + \snippet examples/threads/waitconditions/waitconditions.cpp 4 + + The code is very similar to the producer. Before we read the + byte, we check whether the buffer is empty (\c numUsedBytes is 0) + instead of whether it's full and wait on the \c bufferNotEmpty + condition if it's empty. After we've read the byte, we decrement + \c numUsedBytes (instead of incrementing it), and we signal the + \c bufferNotFull condition (instead of the \c bufferNotEmpty + condition). + + \section1 The main() Function + + In \c main(), we create the two threads and call QThread::wait() + to ensure that both threads get time to finish before we exit: + + \snippet examples/threads/waitconditions/waitconditions.cpp 5 + \snippet examples/threads/waitconditions/waitconditions.cpp 6 + + So what happens when we run the program? Initially, the producer + thread is the only one that can do anything; the consumer is + blocked waiting for the \c bufferNotEmpty condition to be + signalled (\c numUsedBytes is 0). Once the producer has put one + byte in the buffer, \c numUsedBytes is \c BufferSize - 1 and the + \c bufferNotEmpty condition is signalled. At that point, two + things can happen: Either the consumer thread takes over and + reads that byte, or the consumer gets to produce a second byte. + + The producer-consumer model presented in this example makes it + possible to write highly concurrent multithreaded applications. + On a multiprocessor machine, the program is potentially up to + twice as fast as the equivalent mutex-based program, since the + two threads can be active at the same time on different parts of + the buffer. + + Be aware though that these benefits aren't always realized. + Locking and unlocking a QMutex has a cost. In practice, it would + probably be worthwhile to divide the buffer into chunks and to + operate on chunks instead of individual bytes. The buffer size is + also a parameter that must be selected carefully, based on + experimentation. +*/ diff --git a/doc/src/examples/wiggly.qdoc b/doc/src/examples/wiggly.qdoc new file mode 100644 index 0000000..5406c77 --- /dev/null +++ b/doc/src/examples/wiggly.qdoc @@ -0,0 +1,181 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/wiggly + \title Wiggly Example + + The Wiggly example shows how to animate a widget using + QBasicTimer and \l{QObject::timerEvent()}{timerEvent()}. In + addition, the example demonstrates how to use QFontMetrics to + determine the size of text on screen. + + \image wiggly-example.png Screenshot of the Wiggly example + + QBasicTimer is a low-level class for timers. Unlike QTimer, + QBasicTimer doesn't inherit from QObject; instead of emitting a + \l{QTimer::timeout()}{timeout()} signal when a certain amount of + time has passed, it sends a QTimerEvent to a QObject of our + choice. This makes QBasicTimer a more lightweight alternative to + QTimer. Qt's built-in widgets use it internally, and it is + provided in Qt's API for highly-optimized applications (e.g., + \l{Qt for Embedded Linux} applications). + + The example consists of two classes: + + \list + \o \c WigglyWidget is the custom widget displaying the text + in a wiggly line. + + \o \c Dialog is the dialog widget allowing the user to enter a + text. It combines a \c WigglyWidget and a \c QLineEdit. + \endlist + + We will first take a quick look at the \c Dialog class, then we + will review the \c WigglyWidget class. + + \section1 Dialog Class Definition + + \snippet examples/widgets/wiggly/dialog.h 0 + + The \c Dialog class provides a dialog widget that allows the user + to enter a text. The text is then rendered by \c WigglyWidget. + + \section1 Dialog Class Implementation + + \snippet examples/widgets/wiggly/dialog.cpp 0 + + In the constructor we create a wiggly widget along with a + \l{QLineEdit}{line edit}, and we put the two widgets in a + vertical layout. We connect the line edit's \l + {QLineEdit::textChanged()}{textChanged()} signal to the wiggly + widget's \c setText() slot to obtain the real time interaction + with the wiggly widget. The widget's default text is "Hello + world!". + + \section1 WigglyWidget Class Definition + + \snippet examples/widgets/wiggly/wigglywidget.h 0 + + The \c WigglyWidget class provides the wiggly line displaying the + text. We subclass QWidget and reimplement the standard \l + {QWidget::paintEvent()}{paintEvent()} and \l + {QObject::timerEvent()}{timerEvent()} functions to draw and update + the widget. In addition we implement a public \c setText() slot + that sets the widget's text. + + The \c timer variable, of type QBasicTimer, is used to update the + widget at regular intervals, making the widget move. The \c text + variable is used to store the currently displayed text, and \c + step to calculate position and color for each character on the + wiggly line. + + \section1 WigglyWidget Class Implementation + + \snippet examples/widgets/wiggly/wigglywidget.cpp 0 + + In the constructor, we make the widget's background slightly + lighter than the usual background using the QPalette::Midlight + color role. The background role defines the brush from the + widget's palette that Qt uses to paint the background. Then we + enlarge the widget's font with 20 points. + + Finally we start the timer; the call to QBasicTimer::start() + makes sure that \e this particular wiggly widget will receive the + timer events generated when the timer times out (every 60 + milliseconds). + + \snippet examples/widgets/wiggly/wigglywidget.cpp 1 + \snippet examples/widgets/wiggly/wigglywidget.cpp 2 + + The \c paintEvent() function is called whenever a QPaintEvent is + sent to the widget. Paint events are sent to widgets that need to + update themselves, for instance when part of a widget is exposed + because a covering widget was moved. For the wiggly widget, a + paint event will also be generated every 60 milliseconds from + the \c timerEvent() slot. + + The \c sineTable represents y-values of the sine curve, + multiplied by 100. It is used to make the wiggly widget move + along the sine curve. + + The QFontMetrics object provides information about the widget's + font. The \c x variable is the horizontal position where we start + drawing the text. The \c y variable is the vertical position of + the text's base line. Both variables are computed so that the + text is horizontally and vertically centered. To compute the base + line, we take into account the font's ascent (the height of the + font above the base line) and font's descent (the height of the + font below the base line). If the descent equals the ascent, they + cancel out each other and the base line is at \c height() / 2. + + \snippet examples/widgets/wiggly/wigglywidget.cpp 3 + \snippet examples/widgets/wiggly/wigglywidget.cpp 4 + + Each time the \c paintEvent() function is called, we create a + QPainter object \c painter to draw the contents of the widget. + For each character in \c text, we determine the color and the + position on the wiggly line based on \c step. In addition, \c x + is incremented by the character's width. + + For simplicity, we assume that QFontMetrics::width(\c text) + returns the sum of the individual character widths + (QFontMetrics::width(\c text[i])). In practice, this is not + always the case because QFontMetrics::width(\c text) also takes + into account the kerning between certain letters (e.g., 'A' and + 'V'). The result is that the text isn't perfectly centered. You + can verify this by typing "AVAVAVAVAVAV" in the line edit. + + \snippet examples/widgets/wiggly/wigglywidget.cpp 5 + \snippet examples/widgets/wiggly/wigglywidget.cpp 6 + + The \c timerEvent() function receives all the timer events that + are generated for this widget. If a timer event is sent from the + widget's QBasicTimer, we increment \c step to make the text move, + and call QWidget::update() to refresh the display. Any other + timer event is passed on to the base class's implementation of + the \l{QWidget::timerEvent()}{timerEvent()} function. + + The QWidget::update() slot does not cause an immediate repaint; + instead the slot schedules a paint event for processing when Qt + returns to the main event loop. The paint events are then handled + by \c{WigglyWidget}'s \c paintEvent() function. +*/ diff --git a/doc/src/examples/windowflags.qdoc b/doc/src/examples/windowflags.qdoc new file mode 100644 index 0000000..b25206e --- /dev/null +++ b/doc/src/examples/windowflags.qdoc @@ -0,0 +1,230 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/windowflags + \title Window Flags Example + + The Window Flags example shows how to use the window flags + available in Qt. + + A window flag is either a type or a hint. A type is used to + specify various window-system properties for the widget. A widget + can only have one type, and the default is Qt::Widget. However, a + widget can have zero or more hints. The hints are used to + customize the appearance of top-level windows. + + A widget's flags are stored in a Qt::WindowFlags type which stores + an OR combination of the flags. + + \image windowflags-example.png Screenshot of the Window Flags example + + The example consists of two classes: + + \list + \o \c ControllerWindow is the main application widget that allows + the user to choose among the available window flags, and displays + the effect on a separate preview window. + \o \c PreviewWindow is a custom widget displaying the name of + its currently set window flags in a read-only text editor. + \endlist + + We will start by reviewing the \c ControllerWindow class, then we + will take a look at the \c PreviewWindow class. + + \section1 ControllerWindow Class Definition + + \snippet examples/widgets/windowflags/controllerwindow.h 0 + + The \c ControllerWindow class inherits QWidget. The widget allows + the user to choose among the available window flags, and displays + the effect on a separate preview window. + + We declare a private \c updatePreview() slot to refresh the + preview window whenever the user changes the window flags. + + We also declare several private functions to simplify the + constructor: We call the \c createTypeGroupBox() function to + create a radio button for each available window type, using the + private \c createButton() function, and gather them within a group + box. In a similar way we use the \c createHintsGroupBox() function + to create a check box for each available hint, using the private + \c createCheckBox() function. + + In addition to the various radio buttons and checkboxes, we need + an associated \c PreviewWindow to show the effect of the currently + chosen window flags. + + \image windowflags_controllerwindow.png Screenshot of the Controller Window + + \section1 ControllerWindow Class Implementation + + \snippet examples/widgets/windowflags/controllerwindow.cpp 0 + + In the constructor we first create the preview window. Then we + create the group boxes containing the available window flags using + the private \c createTypeGroupBox() and \c createHintsGroupBox() + functions. In addition we create a \gui Quit button. We put the + button and a stretchable space in a separate layout to make the + button appear in the \c WindowFlag widget's right bottom corner. + + Finally, we add the button's layout and the two goup boxes to a + QVBoxLayout, set the window title and refresh the preview window + using the \c updatePreview() slot. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 1 + \snippet examples/widgets/windowflags/controllerwindow.cpp 2 + + The \c updatePreview() slot is called whenever the user changes + any of the window flags. First we create an empty Qt::WindowFlags + \c flags, then we determine which one of the types that is checked + and add it to \c flags. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 3 + + We also determine which of the hints that are checked, and add + them to \c flags using an OR operator. We use \c flags to set the + window flags for the preview window. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 4 + + We adjust the position of the preview window. The reason we do + that, is that playing around with the window's frame may on some + platforms cause the window's position to be changed behind our + back. If a window is located in the upper left corner of the + screen, parts of the window may not be visible. So we adjust the + widget's position to make sure that, if this happens, the window + is moved within the screen's boundaries. Finally, we call + QWidget::show() to make sure the preview window is visible. + + \omit + \skipto pos + \printuntil /^\}/ + \endomit + + \snippet examples/widgets/windowflags/controllerwindow.cpp 5 + + The private \c createTypeGroupBox() function is called from the + constructor. + + First we create a group box, and then we create a radio button + (using the private \c createRadioButton() function) for each of + the available types among the window flags. We make Qt::Window the + initially applied type. We put the radio buttons into a + QGridLayout and install the layout on the group box. + + We do not include the default Qt::Widget type. The reason is that + it behaves somewhat different than the other types. If the type is + not specified for a widget, and it has no parent, the widget is a + window. However, if it has a parent, it is a standard child + widget. The other types are all top-level windows, and since the + hints only affect top-level windows, we abandon the Qt::Widget + type. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 6 + + The private \c createHintsGroupBox() function is also called from + the constructor. + + Again, the first thing we do is to create a group box. Then we + create a checkbox, using the private \c createCheckBox() function, + for each of the available hints among the window flags. We put the + checkboxes into a QGridLayout and install the layout on the group + box. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 7 + + The private \c createCheckBox() function is called from \c + createHintsGroupBox(). + + We simply create a QCheckBox with the provided text, connect it to + the private \c updatePreview() slot, and return a pointer to the + checkbox. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 8 + + In the private \c createRadioButton() function it is a + QRadioButton we create with the provided text, and connect to the + private \c updatePreview() slot. The function is called from \c + createTypeGroupBox(), and returns a pointer to the button. + + \section1 PreviewWindow Class Definition + + \snippet examples/widgets/windowflags/previewwindow.h 0 + + The \c PreviewWindow class inherits QWidget. It is a custom widget + that displays the names of its currently set window flags in a + read-only text editor. It is also provided with a QPushbutton that + closes the window. + + We reimplement the constructor to create the \gui Close button and + the text editor, and the QWidget::setWindowFlags() function to + display the names of the window flags. + + \image windowflags_previewwindow.png Screenshot of the Preview Window + + \section1 PreviewWindow Class Implementation + + \snippet examples/widgets/windowflags/previewwindow.cpp 0 + + In the constructor, we first create a QTextEdit and make sure that + it is read-only. + + We also prohibit any line wrapping in the text editor using the + QTextEdit::setLineWrapMode() function. The result is that a + horizontal scrollbar appears when a window flag's name exceeds the + width of the editor. This is a reasonable solution since we + construct the displayed text with built-in line breaks. If no line + breaks were guaranteed, using another QTextEdit::LineWrapMode + would perhaps make more sense. + + Then we create the \gui Close button, and put both the widgets + into a QVBoxLayout before we set the window title. + + \snippet examples/widgets/windowflags/previewwindow.cpp 1 + + In our reimplementation of the \c setWindowFlags() function, we + first set the widgets flags using the QWidget::setWindowFlags() + function. Then we run through the available window flags, creating + a text that contains the names of the flags that matches the \c + flags parameter. Finally, we display the text in the widgets text + editor. +*/ diff --git a/doc/src/examples/worldtimeclockbuilder.qdoc b/doc/src/examples/worldtimeclockbuilder.qdoc new file mode 100644 index 0000000..644ffdb --- /dev/null +++ b/doc/src/examples/worldtimeclockbuilder.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example designer/worldtimeclockbuilder + \title World Time Clock Builder Example + + The World Time Clock Builder example shows how forms created with Qt + Designer that contain custom widgets can be dynamically generated at + run-time. + + \image worldtimeclockbuilder-example.png + + This example uses a form containing the custom widget plugin described in the + \l{designer/worldtimeclockplugin}{World Time Clock Plugin} example, and + dynamically generates a user interface using the QUiLoader class, part of + the QtUiTools module. + + \section1 Preparation + + As with the \l{designer/calculatorbuilder}{Calculator Builder} example, the + project file for this example needs to include the appropriate definitions + to ensure that it is built against the required Qt modules. + + \snippet examples/designer/worldtimeclockbuilder/worldtimeclockbuilder.pro 0 + + By appending \c form to the \c CONFIG declaration, we instruct \c qmake to + generate a dependency on the \c libQtUiTools library containing the QtUiTools + classes. + + Note that we do not inform \c qmake about any .ui files, and so none will + be processed and built into the application. The resource file contains + an entry for the particular form that we wish to use: + + \quotefile examples/designer/worldtimeclockbuilder/worldtimeclockbuilder.qrc + + Forms do not need to be included with the application in this way. We only + include a form in the application's resources for convenience, and to keep + the example short. + + \section1 Loading and Building the Form + + Since this example only loads and displays a pre-prepared form, all of the + work can be done in the main() function. We are using a class from the + QtUiTools library so, in addition to any other Qt classes that are normally + required to write an application, we must include the appropriate header + file: + + \snippet examples/designer/worldtimeclockbuilder/main.cpp 0 + + The main function initializes the resource system with the Q_INIT_RESOURCE() + macro and constructs an QApplication instance in the usual way: + + \snippet examples/designer/worldtimeclockbuilder/main.cpp 1 + + We construct a QUiLoader object to handle the form we want to use. + + The form itself is obtained from the resource file system using the path + defined in the resource file. We use the form loader to load and construct + the form: + + \snippet examples/designer/worldtimeclockbuilder/main.cpp 2 + + Once the form has been loaded, the resource file can be closed and the + widget is shown. + + \snippet examples/designer/worldtimeclockbuilder/main.cpp 3 + + The form loader ensures that all the signal and slot connections between + objects in the form are set up correctly when the form is loaded. As a + result, the time is updated by the World Time Clock widget, and the time + zone spin box can be used to change the position of the hour hand. +*/ diff --git a/doc/src/examples/worldtimeclockplugin.qdoc b/doc/src/examples/worldtimeclockplugin.qdoc new file mode 100644 index 0000000..072b1f0 --- /dev/null +++ b/doc/src/examples/worldtimeclockplugin.qdoc @@ -0,0 +1,210 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example designer/worldtimeclockplugin + \title World Time Clock Plugin Example + + The World Time Clock Plugin example shows how to create a custom + widget plugin for \QD that uses signals and slots. + + \image worldtimeclockplugin-example.png + + In this example, we simply extend the \l + {designer/customwidgetplugin}{Custom Widget Plugin} example and + its custom widget (based on the \l{widgets/analogclock}{Analog + Clock} example), by introducing the concept of signals and slots. + + The World Time Clock Plugin example consists of two classes: + + \list + \o \c WorldTimeClock is a custom clock widget with hour and + minute hands that is automatically updated every few seconds. + \o \c WorldTimeClockPlugin exposes the \c WorldTimeClock class to \QD. + \endlist + + First we will take a look at the \c WorldTimeClock class which + extends the \l {designer/customwidgetplugin}{Custom Widget Plugin} + example's \c AnalogClock class by providing a signal and a + slot. Then we will take a quick look at the \c + WorldTimeClockPlugin class, but this class is in most parts + identical to the \l {designer/customwidgetplugin}{Custom Widget + Plugin} example's implementation. + + Finally we take a look at the plugin's project file. The project + file for custom widget plugins needs some additional information + to ensure that they will work within \QD. This is also covered in + the \l {designer/customwidgetplugin}{Custom Widget Plugin} example, + but due to its importance (custom widget plugins rely on + components supplied with \QD which must be specified in the + project file that we use) we will repeat it here. + + \section1 WorldTimeClock Class + + The \c WorldTimeClock class inherits QWidget, and is a custom + clock widget with hour and minute hands that is automatically + updated every few seconds. What makes this example different from + the \l {designer/customwidgetplugin}{Custom Widget Plugin} + example, is the introduction of the signal and slot in the custom + widget class: + + \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 1 + + Note the use of the QDESIGNER_WIDGET_EXPORT macro. This is needed + to ensure that \QD can create instances of the widget on some + platforms, but it is a good idea to use it on all platforms. + + We declare the \c setTimeZone() slot with an associated \c + timeZoneOffset variable, and we declare an \c updated() signal + which takes the current time as argument and is emitted whenever + the widget is repainted. + + \image worldtimeclock-connection.png + + In \QD's workspace we can then, for example, connect the \c + WorldTimeClock widget's \c updated() signal to a QTimeEdit's \l + {QDateTimeEdit::setTime()}{setTime()} slot using \QD's mode + for editing signal and slots. + + \image worldtimeclock-signalandslot.png + + We can also connect a QSpinBox's \l + {QSpinBox::valueChanged()}{valueChanged()} signal to the \c + WorldTimeClock's \c setTimeZone() slot. + + \section1 WorldTimeClockPlugin Class + + The \c WorldTimeClockPlugin class exposes the \c WorldTimeClock + class to \QD. Its definition is equivalent to the \l + {designer/customwidgetplugin}{Custom Widget Plugin} example's + plugin class which is explained in detail. The only part of the + class definition that is specific to this particular custom widget + is the class name: + + \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.h 0 + + The plugin class provides \QD with basic information about our + plugin, such as its class name and its include file. Furthermore + it knows how to create instances of the \c WorldTimeClockPlugin + widget. \c WorldTimeClockPlugin also defines the \l + {QDesignerCustomWidgetInterface::initialize()}{initialize()} + function which is called after the plugin is loaded into \QD. The + function's QDesignerFormEditorInterface parameter provides the + plugin with a gateway to all of \QD's API's. + + The \c WorldTimeClockPlugin class inherits from both QObject and + QDesignerCustomWidgetInterface. It is important to remember, when + using multiple inheritance, to ensure that all the interfaces + (i.e. the classes that doesn't inherit Q_OBJECT) are made known to + the meta object system using the Q_INTERFACES() macro. This + enables \QD to use \l qobject_cast() to query for supported + interfaces using nothing but a QObject pointer. + + The implementation of the \c WorldTimeClockPlugin is also + equivalent to the plugin interface implementation in the \l + {designer/customwidgetplugin}{Custom Widget Plugin} example (only + the class name and the implementation of + QDesignerCustomWidgetInterface::domXml() differ). The main thing + to remember is to use the Q_EXPORT_PLUGIN2() macro to export the \c + WorldTimeClockPlugin class for use with \QD: + + \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.cpp 0 + + Without this macro, there is no way for Qt Designer to use the + widget. + + \section1 The Project File: worldtimeclockplugin.pro + + The project file for custom widget plugins needs some additional + information to ensure that they will work as expected within \QD: + + \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 0 + \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 1 + + The \c TEMPLATE variable's value make \c qmake create the custom + widget as a library. The \c CONFIG variable contains two values, + \c designer and \c plugin: + + \list + \o \c designer: Since custom widgets plugins rely on components + supplied with \QD, this value ensures that our plugin links against + \QD's library (\c libQtDesigner.so). + + \o \c plugin: We also need to ensure that \c qmake considers the + custom widget a \e plugin library. + \endlist + + When Qt is configured to build in both debug and release modes, + \QD will be built in release mode. When this occurs, it is + necessary to ensure that plugins are also built in release + mode. For that reason you might have to add a \c release value to + your \c CONFIG variable. Otherwise, if a plugin is built in a mode + that is incompatible with \QD, it won't be loaded and + installed. + + The header and source files for the widget are declared in the + usual way, and in addition we provide an implementation of the + plugin interface so that \QD can use the custom widget. + + \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 2 + + It is important to ensure that the plugin is installed in a location that + is searched by \QD. We do this by specifying a target path for the project + and adding it to the list of items to install: + + \snippet doc/src/snippets/code/doc_src_examples_worldtimeclockplugin.qdoc 0 + + The custom widget is created as a library, and will be installed + alongside the other \QD plugins when the project is installed + (using \c{make install} or an equivalent installation procedure). + Later, we will ensure that it is recognized as a plugin by \QD by + using the Q_EXPORT_PLUGIN2() macro to export the relevant widget + information. + + Note that if you want the plugins to appear in a Visual Studio + integration, the plugins must be built in release mode and their + libraries must be copied into the plugin directory in the install + path of the integration (for an example, see \c {C:/program + files/trolltech as/visual studio integration/plugins}). + + For more information about plugins, see the \l {How to Create Qt + Plugins} document. +*/ diff --git a/doc/src/examples/xmlstreamlint.qdoc b/doc/src/examples/xmlstreamlint.qdoc new file mode 100644 index 0000000..925a7a0 --- /dev/null +++ b/doc/src/examples/xmlstreamlint.qdoc @@ -0,0 +1,86 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/xmlstreamlint + \title XML Stream Lint Example + + The XML Stream Lint example provides a simple command line utility that + accepts a file name as its single argument and writes it to the standard + output file. + + The specified file is parsed using an QXmlStreamReader object and written + to the standard output file using an QXmlStreamWriter object. If the file + does not contain a well-formed XML document or the use of namespaces in + the document is incorrect, a description of the error is printed to + the standard error file and will appear in the console. + + \section1 Basic Operation + + The main function of the example opens the file specified by the user + for input (\c inputFile), and it uses QFile to access the standard output + file. + + Reading XML is handled by an instance of the QXmlStreamReader class, which + operates on the input file object; writing is handled by an instance of + QXmlStreamWriter operating on the output file object: + + \snippet examples/xml/xmlstreamlint/main.cpp 0 + + The work of parsing and rewriting the XML is done in a while loop, and is + driven by input from the reader: + + \snippet examples/xml/xmlstreamlint/main.cpp 1 + + If more input is available, the next token from the input file is read + and parsed. If an error occurred, information is written to the standard + error file via a stream, and the example exits by returning a non-zero + value from the main function. + + \snippet examples/xml/xmlstreamlint/main.cpp 2 + + For valid input, the writer is fed the current token from the reader, + and this is written to the output file that was specified when it was + constructed. + + When there is no more input, the loop terminates, and the example can + exit successfully. +*/ diff --git a/doc/src/exportedfunctions.qdoc b/doc/src/exportedfunctions.qdoc new file mode 100644 index 0000000..f67950c --- /dev/null +++ b/doc/src/exportedfunctions.qdoc @@ -0,0 +1,136 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page exportedfunctions.html + \title Special-Purpose Global Functions Exported by Qt + \ingroup classlists + + Qt provides a few low-level global functions for fine-tuning + applications. Most of these perform very specific tasks and are + platform-specific. In general, we recommend that you try using + Qt's public API before resorting to using any functions mentioned + here. + + These functions are exported by \l QtCore and \l QtGui, but most + of them aren't declared in Qt's header files. To use them in your + application, you must declare them before calling them. For + example: + + \snippet doc/src/snippets/code/doc_src_exportedfunctions.qdoc 0 + + These functions will remain as part of Qt for the lifetime of Qt + 4. + + Functions: + + \tableofcontents + + \section1 void qt_set_library_config_file(const QString &\e{fileName}) + + Specifies the location of the Qt configuration file. You must + call this function before constructing a QApplication or + QCoreApplication object. If no location is specified, Qt + automatically finds an appropriate location. + + \section1 void qt_set_sequence_auto_mnemonic(bool \e{enable}) + + Specifies whether mnemonics for menu items, labels, etc., should + be honored or not. On Windows and X11, this feature is + on by default; on Mac OS X, it is off. When this feature is off, + the QKeySequence::mnemonic() function always returns an empty + string. This feature is also enabled on embedded Linux. + + \section1 void qt_x11_wait_for_window_manager(QWidget *\e{widget}) + + Blocks until the X11 window manager has shown the widget after a + call to QWidget::show(). + + \section1 void qt_mac_secure_keyboard(bool \e{enable}) + + Turns the Mac OS X secure keyboard feature on or off. QLineEdit + uses this when the echo mode is QLineEdit::Password or + QLineEdit::NoEcho to guard the editor against keyboard sniffing. + If you implement your own password editor, you might want to turn + on this feature in your editor's + \l{QWidget::focusInEvent()}{focusInEvent()} and turn it off in + \l{QWidget::focusOutEvent()}{focusOutEvent()}. + + \section1 void qt_mac_set_dock_menu(QMenu *\e{menu}) + + Sets the menu to display in the Mac OS X Dock for the + application. This menu is shown when the user attempts a + press-and-hold operation on the application's dock icon or + \key{Ctrl}-clicks on it while the application is running. + + The menu will be turned into a Mac menu and the items added to the default + Dock menu. There is no merging of the Qt menu items with the items that are + in the Dock menu (i.e., it is not recommended to include actions that + duplicate functionality of items already in the Dock menu). + + \section1 void qt_mac_set_menubar_icons(bool \e{enable}) + + Specifies whether icons associated to menu items for the + application's menu bar should be shown on Mac OS X. By default, + icons are shown on Mac OS X just like on the other platforms. + + In Qt 4.4, this is equivalent to + \c { QApplication::instance()->setAttribute(Qt::AA_DontShowIconsInMenus); }. + + \section1 void qt_mac_set_menubar_merge(bool \e{enable}) + + Specifies whether Qt should attempt to relocate standard menu + items (such as \gui Quit, \gui Preferences, and \gui About) to + the application menu on Mac OS X. This feature is on by default. + See \l{Qt for Mac OS X - Specific Issues} for the list of menu items for + which this applies. + + \section1 void qt_mac_set_native_menubar(bool \e{enable}) + + Specifies whether the application should use the native menu bar + on Mac OS X or be part of the main window. This feature is on by + default. + + \section1 void qt_mac_set_press_and_hold_context(bool \e{enable}) + + Turns emulation of the right mouse button by clicking and holding + the left mouse button on or off. This feature is off by default. +*/ diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc new file mode 100644 index 0000000..f48c3d7 --- /dev/null +++ b/doc/src/external-resources.qdoc @@ -0,0 +1,349 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \externalpage http://www.freedesktop.org/ + \title freedesktop.org +*/ + +/*! + \externalpage http://www.freedesktop.org/Standards/xembed-spec + \title XEmbed Specification +*/ + +/*! + \externalpage http://www.freedesktop.org/Standards/icon-theme-spec + \title Icon Themes Specification +*/ + +/*! + \externalpage http://www.cups.org/ + \title Common Unix Printing System (CUPS) + \keyword CUPS +*/ + +/*! + \externalpage http://www.freedesktop.org/wiki/Standards_2fdesktop_2dentry_2dspec + \title Desktop Entry Specification +*/ + +/*! + \externalpage http://www.kde.org/ + \title The K Desktop Environment + \keyword KDE +*/ + +/*! + \externalpage http://www.gnome.org/ + \title GNOME +*/ + +/*! + \externalpage http://www.gnu.org/software/emacs/ + \title GNU Emacs +*/ + +/*! + \externalpage http://www.amnesty.org/ + \title Amnesty International +*/ + +/*! + \externalpage http://www.w3.org/Graphics/SVG/About.html + \title About SVG + \keyword Scalable Vector Graphics +*/ + +/*! + \externalpage http://www.w3.org/TR/SVG/types.html#ColorKeywords + \title SVG color keyword names +*/ + +/*! + \externalpage http://www.w3.org/Graphics/SVG/ + \title SVG Working Group +*/ + +/*! + \externalpage http://www.w3.org/TR/SVGMobile/ + \title Mobile SVG Profiles + \omit + Mobile SVG Profiles: SVG Tiny and SVG Basic + \endomit +*/ + +/*! + \externalpage http://www.w3.org/TR/SVGMobile12/ + \title SVG 1.2 Tiny +*/ + +/*! + \externalpage http://www.w3.org/Graphics/SVG/feature/1.2/#SVG-static + \title SVG 1.2 Tiny Static Features +*/ + +/*! + \externalpage http://www.ietf.org/rfc/rfc1179.txt + \title RFC 1179 + \keyword lpr +*/ + +/*! + \externalpage http://www.rfc-editor.org/rfc/rfc1738.txt + \title RFC 1738 +*/ + +/*! + \externalpage http://www.rfc-editor.org/rfc/rfc1928.txt + \title RFC 1928 +*/ + +/*! + \externalpage http://www.rfc-editor.org/rfc/rfc1929.txt + \title RFC 1929 +*/ + +/*! + \externalpage http://www.rfc-editor.org/rfc/rfc2045.txt + \title RFC 2045 +*/ + +/*! + \externalpage http://www.rfc-editor.org/rfc/rfc2109.txt + \title RFC 2109 + HTTP State Management Mechanism +*/ + +/*! + \externalpage http://www.rfc-editor.org/rfc/rfc2965.txt + \title RFC 2965 + HTTP State Management Mechanism +*/ + +/*! + \externalpage http://www.rfc-editor.org/rfc/rfc3174.txt + \title RFC 3174 +*/ + +/*! + \externalpage http://www.rfc-editor.org/rfc/rfc3491.txt + \title RFC 3491 +*/ + +/*! + \externalpage http://www.rfc-editor.org/rfc/rfc3986.txt + \title RFC 3986 +*/ + +/*! + \externalpage http://www.dependencywalker.com/ + \title Dependency Walker +*/ + +/*! + \externalpage http://www.ecma-international.org/publications/standards/Ecma-262.htm + \title ECMA-262 +*/ + +/*! + \externalpage http://www.davidflanagan.com/javascript5/ + \title JavaScript: The Definitive Guide +*/ + +/*! + \externalpage http://webkit.org/ + \title WebKit Open Source Project +*/ + +/*! + \externalpage http://www.informit.com/store/product.aspx?isbn=0132354160 + \title C++ GUI Programming with Qt 4, 2nd Edition +*/ + +/*! + \externalpage http://www.openssl.org/ + \title OpenSSL Toolkit +*/ + +/*! + \externalpage http://arora-browser.org/ + \title Arora Browser +*/ + +/*! + \externalpage http://www.activestate.com/Products/activeperl/index.mhtml + \title ActivePerl +*/ + +/*! + \externalpage http://www.w3.org/TR/html401/ + \title HTML 4 +*/ + +/*! + \externalpage http://www.w3.org/TR/html5/ + \title HTML 5 +*/ + +/*! + \externalpage http://pyxml.sourceforge.net/topics/xbel/ + \title XML Bookmark Exchange Language Resource Page +*/ + +/*! + \externalpage http://www.w3.org/TR/xquery/#errors + \title error handling in the XQuery language +*/ + +/*! + \externalpage http://xaos.sourceforge.net/ + \title XaoS +*/ + +/*! + \externalpage http://www.unixodbc.org + \title http://www.unixodbc.org +*/ + +/*! + \externalpage http://www.postgresql.org + \title http://www.postgresql.org +*/ + +/*! + \externalpage http://www.postgresql.org/docs/faqs.FAQ_MINGW.html + \title Compiling PostgreSQL On Native Win32 FAQ +*/ + +/*! + \externalpage http://www.freetds.org + \title http://www.freetds.org +*/ + +/*! + \externalpage http://www.sybase.com + \title http://www.sybase.com +*/ + +/*! + \externalpage http://linux.sybase.com + \title http://linux.sybase.com +*/ + +/*! + \externalpage http://www.sqlite.org + \title http://www.sqlite.org +*/ + +/*! + \externalpage http://www.amazon.com/exec/obidos/ASIN/0134436989/trolltech/t + \title Threads Primer: A Guide to Multithreaded Programming +*/ + +/*! + \externalpage http://www.amazon.com/exec/obidos/ASIN/0131900676/trolltech/t + \title Thread Time: The Multithreaded Programming Guide +*/ + +/*! + \externalpage http://www.amazon.com/exec/obidos/ASIN/1565921151/trolltech/t + \title Pthreads Programming: A POSIX Standard for Better Multiprocessing +*/ + +/*! + \externalpage http://www.amazon.com/exec/obidos/ASIN/1565922964/trolltech/t + \title Win32 Multithreaded Programming +*/ + +/*! + \externalpage http://www.iana.org/assignments/character-sets + \title IANA character-sets encoding file +*/ + +/*! + \externalpage http://www.phptr.com/content/images/0131872494/samplechapter/blanchette_ch10.pdf + \title "Item View Classes" Chapter of C++ GUI Programming with Qt 4 +*/ + +/*! + \externalpage http://developer.apple.com/documentation/UserExperience/Conceptual/AppleHIGuidelines/XHIGIntro/chapter_1_section_1.html + \title Mac OS X Aqua +*/ + +/*! + \externalpage http://www.kdedevelopers.org/node/2345 + \title KDE applications +*/ + +/*! + \externalpage http://cgi.netscape.com/newsref/std/cookie_spec.html + \title Netscape Cookie Specification +*/ + +/*! + \externalpage http://msdn.microsoft.com/en-us/library/ms533046(VS.85).aspx + \title Mitigating Cross-site Scripting With HTTP-only Cookies +*/ + +/*! + \externalpage http://en.tldp.org/HOWTO/Framebuffer-HOWTO.html + \title Framebuffer HOWTO +*/ + +/*! + \externalpage http://wap.trafikanten.no + \title Trafikanten +*/ + +/*! + \externalpage http://www.gnu.org/licenses/gpl.html + \title GNU General Public License +*/ + +/*! + \externalpage http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html + \title GNU Lesser General Public License, version 2.1 +*/ + +/*! + \externalpage http://developers.sun.com/sunstudio/downloads/patches/index.jsp + \title Sun Studio Patches +*/ diff --git a/doc/src/focus.qdoc b/doc/src/focus.qdoc new file mode 100644 index 0000000..defb3e0 --- /dev/null +++ b/doc/src/focus.qdoc @@ -0,0 +1,213 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/**************************************************************************** +** +** Documentation of focus handling in Qt. +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the Qt GUI Toolkit. +** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE +** +****************************************************************************/ + +/*! + \page focus.html + \title Keyboard Focus + \ingroup architecture + \ingroup gui-programming + \brief An overview of the keyboard focus management and handling. + + \keyword keyboard focus + + Qt's widgets handle keyboard focus in the ways that have become + customary in GUIs. + + The basic issue is that the user's key strokes can be directed at any + of several windows on the screen, and any of several widgets inside + the intended window. When the user presses a key, they expect it to go + to the right place, and the software must try to meet this + expectation. The system must determine which application the key stroke + is directed at, which window within that application, and which widget + within that window. + + \section1 Focus Motion + + The customs which have evolved for directing keyboard focus to a + particular widget are these: + + \list 1 + + \o The user presses \key Tab (or \key Shift+Tab). + \o The user clicks a widget. + \o The user presses a keyboard shortcut. + \o The user uses the mouse wheel. + \o The user moves the focus to a window, and the application must + determine which widget within the window should get the focus. + \endlist + + Each of these motion mechanisms is different, and different types of + widgets receive focus in only some of them. We'll cover each of them + in turn. + + \section2 Tab or Shift+Tab + + Pressing \key Tab is by far the most common way to move focus + using the keyboard. (Sometimes in data-entry applications Enter + does the same as \key{Tab}; this can easily be achieved in Qt by + implementing an \l{Events and Event Filters}{event filter}.) + + Pressing \key Tab, in all window systems in common use today, + moves the keyboard focus to the next widget in a circular + per-window list. \key Tab moves focus along the circular list in + one direction, \key Shift+Tab in the other. The order in which + \key Tab presses move from widget to widget is called the tab order. + + You can customize the tab order using QWidget::setTabOrder(). (If + you don't, \key Tab generally moves focus in the order of widget + construction.) \l{Qt Designer} provides a means of visually + changing the tab order. + + Since pressing \key Tab is so common, most widgets that can have focus + should support tab focus. The major exception is widgets that are + rarely used, and where there is some keyboard accelerator or error + handler that moves the focus. + + For example, in a data entry dialog, there might be a field that + is only necessary in one per cent of all cases. In such a dialog, + \key Tab could skip this field, and the dialog could use one of + these mechanisms: + + \list 1 + + \o If the program can determine whether the field is needed, it can + move focus there when the user finishes entry and presses \gui OK, or when + the user presses Enter after finishing the other fields. Alternately, + include the field in the tab order but disable it. Enable it if it + becomes appropriate in view of what the user has set in the other + fields. + + \o The label for the field can include a keyboard shortcut that moves + focus to this field. + + \endlist + + Another exception to \key Tab support is text-entry widgets that + must support the insertion of tabs; almost all text editors fall + into this class. Qt treats \key Ctrl+Tab as \key Tab and \key + Ctrl+Shift+Tab as \key Shift+Tab, and such widgets can + reimplement QWidget::event() and handle Tab before calling + QWidget::event() to get normal processing of all other keys. + However, since some systems use \key Ctrl+Tab for other purposes, + and many users aren't aware of \key Ctrl+Tab anyway, this isn't a + complete solution. + + \section2 The User Clicks a Widget + + This is perhaps even more common than pressing \key Tab on + computers with a mouse or other pointing device. + + Clicking to move the focus is slightly more powerful than \key + Tab. While it moves the focus \e to a widget, for editor widgets + it also moves the text cursor (the widget's internal focus) to + the spot where the mouse is clicked. + + Since it is so common and people are used to it, it's a good idea to + support it for most widgets. However, there is also an important + reason to avoid it: you may not want to remove focus from the widget + where it was. + + For example, in a word processor, when the user clicks the 'B' (bold) + tool button, what should happen to the keyboard focus? Should it + remain where it was, almost certainly in the editing widget, or should + it move to the 'B' button? + + We advise supporting click-to-focus for widgets that support text + entry, and to avoid it for most widgets where a mouse click has a + different effect. (For buttons, we also recommend adding a keyboard + shortcut: QAbstractButton and its subclasses make this very easy.) + + In Qt, only the QWidget::setFocusPolicy() function affects + click-to-focus. + + \section2 The User Presses a Keyboard Shortcut + + It's not unusual for keyboard shortcuts to move the focus. This + can happen implicitly by opening modal dialogs, but also + explicitly using focus accelerators such as those provided by + QLabel::setBuddy(), QGroupBox, and QTabBar. + + We advise supporting shortcut focus for all widgets that the user + may want to jump to. For example, a tab dialog can have keyboard + shortcuts for each of its pages, so the user can press e.g. \key + Alt+P to step to the \underline{P}rinting page. It is easy to + overdo this: there are only a few keys, and it's also important + to provide keyboard shortcuts for commands. \key Alt+P is also + used for Paste, Play, Print, and Print Here in the \l{Standard + Accelerator Keys} list, for example. + + \section2 The User Rotates the Mouse Wheel + + On Microsoft Windows, mouse wheel usage is always handled by the + widget that has keyboard focus. On Mac OS X and X11, it's handled by + the widget that gets other mouse events. + + The way Qt handles this platform difference is by letting widgets move + the keyboard focus when the wheel is used. With the right focus policy + on each widget, applications can work idiomatically correctly on + Windows, Mac OS X, and X11. + + \section2 The User Moves the Focus to This Window + + In this situation the application must determine which widget within + the window should receive the focus. + + This can be simple: If the focus has been in this window before, + then the last widget to have focus should regain it. Qt does this + automatically. + + If focus has never been in this window before and you know where + focus should start out, call QWidget::setFocus() on the widget + which should receive focus before you call QWidget::show() it. If + you don't, Qt will pick a suitable widget. +*/ diff --git a/doc/src/functions.qdoc b/doc/src/functions.qdoc new file mode 100644 index 0000000..4aa0851 --- /dev/null +++ b/doc/src/functions.qdoc @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/**************************************************************************** +** +** Documentation for class overview. +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the Qt GUI Toolkit. +** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE +** +****************************************************************************/ + +/*! + \page functions.html + \title Member Function Index + \ingroup classlists + + Here is the list of all the documented member functions in the Qt + API with links to the class documentation for each function. + + \generatelist functionindex +*/ diff --git a/doc/src/gallery-cde.qdoc b/doc/src/gallery-cde.qdoc new file mode 100644 index 0000000..36916a2 --- /dev/null +++ b/doc/src/gallery-cde.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-cde.html + + \title CDE Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "cde" style. + +\raw HTML +
Buttons
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage cde-pushbutton.png +\raw HTML +	+\endraw +\inlineimage cde-toolbutton.png +\raw HTML +
+\endraw +The QPushButton widget provides a command button. +\raw HTML +	+\endraw +\raw HTML +
+\endraw +\inlineimage cde-checkbox.png +\raw HTML +	+\endraw +\inlineimage cde-radiobutton.png +\raw HTML +
+\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +	+\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +
+\endraw +\raw HTML +
Containers
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage cde-groupbox.png +\raw HTML +	+\endraw +\inlineimage cde-tabwidget.png +\raw HTML +
+\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +	+\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +
+\endraw +\inlineimage cde-frame.png +\raw HTML +	+\endraw +\inlineimage cde-toolbox.png +\raw HTML +
+\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +	+\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +
+\endraw +\raw HTML +
Item Views
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage cde-listview.png +\raw HTML +	+\endraw +\inlineimage cde-treeview.png +\raw HTML +
+\endraw +The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view.\raw HTML +	+\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +
+\endraw +\inlineimage cde-tableview.png +\raw HTML +
+\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +
+\endraw +\raw HTML +
Display Widgets
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage cde-progressbar.png +\raw HTML +	+\endraw +\inlineimage cde-lcdnumber.png +\raw HTML +
+\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +	+\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +
+\endraw +\inlineimage cde-label.png +\raw HTML +
+\endraw +The QLabel widget provides a text or image display.\raw HTML +
+\endraw +\raw HTML +
Input Widgets
+ + ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage cde-slider.png +\raw HTML +	+\endraw +\inlineimage cde-lineedit.png +\raw HTML +
+\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +	+\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +
+\endraw +\inlineimage cde-combobox.png +\raw HTML +	+\endraw +\inlineimage cde-doublespinbox.png +\raw HTML +
+\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +	+\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +
+\endraw +\inlineimage cde-spinbox.png +\raw HTML +	+\endraw +\inlineimage cde-timeedit.png +\raw HTML +
+\endraw +The QSpinBox class provides a spin box widget.\raw HTML +	+\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +
+\endraw +\inlineimage cde-dateedit.png +\raw HTML +	+\endraw +\inlineimage cde-datetimeedit.png +\raw HTML +
+\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +	+\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +
+\endraw +\inlineimage cde-textedit.png +\raw HTML +	+\endraw +\inlineimage cde-horizontalscrollbar.png +\raw HTML +
+\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +	+\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +
+\endraw +\inlineimage cde-dial.png +\raw HTML +	+\endraw +\inlineimage cde-calendarwidget.png +\raw HTML +
+\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +	+\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +
+\endraw +\inlineimage cde-fontcombobox.png +\raw HTML +
+\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +
+\endraw +*/ diff --git a/doc/src/gallery-cleanlooks.qdoc b/doc/src/gallery-cleanlooks.qdoc new file mode 100644 index 0000000..7ae5385 --- /dev/null +++ b/doc/src/gallery-cleanlooks.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-cleanlooks.html + + \title Cleanlooks Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "cleanlooks" style. + +\raw HTML +
Buttons
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage cleanlooks-pushbutton.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-toolbutton.png +\raw HTML +
+\endraw +The QPushButton widget provides a command button.\raw HTML +	+\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +
+\endraw +\inlineimage cleanlooks-checkbox.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-radiobutton.png +\raw HTML +
+\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +	+\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +
+\endraw +\raw HTML +
Containers
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage cleanlooks-groupbox.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-tabwidget.png +\raw HTML +
+\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +	+\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +
+\endraw +\inlineimage cleanlooks-frame.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-toolbox.png +\raw HTML +
+\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +	+\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +
+\endraw +\raw HTML +
Item Views
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage cleanlooks-listview.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-treeview.png +\raw HTML +
+\endraw +The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view.\raw HTML +	+\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +
+\endraw +\inlineimage cleanlooks-tableview.png +\raw HTML +
+\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +
+\endraw +\raw HTML +
Display Widgets
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage cleanlooks-progressbar.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-lcdnumber.png +\raw HTML +
+\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +	+\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +
+\endraw +\inlineimage cleanlooks-label.png +\raw HTML +
+\endraw +The QLabel widget provides a text or image display.\raw HTML +
+\endraw +\raw HTML +
Input Widgets
+ + ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage cleanlooks-slider.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-lineedit.png +\raw HTML +
+\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +	+\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +
+\endraw +\inlineimage cleanlooks-combobox.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-doublespinbox.png +\raw HTML +
+\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +	+\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +
+\endraw +\inlineimage cleanlooks-spinbox.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-timeedit.png +\raw HTML +
+\endraw +The QSpinBox class provides a spin box widget.\raw HTML +	+\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +
+\endraw +\inlineimage cleanlooks-dateedit.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-datetimeedit.png +\raw HTML +
+\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +	+\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +
+\endraw +\inlineimage cleanlooks-textedit.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-horizontalscrollbar.png +\raw HTML +
+\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +	+\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +
+\endraw +\inlineimage cleanlooks-dial.png +\raw HTML +	+\endraw +\inlineimage cleanlooks-calendarwidget.png +\raw HTML +
+\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +	+\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +
+\endraw +\inlineimage cleanlooks-fontcombobox.png +\raw HTML +
+\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +
+\endraw +*/ diff --git a/doc/src/gallery-gtk.qdoc b/doc/src/gallery-gtk.qdoc new file mode 100644 index 0000000..8251f04 --- /dev/null +++ b/doc/src/gallery-gtk.qdoc @@ -0,0 +1,358 @@ +/*! + \page gallery-gtk.html + + \title GTK Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "gtk" style. + + Take a look at the \l{Qt Widget Gallery} to see how Qt + applications appear in other styles. + +\raw HTML +
Buttons
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage gtk-pushbutton.png +\raw HTML +	+\endraw +\inlineimage gtk-toolbutton.png +\raw HTML +
+\endraw +The QPushButton widget provides a command button.\raw HTML +	+\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +
+\endraw +\inlineimage gtk-checkbox.png +\raw HTML +	+\endraw +\inlineimage gtk-radiobutton.png +\raw HTML +
+\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +	+\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +
+\endraw +\raw HTML +
Containers
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage gtk-groupbox.png +\raw HTML +	+\endraw +\inlineimage gtk-tabwidget.png +\raw HTML +
+\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +	+\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +
+\endraw +\inlineimage gtk-toolbox.png +\raw HTML +	+\endraw +\inlineimage gtk-frame.png +\raw HTML +
+\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +	+\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +
+\endraw +\raw HTML +
Item Views
+ + ++ + + + + + + + + + + + + + + + +
+\endraw +\inlineimage gtk-listview.png +\raw HTML +	+\endraw +\inlineimage gtk-treeview.png +\raw HTML +
+\endraw +The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view.\raw HTML +	+\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +
+\endraw +\inlineimage gtk-tableview.png +\raw HTML +
+\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +	+\endraw +\raw HTML +
+\endraw +\raw HTML +
Display Widgets
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage gtk-progressbar.png +\raw HTML +	+\endraw +\inlineimage gtk-lcdnumber.png +\raw HTML +
+\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +	+\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +
+\endraw +\inlineimage gtk-label.png +\raw HTML +
+\endraw +The QLabel widget provides a text or image display.\raw HTML +
+\endraw +\raw HTML +
Input Widgets
+ + ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage gtk-slider.png +\raw HTML +	+\endraw +\inlineimage gtk-lineedit.png +\raw HTML +
+\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +	+\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +
+\endraw +\inlineimage gtk-combobox.png +\raw HTML +	+\endraw +\inlineimage gtk-doublespinbox.png +\raw HTML +
+\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +	+\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +
+\endraw +\inlineimage gtk-spinbox.png +\raw HTML +	+\endraw +\inlineimage gtk-timeedit.png +\raw HTML +
+\endraw +The QSpinBox class provides a spin box widget.\raw HTML +	+\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +
+\endraw +\inlineimage gtk-dateedit.png +\raw HTML +	+\endraw +\inlineimage gtk-datetimeedit.png +\raw HTML +
+\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +	+\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +
+\endraw +\inlineimage gtk-textedit.png +\raw HTML +	+\endraw +\inlineimage gtk-horizontalscrollbar.png +\raw HTML +
+\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +	+\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +
+\endraw +\inlineimage gtk-dial.png +\raw HTML +	+\endraw +\inlineimage gtk-calendarwidget.png +\raw HTML +
+\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +	+\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +
+\endraw +\inlineimage gtk-fontcombobox.png +\raw HTML +
+\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +
+\endraw +*/ diff --git a/doc/src/gallery-macintosh.qdoc b/doc/src/gallery-macintosh.qdoc new file mode 100644 index 0000000..608713d --- /dev/null +++ b/doc/src/gallery-macintosh.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-macintosh.html + + \title Macintosh Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "macintosh" style. + +\raw HTML +
Buttons
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage macintosh-pushbutton.png +\raw HTML +	+\endraw +\inlineimage macintosh-toolbutton.png +\raw HTML +
+\endraw +The QPushButton widget provides a command button.\raw HTML +	+\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +
+\endraw +\inlineimage macintosh-checkbox.png +\raw HTML +	+\endraw +\inlineimage macintosh-radiobutton.png +\raw HTML +
+\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +	+\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +
+\endraw +\raw HTML +
Containers
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage macintosh-groupbox.png +\raw HTML +	+\endraw +\inlineimage macintosh-tabwidget.png +\raw HTML +
+\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +	+\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +
+\endraw +\inlineimage macintosh-frame.png +\raw HTML +	+\endraw +\inlineimage macintosh-toolbox.png +\raw HTML +
+\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +	+\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +
+\endraw +\raw HTML +
Item Views
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage macintosh-listview.png +\raw HTML +	+\endraw +\inlineimage macintosh-treeview.png +\raw HTML +
+\endraw +The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view.\raw HTML +	+\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +
+\endraw +\inlineimage macintosh-tableview.png +\raw HTML +
+\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +
+\endraw +\raw HTML +
Display Widgets
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage macintosh-progressbar.png +\raw HTML +	+\endraw +\inlineimage macintosh-lcdnumber.png +\raw HTML +
+\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +	+\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +
+\endraw +\inlineimage macintosh-label.png +\raw HTML +
+\endraw +The QLabel widget provides a text or image display.\raw HTML +
+\endraw +\raw HTML +
Input Widgets
+ + ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage macintosh-slider.png +\raw HTML +	+\endraw +\inlineimage macintosh-lineedit.png +\raw HTML +
+\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +	+\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +
+\endraw +\inlineimage macintosh-combobox.png +\raw HTML +	+\endraw +\inlineimage macintosh-doublespinbox.png +\raw HTML +
+\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +	+\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +
+\endraw +\inlineimage macintosh-spinbox.png +\raw HTML +	+\endraw +\inlineimage macintosh-timeedit.png +\raw HTML +
+\endraw +The QSpinBox class provides a spin box widget.\raw HTML +	+\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +
+\endraw +\inlineimage macintosh-dateedit.png +\raw HTML +	+\endraw +\inlineimage macintosh-datetimeedit.png +\raw HTML +
+\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +	+\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +
+\endraw +\inlineimage macintosh-textedit.png +\raw HTML +	+\endraw +\inlineimage macintosh-horizontalscrollbar.png +\raw HTML +
+\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +	+\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +
+\endraw +\inlineimage macintosh-dial.png +\raw HTML +	+\endraw +\inlineimage macintosh-calendarwidget.png +\raw HTML +
+\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +	+\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +
+\endraw +\inlineimage macintosh-fontcombobox.png +\raw HTML +
+\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +
+\endraw +*/ diff --git a/doc/src/gallery-motif.qdoc b/doc/src/gallery-motif.qdoc new file mode 100644 index 0000000..79c44b1 --- /dev/null +++ b/doc/src/gallery-motif.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-motif.html + + \title Motif Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "motif" style. + +\raw HTML +
Buttons
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage motif-pushbutton.png +\raw HTML +	+\endraw +\inlineimage motif-toolbutton.png +\raw HTML +
+\endraw +The QPushButton widget provides a command button.\raw HTML +	+\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +
+\endraw +\inlineimage motif-checkbox.png +\raw HTML +	+\endraw +\inlineimage motif-radiobutton.png +\raw HTML +
+\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +	+\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +
+\endraw +\raw HTML +
Containers
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage motif-groupbox.png +\raw HTML +	+\endraw +\inlineimage motif-tabwidget.png +\raw HTML +
+\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +	+\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +
+\endraw +\inlineimage motif-frame.png +\raw HTML +	+\endraw +\inlineimage motif-toolbox.png +\raw HTML +
+\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +	+\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +
+\endraw +\raw HTML +
Item Views
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage motif-listview.png +\raw HTML +	+\endraw +\inlineimage motif-treeview.png +\raw HTML +
+\endraw +The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view.\raw HTML +	+\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +
+\endraw +\inlineimage motif-tableview.png +\raw HTML +
+\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +
+\endraw +\raw HTML +
Display Widgets
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage motif-progressbar.png +\raw HTML +	+\endraw +\inlineimage motif-lcdnumber.png +\raw HTML +
+\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +	+\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +
+\endraw +\inlineimage motif-label.png +\raw HTML +
+\endraw +The QLabel widget provides a text or image display.\raw HTML +
+\endraw +\raw HTML +
Input Widgets
+ + ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage motif-slider.png +\raw HTML +	+\endraw +\inlineimage motif-lineedit.png +\raw HTML +
+\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +	+\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +
+\endraw +\inlineimage motif-combobox.png +\raw HTML +	+\endraw +\inlineimage motif-doublespinbox.png +\raw HTML +
+\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +	+\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +
+\endraw +\inlineimage motif-spinbox.png +\raw HTML +	+\endraw +\inlineimage motif-timeedit.png +\raw HTML +
+\endraw +The QSpinBox class provides a spin box widget.\raw HTML +	+\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +
+\endraw +\inlineimage motif-dateedit.png +\raw HTML +	+\endraw +\inlineimage motif-datetimeedit.png +\raw HTML +
+\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +	+\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +
+\endraw +\inlineimage motif-textedit.png +\raw HTML +	+\endraw +\inlineimage motif-horizontalscrollbar.png +\raw HTML +
+\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +	+\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +
+\endraw +\inlineimage motif-dial.png +\raw HTML +	+\endraw +\inlineimage motif-calendarwidget.png +\raw HTML +
+\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +	+\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +
+\endraw +\inlineimage motif-fontcombobox.png +\raw HTML +
+\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +
+\endraw +*/ diff --git a/doc/src/gallery-plastique.qdoc b/doc/src/gallery-plastique.qdoc new file mode 100644 index 0000000..b184ea8 --- /dev/null +++ b/doc/src/gallery-plastique.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-plastique.html + + \title Plastique Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "plastique" style. + +\raw HTML +
Buttons
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage plastique-pushbutton.png +\raw HTML +	+\endraw +\inlineimage plastique-toolbutton.png +\raw HTML +
+\endraw +The QPushButton widget provides a command button.\raw HTML +	+\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +
+\endraw +\inlineimage plastique-checkbox.png +\raw HTML +	+\endraw +\inlineimage plastique-radiobutton.png +\raw HTML +
+\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +	+\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +
+\endraw +\raw HTML +
Containers
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage plastique-groupbox.png +\raw HTML +	+\endraw +\inlineimage plastique-tabwidget.png +\raw HTML +
+\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +	+\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +
+\endraw +\inlineimage plastique-frame.png +\raw HTML +	+\endraw +\inlineimage plastique-toolbox.png +\raw HTML +
+\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +	+\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +
+\endraw +\raw HTML +
Item Views
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage plastique-listview.png +\raw HTML +	+\endraw +\inlineimage plastique-treeview.png +\raw HTML +
+\endraw +The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view.\raw HTML +	+\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +
+\endraw +\inlineimage plastique-tableview.png +\raw HTML +
+\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +
+\endraw +\raw HTML +
Display Widgets
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage plastique-progressbar.png +\raw HTML +	+\endraw +\inlineimage plastique-lcdnumber.png +\raw HTML +
+\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +	+\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +
+\endraw +\inlineimage plastique-label.png +\raw HTML +
+\endraw +The QLabel widget provides a text or image display.\raw HTML +
+\endraw +\raw HTML +
Input Widgets
+ + ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage plastique-slider.png +\raw HTML +	+\endraw +\inlineimage plastique-lineedit.png +\raw HTML +
+\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +	+\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +
+\endraw +\inlineimage plastique-combobox.png +\raw HTML +	+\endraw +\inlineimage plastique-doublespinbox.png +\raw HTML +
+\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +	+\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +
+\endraw +\inlineimage plastique-spinbox.png +\raw HTML +	+\endraw +\inlineimage plastique-timeedit.png +\raw HTML +
+\endraw +The QSpinBox class provides a spin box widget.\raw HTML +	+\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +
+\endraw +\inlineimage plastique-dateedit.png +\raw HTML +	+\endraw +\inlineimage plastique-datetimeedit.png +\raw HTML +
+\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +	+\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +
+\endraw +\inlineimage plastique-textedit.png +\raw HTML +	+\endraw +\inlineimage plastique-horizontalscrollbar.png +\raw HTML +
+\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +	+\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +
+\endraw +\inlineimage plastique-dial.png +\raw HTML +	+\endraw +\inlineimage plastique-calendarwidget.png +\raw HTML +
+\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +	+\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +
+\endraw +\inlineimage plastique-fontcombobox.png +\raw HTML +
+\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +
+\endraw +*/ diff --git a/doc/src/gallery-windows.qdoc b/doc/src/gallery-windows.qdoc new file mode 100644 index 0000000..40ba7ce --- /dev/null +++ b/doc/src/gallery-windows.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-windows.html + + \title Windows Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "windows" style. + +\raw HTML +
Buttons
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage windows-pushbutton.png +\raw HTML +	+\endraw +\inlineimage windows-toolbutton.png +\raw HTML +
+\endraw +The QPushButton widget provides a command button.\raw HTML +	+\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +
+\endraw +\inlineimage windows-checkbox.png +\raw HTML +	+\endraw +\inlineimage windows-radiobutton.png +\raw HTML +
+\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +	+\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +
+\endraw +\raw HTML +
Containers
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage windows-groupbox.png +\raw HTML +	+\endraw +\inlineimage windows-tabwidget.png +\raw HTML +
+\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +	+\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +
+\endraw +\inlineimage windows-frame.png +\raw HTML +	+\endraw +\inlineimage windows-toolbox.png +\raw HTML +
+\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +	+\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +
+\endraw +\raw HTML +
Item Views
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage windows-listview.png +\raw HTML +	+\endraw +\inlineimage windows-treeview.png +\raw HTML +
+\endraw +The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view.\raw HTML +	+\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +
+\endraw +\inlineimage windows-tableview.png +\raw HTML +
+\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +
+\endraw +\raw HTML +
Display Widgets
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage windows-progressbar.png +\raw HTML +	+\endraw +\inlineimage windows-lcdnumber.png +\raw HTML +
+\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +	+\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +
+\endraw +\inlineimage windows-label.png +\raw HTML +
+\endraw +The QLabel widget provides a text or image display.\raw HTML +
+\endraw +\raw HTML +
Input Widgets
+ + ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage windows-slider.png +\raw HTML +	+\endraw +\inlineimage windows-lineedit.png +\raw HTML +
+\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +	+\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +
+\endraw +\inlineimage windows-combobox.png +\raw HTML +	+\endraw +\inlineimage windows-doublespinbox.png +\raw HTML +
+\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +	+\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +
+\endraw +\inlineimage windows-spinbox.png +\raw HTML +	+\endraw +\inlineimage windows-timeedit.png +\raw HTML +
+\endraw +The QSpinBox class provides a spin box widget.\raw HTML +	+\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +
+\endraw +\inlineimage windows-dateedit.png +\raw HTML +	+\endraw +\inlineimage windows-datetimeedit.png +\raw HTML +
+\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +	+\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +
+\endraw +\inlineimage windows-textedit.png +\raw HTML +	+\endraw +\inlineimage windows-horizontalscrollbar.png +\raw HTML +
+\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +	+\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +
+\endraw +\inlineimage windows-dial.png +\raw HTML +	+\endraw +\inlineimage windows-calendarwidget.png +\raw HTML +
+\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +	+\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +
+\endraw +\inlineimage windows-fontcombobox.png +\raw HTML +
+\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +
+\endraw +*/ diff --git a/doc/src/gallery-windowsvista.qdoc b/doc/src/gallery-windowsvista.qdoc new file mode 100644 index 0000000..1ad8823 --- /dev/null +++ b/doc/src/gallery-windowsvista.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-windowsvista.html + + \title Windows Vista Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "windowsvista" style. + +\raw HTML +
Buttons
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage windowsvista-pushbutton.png +\raw HTML +	+\endraw +\inlineimage windowsvista-toolbutton.png +\raw HTML +
+\endraw +The QPushButton widget provides a command button.\raw HTML +	+\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +
+\endraw +\inlineimage windowsvista-checkbox.png +\raw HTML +	+\endraw +\inlineimage windowsvista-radiobutton.png +\raw HTML +
+\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +	+\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +
+\endraw +\raw HTML +
Containers
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage windowsvista-groupbox.png +\raw HTML +	+\endraw +\inlineimage windowsvista-tabwidget.png +\raw HTML +
+\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +	+\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +
+\endraw +\inlineimage windowsvista-frame.png +\raw HTML +	+\endraw +\inlineimage windowsvista-toolbox.png +\raw HTML +
+\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +	+\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +
+\endraw +\raw HTML +
Item Views
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage windowsvista-listview.png +\raw HTML +	+\endraw +\inlineimage windowsvista-treeview.png +\raw HTML +
+\endraw +The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view.\raw HTML +	+\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +
+\endraw +\inlineimage windowsvista-tableview.png +\raw HTML +
+\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +
+\endraw +\raw HTML +
Display Widgets
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage windowsvista-progressbar.png +\raw HTML +	+\endraw +\inlineimage windowsvista-lcdnumber.png +\raw HTML +
+\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +	+\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +
+\endraw +\inlineimage windowsvista-label.png +\raw HTML +
+\endraw +The QLabel widget provides a text or image display.\raw HTML +
+\endraw +\raw HTML +
Input Widgets
+ + ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage windowsvista-slider.png +\raw HTML +	+\endraw +\inlineimage windowsvista-lineedit.png +\raw HTML +
+\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +	+\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +
+\endraw +\inlineimage windowsvista-combobox.png +\raw HTML +	+\endraw +\inlineimage windowsvista-doublespinbox.png +\raw HTML +
+\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +	+\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +
+\endraw +\inlineimage windowsvista-spinbox.png +\raw HTML +	+\endraw +\inlineimage windowsvista-timeedit.png +\raw HTML +
+\endraw +The QSpinBox class provides a spin box widget.\raw HTML +	+\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +
+\endraw +\inlineimage windowsvista-dateedit.png +\raw HTML +	+\endraw +\inlineimage windowsvista-datetimeedit.png +\raw HTML +
+\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +	+\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +
+\endraw +\inlineimage windowsvista-textedit.png +\raw HTML +	+\endraw +\inlineimage windowsvista-horizontalscrollbar.png +\raw HTML +
+\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +	+\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +
+\endraw +\inlineimage windowsvista-dial.png +\raw HTML +	+\endraw +\inlineimage windowsvista-calendarwidget.png +\raw HTML +
+\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +	+\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +
+\endraw +\inlineimage windowsvista-fontcombobox.png +\raw HTML +
+\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +
+\endraw +*/ diff --git a/doc/src/gallery-windowsxp.qdoc b/doc/src/gallery-windowsxp.qdoc new file mode 100644 index 0000000..dcb8e82 --- /dev/null +++ b/doc/src/gallery-windowsxp.qdoc @@ -0,0 +1,392 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-windowsxp.html + + \title Windows XP Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "windowsxp" style. + +\raw HTML +
Buttons
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage windowsxp-pushbutton.png +\raw HTML +	+\endraw +\inlineimage windowsxp-toolbutton.png +\raw HTML +
+\endraw +The QPushButton widget provides a command button.\raw HTML +	+\endraw +The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar.\raw HTML +
+\endraw +\inlineimage windowsxp-checkbox.png +\raw HTML +	+\endraw +\inlineimage windowsxp-radiobutton.png +\raw HTML +
+\endraw +The QCheckBox widget provides a checkbox with a text label.\raw HTML +	+\endraw +The QRadioButton widget provides a radio button with a text or pixmap label.\raw HTML +
+\endraw +\raw HTML +
Containers
+ + ++ + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage windowsxp-groupbox.png +\raw HTML +	+\endraw +\inlineimage windowsxp-tabwidget.png +\raw HTML +
+\endraw +The QGroupBox widget provides a group box frame with a title.\raw HTML +	+\endraw +The QTabWidget class provides a stack of tabbed widgets.\raw HTML +
+\endraw +\inlineimage windowsxp-frame.png +\raw HTML +	+\endraw +\inlineimage windowsxp-toolbox.png +\raw HTML +
+\endraw +The QFrame widget provides a simple decorated container for other widgets.\raw HTML +	+\endraw +The QToolBox class provides a column of tabbed widget items.\raw HTML +
+\endraw +\raw HTML +
Item Views
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage windowsxp-listview.png +\raw HTML +	+\endraw +\inlineimage windowsxp-treeview.png +\raw HTML +
+\endraw +The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view.\raw HTML +	+\endraw +The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view.\raw HTML +
+\endraw +\inlineimage windowsxp-tableview.png +\raw HTML +
+\endraw +The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\raw HTML +
+\endraw +\raw HTML +
Display Widgets
+ + ++ + + + + + + + + + + + + + + +
+\endraw +\inlineimage windowsxp-progressbar.png +\raw HTML +	+\endraw +\inlineimage windowsxp-lcdnumber.png +\raw HTML +
+\endraw +The QProgressBar widget provides a horizontal progress bar.\raw HTML +	+\endraw +The QLCDNumber widget displays a number with LCD-like digits.\raw HTML +
+\endraw +\inlineimage windowsxp-label.png +\raw HTML +
+\endraw +The QLabel widget provides a text or image display.\raw HTML +
+\endraw +\raw HTML +
Input Widgets
+ + ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+\endraw +\inlineimage windowsxp-slider.png +\raw HTML +	+\endraw +\inlineimage windowsxp-lineedit.png +\raw HTML +
+\endraw +The QSlider widget provides a vertical or horizontal slider.\raw HTML +	+\endraw +The QLineEdit widget is a one-line text editor.\raw HTML +
+\endraw +\inlineimage windowsxp-combobox.png +\raw HTML +	+\endraw +\inlineimage windowsxp-doublespinbox.png +\raw HTML +
+\endraw +The QComboBox widget is a combined button and pop-up list.\raw HTML +	+\endraw +The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered.\raw HTML +
+\endraw +\inlineimage windowsxp-spinbox.png +\raw HTML +	+\endraw +\inlineimage windowsxp-timeedit.png +\raw HTML +
+\endraw +The QSpinBox class provides a spin box widget.\raw HTML +	+\endraw +The QTimeEdit class provides a widget for editing times.\raw HTML +
+\endraw +\inlineimage windowsxp-dateedit.png +\raw HTML +	+\endraw +\inlineimage windowsxp-datetimeedit.png +\raw HTML +
+\endraw +The QDateEdit class provides a widget for editing dates.\raw HTML +	+\endraw +The QDateTimeEdit class provides a widget for editing dates and times.\raw HTML +
+\endraw +\inlineimage windowsxp-textedit.png +\raw HTML +	+\endraw +\inlineimage windowsxp-horizontalscrollbar.png +\raw HTML +
+\endraw +The QTextEdit class provides a widget that is used to edit and + display both plain and rich text.\raw HTML +	+\endraw +The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation.\raw HTML +
+\endraw +\inlineimage windowsxp-dial.png +\raw HTML +	+\endraw +\inlineimage windowsxp-calendarwidget.png +\raw HTML +
+\endraw +The QDial class provides a rounded range control (like a + speedometer or potentiometer).\raw HTML +	+\endraw +The QCalendarWidget class provides a monthly calendar widget that can be used to select dates.\raw HTML +
+\endraw +\inlineimage windowsxp-fontcombobox.png +\raw HTML +
+\endraw +The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts.\raw HTML +
+\endraw +*/ diff --git a/doc/src/gallery.qdoc b/doc/src/gallery.qdoc new file mode 100644 index 0000000..dc9f732 --- /dev/null +++ b/doc/src/gallery.qdoc @@ -0,0 +1,151 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group gallery + \title Qt Widget Gallery + \ingroup topics + \brief Qt widgets shown in different styles on various platforms. + + Qt's support for widget styles and themes enables your application to fit in + with the native desktop enviroment. Below, you can find links to the various + widget styles that are supplied with Qt 4. + + \raw HTML + + + + + + + + + + + + + + + + + + + + + + + + +
+ \endraw + \image plastique-tabwidget.png Plastique Style Widget Gallery + + \bold{\l{Plastique Style Widget Gallery}} + + The Plastique style is provided by QPlastiqueStyle. + \raw HTML +	+ \endraw + \image windowsxp-tabwidget.png Windows XP Style Widget Gallery + + \bold{\l{Windows XP Style Widget Gallery}} + + The Windows XP style is provided by QWindowsXPStyle. + \raw HTML +
+ \endraw + \image gtk-tabwidget.png GTK Style Widget Gallery + + \bold{\l{GTK Style Widget Gallery}} + + The GTK style is provided by QGtkStyle. + \raw HTML +	+ \endraw + \image macintosh-tabwidget.png Macintosh Style Widget Gallery + + \bold{\l{Macintosh Style Widget Gallery}} + + The Macintosh style is provided by QMacStyle. + \raw HTML +
+ \endraw + \image cleanlooks-tabwidget.png Cleanlooks Style Widget Gallery + + \bold{\l{Cleanlooks Style Widget Gallery}} + + The Cleanlooks style is provided by QCleanlooksStyle. + \raw HTML +	+ \endraw + \image windowsvista-tabwidget.png Windows Vista Style Widget Gallery + + \bold{\l{Windows Vista Style Widget Gallery}} + + The Windows Vista style is provided by QWindowsVistaStyle. + \raw HTML +
+ \endraw + \image motif-tabwidget.png Motif Style Widget Gallery + + \bold{\l{Motif Style Widget Gallery}} + + The Motif style is provided by QMotifStyle. + \raw HTML +	+ \endraw + \image windows-tabwidget.png Windows Style Widget Gallery + + \bold{\l{Windows Style Widget Gallery}} + + The Windows style is provided by QWindowsStyle. + \raw HTML +
+ \endraw + \image cde-tabwidget.png CDE Style Widget Gallery + + \bold{\l{CDE Style Widget Gallery}} + + The Common Desktop Environment style is provided by QCDEStyle. + \raw HTML +
+ \endraw +*/ diff --git a/doc/src/geometry.qdoc b/doc/src/geometry.qdoc new file mode 100644 index 0000000..b17aa39 --- /dev/null +++ b/doc/src/geometry.qdoc @@ -0,0 +1,150 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page geometry.html + \title Window Geometry + \ingroup architecture + \brief An overview of window geometry handling and management. + + QWidget provides several functions that deal with a widget's + geometry. Some of these functions operate on the pure client area + (i.e. the window excluding the window frame), others include the + window frame. The differentiation is done in a way that covers the + most common usage transparently. + + \list + \o \bold{Including the window frame:} + \l{QWidget::x()}{x()}, + \l{QWidget::y()}{y()}, + \l{QWidget::frameGeometry()}{frameGeometry()}, + \l{QWidget::pos()}{pos()}, and + \l{QWidget::move()}{move()}. + \o \bold{Excluding the window frame:} + \l{QWidget::geometry()}{geometry()}, + \l{QWidget::width()}{width()}, + \l{QWidget::height()}{height()}, + \l{QWidget::rect()}{rect()}, and + \l{QWidget::size()}{size()}. + \endlist + + Note that the distinction only matters for decorated top-level + widgets. For all child widgets, the frame geometry is equal to the + widget's client geometry. + + This diagram shows most of the functions in use: + \img geometry.png Geometry diagram + + Topics: + + \tableofcontents + + \section1 X11 Peculiarities + + On X11, a window does not have a frame until the window manager + decorates it. This happens asynchronously at some point in time + after calling QWidget::show() and the first paint event the + window receives, or it does not happen at all. Bear in mind that + X11 is policy-free (others call it flexible). Thus you cannot + make any safe assumption about the decoration frame your window + will get. Basic rule: There's always one user who uses a window + manager that breaks your assumption, and who will complain to + you. + + Furthermore, a toolkit cannot simply place windows on the screen. All + Qt can do is to send certain hints to the window manager. The window + manager, a separate process, may either obey, ignore or misunderstand + them. Due to the partially unclear Inter-Client Communication + Conventions Manual (ICCCM), window placement is handled quite + differently in existing window managers. + + X11 provides no standard or easy way to get the frame geometry + once the window is decorated. Qt solves this problem with nifty + heuristics and clever code that works on a wide range of window + managers that exist today. Don't be surprised if you find one + where QWidget::frameGeometry() returns wrong results though. + + Nor does X11 provide a way to maximize a window. + QWidget::showMaximized() has to emulate the feature. Its result + depends on the result of QWidget::frameGeometry() and the + capability of the window manager to do proper window placement, + neither of which can be guaranteed. + + \section1 Restoring a Window's Geometry + + Since version 4.2, Qt provides functions that saves and restores a + window's geometry and state for you. QWidget::saveGeometry() + saves the window geometry and maximized/fullscreen state, while + QWidget::restoreGeometry() restores it. The restore function also + checks if the restored geometry is outside the available screen + geometry, and modifies it as appropriate if it is. + + The rest of this document describes how to save and restore the + geometry using the geometry properties. On Windows, this is + basically storing the result of QWidget::geometry() and calling + QWidget::setGeometry() in the next session before calling + \l{QWidget::show()}{show()}. On X11, this won't work because an + invisible window doesn't have a frame yet. The window manager + will decorate the window later. When this happens, the window + shifts towards the bottom/right corner of the screen depending on + the size of the decoration frame. Although X provides a way to + avoid this shift, most window managers fail to implement this + feature. + + A workaround is to call \l{QWidget::setGeometry()}{setGeometry()} + after \l{QWidget::show()}{show()}. This has the two disadvantages + that the widget appears at a wrong place for a millisecond + (results in flashing) and that currently only every second window + manager gets it right. A safer solution is to store both + \l{QWidget::pos()}{pos()} and \l{QWidget::size()}{size()} and to + restore the geometry using \l{QWidget::resize()} and + \l{QWidget::move()}{move()} before calling + \l{QWidget::show()}{show()}, as demonstrated in the following + code snippets (from the \l{mainwindows/application}{Application} + example): + + \snippet examples/mainwindows/application/mainwindow.cpp 35 + \codeline + \snippet examples/mainwindows/application/mainwindow.cpp 38 + + This method works on Windows, Mac OS X, and most X11 window + managers. +*/ diff --git a/doc/src/gpl.qdoc b/doc/src/gpl.qdoc new file mode 100644 index 0000000..e423171 --- /dev/null +++ b/doc/src/gpl.qdoc @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! \page gpl.html +\title GNU General Public License (GPL) +\ingroup licensing +\brief About the GPL license used for Qt. + +The Qt GUI Toolkit is Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).\br +Contact: Qt Software Information (qt-info@nokia.com) + +Qt is available under the GPL. + +\section1 The GNU General Public License (Version 3) + +Reference: \l{GNU General Public License} + +\snippet doc/src/snippets/code/doc_src_gpl.qdoc GPL v3 +*/ + +/*! \page lgpl.html +\title GNU Lesser General Public License (LGPL) +\ingroup licensing +\brief About the LGPL license used for Qt. + +The Qt GUI Toolkit is Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).\br +Contact: Qt Software Information (qt-info@nokia.com) + +Qt is available under the LGPL. + +\section1 The GNU Lesser General Public License (Version 2.1) + +Reference: \l{GNU Lesser General Public License, version 2.1} + +\snippet doc/src/snippets/code/doc_src_lgpl.qdoc LGPL v2.1 + +\section1 Nokia Qt LGPL Exception version 1.0 + +As a special exception to the GNU Lesser General Public License version 2.1, +the object code form of a "work that uses the Library" may incorporate material +from a header file that is part of the Library. You may distribute such object +code under terms of your choice, provided that the incorporated material +(i) does not exceed more than 5% of the total size of the Library; and +(ii) is limited to numerical parameters, data structure layouts, accessors, +macros, inline functions and templates. +*/ diff --git a/doc/src/graphicsview.qdoc b/doc/src/graphicsview.qdoc new file mode 100644 index 0000000..049b0c3 --- /dev/null +++ b/doc/src/graphicsview.qdoc @@ -0,0 +1,544 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page graphicsview.html + \title The Graphics View Framework + \ingroup architecture + \ingroup multimedia + \brief An overview of the Graphics View framework for interactive 2D + graphics. + + \keyword Graphics View + \keyword GraphicsView + \keyword Graphics + \keyword Canvas + \since 4.2 + + Graphics View provides a surface for managing and interacting with a large + number of custom-made 2D graphical items, and a view widget for + visualizing the items, with support for zooming and rotation. + + The framework includes an event propagation architecture that allows + precise double-precision interaction capabilities for the items on the + scene. Items can handle key events, mouse press, move, release and + double click events, and they can also track mouse movement. + + Graphics View uses a BSP (Binary Space Partitioning) tree to provide very + fast item discovery, and as a result of this, it can visualize large + scenes in real-time, even with millions of items. + + Graphics View was introduced in Qt 4.2, replacing its predecessor, + QCanvas. If you are porting from QCanvas, see \l{Porting to Graphics + View}. + + Topics: + + \tableofcontents + + \section1 The Graphics View Architecture + + Graphics View provides an item-based approach to model-view programming, + much like InterView's convenience classes QTableView, QTreeView and + QListView. Several views can observe a single scene, and the scene + contains items of varying geometric shapes. + + \section2 The Scene + + QGraphicsScene provides the Graphics View scene. The scene has the + following responsibilities: + + \list + \o Providing a fast interface for managing a large number of items + \o Propagating events to each item + \o Managing item state, such as selection and focus handling + \o Providing untransformed rendering functionality; mainly for printing + \endlist + + The scene serves as a container for QGraphicsItem objects. Items are + added to the scene by calling QGraphicsScene::addItem(), and then + retrieved by calling one of the many item discovery functions. + QGraphicsScene::items() and its overloads return all items contained + by or intersecting with a point, a rectangle, a polygon or a general + vector path. QGraphicsScene::itemAt() returns the topmost item at a + particular point. All item discovery functions return the items in + descending stacking order (i.e., the first returned item is topmost, + and the last item is bottom-most). + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 0 + + QGraphicsScene's event propagation architecture schedules scene events + for delivery to items, and also manages propagation between items. If + the scene receives a mouse press event at a certain position, the + scene passes the event on to whichever item is at that position. + + QGraphicsScene also manages certain item states, such as item + selection and focus. You can select items on the scene by calling + QGraphicsScene::setSelectionArea(), passing an arbitrary shape. This + functionality is also used as a basis for rubberband selection in + QGraphicsView. To get the list of all currently selected items, call + QGraphicsScene::selectedItems(). Another state handled by + QGraphicsScene is whether or not an item has keyboard input focus. You + can set focus on an item by calling QGraphicsScene::setFocusItem() or + QGraphicsItem::setFocus(), or get the current focus item by calling + QGraphicsScene::focusItem(). + + Finally, QGraphicsScene allows you to render parts of the scene into a + paint device through the QGraphicsScene::render() function. You can + read more about this in the Printing section later in this document. + + \section2 The View + + QGraphicsView provides the view widget, which visualizes the contents + of a scene. You can attach several views to the same scene, to provide + several viewports into the same data set. The view widget is a scroll + area, and provides scroll bars for navigating through large scenes. To + enable OpenGL support, you can set a QGLWidget as the viewport by + calling QGraphicsView::setViewport(). + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 1 + + The view receives input events from the keyboard and mouse, and + translates these to scene events (converting the coordinates used + to scene coordinates where appropriate), before sending the events + to the visualized scene. + + Using its transformation matrix, QGraphicsView::matrix(), the view can + \e transform the scene's coordinate system. This allows advanced + navigation features such as zooming and rotation. For convenience, + QGraphicsView also provides functions for translating between view and + scene coordinates: QGraphicsView::mapToScene() and + QGraphicsView::mapFromScene(). + + \img graphicsview-view.png + + \section2 The Item + + QGraphicsItem is the base class for graphical items in a + scene. Graphics View provides several standard items for typical + shapes, such as rectangles (QGraphicsRectItem), ellipses + (QGraphicsEllipseItem) and text items (QGraphicsTextItem), but the + most powerful QGraphicsItem features are available when you write a + custom item. Among other things, QGraphicsItem supports the following + features: + + \list + \o Mouse press, move, release and double click events, as well as mouse + hover events, wheel events, and context menu events. + \o Keyboard input focus, and key events + \o Drag and drop + \o Grouping, both through parent-child relationships, and with + QGraphicsItemGroup + \o Collision detection + \endlist + + Items live in a local coordinate system, and like QGraphicsView, it + also provides many functions for mapping coordinates between the item + and the scene, and from item to item. Also, like QGraphicsView, it can + transform its coordinate system using a matrix: + QGraphicsItem::matrix(). This is useful for rotating and scaling + individual items. + + Items can contain other items (children). Parent items' + transformations are inherited by all its children. Regardless of an + item's accumulated transformation, though, all its functions (e.g., + QGraphicsItem::contains(), QGraphicsItem::boundingRect(), + QGraphicsItem::collidesWith()) still operate in local coordinates. + + QGraphicsItem supports collision detection through the + QGraphicsItem::shape() function, and QGraphicsItem::collidesWith(), + which are both virtual functions. By returning your item's shape as a + local coordinate QPainterPath from QGraphicsItem::shape(), + QGraphicsItem will handle all collision detection for you. If you want + to provide your own collision detection, however, you can reimplement + QGraphicsItem::collidesWith(). + + \img graphicsview-items.png + + \section1 The Graphics View Coordinate System + + Graphics View is based on the Cartesian coordinate system; items' + position and geometry on the scene are represented by sets of two + numbers: the x-coordinate, and the y-coordinate. When observing a scene + using an untransformed view, one unit on the scene is represented by + one pixel on the screen. + + There are three effective coordinate systems in play in Graphics View: + Item coordinates, scene coordinates, and view coordinates. To simplify + your implementation, Graphics View provides convenience functions that + allow you to map between the three coordinate systems. + + When rendering, Graphics View's scene coordinates correspond to + QPainter's \e logical coordinates, and view coordinates are the same as + \e device coordinates. In \l{The Coordinate System}, you can read about + the relationship between logical coordinates and device coordinates. + + \img graphicsview-parentchild.png + + \section2 Item Coordinates + + Items live in their own local coordinate system. Their coordinates + are usually centered around its center point (0, 0), and this is + also the center for all transformations. Geometric primitives in the + item coordinate system are often referred to as item points, item + lines, or item rectangles. + + When creating a custom item, item coordinates are all you need to + worry about; QGraphicsScene and QGraphicsView will perform all + transformations for you. This makes it very easy to implement custom + items. For example, if you receive a mouse press or a drag enter + event, the event position is given in item coordinates. The + QGraphicsItem::contains() virtual function, which returns true if a + certain point is inside your item, and false otherwise, takes a + point argument in item coordinates. Similarly, an item's bounding + rect and shape are in item coordinates. + + At item's \e position is the coordinate of the item's center point + in its parent's coordinate system; sometimes referred to as \e + parent coordinates. The scene is in this sense regarded as all + parent-less items' "parent". Top level items' position are in scene + coordinates. + + Child coordinates are relative to the parent's coordinates. If the + child is untransformed, the difference between a child coordinate + and a parent coordinate is the same as the distance between the + items in parent coordinates. For example: If an untransformed child + item is positioned precisely in its parent's center point, then the + two items' coordinate systems will be identical. If the child's + position is (10, 0), however, the child's (0, 10) point will + correspond to its parent's (10, 10) point. + + Because items' position and transformation are relative to the + parent, child items' coordinates are unaffected by the parent's + transformation, although the parent's transformation implicitly + transforms the child. In the above example, even if the parent is + rotated and scaled, the child's (0, 10) point will still correspond + to the parent's (10, 10) point. Relative to the scene, however, the + child will follow the parent's transformation and position. If the + parent is scaled (2x, 2x), the child's position will be at scene + coordinate (20, 0), and its (10, 0) point will correspond to the + point (40, 0) on the scene. + + With QGraphicsItem::pos() being one of the few exceptions, + QGraphicsItem's functions operate in item coordinates, regardless of + the item, or any of its parents' transformation. For example, an + item's bounding rect (i.e. QGraphicsItem::boundingRect()) is always + given in item coordinates. + + \section2 Scene Coordinates + + The scene represents the base coordinate system for all its items. + The scene coordinate system describes the position of each top-level + item, and also forms the basis for all scene events delivered to the + scene from the view. Each item on the scene has a scene position + and bounding rectangle (QGraphicsItem::scenePos(), + QGraphicsItem::sceneBoundingRect()), in addition to its local item + pos and bounding rectangle. The scene position describes the item's + position in scene coordinates, and its scene bounding rect forms the + basis for how QGraphicsScene determines what areas of the scene have + changed. Changes in the scene are communicated through the + QGraphicsScene::changed() signal, and the argument is a list of + scene rectangles. + + \section2 View Coordinates + + View coordinates are the coordinates of the widget. Each unit in + view coordinates corresponds to one pixel. What's special about this + coordinate system is that it is relative to the widget, or viewport, + and unaffected by the observed scene. The top left corner of + QGraphicsView's viewport is always (0, 0), and the bottom right + corner is always (viewport width, viewport height). All mouse events + and drag and drop events are originally received as view + coordinates, and you need to map these coordinates to the scene in + order to interact with items. + + \section2 Coordinate Mapping + + Often when dealing with items in a scene, it can be useful to map + coordinates and arbitrary shapes from the scene to an item, from + item to item, or from the view to the scene. For example, when you + click your mouse in QGraphicsView's viewport, you can ask the scene + what item is under the cursor by calling + QGraphicsView::mapToScene(), followed by + QGraphicsScene::itemAt(). If you want to know where in the viewport + an item is located, you can call QGraphicsItem::mapToScene() on the + item, then QGraphicsView::mapFromScene() on the view. Finally, if + you use want to find what items are inside a view ellipse, you can + pass a QPainterPath to mapToScene(), and then pass the mapped path + to QGraphicsScene::items(). + + You can map coordinates and shapes to and from and item's scene by + calling QGraphicsItem::mapToScene() and + QGraphicsItem::mapFromScene(). You can also map to an item's parent + item by calling QGraphicsItem::mapToParent() and + QGraphicsItem::mapFromParent(), or between items by calling + QGraphicsItem::mapToItem() and QGraphicsItem::mapFromItem(). All + mapping functions can map both points, rectangles, polygons and + paths. + + The same mapping functions are available in the view, for mapping to + and from the scene. QGraphicsView::mapFromScene() and + QGraphicsView::mapToScene(). To map from a view to an item, you + first map to the scene, and then map from the scene to the item. + + \section1 Key Features + + \section2 Zooming and rotating + + QGraphicsView supports the same affine transformations as QPainter + does through QGraphicsView::setMatrix(). By applying a transformation + to the view, you can easily add support for common navigation features + such as zooming and rotating. + + Here is an example of how to implement zoom and rotate slots in a + subclass of QGraphicsView: + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 2 + + The slots could be connected to \l{QToolButton}{QToolButtons} with + \l{QAbstractButton::autoRepeat}{autoRepeat} enabled. + + QGraphicsView keeps the center of the view aligned when you transform + the view. + + See also the \l{Elastic Nodes Example}{Elastic Nodes} example for + code that shows how to implement basic zooming features. + + \section2 Printing + + Graphics View provides single-line printing through its rendering + functions, QGraphicsScene::render() and QGraphicsView::render(). The + functions provide the same API: You can have the scene or the view + render all or parts of their contents into any paint device by passing + a QPainter to either of the rendering functions. This example shows + how to print the whole scene into a full page, using QPrinter. + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 3 + + The difference between the scene and view rendering functions is that + one operates in scene coordinates, and the other in view coordinates. + QGraphicsScene::render() is often preferred for printing whole + segments of a scene untransformed, such as for plotting geometrical + data, or for printing a text document. QGraphicsView::render(), on the + other hand, is suitable for taking screenshots; its default behavior + is to render the exact contents of the viewport using the provided + painter. + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 4 + + When the source and target areas' sizes do not match, the source + contents are stretched to fit into the target area. By passing a + Qt::AspectRatioMode to the rendering function you are using, you can + choose to maintain or ignore the aspect ratio of the scene when the + contents are stretched. + + \section2 Drag and Drop + + Because QGraphicsView inherits QWidget indirectly, it already provides + the same drag and drop functionality that QWidget provides. In + addition, as a convenience, the Graphics View framework provides drag + and drop support for the scene, and for each and every item. As the + view receives a drag, it translates the drag and drop events into a + QGraphicsSceneDragDropEvent, which is then forwarded to the scene. The + scene takes over scheduling of this event, and sends it to the first + item under the mouse cursor that accepts drops. + + To start a drag from an item, create a QDrag object, passing a pointer + to the widget that starts the drag. Items can be observed by many + views at the same time, but only one view can start the drag. Drags + are in most cases started as a result of pressing or moving the mouse, + so in mousePressEvent() or mouseMoveEvent(), you can get the + originating widget pointer from the event. For example: + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 5 + + To intercept drag and drop events for the scene, you reimplement + QGraphicsScene::dragEnterEvent() and whichever event handlers your + particular scene needs, in a QGraphicsItem subclass. You can read more + about drag and drop in Graphics View in the documentation for each of + QGraphicsScene's event handlers. + + Items can enable drag and drop support by calling + QGraphicsItem::setAcceptDrops(). To handle the incoming drag, + reimplement QGraphicsItem::dragEnterEvent(), + QGraphicsItem::dragMoveEvent(), QGraphicsItem::dragLeaveEvent(), and + QGraphicsItem::dropEvent(). + + See also the \l{Drag and Drop Robot Example}{Drag and Drop Robot} example + for a demonstration of Graphics View's support for drag and drop + operations. + + \section2 Cursors and Tooltips + + Like QWidget, QGraphicsItem also supports cursors + (QGraphicsItem::setCursor()), and tooltips + (QGraphicsItem::setToolTip()). The cursors and tooltips are activated + by QGraphicsView as the mouse cursor enters the item's area (detected + by calling QGraphicsItem::contains()). + + You can also set a default cursor directly on the view by calling + QGraphicsView::setCursor(). + + See also the \l{Drag and Drop Robot Example}{Drag and Drop Robot} + example for code that implements tooltips and cursor shape handling. + + \section2 Animation + + Graphics View supports animation at several levels. You can easily + assemble animation paths by associating a QGraphicsItemAnimation with + your item. This allows timeline controlled animations that operate at + a steady speed on all platforms (although the frame rate may vary + depending on the platform's performance). QGraphicsItemAnimation + allows you to create a path for an item's position, rotation, scale, + shear and translation. The animation can be controlled by a QSlider, + or more commonly by QTimeLine. + + Another option is to create a custom item that inherits from QObject + and QGraphicsItem. The item can the set up its own timers, and control + animations with incremental steps in QObject::timerEvent(). + + A third option, which is mostly available for compatibility with + QCanvas in Qt 3, is to \e advance the scene by calling + QGraphicsScene::advance(), which in turn calls + QGraphicsItem::advance(). + + See also the \l{Drag and Drop Robot Example}{Drag and Drop Robot} + example for an illustration of timeline-based animation techniques. + + \section2 OpenGL Rendering + + To enable OpenGL rendering, you simply set a new QGLWidget as the + viewport of QGraphicsView by calling QGraphicsView::setViewport(). If + you want OpenGL with antialiasing, you need OpenGL sample buffer + support (see QGLFormat::sampleBuffers()). + + Example: + + \snippet doc/src/snippets/code/doc_src_graphicsview.qdoc 6 + + \section2 Item Groups + + By making an item a child of another, you can achieve the most + essential feature of item grouping: the items will move together, and + all transformations are propagated from parent to child. QGraphicsItem + can also handle all events for its children (see + QGraphicsItem::setHandlesChildEvents()). This allows the parent item + to act on behalf of its children, effectively treating all items as + one. + + In addition, QGraphicsItemGroup is a special item that combines child + event handling with a useful interface for adding and removing items + to and from a group. Adding an item to a QGraphicsItemGroup will keep + the item's original position and transformation, whereas reparenting + items in general will cause the child to reposition itself relative to + its new parent. For convenience, you can create + \l{QGraphicsItemGroup}s through the scene by calling + QGraphicsScene::createItemGroup(). + + \section2 Widgets and Layouts + + Qt 4.4 introduced support for geometry and layout-aware items through + QGraphicsWidget. This special base item is similar to QWidget, but + unlike QWidget, it doesn't inherit from QPaintDevice; rather from + QGraphicsItem instead. This allows you to write complete widgets with + events, signals & slots, size hints and policies, and you can also + manage your widgets geometries in layouts through + QGraphicsLinearLayout and QGraphicsGridLayout. + + \section3 QGraphicsWidget + + Building on top of QGraphicsItem's capabilities and lean footprint, + QGraphicsWidget provides the best of both worlds: extra + functionality from QWidget, such as the style, font, palette, layout + direction, and its geometry, and resolution independence and + transformation support from QGraphicsItem. Because Graphics View + uses real coordinates instead of integers, QGraphicsWidget's + geometry functions also operate on QRectF and QPointF. This also + applies to frame rects, margins and spacing. With QGraphicsWidget + it's not uncommon to specify contents margins of (0.5, 0.5, 0.5, + 0.5), for example. You can create both subwidgets and "top-level" + windows; in some cases you can now use Graphics View for advanced + MDI applications. + + Some of QWidget's properties are supported, including window flags + and attributes, but not all. You should refer to QGraphicsWidget's + class documentation for a complete overview of what is and what is + not supported. For example, you can create decorated windows by + passing the Qt::Window window flag to QGraphicsWidget's constructor, + but Graphics View currently doesn't support the Qt::Sheet and + Qt::Drawer flags that are common on Mac OS X. + + The capabilities of QGraphicsWidget are expected to grow depending + on community feedback. + + \section3 QGraphicsLayout + + QGraphicsLayout is part of a second-generation layout framework + designed specifically for QGraphicsWidget. Its API is very similar + to that of QLayout. You can manage widgets and sublayouts inside + either QGraphicsLinearLayout and QGraphicsGridLayout. You can also + easily write your own layout by subclassing QGraphicsLayout + yourself, or add your own QGraphicsItem items to the layout by + writing an adaptor subclass of QGraphicsLayoutItem. + + \section2 Embedded Widget Support + + Graphics View provides seamless support for embedding any widget + into the scene. You can embed simple widgets, such as QLineEdit or + QPushButton, complex widgets such as QTabWidget, and even complete + main windows. To embed your widget to the scene, simply call + QGraphicsScene::addWidget(), or create an instance of + QGraphicsProxyWidget to embed your widget manually. + + Through QGraphicsProxyWidget, Graphics View is able to deeply + integrate the client widget features including its cursors, + tooltips, mouse, tablet and keyboard events, child widgets, + animations, pop-ups (e.g., QComboBox or QCompleter), and the widget's + input focus and activation. QGraphicsProxyWidget even integrates the + embedded widget's tab order so that you can tab in and out of + embedded widgets. You can even embed a new QGraphicsView into your + scene to provide complex nested scenes. + + When transforming an embedded widget, Graphics View makes sure that + the widget is transformed resolution independently, allowing the + fonts and style to stay crisp when zoomed in. (Note that the effect + of resolution independence depends on the style.) +*/ diff --git a/doc/src/groups.qdoc b/doc/src/groups.qdoc new file mode 100644 index 0000000..c9cedc4 --- /dev/null +++ b/doc/src/groups.qdoc @@ -0,0 +1,599 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group groups + \title Grouped Classes + \ingroup classlists + + This page provides a way of navigating Qt's classes by grouping + related classes together. Some classes may appear in more than one group. + + \generatelist{related} + + \omit + \row + \o \l{Component Model} + \o Interfaces and helper classes for the Qt Component Model. + \endomit + +*/ + +/*! + \group advanced + \title Advanced Widgets + \ingroup groups + + \brief Advanced GUI widgets such as tab widgets and progress bars. + + These classes provide more complex user interface widgets (controls). + +*/ + +/*! + \group abstractwidgets + \title Abstract Widget Classes + \ingroup groups + + \brief Abstract widget classes usable through subclassing. + + These classes are abstract widgets; they are generally not usable in + themselves, but provide functionality that can be used by inheriting + these classes. + +*/ + +/*! + \group accessibility + \title Accessibility Classes + \ingroup groups + \ingroup topics + + \brief Classes that provide support for accessibility. + + Accessible applications are able to be used by users who cannot use + conventional means of interaction. These classes provide support for + accessible applications. + +*/ + +/*! + \group appearance + \title Widget Appearance and Style + \ingroup groups + + \brief Appearance customization with styles, fonts, colors etc. + + These classes are used to customize an application's appearance and + style. + +*/ + +/*! + \group application + \title Main Window and Related Classes + \ingroup groups + + \brief Everything you need for a typical modern main application window, + including menus, toolbars, workspace, etc. + + These classes provide everything you need for a typical modern main + application window, like the main window itself, menu and tool bars, + a status bar, etc. + +*/ + + +/*! + \group basicwidgets + \title Basic Widgets + \ingroup groups + + \brief Basic GUI widgets such as buttons, comboboxes and scroll bars. + + These basic widgets (controls) are designed for direct use. + There are also some \l{Abstract Widget Classes} that are designed for + subclassing, and some more complex \l{Advanced Widgets}. + +*/ + +/* \group componentmodel + \title Component Model + + These classes and interfaces form the basis of the \l{Qt Component Model}. + +*/ + +/*! + \group database + \title Database Classes + \ingroup groups + + \brief Database related classes, e.g. for SQL databases. + + These classes provide access to SQL databases. +*/ + + +/*! + \group dialogs + \title Standard Dialog Classes + \ingroup groups + + \brief Ready-made dialogs for file, font, color selection and more. + + These classes are complex widgets, composed of simpler widgets; dialog + boxes, generally. +*/ + +/*! + \group desktop + \title Desktop Environment Classes + \ingroup groups + + \brief Classes for interacting with the user's desktop environment. + + These classes provide ways to interact with the user's desktop environment and + take advantage of common services. +*/ + +/*! + \group draganddrop + \title Drag And Drop Classes + \ingroup groups + + \brief Classes dealing with drag and drop and mime type encoding and decoding. + + These classes deal with drag and drop and the necessary mime type + encoding and decoding. See also \link dnd.html Drag and Drop with + Qt. \endlink +*/ + +/*! + \group environment + \title Environment Classes + \ingroup groups + + \brief Classes providing various global services such as event handling, + access to system settings and internationalization. + + These classes providing various global services to your application such as + event handling, access to system settings, internationalization, etc. + +*/ + +/*! + \group events + \title Event Classes + \ingroup groups + + \brief Classes used to create and handle events. + + These classes are used to create and handle events. + + For more information see the \link object.html Object model\endlink + and \link signalsandslots.html Signals and Slots\endlink. +*/ + +/*! + \group explicitly-shared + \ingroup groups + + \title Explicitly Shared Classes + \brief Classes that use explicit sharing to manage internal data. + + \keyword explicit sharing + \keyword explicitly shared + + Unlike many of Qt's data types, which use \l{implicit sharing}, these + classes use explicit sharing to manage internal data. +*/ + +/*! + \group geomanagement + \title Layout Management + \ingroup groups + + \brief Classes handling automatic resizing and moving of widgets, for + composing complex dialogs. + + These classes provide automatic geometry (layout) management of widgets. + +*/ + +/*! + \group graphicsview-api + \title Graphics View Classes + \ingroup groups + + \brief Classes in the Graphics View framework for interactive applications. + + These classes are provided by \l{The Graphics View Framework} for interactive + applications and are part of a larger collection of classes related to + \l{Multimedia, Graphics and Printing}. + + \note These classes are part of the \l{Open Source Versions of Qt} and + \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial users. +*/ + +/*! + \group helpsystem + \title Help System + \ingroup groups + + \brief Classes used to provide online-help for applications. + + \keyword help system + + These classes provide for all forms of online-help in your application, + with three levels of detail: + + \list 1 + \o Tool Tips and Status Bar message - flyweight help, extremely brief, + entirely integrated in the user interface, requiring little + or no user interaction to invoke. + \o What's This? - lightweight, but can be + a three-paragraph explanation. + \o Online Help - can encompass any amount of information, + but is typically slower to call up, somewhat separated + from the user's work, and often users feel that using online + help is a digression from their real task. + \endlist + +*/ + + +/*! + \group io + \title Input/Output and Networking + \ingroup groups + + \brief Classes providing file input and output along with directory and + network handling. + + These classes are used to handle input and output to and from external + devices, processes, files etc. as well as manipulating files and directories. +*/ + +/*! + \group misc + \title Miscellaneous Classes + \ingroup groups + + \brief Various other useful classes. + + These classes are useful classes not fitting into any other category. + +*/ + + +/*! + \group model-view + \title Model/View Classes + \ingroup groups + + \brief Classes that use the model/view design pattern. + + These classes use the model/view design pattern in which the + underlying data (in the model) is kept separate from the way the data + is presented and manipulated by the user (in the view). See also + \link model-view-programming.html Model/View Programming\endlink. + +*/ + +/*! + \group multimedia + \title Multimedia, Graphics and Printing + \ingroup groups + + \brief Classes that provide support for graphics (2D, and with OpenGL, 3D), + image encoding, decoding, and manipulation, sound, animation, + printing, etc. + + These classes provide support for graphics (2D, and with OpenGL, 3D), + image encoding, decoding, and manipulation, sound, animation, printing + etc. + + See also this introduction to the \link coordsys.html Qt + coordinate system. \endlink + +*/ + +/*! + \group objectmodel + \title Object Model + \ingroup groups + + \brief The Qt GUI toolkit's underlying object model. + + These classes form the basis of the \l{Qt Object Model}. + +*/ + +/*! + \group organizers + \title Organizers + \ingroup groups + + \brief User interface organizers such as splitters, tab bars, button groups, etc. + + These classes are used to organize and group GUI primitives into more + complex applications or dialogs. + +*/ + + +/*! + \group plugins + \title Plugin Classes + \ingroup groups + + \brief Plugin related classes. + + These classes deal with shared libraries, (e.g. .so and DLL files), + and with Qt plugins. + + See the \link plugins-howto.html plugins documentation\endlink. + + See also the \l{ActiveQt framework} for Windows. + +*/ + +/*! + \group qws + \title Qt for Embedded Linux Classes + \ingroup groups + + \ingroup qt-embedded-linux + \brief Classes that are specific to Qt for Embedded Linux. + + These classes are relevant to \l{Qt for Embedded Linux} users. +*/ + +/*! + \group shared + \title Implicitly Shared Classes + \ingroup architecture + \ingroup groups + + \brief Classes that use reference counting for fast copying. + + \keyword implicit data sharing + \keyword implicit sharing + \keyword implicitly shared + \keyword reference counting + \keyword shared implicitly + \keyword shared classes + + Many C++ classes in Qt use implicit data sharing to maximize + resource usage and minimize copying. Implicitly shared classes are + both safe and efficient when passed as arguments, because only a + pointer to the data is passed around, and the data is copied only + if and when a function writes to it, i.e., \e {copy-on-write}. + + \tableofcontents + + \section1 Overview + + A shared class consists of a pointer to a shared data block that + contains a reference count and the data. + + When a shared object is created, it sets the reference count to 1. The + reference count is incremented whenever a new object references the + shared data, and decremented when the object dereferences the shared + data. The shared data is deleted when the reference count becomes + zero. + + \keyword deep copy + \keyword shallow copy + + When dealing with shared objects, there are two ways of copying an + object. We usually speak about \e deep and \e shallow copies. A deep + copy implies duplicating an object. A shallow copy is a reference + copy, i.e. just a pointer to a shared data block. Making a deep copy + can be expensive in terms of memory and CPU. Making a shallow copy is + very fast, because it only involves setting a pointer and incrementing + the reference count. + + Object assignment (with operator=()) for implicitly shared objects is + implemented using shallow copies. + + The benefit of sharing is that a program does not need to duplicate + data unnecessarily, which results in lower memory use and less copying + of data. Objects can easily be assigned, sent as function arguments, + and returned from functions. + + Implicit sharing takes place behind the scenes; the programmer + does not need to worry about it. Even in multithreaded + applications, implicit sharing takes place, as explained in + \l{Threads and Implicit Sharing}. + + \section1 Implicit Sharing in Detail + + Implicit sharing automatically detaches the object from a shared + block if the object is about to change and the reference count is + greater than one. (This is often called \e {copy-on-write} or + \e {value semantics}.) + + An implicitly shared class has total control of its internal data. In + any member functions that modify its data, it automatically detaches + before modifying the data. + + The QPen class, which uses implicit sharing, detaches from the shared + data in all member functions that change the internal data. + + Code fragment: + \snippet doc/src/snippets/code/doc_src_groups.qdoc 0 + + \section1 List of Classes + + The classes listed below automatically detach from common data if + an object is about to be changed. The programmer will not even + notice that the objects are shared. Thus you should treat + separate instances of them as separate objects. They will always + behave as separate objects but with the added benefit of sharing + data whenever possible. For this reason, you can pass instances + of these classes as arguments to functions by value without + concern for the copying overhead. + + Example: + \snippet doc/src/snippets/code/doc_src_groups.qdoc 1 + + In this example, \c p1 and \c p2 share data until QPainter::begin() + is called for \c p2, because painting a pixmap will modify it. + + \warning Do not copy an implicitly shared container (QMap, + QVector, etc.) while you are iterating over it using an non-const + \l{STL-style iterator}. +*/ + +/*! + \group ssl + \title Secure Sockets Layer (SSL) Classes + \ingroup groups + + \brief Classes for secure communication over network sockets. + \keyword SSL + + The classes below provide support for secure network communication using + the Secure Sockets Layer (SSL) protocol, using the \l{OpenSSL Toolkit} to + perform encryption and protocol handling. + + See the \l{General Qt Requirements} page for information about the + versions of OpenSSL that are known to work with Qt. + + \note Due to import and export restrictions in some parts of the world, we + are unable to supply the OpenSSL Toolkit with Qt packages. Developers wishing + to use SSL communication in their deployed applications should either ensure + that their users have the appropriate libraries installed, or they should + consult a suitably qualified legal professional to ensure that applications + using code from the OpenSSL project are correctly certified for import + and export in relevant regions of the world. + + When the QtNetwork module is built with SSL support, the library is linked + against OpenSSL in a way that requires OpenSSL license compliance. +*/ + +/*! + \group text + \title Text Processing Classes + \ingroup groups + \ingroup text-processing + + \brief Classes for text processing. (See also \l{XML Classes}.) + + These classes are relevant to text processing. See also the + \l{Rich Text Processing} overview and the + \l{XML classes}. +*/ + +/*! + \group thread + \title Threading Classes + \ingroup groups + + \brief Classes that provide threading support. + + These classes are relevant to threaded applications. See + \l{Thread Support in Qt} for an overview of the features + Qt provides to help with multithreaded programming. +*/ + + +/*! + \group time + \title Date and Time Classes + \ingroup groups + + \brief Classes for handling date and time. + + These classes provide system-independent date and time abstractions. + +*/ + +/*! + \group tools + \title Non-GUI Classes + \ingroup groups + + \brief Collection classes such as list, queue, stack and string, along + with other classes that can be used without needing QApplication. + + The non-GUI classes are general-purpose collection and string classes + that may be used independently of the GUI classes. + + In particular, these classes do not depend on QApplication at all, + and so can be used in non-GUI programs. + +*/ + +/*! + \group xml-tools + \title XML Classes + \ingroup groups + + \brief Classes that support XML, via, for example DOM and SAX. + + These classes are relevant to XML users. +*/ + +/*! + \group script + \title Scripting Classes + \ingroup groups + \ingroup scripting + + \brief Qt Script-related classes and overviews. + + These classes are relevant to Qt Script users. +*/ + +/*! + \group scripttools + \title Script Tools + \ingroup groups + \ingroup scripting + + \brief Classes for managing and debugging scripts. + + These classes are relevant to developers who are working with Qt Script's + debugging features. +*/ diff --git a/doc/src/guibooks.qdoc b/doc/src/guibooks.qdoc new file mode 100644 index 0000000..888368b --- /dev/null +++ b/doc/src/guibooks.qdoc @@ -0,0 +1,121 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page guibooks.html + + \title Books about GUI Design + \ingroup gui-programming + + This is not a comprehensive list -- there are many other books worth + buying. Here we mention just a few user interface books that don't + gather dust on our shelves. + + \bold{\l{http://www.amazon.com/gp/product/0132354160/ref=ase_trolltech/}{C++ + GUI Programming with Qt 4, Second Edition}} + by Jasmin Blanchette and Mark + Summerfield, ISBN 0-13-235416-0. This is the official Qt book written + by two veteran Trolls. The first edition, which is based on Qt 4.1, is available + \l{http://www.qtrac.eu/C++-GUI-Programming-with-Qt-4-1st-ed.zip}{online}. + + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/0385267746/trolltech/t}{The Design of Everyday Things}} + by Donald Norman, ISBN 0-38526774-6, is one of the classics of human + interface design. Norman shows how badly something as simple as a + kitchen stove can be designed, and everyone should read it who will + design a dialog box, write an error message, or design just about + anything else humans are supposed to use. + + \target fowler + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/0070592748/trolltech/t}{GUI Design Handbook}} + by Susan Fowler, ISBN 0-07-059274-8, is an + alphabetical dictionary of widgets and other user interface elements, + with comprehensive coverage of each. Each chapter covers one widget + or other element, contains the most important recommendation from the + Macintosh, Windows and Motif style guides, notes about common + problems, comparison with other widgets that can serve some of the + same roles as this one, etc. + + \target Design Patterns + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/0201633612/103-8144203-3273444} + {Design Patterns - Elements of Reusable Object-Oriented Software}} + by Gamma, Helm, Johnson, and Vlissides, ISBN 0-201-63361-2, provides + more information on the Model-View-Controller (MVC) paradigm, explaining + MVC and its sub-patterns in detail. + + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/0201622165/trolltech/t}{Macintosh + Human Interface Guidelines}}, Second Edition, ISBN + 0-201-62216-5, is worth buying for the \e {don't}s alone. Even + if you're not writing Macintosh software, avoiding most of what it + advises against will produce more easily comprehensible software. + Doing what it tells you to do may also help. This book is now available + \link http://developer.apple.com/techpubs/mac/HIGuidelines/HIGuidelines-2.html + online\endlink and there is a + \link http://developer.apple.com/techpubs/mac/HIGOS8Guide/thig-2.html Mac + OS 8 addendum.\endlink + + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/047159900X/trolltech/t}{The + Microsoft Windows User Experience}}, ISBN 1-55615-679-0, + is Microsoft's look and feel bible. Indispensable for everyone who + has customers that worship Microsoft, and it's quite good, too. + It is also available + \link http://msdn.microsoft.com/library/en-us/dnwue/html/welcome.asp online\endlink. + + \bold{\l{http://www.amazon.com/exec/obidos/ASIN/047159900X/trolltech/t}{The Icon Book}} + by William Horton, ISBN 0-471-59900-X, is perhaps the only thorough + coverage of icons and icon use in software. In order for icons to be + successful, people must be able to do four things with them: decode, + recognize, find and activate them. This book explains these goals + from scratch and how to reach them, both with single icons and icon + families. Some 500 examples are scattered throughout the text. + + + \section1 Buying these Books from Amazon.com + + These books are made available in association with Amazon.com, our + favorite online bookstore. Here is more information about + \link http://www.amazon.com/exec/obidos/subst/help/shipping-policy.html/t + Amazon.com's shipping options\endlink and its + \link http://www.amazon.com/exec/obidos/subst/help/desk.html/t + customer service.\endlink When you buy a book by following one of these + links, Amazon.com gives about 15% of the purchase price to + \link http://www.amnesty.org/ Amnesty International.\endlink + +*/ diff --git a/doc/src/hierarchy.qdoc b/doc/src/hierarchy.qdoc new file mode 100644 index 0000000..2b70964 --- /dev/null +++ b/doc/src/hierarchy.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page hierarchy.html + + \title Class Inheritance Hierarchy + \ingroup classlists + + This list shows the C++ class inheritance relations between the + classes in the Qt API. + + \generatelist classhierarchy +*/ diff --git a/doc/src/how-to-learn-qt.qdoc b/doc/src/how-to-learn-qt.qdoc new file mode 100644 index 0000000..4b16294 --- /dev/null +++ b/doc/src/how-to-learn-qt.qdoc @@ -0,0 +1,115 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page how-to-learn-qt.html + \brief Links to guides and resources for learning Qt. + \title How to Learn Qt + \ingroup howto + + We assume that you already know C++ and will be using it for Qt + development. See the \l{Qt website} for more information about + using other programming languages with Qt. + + The best way to learn Qt is to read the official Qt book, + \l{http://www.amazon.com/gp/product/0132354160/ref=ase_trolltech/}{C++ + GUI Programming with Qt 4, Second Edition} (ISBN 0-13-235416-0). This book + provides comprehensive coverage of Qt programming all the way + from "Hello Qt" to advanced features such as multithreading, 2D and + 3D graphics, networking, item view classes, and XML. (The first edition, + which is based on Qt 4.1, is available + \l{http://www.qtrac.eu/C++-GUI-Programming-with-Qt-4-1st-ed.zip}{online}.) + + If you want to program purely in C++, designing your interfaces + in code without the aid of any design tools, take a look at the + \l{Tutorials}. These are designed to get you into Qt programming, + with an emphasis on working code rather than being a tour of features. + + If you want to design your user interfaces using a design tool, then + read at least the first few chapters of the \l{Qt Designer manual}. + + By now you'll have produced some small working applications and have a + broad feel for Qt programming. You could start work on your own + projects straight away, but we recommend reading a couple of key + overviews to deepen your understanding of Qt: \l{Qt Object Model} + and \l{Signals and Slots}. + + At this point, we recommend looking at the + \l{All Overviews and HOWTOs}{overviews} and reading those that are + relevant to your projects. You may also find it useful to browse the + source code of the \l{Qt Examples}{examples} that have things in + common with your projects. You can also read Qt's source code since + this is supplied. + + \table + \row \o \inlineimage qtdemo-small.png + \o \bold{Getting an Overview} + + If you run the \l{Examples and Demos Launcher}, you'll see many of Qt's + widgets in action. + + The \l{Qt Widget Gallery} also provides overviews of selected Qt + widgets in each of the styles used on various supported platforms. + \endtable + + Qt comes with extensive documentation, with hypertext + cross-references throughout, so you can easily click your way to + whatever interests you. The part of the documentation that you'll + probably use the most is the \link index.html API + Reference\endlink. Each link provides a different way of + navigating the API Reference; try them all to see which work best + for you. You might also like to try \l{Qt Assistant}: + this tool is supplied with Qt and provides access to the entire + Qt API, and it provides a full text search facility. + + There are also a growing number of books about Qt programming; see + \l{Books about Qt Programming} for a complete list of Qt books, + including translations to various languages. + + Another valuable source of example code and explanations of Qt + features is the archive of articles from \l {http://doc.trolltech.com/qq} + {Qt Quarterly}, a quarterly newsletter for users of Qt. + + For documentation on specific Qt modules and other guides, refer to + \l{All Overviews and HOWTOs}. + + Good luck, and have fun! +*/ diff --git a/doc/src/i18n.qdoc b/doc/src/i18n.qdoc new file mode 100644 index 0000000..5018b51 --- /dev/null +++ b/doc/src/i18n.qdoc @@ -0,0 +1,508 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group i18n + \title Internationalization with Qt + \ingroup topics + + \brief Information about Qt's support for internationalization and multiple languages. + + \keyword internationalization + \keyword i18n + + The internationalization of an application is the process of making + the application usable by people in countries other than one's own. + + \tableofcontents + + In some cases internationalization is simple, for example, making a US + application accessible to Australian or British users may require + little more than a few spelling corrections. But to make a US + application usable by Japanese users, or a Korean application usable + by German users, will require that the software operate not only in + different languages, but use different input techniques, character + encodings and presentation conventions. + + Qt tries to make internationalization as painless as possible for + developers. All input widgets and text drawing methods in Qt offer + built-in support for all supported languages. The built-in font engine + is capable of correctly and attractively rendering text that contains + characters from a variety of different writing systems at the same + time. + + Qt supports most languages in use today, in particular: + \list + \o All East Asian languages (Chinese, Japanese and Korean) + \o All Western languages (using Latin script) + \o Arabic + \o Cyrillic languages (Russian, Ukrainian, etc.) + \o Greek + \o Hebrew + \o Thai and Lao + \o All scripts in Unicode 4.0 that do not require special processing + \endlist + + On Windows, Unix/X11 with FontConfig (client side font support) + and Qt for Embedded Linux the following languages are also supported: + \list + \o Bengali + \o Devanagari + \o Dhivehi (Thaana) + \o Gujarati + \o Gurmukhi + \o Kannada + \o Khmer + \o Malayalam + \o Myanmar + \o Syriac + \o Tamil + \o Telugu + \o Tibetan + \endlist + + Many of these writing systems exhibit special features: + + \list + + \o \bold{Special line breaking behavior.} Some of the Asian languages are + written without spaces between words. Line breaking can occur either + after every character (with exceptions) as in Chinese, Japanese and + Korean, or after logical word boundaries as in Thai. + + \o \bold{Bidirectional writing.} Arabic and Hebrew are written from right to + left, except for numbers and embedded English text which is written + left to right. The exact behavior is defined in the + \l{http://www.unicode.org/unicode/reports/tr9/}{Unicode Technical Annex #9}. + + \o \bold{Non-spacing or diacritical marks (accents or umlauts in European + languages).} Some languages such as Vietnamese make extensive use of + these marks and some characters can have more than one mark at the + same time to clarify pronunciation. + + \o \bold{Ligatures.} In special contexts, some pairs of characters get + replaced by a combined glyph forming a ligature. Common examples are + the fl and fi ligatures used in typesetting US and European books. + + \endlist + + Qt tries to take care of all the special features listed above. You + usually don't have to worry about these features so long as you use + Qt's input widgets (e.g. QLineEdit, QTextEdit, and derived classes) + and Qt's display widgets (e.g. QLabel). + + Support for these writing systems is transparent to the + programmer and completely encapsulated in \l{rich text + processing}{Qt's text engine}. This means that you don't need to + have any knowledge about the writing system used in a particular + language, except for the following small points: + + \list + + \o QPainter::drawText(int x, int y, const QString &str) will always + draw the string with its left edge at the position specified with + the x, y parameters. This will usually give you left aligned strings. + Arabic and Hebrew application strings are usually right + aligned, so for these languages use the version of drawText() that + takes a QRect since this will align in accordance with the language. + + \o When you write your own text input controls, use \l + QFontMetrics::charWidth() to determine the width of a character in a + string. In some languages (e.g. Arabic or languages from the Indian + subcontinent), the width and shape of a glyph changes depending on the + surrounding characters. Writing input controls usually requires a + certain knowledge of the scripts it is going to be used in. Usually + the easiest way is to subclass QLineEdit or QTextEdit. + + \endlist + + The following sections give some information on the status of the + internationalization (i18n) support in Qt. See also the \l{Qt + Linguist manual}. + + \section1 Step by Step + + Writing cross-platform international software with Qt is a gentle, + incremental process. Your software can become internationalized in + the following stages: + + \section2 Use QString for All User-Visible Text + + Since QString uses the Unicode 4.0 encoding internally, every + language in the world can be processed transparently using + familiar text processing operations. Also, since all Qt functions + that present text to the user take a QString as a parameter, + there is no \c{char *} to QString conversion overhead. + + Strings that are in "programmer space" (such as QObject names + and file format texts) need not use QString; the traditional + \c{char *} or the QByteArray class will suffice. + + You're unlikely to notice that you are using Unicode; + QString, and QChar are just like easier versions of the crude + \c{const char *} and char from traditional C. + + \section2 Use tr() for All Literal Text + + Wherever your program uses "quoted text" for text that will + be presented to the user, ensure that it is processed by the \l + QCoreApplication::translate() function. Essentially all that is necessary + to achieve this is to use QObject::tr(). For example, assuming the + \c LoginWidget is a subclass of QWidget: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 0 + + This accounts for 99% of the user-visible strings you're likely to + write. + + If the quoted text is not in a member function of a + QObject subclass, use either the tr() function of an + appropriate class, or the QCoreApplication::translate() function + directly: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 1 + + If you need to have translatable text completely + outside a function, there are two macros to help: QT_TR_NOOP() + and QT_TRANSLATE_NOOP(). They merely mark the text for + extraction by the \c lupdate utility described below. + The macros expand to just the text (without the context). + + Example of QT_TR_NOOP(): + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 2 + + Example of QT_TRANSLATE_NOOP(): + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 3 + + If you disable the \c{const char *} to QString automatic + conversion by compiling your software with the macro \c + QT_NO_CAST_FROM_ASCII defined, you'll be very likely to catch any + strings you are missing. See QString::fromLatin1() for more + information. Disabling the conversion can make programming a bit + cumbersome. + + If your source language uses characters outside Latin1, you + might find QObject::trUtf8() more convenient than + QObject::tr(), as tr() depends on the + QTextCodec::codecForTr(), which makes it more fragile than + QObject::trUtf8(). + + \section2 Use QKeySequence() for Accelerator Values + + Accelerator values such as Ctrl+Q or Alt+F need to be translated + too. If you hardcode Qt::CTRL + Qt::Key_Q for "quit" in your + application, translators won't be able to override it. The + correct idiom is + + \snippet examples/mainwindows/application/mainwindow.cpp 20 + + \section2 Use QString::arg() for Dynamic Text + + The QString::arg() functions offer a simple means for substituting + arguments: + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 4 + + In some languages the order of arguments may need to change, and this + can easily be achieved by changing the order of the % arguments. For + example: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 5 + + produces the correct output in English and Norwegian: + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 6 + + \section2 Produce Translations + + Once you are using tr() throughout an application, you can start + producing translations of the user-visible text in your program. + + The \l{Qt Linguist manual} provides further information about + Qt's translation tools, \e{Qt Linguist}, \c lupdate and \c + lrelease. + + Translation of a Qt application is a three-step process: + + \list 1 + + \o Run \c lupdate to extract translatable text from the C++ + source code of the Qt application, resulting in a message file + for translators (a \c .ts file). The utility recognizes the tr() + construct and the \c{QT_TR*_NOOP()} macros described above and + produces \c .ts files (usually one per language). + + \o Provide translations for the source texts in the \c .ts file, using + \e{Qt Linguist}. Since \c .ts files are in XML format, you can also + edit them by hand. + + \o Run \c lrelease to obtain a light-weight message file (a \c .qm + file) from the \c .ts file, suitable only for end use. Think of the \c + .ts files as "source files", and \c .qm files as "object files". The + translator edits the \c .ts files, but the users of your application + only need the \c .qm files. Both kinds of files are platform and + locale independent. + + \endlist + + Typically, you will repeat these steps for every release of your + application. The \c lupdate utility does its best to reuse the + translations from previous releases. + + Before you run \c lupdate, you should prepare a project file. Here's + an example project file (\c .pro file): + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 7 + + When you run \c lupdate or \c lrelease, you must give the name of the + project file as a command-line argument. + + In this example, four exotic languages are supported: Danish, + Finnish, Norwegian and Swedish. If you use \l{qmake}, you usually + don't need an extra project file for \c lupdate; your \c qmake + project file will work fine once you add the \c TRANSLATIONS + entry. + + In your application, you must \l QTranslator::load() the translation + files appropriate for the user's language, and install them using \l + QCoreApplication::installTranslator(). + + \c linguist, \c lupdate and \c lrelease are installed in the \c bin + subdirectory of the base directory Qt is installed into. Click Help|Manual + in \e{Qt Linguist} to access the user's manual; it contains a tutorial + to get you started. + + \target qt-itself + Qt itself contains over 400 strings that will also need to be + translated into the languages that you are targeting. You will find + translation files for French, German and Simplified Chinese in + \c{$QTDIR/translations}, as well as a template for translating to + other languages. (This directory also contains some additional + unsupported translations which may be useful.) + + Typically, your application's \c main() function will look like + this: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 8 + + Note the use of QLibraryInfo::location() to locate the Qt translations. + Developers should request the path to the translations at run-time by + passing QLibraryInfo::TranslationsPath to this function instead of + using the \c QTDIR environment variable in their applications. + + \section2 Support for Encodings + + The QTextCodec class and the facilities in QTextStream make it easy to + support many input and output encodings for your users' data. When an + application starts, the locale of the machine will determine the 8-bit + encoding used when dealing with 8-bit data: such as for font + selection, text display, 8-bit text I/O, and character input. + + The application may occasionally require encodings other than the + default local 8-bit encoding. For example, an application in a + Cyrillic KOI8-R locale (the de-facto standard locale in Russia) might + need to output Cyrillic in the ISO 8859-5 encoding. Code for this + would be: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 9 + + For converting Unicode to local 8-bit encodings, a shortcut is + available: the QString::toLocal8Bit() function returns such 8-bit + data. Another useful shortcut is QString::toUtf8(), which returns + text in the 8-bit UTF-8 encoding: this perfectly preserves + Unicode information while looking like plain ASCII if the text is + wholly ASCII. + + For converting the other way, there are the QString::fromUtf8() and + QString::fromLocal8Bit() convenience functions, or the general code, + demonstrated by this conversion from ISO 8859-5 Cyrillic to Unicode + conversion: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 10 + + Ideally Unicode I/O should be used as this maximizes the portability + of documents between users around the world, but in reality it is + useful to support all the appropriate encodings that your users will + need to process existing documents. In general, Unicode (UTF-16 or + UTF-8) is best for information transferred between arbitrary people, + while within a language or national group, a local standard is often + more appropriate. The most important encoding to support is the one + returned by QTextCodec::codecForLocale(), as this is the one the user + is most likely to need for communicating with other people and + applications (this is the codec used by local8Bit()). + + Qt supports most of the more frequently used encodings natively. For a + complete list of supported encodings see the \l QTextCodec + documentation. + + In some cases and for less frequently used encodings it may be + necessary to write your own QTextCodec subclass. Depending on the + urgency, it may be useful to contact Qt's technical support team or + ask on the \c qt-interest mailing list to see if someone else is + already working on supporting the encoding. + + \keyword localization + + \section2 Localize + + Localization is the process of adapting to local conventions, for + example presenting dates and times using the locally preferred + formats. Such localizations can be accomplished using appropriate tr() + strings. + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 11 + + In the example, for the US we would leave the translation of + "AMPM" as it is and thereby use the 12-hour clock branch; but in + Europe we would translate it as something else and this will make + the code use the 24-hour clock branch. + + For localized numbers use the QLocale class. + + Localizing images is not recommended. Choose clear icons that are + appropriate for all localities, rather than relying on local puns or + stretched metaphors. The exception is for images of left and right + pointing arrows which may need to be reversed for Arabic and Hebrew + locales. + + \section1 Dynamic Translation + + Some applications, such as Qt Linguist, must be able to support changes + to the user's language settings while they are still running. To make + widgets aware of changes to the installed QTranslators, reimplement the + widget's \l{QWidget::changeEvent()}{changeEvent()} function to check whether + the event is a \l{QEvent::LanguageChange}{LanguageChange} event, and update + the text displayed by widgets using the \l{QObject::tr()}{tr()} function + in the usual way. For example: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 12 + + All other change events should be passed on by calling the default + implementation of the function. + + The list of installed translators might change in reaction to a + \l{QEvent::LocaleChange}{LocaleChange} event, or the application might + provide a user interface that allows the user to change the current + application language. + + The default event handler for QWidget subclasses responds to the + QEvent::LanguageChange event, and will call this function when necessary; + other application components can also force widgets to update themselves + by posting the \l{QEvent::LanguageChange}{LanguageChange} event to them. + + \section1 Translating Non-Qt Classes + + It is sometimes necessary to provide internationalization support for + strings used in classes that do not inherit QObject or use the Q_OBJECT + macro to enable translation features. Since Qt translates strings at + run-time based on the class they are associated with and \c lupdate + looks for translatable strings in the source code, non-Qt classes must + use mechanisms that also provide this information. + + One way to do this is to add translation support to a non-Qt class + using the Q_DECLARE_TR_FUNCTIONS() macro; for example: + + \snippet doc/src/snippets/i18n-non-qt-class/myclass.h 0 + \dots + \snippet doc/src/snippets/i18n-non-qt-class/myclass.h 1 + + This provides the class with \l{QObject::}{tr()} functions that can + be used to translate strings associated with the class, and makes it + possible for \c lupdate to find translatable strings in the source + code. + + Alternatively, the QCoreApplication::translate() function can be called + with a specific context, and this will be recognized by \c lupdate and + Qt Linguist. + + \section1 System Support + + Some of the operating systems and windowing systems that Qt runs on + only have limited support for Unicode. The level of support available + in the underlying system has some influence on the support that Qt can + provide on those platforms, although in general Qt applications need + not be too concerned with platform-specific limitations. + + \section2 Unix/X11 + + \list + \o Locale-oriented fonts and input methods. Qt hides these and + provides Unicode input and output. + \o Filesystem conventions such as + \l{http://www.ietf.org/rfc/rfc2279.txt}{UTF-8} + are under development in some Unix variants. All Qt file + functions allow Unicode, but convert filenames to the local + 8-bit encoding, as this is the Unix convention (see + QFile::setEncodingFunction() to explore alternative + encodings). + \o File I/O defaults to the local 8-bit encoding, + with Unicode options in QTextStream. + \o Many Unix distributions contain only partial support for some locales. + For example, if you have a \c /usr/share/locale/ja_JP.EUC directory, + this does not necessarily mean you can display Japanese text; you also + need JIS encoded fonts (or Unicode fonts), and the + \c /usr/share/locale/ja_JP.EUC directory needs to be complete. For + best results, use complete locales from your system vendor. + \endlist + + \section2 Windows + + \list + \o Qt provides full Unicode support, including input methods, fonts, + clipboard, drag-and-drop and file names. + \o File I/O defaults to Latin1, with Unicode options in QTextStream. + Note that some Windows programs do not understand big-endian + Unicode text files even though that is the order prescribed by + the Unicode Standard in the absence of higher-level protocols. + \o Unlike programs written with MFC or plain winlib, Qt programs + are portable between Windows 98 and Windows NT. + \e {You do not need different binaries to support Unicode.} + \endlist + + \section2 Mac OS X + + For details on Mac-specific translation, refer to the Qt/Mac Specific Issues + document \l{Qt for Mac OS X - Specific Issues#Translating the Application Menu and Native Dialogs}{here}. + + \section1 Relevant Qt Classes + + These classes are relevant to internationalizing Qt applications. +*/ diff --git a/doc/src/images/2dpainting-example.png b/doc/src/images/2dpainting-example.png new file mode 100644 index 0000000..2a77e7d Binary files /dev/null and b/doc/src/images/2dpainting-example.png differ diff --git a/doc/src/images/abstract-connections.png b/doc/src/images/abstract-connections.png new file mode 100644 index 0000000..18d2f4e Binary files /dev/null and b/doc/src/images/abstract-connections.png differ diff --git a/doc/src/images/accessibilityarchitecture.png b/doc/src/images/accessibilityarchitecture.png new file mode 100644 index 0000000..40cd6dc Binary files /dev/null and b/doc/src/images/accessibilityarchitecture.png differ diff --git a/doc/src/images/accessibleobjecttree.png b/doc/src/images/accessibleobjecttree.png new file mode 100644 index 0000000..8b82158 Binary files /dev/null and b/doc/src/images/accessibleobjecttree.png differ diff --git a/doc/src/images/addressbook-adddialog.png b/doc/src/images/addressbook-adddialog.png new file mode 100644 index 0000000..e2bab80 Binary files /dev/null and b/doc/src/images/addressbook-adddialog.png differ diff --git a/doc/src/images/addressbook-classes.png b/doc/src/images/addressbook-classes.png new file mode 100644 index 0000000..2920f16 Binary files /dev/null and b/doc/src/images/addressbook-classes.png differ diff --git a/doc/src/images/addressbook-editdialog.png b/doc/src/images/addressbook-editdialog.png new file mode 100644 index 0000000..fd41ee6 Binary files /dev/null and b/doc/src/images/addressbook-editdialog.png differ diff --git a/doc/src/images/addressbook-example.png b/doc/src/images/addressbook-example.png new file mode 100644 index 0000000..b743c16 Binary files /dev/null and b/doc/src/images/addressbook-example.png differ diff --git a/doc/src/images/addressbook-filemenu.png b/doc/src/images/addressbook-filemenu.png new file mode 100644 index 0000000..ebd14b6 Binary files /dev/null and b/doc/src/images/addressbook-filemenu.png differ diff --git a/doc/src/images/addressbook-newaddresstab.png b/doc/src/images/addressbook-newaddresstab.png new file mode 100644 index 0000000..ff215a4 Binary files /dev/null and b/doc/src/images/addressbook-newaddresstab.png differ diff --git a/doc/src/images/addressbook-signals.png b/doc/src/images/addressbook-signals.png new file mode 100644 index 0000000..cda4269 Binary files /dev/null and b/doc/src/images/addressbook-signals.png differ diff --git a/doc/src/images/addressbook-toolsmenu.png b/doc/src/images/addressbook-toolsmenu.png new file mode 100644 index 0000000..092e9a2 Binary files /dev/null and b/doc/src/images/addressbook-toolsmenu.png differ diff --git a/doc/src/images/addressbook-tutorial-part1-labeled-layout.png b/doc/src/images/addressbook-tutorial-part1-labeled-layout.png new file mode 100644 index 0000000..ef514c8 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part1-labeled-layout.png differ diff --git a/doc/src/images/addressbook-tutorial-part1-labeled-screenshot.png b/doc/src/images/addressbook-tutorial-part1-labeled-screenshot.png new file mode 100644 index 0000000..4381079 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part1-labeled-screenshot.png differ diff --git a/doc/src/images/addressbook-tutorial-part1-screenshot.png b/doc/src/images/addressbook-tutorial-part1-screenshot.png new file mode 100644 index 0000000..cf15627 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part1-screenshot.png differ diff --git a/doc/src/images/addressbook-tutorial-part2-add-contact.png b/doc/src/images/addressbook-tutorial-part2-add-contact.png new file mode 100644 index 0000000..330858d Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part2-add-contact.png differ diff --git a/doc/src/images/addressbook-tutorial-part2-add-flowchart.png b/doc/src/images/addressbook-tutorial-part2-add-flowchart.png new file mode 100644 index 0000000..ca9af37 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part2-add-flowchart.png differ diff --git a/doc/src/images/addressbook-tutorial-part2-add-successful.png b/doc/src/images/addressbook-tutorial-part2-add-successful.png new file mode 100644 index 0000000..3b108fb Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part2-add-successful.png differ diff --git a/doc/src/images/addressbook-tutorial-part2-labeled-layout.png b/doc/src/images/addressbook-tutorial-part2-labeled-layout.png new file mode 100644 index 0000000..73f6dfb Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part2-labeled-layout.png differ diff --git a/doc/src/images/addressbook-tutorial-part2-signals-and-slots.png b/doc/src/images/addressbook-tutorial-part2-signals-and-slots.png new file mode 100644 index 0000000..e49f8dc Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part2-signals-and-slots.png differ diff --git a/doc/src/images/addressbook-tutorial-part2-stretch-effects.png b/doc/src/images/addressbook-tutorial-part2-stretch-effects.png new file mode 100644 index 0000000..d9f7f31 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part2-stretch-effects.png differ diff --git a/doc/src/images/addressbook-tutorial-part3-labeled-layout.png b/doc/src/images/addressbook-tutorial-part3-labeled-layout.png new file mode 100644 index 0000000..662fa7f Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part3-labeled-layout.png differ diff --git a/doc/src/images/addressbook-tutorial-part3-linkedlist.png b/doc/src/images/addressbook-tutorial-part3-linkedlist.png new file mode 100644 index 0000000..e7f4725 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part3-linkedlist.png differ diff --git a/doc/src/images/addressbook-tutorial-part3-screenshot.png b/doc/src/images/addressbook-tutorial-part3-screenshot.png new file mode 100644 index 0000000..97d1357 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part3-screenshot.png differ diff --git a/doc/src/images/addressbook-tutorial-part4-remove.png b/doc/src/images/addressbook-tutorial-part4-remove.png new file mode 100644 index 0000000..42b0f92 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part4-remove.png differ diff --git a/doc/src/images/addressbook-tutorial-part5-finddialog.png b/doc/src/images/addressbook-tutorial-part5-finddialog.png new file mode 100644 index 0000000..18e5451 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part5-finddialog.png differ diff --git a/doc/src/images/addressbook-tutorial-part5-notfound.png b/doc/src/images/addressbook-tutorial-part5-notfound.png new file mode 100644 index 0000000..be7172e Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part5-notfound.png differ diff --git a/doc/src/images/addressbook-tutorial-part5-screenshot.png b/doc/src/images/addressbook-tutorial-part5-screenshot.png new file mode 100644 index 0000000..ea4a66c Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part5-screenshot.png differ diff --git a/doc/src/images/addressbook-tutorial-part5-signals-and-slots.png b/doc/src/images/addressbook-tutorial-part5-signals-and-slots.png new file mode 100644 index 0000000..1771e7b Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part5-signals-and-slots.png differ diff --git a/doc/src/images/addressbook-tutorial-part6-load.png b/doc/src/images/addressbook-tutorial-part6-load.png new file mode 100644 index 0000000..95fdcaf Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part6-load.png differ diff --git a/doc/src/images/addressbook-tutorial-part6-save.png b/doc/src/images/addressbook-tutorial-part6-save.png new file mode 100644 index 0000000..c0deb70 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part6-save.png differ diff --git a/doc/src/images/addressbook-tutorial-part6-screenshot.png b/doc/src/images/addressbook-tutorial-part6-screenshot.png new file mode 100644 index 0000000..f77bf03 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part6-screenshot.png differ diff --git a/doc/src/images/addressbook-tutorial-part7-screenshot.png b/doc/src/images/addressbook-tutorial-part7-screenshot.png new file mode 100644 index 0000000..d6b0a50 Binary files /dev/null and b/doc/src/images/addressbook-tutorial-part7-screenshot.png differ diff --git a/doc/src/images/addressbook-tutorial-screenshot.png b/doc/src/images/addressbook-tutorial-screenshot.png new file mode 100644 index 0000000..d6727dc Binary files /dev/null and b/doc/src/images/addressbook-tutorial-screenshot.png differ diff --git a/doc/src/images/addressbook-tutorial.png b/doc/src/images/addressbook-tutorial.png new file mode 100644 index 0000000..495edda Binary files /dev/null and b/doc/src/images/addressbook-tutorial.png differ diff --git a/doc/src/images/affine-demo.png b/doc/src/images/affine-demo.png new file mode 100644 index 0000000..534d695 Binary files /dev/null and b/doc/src/images/affine-demo.png differ diff --git a/doc/src/images/alphachannelimage.png b/doc/src/images/alphachannelimage.png new file mode 100644 index 0000000..57b17c6 Binary files /dev/null and b/doc/src/images/alphachannelimage.png differ diff --git a/doc/src/images/alphafill.png b/doc/src/images/alphafill.png new file mode 100644 index 0000000..3feff296 Binary files /dev/null and b/doc/src/images/alphafill.png differ diff --git a/doc/src/images/analogclock-example.png b/doc/src/images/analogclock-example.png new file mode 100644 index 0000000..ffd7baa Binary files /dev/null and b/doc/src/images/analogclock-example.png differ diff --git a/doc/src/images/analogclock-viewport.png b/doc/src/images/analogclock-viewport.png new file mode 100644 index 0000000..31ce0c3 Binary files /dev/null and b/doc/src/images/analogclock-viewport.png differ diff --git a/doc/src/images/antialiased.png b/doc/src/images/antialiased.png new file mode 100644 index 0000000..70619cc Binary files /dev/null and b/doc/src/images/antialiased.png differ diff --git a/doc/src/images/application-menus.png b/doc/src/images/application-menus.png new file mode 100644 index 0000000..1815a2a Binary files /dev/null and b/doc/src/images/application-menus.png differ diff --git a/doc/src/images/application.png b/doc/src/images/application.png new file mode 100644 index 0000000..2fb7f2f Binary files /dev/null and b/doc/src/images/application.png differ diff --git a/doc/src/images/arthurplugin-demo.png b/doc/src/images/arthurplugin-demo.png new file mode 100644 index 0000000..6d372c2 Binary files /dev/null and b/doc/src/images/arthurplugin-demo.png differ diff --git a/doc/src/images/assistant-address-toolbar.png b/doc/src/images/assistant-address-toolbar.png new file mode 100644 index 0000000..7f00942 Binary files /dev/null and b/doc/src/images/assistant-address-toolbar.png differ diff --git a/doc/src/images/assistant-assistant.png b/doc/src/images/assistant-assistant.png new file mode 100644 index 0000000..d728889 Binary files /dev/null and b/doc/src/images/assistant-assistant.png differ diff --git a/doc/src/images/assistant-dockwidgets.png b/doc/src/images/assistant-dockwidgets.png new file mode 100644 index 0000000..17bc064 Binary files /dev/null and b/doc/src/images/assistant-dockwidgets.png differ diff --git a/doc/src/images/assistant-docwindow.png b/doc/src/images/assistant-docwindow.png new file mode 100644 index 0000000..c5bac58 Binary files /dev/null and b/doc/src/images/assistant-docwindow.png differ diff --git a/doc/src/images/assistant-examples.png b/doc/src/images/assistant-examples.png new file mode 100644 index 0000000..47c01bc Binary files /dev/null and b/doc/src/images/assistant-examples.png differ diff --git a/doc/src/images/assistant-filter-toolbar.png b/doc/src/images/assistant-filter-toolbar.png new file mode 100644 index 0000000..e1411e4 Binary files /dev/null and b/doc/src/images/assistant-filter-toolbar.png differ diff --git a/doc/src/images/assistant-preferences-documentation.png b/doc/src/images/assistant-preferences-documentation.png new file mode 100644 index 0000000..42c1fd0 Binary files /dev/null and b/doc/src/images/assistant-preferences-documentation.png differ diff --git a/doc/src/images/assistant-preferences-filters.png b/doc/src/images/assistant-preferences-filters.png new file mode 100644 index 0000000..6844d88 Binary files /dev/null and b/doc/src/images/assistant-preferences-filters.png differ diff --git a/doc/src/images/assistant-preferences-fonts.png b/doc/src/images/assistant-preferences-fonts.png new file mode 100644 index 0000000..172fcce Binary files /dev/null and b/doc/src/images/assistant-preferences-fonts.png differ diff --git a/doc/src/images/assistant-preferences-options.png b/doc/src/images/assistant-preferences-options.png new file mode 100644 index 0000000..f04499f Binary files /dev/null and b/doc/src/images/assistant-preferences-options.png differ diff --git a/doc/src/images/assistant-search.png b/doc/src/images/assistant-search.png new file mode 100644 index 0000000..ef75c33 Binary files /dev/null and b/doc/src/images/assistant-search.png differ diff --git a/doc/src/images/assistant-toolbar.png b/doc/src/images/assistant-toolbar.png new file mode 100644 index 0000000..1b41825 Binary files /dev/null and b/doc/src/images/assistant-toolbar.png differ diff --git a/doc/src/images/basicdrawing-example.png b/doc/src/images/basicdrawing-example.png new file mode 100644 index 0000000..043acbe Binary files /dev/null and b/doc/src/images/basicdrawing-example.png differ diff --git a/doc/src/images/basicgraphicslayouts-example.png b/doc/src/images/basicgraphicslayouts-example.png new file mode 100644 index 0000000..5c8f4cb Binary files /dev/null and b/doc/src/images/basicgraphicslayouts-example.png differ diff --git a/doc/src/images/basiclayouts-example.png b/doc/src/images/basiclayouts-example.png new file mode 100644 index 0000000..f293423 Binary files /dev/null and b/doc/src/images/basiclayouts-example.png differ diff --git a/doc/src/images/basicsortfiltermodel-example.png b/doc/src/images/basicsortfiltermodel-example.png new file mode 100644 index 0000000..7f3bfdf Binary files /dev/null and b/doc/src/images/basicsortfiltermodel-example.png differ diff --git a/doc/src/images/bearings.png b/doc/src/images/bearings.png new file mode 100644 index 0000000..0010892 Binary files /dev/null and b/doc/src/images/bearings.png differ diff --git a/doc/src/images/blockingfortuneclient-example.png b/doc/src/images/blockingfortuneclient-example.png new file mode 100644 index 0000000..cdb7cac Binary files /dev/null and b/doc/src/images/blockingfortuneclient-example.png differ diff --git a/doc/src/images/books-demo.png b/doc/src/images/books-demo.png new file mode 100644 index 0000000..5bcc20b Binary files /dev/null and b/doc/src/images/books-demo.png differ diff --git a/doc/src/images/borderlayout-example.png b/doc/src/images/borderlayout-example.png new file mode 100644 index 0000000..e856e06 Binary files /dev/null and b/doc/src/images/borderlayout-example.png differ diff --git a/doc/src/images/boxes-demo.png b/doc/src/images/boxes-demo.png new file mode 100644 index 0000000..6ad253c Binary files /dev/null and b/doc/src/images/boxes-demo.png differ diff --git a/doc/src/images/broadcastreceiver-example.png b/doc/src/images/broadcastreceiver-example.png new file mode 100644 index 0000000..b837895 Binary files /dev/null and b/doc/src/images/broadcastreceiver-example.png differ diff --git a/doc/src/images/broadcastsender-example.png b/doc/src/images/broadcastsender-example.png new file mode 100644 index 0000000..bf7ccbe Binary files /dev/null and b/doc/src/images/broadcastsender-example.png differ diff --git a/doc/src/images/browser-demo.png b/doc/src/images/browser-demo.png new file mode 100644 index 0000000..466f218 Binary files /dev/null and b/doc/src/images/browser-demo.png differ diff --git a/doc/src/images/brush-outline.png b/doc/src/images/brush-outline.png new file mode 100644 index 0000000..f560c9f Binary files /dev/null and b/doc/src/images/brush-outline.png differ diff --git a/doc/src/images/brush-styles.png b/doc/src/images/brush-styles.png new file mode 100644 index 0000000..eecb006 Binary files /dev/null and b/doc/src/images/brush-styles.png differ diff --git a/doc/src/images/buttonbox-gnomelayout-horizontal.png b/doc/src/images/buttonbox-gnomelayout-horizontal.png new file mode 100644 index 0000000..b2f74bb Binary files /dev/null and b/doc/src/images/buttonbox-gnomelayout-horizontal.png differ diff --git a/doc/src/images/buttonbox-gnomelayout-vertical.png b/doc/src/images/buttonbox-gnomelayout-vertical.png new file mode 100644 index 0000000..e7843dc Binary files /dev/null and b/doc/src/images/buttonbox-gnomelayout-vertical.png differ diff --git a/doc/src/images/buttonbox-kdelayout-horizontal.png b/doc/src/images/buttonbox-kdelayout-horizontal.png new file mode 100644 index 0000000..5da11f4 Binary files /dev/null and b/doc/src/images/buttonbox-kdelayout-horizontal.png differ diff --git a/doc/src/images/buttonbox-kdelayout-vertical.png b/doc/src/images/buttonbox-kdelayout-vertical.png new file mode 100644 index 0000000..6f5dfc6 Binary files /dev/null and b/doc/src/images/buttonbox-kdelayout-vertical.png differ diff --git a/doc/src/images/buttonbox-mac-modeless-horizontal.png b/doc/src/images/buttonbox-mac-modeless-horizontal.png new file mode 100644 index 0000000..2e853d3 Binary files /dev/null and b/doc/src/images/buttonbox-mac-modeless-horizontal.png differ diff --git a/doc/src/images/buttonbox-mac-modeless-vertical.png b/doc/src/images/buttonbox-mac-modeless-vertical.png new file mode 100644 index 0000000..f59bd8d Binary files /dev/null and b/doc/src/images/buttonbox-mac-modeless-vertical.png differ diff --git a/doc/src/images/buttonbox-maclayout-horizontal.png b/doc/src/images/buttonbox-maclayout-horizontal.png new file mode 100644 index 0000000..89ae84d Binary files /dev/null and b/doc/src/images/buttonbox-maclayout-horizontal.png differ diff --git a/doc/src/images/buttonbox-maclayout-vertical.png b/doc/src/images/buttonbox-maclayout-vertical.png new file mode 100644 index 0000000..7287600 Binary files /dev/null and b/doc/src/images/buttonbox-maclayout-vertical.png differ diff --git a/doc/src/images/buttonbox-winlayout-horizontal.png b/doc/src/images/buttonbox-winlayout-horizontal.png new file mode 100644 index 0000000..dd4ce1c Binary files /dev/null and b/doc/src/images/buttonbox-winlayout-horizontal.png differ diff --git a/doc/src/images/buttonbox-winlayout-vertical.png b/doc/src/images/buttonbox-winlayout-vertical.png new file mode 100644 index 0000000..539de1a Binary files /dev/null and b/doc/src/images/buttonbox-winlayout-vertical.png differ diff --git a/doc/src/images/cachedtable-example.png b/doc/src/images/cachedtable-example.png new file mode 100644 index 0000000..db770df Binary files /dev/null and b/doc/src/images/cachedtable-example.png differ diff --git a/doc/src/images/calculator-example.png b/doc/src/images/calculator-example.png new file mode 100644 index 0000000..6f1158d Binary files /dev/null and b/doc/src/images/calculator-example.png differ diff --git a/doc/src/images/calculator-ugly.png b/doc/src/images/calculator-ugly.png new file mode 100644 index 0000000..cdfa902 Binary files /dev/null and b/doc/src/images/calculator-ugly.png differ diff --git a/doc/src/images/calculatorbuilder-example.png b/doc/src/images/calculatorbuilder-example.png new file mode 100644 index 0000000..561e500 Binary files /dev/null and b/doc/src/images/calculatorbuilder-example.png differ diff --git a/doc/src/images/calculatorform-example.png b/doc/src/images/calculatorform-example.png new file mode 100644 index 0000000..91432ac Binary files /dev/null and b/doc/src/images/calculatorform-example.png differ diff --git a/doc/src/images/calendar-example.png b/doc/src/images/calendar-example.png new file mode 100644 index 0000000..895ce76 Binary files /dev/null and b/doc/src/images/calendar-example.png differ diff --git a/doc/src/images/calendarwidgetexample.png b/doc/src/images/calendarwidgetexample.png new file mode 100644 index 0000000..464be90 Binary files /dev/null and b/doc/src/images/calendarwidgetexample.png differ diff --git a/doc/src/images/cannon-tutorial.png b/doc/src/images/cannon-tutorial.png new file mode 100644 index 0000000..7347153 Binary files /dev/null and b/doc/src/images/cannon-tutorial.png differ diff --git a/doc/src/images/capabilitiesexample.png b/doc/src/images/capabilitiesexample.png new file mode 100644 index 0000000..d760592 Binary files /dev/null and b/doc/src/images/capabilitiesexample.png differ diff --git a/doc/src/images/cde-calendarwidget.png b/doc/src/images/cde-calendarwidget.png new file mode 100644 index 0000000..9615eae Binary files /dev/null and b/doc/src/images/cde-calendarwidget.png differ diff --git a/doc/src/images/cde-checkbox.png b/doc/src/images/cde-checkbox.png new file mode 100644 index 0000000..b2528dc Binary files /dev/null and b/doc/src/images/cde-checkbox.png differ diff --git a/doc/src/images/cde-combobox.png b/doc/src/images/cde-combobox.png new file mode 100644 index 0000000..7458643 Binary files /dev/null and b/doc/src/images/cde-combobox.png differ diff --git a/doc/src/images/cde-dateedit.png b/doc/src/images/cde-dateedit.png new file mode 100644 index 0000000..ebb24d5 Binary files /dev/null and b/doc/src/images/cde-dateedit.png differ diff --git a/doc/src/images/cde-datetimeedit.png b/doc/src/images/cde-datetimeedit.png new file mode 100644 index 0000000..9ac659a Binary files /dev/null and b/doc/src/images/cde-datetimeedit.png differ diff --git a/doc/src/images/cde-dial.png b/doc/src/images/cde-dial.png new file mode 100644 index 0000000..956d19c Binary files /dev/null and b/doc/src/images/cde-dial.png differ diff --git a/doc/src/images/cde-doublespinbox.png b/doc/src/images/cde-doublespinbox.png new file mode 100644 index 0000000..30a9af6 Binary files /dev/null and b/doc/src/images/cde-doublespinbox.png differ diff --git a/doc/src/images/cde-fontcombobox.png b/doc/src/images/cde-fontcombobox.png new file mode 100644 index 0000000..043ca1d Binary files /dev/null and b/doc/src/images/cde-fontcombobox.png differ diff --git a/doc/src/images/cde-frame.png b/doc/src/images/cde-frame.png new file mode 100644 index 0000000..221576e Binary files /dev/null and b/doc/src/images/cde-frame.png differ diff --git a/doc/src/images/cde-groupbox.png b/doc/src/images/cde-groupbox.png new file mode 100644 index 0000000..8bad69b Binary files /dev/null and b/doc/src/images/cde-groupbox.png differ diff --git a/doc/src/images/cde-horizontalscrollbar.png b/doc/src/images/cde-horizontalscrollbar.png new file mode 100644 index 0000000..6e7cde8 Binary files /dev/null and b/doc/src/images/cde-horizontalscrollbar.png differ diff --git a/doc/src/images/cde-label.png b/doc/src/images/cde-label.png new file mode 100644 index 0000000..4e906ea Binary files /dev/null and b/doc/src/images/cde-label.png differ diff --git a/doc/src/images/cde-lcdnumber.png b/doc/src/images/cde-lcdnumber.png new file mode 100644 index 0000000..97324c1 Binary files /dev/null and b/doc/src/images/cde-lcdnumber.png differ diff --git a/doc/src/images/cde-lineedit.png b/doc/src/images/cde-lineedit.png new file mode 100644 index 0000000..6c1527b Binary files /dev/null and b/doc/src/images/cde-lineedit.png differ diff --git a/doc/src/images/cde-listview.png b/doc/src/images/cde-listview.png new file mode 100644 index 0000000..2e58140 Binary files /dev/null and b/doc/src/images/cde-listview.png differ diff --git a/doc/src/images/cde-progressbar.png b/doc/src/images/cde-progressbar.png new file mode 100644 index 0000000..41715de Binary files /dev/null and b/doc/src/images/cde-progressbar.png differ diff --git a/doc/src/images/cde-pushbutton.png b/doc/src/images/cde-pushbutton.png new file mode 100644 index 0000000..2d9bdd2 Binary files /dev/null and b/doc/src/images/cde-pushbutton.png differ diff --git a/doc/src/images/cde-radiobutton.png b/doc/src/images/cde-radiobutton.png new file mode 100644 index 0000000..e053665 Binary files /dev/null and b/doc/src/images/cde-radiobutton.png differ diff --git a/doc/src/images/cde-slider.png b/doc/src/images/cde-slider.png new file mode 100644 index 0000000..bd84371 Binary files /dev/null and b/doc/src/images/cde-slider.png differ diff --git a/doc/src/images/cde-spinbox.png b/doc/src/images/cde-spinbox.png new file mode 100644 index 0000000..5f53c8e Binary files /dev/null and b/doc/src/images/cde-spinbox.png differ diff --git a/doc/src/images/cde-tableview.png b/doc/src/images/cde-tableview.png new file mode 100644 index 0000000..7a99217 Binary files /dev/null and b/doc/src/images/cde-tableview.png differ diff --git a/doc/src/images/cde-tabwidget.png b/doc/src/images/cde-tabwidget.png new file mode 100644 index 0000000..8cf5473 Binary files /dev/null and b/doc/src/images/cde-tabwidget.png differ diff --git a/doc/src/images/cde-textedit.png b/doc/src/images/cde-textedit.png new file mode 100644 index 0000000..c65b8da Binary files /dev/null and b/doc/src/images/cde-textedit.png differ diff --git a/doc/src/images/cde-timeedit.png b/doc/src/images/cde-timeedit.png new file mode 100644 index 0000000..6a5a4b9 Binary files /dev/null and b/doc/src/images/cde-timeedit.png differ diff --git a/doc/src/images/cde-toolbox.png b/doc/src/images/cde-toolbox.png new file mode 100644 index 0000000..c0dd4e9 Binary files /dev/null and b/doc/src/images/cde-toolbox.png differ diff --git a/doc/src/images/cde-toolbutton.png b/doc/src/images/cde-toolbutton.png new file mode 100644 index 0000000..baff25c Binary files /dev/null and b/doc/src/images/cde-toolbutton.png differ diff --git a/doc/src/images/cde-treeview.png b/doc/src/images/cde-treeview.png new file mode 100644 index 0000000..df3184b Binary files /dev/null and b/doc/src/images/cde-treeview.png differ diff --git a/doc/src/images/charactermap-example.png b/doc/src/images/charactermap-example.png new file mode 100644 index 0000000..c1f25a5 Binary files /dev/null and b/doc/src/images/charactermap-example.png differ diff --git a/doc/src/images/chart-example.png b/doc/src/images/chart-example.png new file mode 100644 index 0000000..9823666 Binary files /dev/null and b/doc/src/images/chart-example.png differ diff --git a/doc/src/images/chip-demo.png b/doc/src/images/chip-demo.png new file mode 100644 index 0000000..8889424 Binary files /dev/null and b/doc/src/images/chip-demo.png differ diff --git a/doc/src/images/classwizard-flow.png b/doc/src/images/classwizard-flow.png new file mode 100644 index 0000000..ad9446c Binary files /dev/null and b/doc/src/images/classwizard-flow.png differ diff --git a/doc/src/images/classwizard.png b/doc/src/images/classwizard.png new file mode 100644 index 0000000..ea740bd Binary files /dev/null and b/doc/src/images/classwizard.png differ diff --git a/doc/src/images/cleanlooks-calendarwidget.png b/doc/src/images/cleanlooks-calendarwidget.png new file mode 100644 index 0000000..99c57b6 Binary files /dev/null and b/doc/src/images/cleanlooks-calendarwidget.png differ diff --git a/doc/src/images/cleanlooks-checkbox.png b/doc/src/images/cleanlooks-checkbox.png new file mode 100644 index 0000000..aaf2daa Binary files /dev/null and b/doc/src/images/cleanlooks-checkbox.png differ diff --git a/doc/src/images/cleanlooks-combobox.png b/doc/src/images/cleanlooks-combobox.png new file mode 100644 index 0000000..5fff4c8 Binary files /dev/null and b/doc/src/images/cleanlooks-combobox.png differ diff --git a/doc/src/images/cleanlooks-dateedit.png b/doc/src/images/cleanlooks-dateedit.png new file mode 100644 index 0000000..384136a Binary files /dev/null and b/doc/src/images/cleanlooks-dateedit.png differ diff --git a/doc/src/images/cleanlooks-datetimeedit.png b/doc/src/images/cleanlooks-datetimeedit.png new file mode 100644 index 0000000..7a62ceb Binary files /dev/null and b/doc/src/images/cleanlooks-datetimeedit.png differ diff --git a/doc/src/images/cleanlooks-dial.png b/doc/src/images/cleanlooks-dial.png new file mode 100644 index 0000000..259a088 Binary files /dev/null and b/doc/src/images/cleanlooks-dial.png differ diff --git a/doc/src/images/cleanlooks-dialogbuttonbox.png b/doc/src/images/cleanlooks-dialogbuttonbox.png new file mode 100644 index 0000000..907dfda Binary files /dev/null and b/doc/src/images/cleanlooks-dialogbuttonbox.png differ diff --git a/doc/src/images/cleanlooks-doublespinbox.png b/doc/src/images/cleanlooks-doublespinbox.png new file mode 100644 index 0000000..93b11f9 Binary files /dev/null and b/doc/src/images/cleanlooks-doublespinbox.png differ diff --git a/doc/src/images/cleanlooks-fontcombobox.png b/doc/src/images/cleanlooks-fontcombobox.png new file mode 100644 index 0000000..47a5907 Binary files /dev/null and b/doc/src/images/cleanlooks-fontcombobox.png differ diff --git a/doc/src/images/cleanlooks-frame.png b/doc/src/images/cleanlooks-frame.png new file mode 100644 index 0000000..2427b08 Binary files /dev/null and b/doc/src/images/cleanlooks-frame.png differ diff --git a/doc/src/images/cleanlooks-groupbox.png b/doc/src/images/cleanlooks-groupbox.png new file mode 100644 index 0000000..89c6eb2 Binary files /dev/null and b/doc/src/images/cleanlooks-groupbox.png differ diff --git a/doc/src/images/cleanlooks-horizontalscrollbar.png b/doc/src/images/cleanlooks-horizontalscrollbar.png new file mode 100644 index 0000000..ca1c806 Binary files /dev/null and b/doc/src/images/cleanlooks-horizontalscrollbar.png differ diff --git a/doc/src/images/cleanlooks-label.png b/doc/src/images/cleanlooks-label.png new file mode 100644 index 0000000..199758f Binary files /dev/null and b/doc/src/images/cleanlooks-label.png differ diff --git a/doc/src/images/cleanlooks-lcdnumber.png b/doc/src/images/cleanlooks-lcdnumber.png new file mode 100644 index 0000000..c6e3412 Binary files /dev/null and b/doc/src/images/cleanlooks-lcdnumber.png differ diff --git a/doc/src/images/cleanlooks-lineedit.png b/doc/src/images/cleanlooks-lineedit.png new file mode 100644 index 0000000..3e9f1a4 Binary files /dev/null and b/doc/src/images/cleanlooks-lineedit.png differ diff --git a/doc/src/images/cleanlooks-listview.png b/doc/src/images/cleanlooks-listview.png new file mode 100644 index 0000000..95f836c Binary files /dev/null and b/doc/src/images/cleanlooks-listview.png differ diff --git a/doc/src/images/cleanlooks-progressbar.png b/doc/src/images/cleanlooks-progressbar.png new file mode 100644 index 0000000..53fc6c1 Binary files /dev/null and b/doc/src/images/cleanlooks-progressbar.png differ diff --git a/doc/src/images/cleanlooks-pushbutton-menu.png b/doc/src/images/cleanlooks-pushbutton-menu.png new file mode 100644 index 0000000..0d5cb59 Binary files /dev/null and b/doc/src/images/cleanlooks-pushbutton-menu.png differ diff --git a/doc/src/images/cleanlooks-pushbutton.png b/doc/src/images/cleanlooks-pushbutton.png new file mode 100644 index 0000000..7b3b335 Binary files /dev/null and b/doc/src/images/cleanlooks-pushbutton.png differ diff --git a/doc/src/images/cleanlooks-radiobutton.png b/doc/src/images/cleanlooks-radiobutton.png new file mode 100644 index 0000000..4e07768 Binary files /dev/null and b/doc/src/images/cleanlooks-radiobutton.png differ diff --git a/doc/src/images/cleanlooks-slider.png b/doc/src/images/cleanlooks-slider.png new file mode 100644 index 0000000..8dfaa01 Binary files /dev/null and b/doc/src/images/cleanlooks-slider.png differ diff --git a/doc/src/images/cleanlooks-spinbox.png b/doc/src/images/cleanlooks-spinbox.png new file mode 100644 index 0000000..ad5b5a0 Binary files /dev/null and b/doc/src/images/cleanlooks-spinbox.png differ diff --git a/doc/src/images/cleanlooks-tableview.png b/doc/src/images/cleanlooks-tableview.png new file mode 100644 index 0000000..d89fecc Binary files /dev/null and b/doc/src/images/cleanlooks-tableview.png differ diff --git a/doc/src/images/cleanlooks-tabwidget.png b/doc/src/images/cleanlooks-tabwidget.png new file mode 100644 index 0000000..bcff296 Binary files /dev/null and b/doc/src/images/cleanlooks-tabwidget.png differ diff --git a/doc/src/images/cleanlooks-textedit.png b/doc/src/images/cleanlooks-textedit.png new file mode 100644 index 0000000..0c825a1 Binary files /dev/null and b/doc/src/images/cleanlooks-textedit.png differ diff --git a/doc/src/images/cleanlooks-timeedit.png b/doc/src/images/cleanlooks-timeedit.png new file mode 100644 index 0000000..00420a2 Binary files /dev/null and b/doc/src/images/cleanlooks-timeedit.png differ diff --git a/doc/src/images/cleanlooks-toolbox.png b/doc/src/images/cleanlooks-toolbox.png new file mode 100644 index 0000000..63366e5 Binary files /dev/null and b/doc/src/images/cleanlooks-toolbox.png differ diff --git a/doc/src/images/cleanlooks-toolbutton.png b/doc/src/images/cleanlooks-toolbutton.png new file mode 100644 index 0000000..bcf86ea Binary files /dev/null and b/doc/src/images/cleanlooks-toolbutton.png differ diff --git a/doc/src/images/cleanlooks-treeview.png b/doc/src/images/cleanlooks-treeview.png new file mode 100644 index 0000000..5bc4a06 Binary files /dev/null and b/doc/src/images/cleanlooks-treeview.png differ diff --git a/doc/src/images/codecs-example.png b/doc/src/images/codecs-example.png new file mode 100644 index 0000000..8e7ae95 Binary files /dev/null and b/doc/src/images/codecs-example.png differ diff --git a/doc/src/images/codeeditor-example.png b/doc/src/images/codeeditor-example.png new file mode 100644 index 0000000..b176406 Binary files /dev/null and b/doc/src/images/codeeditor-example.png differ diff --git a/doc/src/images/collidingmice-example.png b/doc/src/images/collidingmice-example.png new file mode 100644 index 0000000..41561de Binary files /dev/null and b/doc/src/images/collidingmice-example.png differ diff --git a/doc/src/images/coloreditorfactoryimage.png b/doc/src/images/coloreditorfactoryimage.png new file mode 100644 index 0000000..cd839a6 Binary files /dev/null and b/doc/src/images/coloreditorfactoryimage.png differ diff --git a/doc/src/images/combo-widget-mapper.png b/doc/src/images/combo-widget-mapper.png new file mode 100644 index 0000000..910d6ed Binary files /dev/null and b/doc/src/images/combo-widget-mapper.png differ diff --git a/doc/src/images/completer-example-country.png b/doc/src/images/completer-example-country.png new file mode 100644 index 0000000..fa7c8a9 Binary files /dev/null and b/doc/src/images/completer-example-country.png differ diff --git a/doc/src/images/completer-example-dirmodel.png b/doc/src/images/completer-example-dirmodel.png new file mode 100644 index 0000000..94b75b0 Binary files /dev/null and b/doc/src/images/completer-example-dirmodel.png differ diff --git a/doc/src/images/completer-example-qdirmodel.png b/doc/src/images/completer-example-qdirmodel.png new file mode 100644 index 0000000..904c198 Binary files /dev/null and b/doc/src/images/completer-example-qdirmodel.png differ diff --git a/doc/src/images/completer-example-word.png b/doc/src/images/completer-example-word.png new file mode 100644 index 0000000..aa3fb9c Binary files /dev/null and b/doc/src/images/completer-example-word.png differ diff --git a/doc/src/images/completer-example.png b/doc/src/images/completer-example.png new file mode 100644 index 0000000..dcaa253 Binary files /dev/null and b/doc/src/images/completer-example.png differ diff --git a/doc/src/images/complexwizard-detailspage.png b/doc/src/images/complexwizard-detailspage.png new file mode 100644 index 0000000..58eeae4 Binary files /dev/null and b/doc/src/images/complexwizard-detailspage.png differ diff --git a/doc/src/images/complexwizard-evaluatepage.png b/doc/src/images/complexwizard-evaluatepage.png new file mode 100644 index 0000000..23f200e Binary files /dev/null and b/doc/src/images/complexwizard-evaluatepage.png differ diff --git a/doc/src/images/complexwizard-finishpage.png b/doc/src/images/complexwizard-finishpage.png new file mode 100644 index 0000000..60703a0 Binary files /dev/null and b/doc/src/images/complexwizard-finishpage.png differ diff --git a/doc/src/images/complexwizard-flow.png b/doc/src/images/complexwizard-flow.png new file mode 100644 index 0000000..c74b0ee Binary files /dev/null and b/doc/src/images/complexwizard-flow.png differ diff --git a/doc/src/images/complexwizard-registerpage.png b/doc/src/images/complexwizard-registerpage.png new file mode 100644 index 0000000..18a359c Binary files /dev/null and b/doc/src/images/complexwizard-registerpage.png differ diff --git a/doc/src/images/complexwizard-titlepage.png b/doc/src/images/complexwizard-titlepage.png new file mode 100644 index 0000000..29acbbc Binary files /dev/null and b/doc/src/images/complexwizard-titlepage.png differ diff --git a/doc/src/images/complexwizard.png b/doc/src/images/complexwizard.png new file mode 100644 index 0000000..d08942e Binary files /dev/null and b/doc/src/images/complexwizard.png differ diff --git a/doc/src/images/composition-demo.png b/doc/src/images/composition-demo.png new file mode 100644 index 0000000..942bc58 Binary files /dev/null and b/doc/src/images/composition-demo.png differ diff --git a/doc/src/images/concentriccircles-example.png b/doc/src/images/concentriccircles-example.png new file mode 100644 index 0000000..fd308b5 Binary files /dev/null and b/doc/src/images/concentriccircles-example.png differ diff --git a/doc/src/images/conceptaudio.png b/doc/src/images/conceptaudio.png new file mode 100644 index 0000000..b4eabad Binary files /dev/null and b/doc/src/images/conceptaudio.png differ diff --git a/doc/src/images/conceptprocessor.png b/doc/src/images/conceptprocessor.png new file mode 100644 index 0000000..2b76df3 --- /dev/null +++ b/doc/src/images/conceptprocessor.png @@ -0,0 +1 @@ +This is a temporary placeholder. diff --git a/doc/src/images/conceptvideo.png b/doc/src/images/conceptvideo.png new file mode 100644 index 0000000..1777b21 Binary files /dev/null and b/doc/src/images/conceptvideo.png differ diff --git a/doc/src/images/configdialog-example.png b/doc/src/images/configdialog-example.png new file mode 100644 index 0000000..20d917b Binary files /dev/null and b/doc/src/images/configdialog-example.png differ diff --git a/doc/src/images/conicalGradient.png b/doc/src/images/conicalGradient.png new file mode 100644 index 0000000..013f6ef Binary files /dev/null and b/doc/src/images/conicalGradient.png differ diff --git a/doc/src/images/containerextension-example.png b/doc/src/images/containerextension-example.png new file mode 100644 index 0000000..2427f91 Binary files /dev/null and b/doc/src/images/containerextension-example.png differ diff --git a/doc/src/images/context2d-example-smileysmile.png b/doc/src/images/context2d-example-smileysmile.png new file mode 100644 index 0000000..369f32e Binary files /dev/null and b/doc/src/images/context2d-example-smileysmile.png differ diff --git a/doc/src/images/context2d-example.png b/doc/src/images/context2d-example.png new file mode 100644 index 0000000..0c12754 Binary files /dev/null and b/doc/src/images/context2d-example.png differ diff --git a/doc/src/images/coordinatesystem-analogclock.png b/doc/src/images/coordinatesystem-analogclock.png new file mode 100644 index 0000000..16e3091 Binary files /dev/null and b/doc/src/images/coordinatesystem-analogclock.png differ diff --git a/doc/src/images/coordinatesystem-line-antialias.png b/doc/src/images/coordinatesystem-line-antialias.png new file mode 100644 index 0000000..90dfa87 Binary files /dev/null and b/doc/src/images/coordinatesystem-line-antialias.png differ diff --git a/doc/src/images/coordinatesystem-line-raster.png b/doc/src/images/coordinatesystem-line-raster.png new file mode 100644 index 0000000..65201bd Binary files /dev/null and b/doc/src/images/coordinatesystem-line-raster.png differ diff --git a/doc/src/images/coordinatesystem-line.png b/doc/src/images/coordinatesystem-line.png new file mode 100644 index 0000000..fbf6873 Binary files /dev/null and b/doc/src/images/coordinatesystem-line.png differ diff --git a/doc/src/images/coordinatesystem-rect-antialias.png b/doc/src/images/coordinatesystem-rect-antialias.png new file mode 100644 index 0000000..162e1df Binary files /dev/null and b/doc/src/images/coordinatesystem-rect-antialias.png differ diff --git a/doc/src/images/coordinatesystem-rect-raster.png b/doc/src/images/coordinatesystem-rect-raster.png new file mode 100644 index 0000000..be3690d Binary files /dev/null and b/doc/src/images/coordinatesystem-rect-raster.png differ diff --git a/doc/src/images/coordinatesystem-rect.png b/doc/src/images/coordinatesystem-rect.png new file mode 100644 index 0000000..76c06be Binary files /dev/null and b/doc/src/images/coordinatesystem-rect.png differ diff --git a/doc/src/images/coordinatesystem-transformations.png b/doc/src/images/coordinatesystem-transformations.png new file mode 100644 index 0000000..2736213 Binary files /dev/null and b/doc/src/images/coordinatesystem-transformations.png differ diff --git a/doc/src/images/coordsys.png b/doc/src/images/coordsys.png new file mode 100644 index 0000000..181f2f6 Binary files /dev/null and b/doc/src/images/coordsys.png differ diff --git a/doc/src/images/cursor-arrow.png b/doc/src/images/cursor-arrow.png new file mode 100644 index 0000000..a69ef4e Binary files /dev/null and b/doc/src/images/cursor-arrow.png differ diff --git a/doc/src/images/cursor-busy.png b/doc/src/images/cursor-busy.png new file mode 100644 index 0000000..53717e4 Binary files /dev/null and b/doc/src/images/cursor-busy.png differ diff --git a/doc/src/images/cursor-closedhand.png b/doc/src/images/cursor-closedhand.png new file mode 100644 index 0000000..b78dd1d Binary files /dev/null and b/doc/src/images/cursor-closedhand.png differ diff --git a/doc/src/images/cursor-cross.png b/doc/src/images/cursor-cross.png new file mode 100644 index 0000000..fe38e74 Binary files /dev/null and b/doc/src/images/cursor-cross.png differ diff --git a/doc/src/images/cursor-forbidden.png b/doc/src/images/cursor-forbidden.png new file mode 100644 index 0000000..2b08c4e Binary files /dev/null and b/doc/src/images/cursor-forbidden.png differ diff --git a/doc/src/images/cursor-hand.png b/doc/src/images/cursor-hand.png new file mode 100644 index 0000000..d2004ae Binary files /dev/null and b/doc/src/images/cursor-hand.png differ diff --git a/doc/src/images/cursor-hsplit.png b/doc/src/images/cursor-hsplit.png new file mode 100644 index 0000000..1beda25 Binary files /dev/null and b/doc/src/images/cursor-hsplit.png differ diff --git a/doc/src/images/cursor-ibeam.png b/doc/src/images/cursor-ibeam.png new file mode 100644 index 0000000..097fc5f Binary files /dev/null and b/doc/src/images/cursor-ibeam.png differ diff --git a/doc/src/images/cursor-openhand.png b/doc/src/images/cursor-openhand.png new file mode 100644 index 0000000..9181c85 Binary files /dev/null and b/doc/src/images/cursor-openhand.png differ diff --git a/doc/src/images/cursor-sizeall.png b/doc/src/images/cursor-sizeall.png new file mode 100644 index 0000000..69f13eb Binary files /dev/null and b/doc/src/images/cursor-sizeall.png differ diff --git a/doc/src/images/cursor-sizeb.png b/doc/src/images/cursor-sizeb.png new file mode 100644 index 0000000..f37d7b9 Binary files /dev/null and b/doc/src/images/cursor-sizeb.png differ diff --git a/doc/src/images/cursor-sizef.png b/doc/src/images/cursor-sizef.png new file mode 100644 index 0000000..3b127a0 Binary files /dev/null and b/doc/src/images/cursor-sizef.png differ diff --git a/doc/src/images/cursor-sizeh.png b/doc/src/images/cursor-sizeh.png new file mode 100644 index 0000000..a9f40cb Binary files /dev/null and b/doc/src/images/cursor-sizeh.png differ diff --git a/doc/src/images/cursor-sizev.png b/doc/src/images/cursor-sizev.png new file mode 100644 index 0000000..1edbab2 Binary files /dev/null and b/doc/src/images/cursor-sizev.png differ diff --git a/doc/src/images/cursor-uparrow.png b/doc/src/images/cursor-uparrow.png new file mode 100644 index 0000000..d3e70ef Binary files /dev/null and b/doc/src/images/cursor-uparrow.png differ diff --git a/doc/src/images/cursor-vsplit.png b/doc/src/images/cursor-vsplit.png new file mode 100644 index 0000000..a5667e3 Binary files /dev/null and b/doc/src/images/cursor-vsplit.png differ diff --git a/doc/src/images/cursor-wait.png b/doc/src/images/cursor-wait.png new file mode 100644 index 0000000..69056c4 Binary files /dev/null and b/doc/src/images/cursor-wait.png differ diff --git a/doc/src/images/cursor-whatsthis.png b/doc/src/images/cursor-whatsthis.png new file mode 100644 index 0000000..b47601c Binary files /dev/null and b/doc/src/images/cursor-whatsthis.png differ diff --git a/doc/src/images/customcompleter-example.png b/doc/src/images/customcompleter-example.png new file mode 100644 index 0000000..a525208 Binary files /dev/null and b/doc/src/images/customcompleter-example.png differ diff --git a/doc/src/images/customcompleter-insertcompletion.png b/doc/src/images/customcompleter-insertcompletion.png new file mode 100644 index 0000000..0bb2c25 Binary files /dev/null and b/doc/src/images/customcompleter-insertcompletion.png differ diff --git a/doc/src/images/customsortfiltermodel-example.png b/doc/src/images/customsortfiltermodel-example.png new file mode 100644 index 0000000..d7ee8bd Binary files /dev/null and b/doc/src/images/customsortfiltermodel-example.png differ diff --git a/doc/src/images/customtypesending-example.png b/doc/src/images/customtypesending-example.png new file mode 100644 index 0000000..fbc3953 Binary files /dev/null and b/doc/src/images/customtypesending-example.png differ diff --git a/doc/src/images/customwidgetplugin-example.png b/doc/src/images/customwidgetplugin-example.png new file mode 100644 index 0000000..87fde81 Binary files /dev/null and b/doc/src/images/customwidgetplugin-example.png differ diff --git a/doc/src/images/datetimewidgets.png b/doc/src/images/datetimewidgets.png new file mode 100644 index 0000000..c2d498c Binary files /dev/null and b/doc/src/images/datetimewidgets.png differ diff --git a/doc/src/images/dbus-chat-example.png b/doc/src/images/dbus-chat-example.png new file mode 100644 index 0000000..ad66d08 Binary files /dev/null and b/doc/src/images/dbus-chat-example.png differ diff --git a/doc/src/images/defaultprototypes-example.png b/doc/src/images/defaultprototypes-example.png new file mode 100644 index 0000000..72fe3c4 Binary files /dev/null and b/doc/src/images/defaultprototypes-example.png differ diff --git a/doc/src/images/deform-demo.png b/doc/src/images/deform-demo.png new file mode 100644 index 0000000..2f037f0 Binary files /dev/null and b/doc/src/images/deform-demo.png differ diff --git a/doc/src/images/delayedecoding-example.png b/doc/src/images/delayedecoding-example.png new file mode 100644 index 0000000..1cafba6 Binary files /dev/null and b/doc/src/images/delayedecoding-example.png differ diff --git a/doc/src/images/deployment-mac-application.png b/doc/src/images/deployment-mac-application.png new file mode 100644 index 0000000..99ad23f Binary files /dev/null and b/doc/src/images/deployment-mac-application.png differ diff --git a/doc/src/images/deployment-mac-bundlestructure.png b/doc/src/images/deployment-mac-bundlestructure.png new file mode 100644 index 0000000..db7a298 Binary files /dev/null and b/doc/src/images/deployment-mac-bundlestructure.png differ diff --git a/doc/src/images/deployment-windows-depends.png b/doc/src/images/deployment-windows-depends.png new file mode 100644 index 0000000..56c8439 Binary files /dev/null and b/doc/src/images/deployment-windows-depends.png differ diff --git a/doc/src/images/designer-action-editor.png b/doc/src/images/designer-action-editor.png new file mode 100644 index 0000000..7d17573 Binary files /dev/null and b/doc/src/images/designer-action-editor.png differ diff --git a/doc/src/images/designer-add-custom-toolbar.png b/doc/src/images/designer-add-custom-toolbar.png new file mode 100644 index 0000000..fe16586 Binary files /dev/null and b/doc/src/images/designer-add-custom-toolbar.png differ diff --git a/doc/src/images/designer-add-files-button.png b/doc/src/images/designer-add-files-button.png new file mode 100644 index 0000000..45ff4a0 Binary files /dev/null and b/doc/src/images/designer-add-files-button.png differ diff --git a/doc/src/images/designer-add-resource-entry-button.png b/doc/src/images/designer-add-resource-entry-button.png new file mode 100644 index 0000000..e29fcf8 Binary files /dev/null and b/doc/src/images/designer-add-resource-entry-button.png differ diff --git a/doc/src/images/designer-adding-dockwidget.png b/doc/src/images/designer-adding-dockwidget.png new file mode 100644 index 0000000..87b0fb8 Binary files /dev/null and b/doc/src/images/designer-adding-dockwidget.png differ diff --git a/doc/src/images/designer-adding-dynamic-property.png b/doc/src/images/designer-adding-dynamic-property.png new file mode 100644 index 0000000..a92320e Binary files /dev/null and b/doc/src/images/designer-adding-dynamic-property.png differ diff --git a/doc/src/images/designer-adding-menu-action.png b/doc/src/images/designer-adding-menu-action.png new file mode 100644 index 0000000..cf2a9c9 Binary files /dev/null and b/doc/src/images/designer-adding-menu-action.png differ diff --git a/doc/src/images/designer-adding-toolbar-action.png b/doc/src/images/designer-adding-toolbar-action.png new file mode 100644 index 0000000..e2201cb Binary files /dev/null and b/doc/src/images/designer-adding-toolbar-action.png differ diff --git a/doc/src/images/designer-buddy-making.png b/doc/src/images/designer-buddy-making.png new file mode 100644 index 0000000..3d8e8a1 Binary files /dev/null and b/doc/src/images/designer-buddy-making.png differ diff --git a/doc/src/images/designer-buddy-mode.png b/doc/src/images/designer-buddy-mode.png new file mode 100644 index 0000000..48197f6 Binary files /dev/null and b/doc/src/images/designer-buddy-mode.png differ diff --git a/doc/src/images/designer-buddy-tool.png b/doc/src/images/designer-buddy-tool.png new file mode 100644 index 0000000..2a42870 Binary files /dev/null and b/doc/src/images/designer-buddy-tool.png differ diff --git a/doc/src/images/designer-choosing-form.png b/doc/src/images/designer-choosing-form.png new file mode 100644 index 0000000..fa6e470 Binary files /dev/null and b/doc/src/images/designer-choosing-form.png differ diff --git a/doc/src/images/designer-code-viewer.png b/doc/src/images/designer-code-viewer.png new file mode 100644 index 0000000..c9d8528 Binary files /dev/null and b/doc/src/images/designer-code-viewer.png differ diff --git a/doc/src/images/designer-connection-dialog.png b/doc/src/images/designer-connection-dialog.png new file mode 100644 index 0000000..28dfeae Binary files /dev/null and b/doc/src/images/designer-connection-dialog.png differ diff --git a/doc/src/images/designer-connection-editing.png b/doc/src/images/designer-connection-editing.png new file mode 100644 index 0000000..90b6a3a Binary files /dev/null and b/doc/src/images/designer-connection-editing.png differ diff --git a/doc/src/images/designer-connection-editor.png b/doc/src/images/designer-connection-editor.png new file mode 100644 index 0000000..fd4d17d Binary files /dev/null and b/doc/src/images/designer-connection-editor.png differ diff --git a/doc/src/images/designer-connection-highlight.png b/doc/src/images/designer-connection-highlight.png new file mode 100644 index 0000000..089d1e4 Binary files /dev/null and b/doc/src/images/designer-connection-highlight.png differ diff --git a/doc/src/images/designer-connection-making.png b/doc/src/images/designer-connection-making.png new file mode 100644 index 0000000..a7ce33f Binary files /dev/null and b/doc/src/images/designer-connection-making.png differ diff --git a/doc/src/images/designer-connection-mode.png b/doc/src/images/designer-connection-mode.png new file mode 100644 index 0000000..8b98f9f Binary files /dev/null and b/doc/src/images/designer-connection-mode.png differ diff --git a/doc/src/images/designer-connection-to-form.png b/doc/src/images/designer-connection-to-form.png new file mode 100644 index 0000000..320f70f Binary files /dev/null and b/doc/src/images/designer-connection-to-form.png differ diff --git a/doc/src/images/designer-connection-tool.png b/doc/src/images/designer-connection-tool.png new file mode 100644 index 0000000..71c9b07 Binary files /dev/null and b/doc/src/images/designer-connection-tool.png differ diff --git a/doc/src/images/designer-containers-dockwidget.png b/doc/src/images/designer-containers-dockwidget.png new file mode 100644 index 0000000..f4dcc0b Binary files /dev/null and b/doc/src/images/designer-containers-dockwidget.png differ diff --git a/doc/src/images/designer-containers-frame.png b/doc/src/images/designer-containers-frame.png new file mode 100644 index 0000000..d16823a Binary files /dev/null and b/doc/src/images/designer-containers-frame.png differ diff --git a/doc/src/images/designer-containers-groupbox.png b/doc/src/images/designer-containers-groupbox.png new file mode 100644 index 0000000..d347e2f Binary files /dev/null and b/doc/src/images/designer-containers-groupbox.png differ diff --git a/doc/src/images/designer-containers-stackedwidget.png b/doc/src/images/designer-containers-stackedwidget.png new file mode 100644 index 0000000..3239e52 Binary files /dev/null and b/doc/src/images/designer-containers-stackedwidget.png differ diff --git a/doc/src/images/designer-containers-tabwidget.png b/doc/src/images/designer-containers-tabwidget.png new file mode 100644 index 0000000..dab3dfd Binary files /dev/null and b/doc/src/images/designer-containers-tabwidget.png differ diff --git a/doc/src/images/designer-containers-toolbox.png b/doc/src/images/designer-containers-toolbox.png new file mode 100644 index 0000000..e51fad6 Binary files /dev/null and b/doc/src/images/designer-containers-toolbox.png differ diff --git a/doc/src/images/designer-creating-dynamic-property.png b/doc/src/images/designer-creating-dynamic-property.png new file mode 100644 index 0000000..0d4f838 Binary files /dev/null and b/doc/src/images/designer-creating-dynamic-property.png differ diff --git a/doc/src/images/designer-creating-menu-entry1.png b/doc/src/images/designer-creating-menu-entry1.png new file mode 100644 index 0000000..1fcac22 Binary files /dev/null and b/doc/src/images/designer-creating-menu-entry1.png differ diff --git a/doc/src/images/designer-creating-menu-entry2.png b/doc/src/images/designer-creating-menu-entry2.png new file mode 100644 index 0000000..e7a537c Binary files /dev/null and b/doc/src/images/designer-creating-menu-entry2.png differ diff --git a/doc/src/images/designer-creating-menu-entry3.png b/doc/src/images/designer-creating-menu-entry3.png new file mode 100644 index 0000000..f50a448 Binary files /dev/null and b/doc/src/images/designer-creating-menu-entry3.png differ diff --git a/doc/src/images/designer-creating-menu-entry4.png b/doc/src/images/designer-creating-menu-entry4.png new file mode 100644 index 0000000..aea6639 Binary files /dev/null and b/doc/src/images/designer-creating-menu-entry4.png differ diff --git a/doc/src/images/designer-creating-menu.png b/doc/src/images/designer-creating-menu.png new file mode 100644 index 0000000..5268aac Binary files /dev/null and b/doc/src/images/designer-creating-menu.png differ diff --git a/doc/src/images/designer-creating-menu1.png b/doc/src/images/designer-creating-menu1.png new file mode 100644 index 0000000..ee2732a Binary files /dev/null and b/doc/src/images/designer-creating-menu1.png differ diff --git a/doc/src/images/designer-creating-menu2.png b/doc/src/images/designer-creating-menu2.png new file mode 100644 index 0000000..95808d5 Binary files /dev/null and b/doc/src/images/designer-creating-menu2.png differ diff --git a/doc/src/images/designer-creating-menu3.png b/doc/src/images/designer-creating-menu3.png new file mode 100644 index 0000000..b9d80c0 Binary files /dev/null and b/doc/src/images/designer-creating-menu3.png differ diff --git a/doc/src/images/designer-creating-menu4.png b/doc/src/images/designer-creating-menu4.png new file mode 100644 index 0000000..e05c931 Binary files /dev/null and b/doc/src/images/designer-creating-menu4.png differ diff --git a/doc/src/images/designer-creating-menubar.png b/doc/src/images/designer-creating-menubar.png new file mode 100644 index 0000000..87606f7 Binary files /dev/null and b/doc/src/images/designer-creating-menubar.png differ diff --git a/doc/src/images/designer-custom-widget-box.png b/doc/src/images/designer-custom-widget-box.png new file mode 100644 index 0000000..f3b9c1a Binary files /dev/null and b/doc/src/images/designer-custom-widget-box.png differ diff --git a/doc/src/images/designer-customize-toolbar.png b/doc/src/images/designer-customize-toolbar.png new file mode 100644 index 0000000..3fad021 Binary files /dev/null and b/doc/src/images/designer-customize-toolbar.png differ diff --git a/doc/src/images/designer-dialog-final.png b/doc/src/images/designer-dialog-final.png new file mode 100644 index 0000000..0a75670 Binary files /dev/null and b/doc/src/images/designer-dialog-final.png differ diff --git a/doc/src/images/designer-dialog-initial.png b/doc/src/images/designer-dialog-initial.png new file mode 100644 index 0000000..a2ebbf0 Binary files /dev/null and b/doc/src/images/designer-dialog-initial.png differ diff --git a/doc/src/images/designer-dialog-layout.png b/doc/src/images/designer-dialog-layout.png new file mode 100644 index 0000000..bae945d Binary files /dev/null and b/doc/src/images/designer-dialog-layout.png differ diff --git a/doc/src/images/designer-dialog-preview.png b/doc/src/images/designer-dialog-preview.png new file mode 100644 index 0000000..1059aea Binary files /dev/null and b/doc/src/images/designer-dialog-preview.png differ diff --git a/doc/src/images/designer-disambiguation.png b/doc/src/images/designer-disambiguation.png new file mode 100644 index 0000000..364e70d Binary files /dev/null and b/doc/src/images/designer-disambiguation.png differ diff --git a/doc/src/images/designer-dragging-onto-form.png b/doc/src/images/designer-dragging-onto-form.png new file mode 100644 index 0000000..07b4393 Binary files /dev/null and b/doc/src/images/designer-dragging-onto-form.png differ diff --git a/doc/src/images/designer-edit-resource.png b/doc/src/images/designer-edit-resource.png new file mode 100644 index 0000000..390087c Binary files /dev/null and b/doc/src/images/designer-edit-resource.png differ diff --git a/doc/src/images/designer-edit-resources-button.png b/doc/src/images/designer-edit-resources-button.png new file mode 100644 index 0000000..1697836 Binary files /dev/null and b/doc/src/images/designer-edit-resources-button.png differ diff --git a/doc/src/images/designer-editing-mode.png b/doc/src/images/designer-editing-mode.png new file mode 100644 index 0000000..cd1c802 Binary files /dev/null and b/doc/src/images/designer-editing-mode.png differ diff --git a/doc/src/images/designer-embedded-preview.png b/doc/src/images/designer-embedded-preview.png new file mode 100644 index 0000000..afa6faf Binary files /dev/null and b/doc/src/images/designer-embedded-preview.png differ diff --git a/doc/src/images/designer-english-dialog.png b/doc/src/images/designer-english-dialog.png new file mode 100644 index 0000000..591d971 Binary files /dev/null and b/doc/src/images/designer-english-dialog.png differ diff --git a/doc/src/images/designer-examples.png b/doc/src/images/designer-examples.png new file mode 100644 index 0000000..36e54f9 Binary files /dev/null and b/doc/src/images/designer-examples.png differ diff --git a/doc/src/images/designer-file-menu.png b/doc/src/images/designer-file-menu.png new file mode 100644 index 0000000..ae65f04 Binary files /dev/null and b/doc/src/images/designer-file-menu.png differ diff --git a/doc/src/images/designer-find-icon.png b/doc/src/images/designer-find-icon.png new file mode 100644 index 0000000..aa84bad Binary files /dev/null and b/doc/src/images/designer-find-icon.png differ diff --git a/doc/src/images/designer-form-layout-cleanlooks.png b/doc/src/images/designer-form-layout-cleanlooks.png new file mode 100644 index 0000000..13d5674 Binary files /dev/null and b/doc/src/images/designer-form-layout-cleanlooks.png differ diff --git a/doc/src/images/designer-form-layout-macintosh.png b/doc/src/images/designer-form-layout-macintosh.png new file mode 100644 index 0000000..ead3069 Binary files /dev/null and b/doc/src/images/designer-form-layout-macintosh.png differ diff --git a/doc/src/images/designer-form-layout-windowsXP.png b/doc/src/images/designer-form-layout-windowsXP.png new file mode 100644 index 0000000..8389986 Binary files /dev/null and b/doc/src/images/designer-form-layout-windowsXP.png differ diff --git a/doc/src/images/designer-form-layout.png b/doc/src/images/designer-form-layout.png new file mode 100644 index 0000000..3fb5747 Binary files /dev/null and b/doc/src/images/designer-form-layout.png differ diff --git a/doc/src/images/designer-form-layoutfunction.png b/doc/src/images/designer-form-layoutfunction.png new file mode 100644 index 0000000..0c25605 Binary files /dev/null and b/doc/src/images/designer-form-layoutfunction.png differ diff --git a/doc/src/images/designer-form-settings.png b/doc/src/images/designer-form-settings.png new file mode 100644 index 0000000..522a978 Binary files /dev/null and b/doc/src/images/designer-form-settings.png differ diff --git a/doc/src/images/designer-form-viewcode.png b/doc/src/images/designer-form-viewcode.png new file mode 100644 index 0000000..d79fedd Binary files /dev/null and b/doc/src/images/designer-form-viewcode.png differ diff --git a/doc/src/images/designer-french-dialog.png b/doc/src/images/designer-french-dialog.png new file mode 100644 index 0000000..f76a6e9 Binary files /dev/null and b/doc/src/images/designer-french-dialog.png differ diff --git a/doc/src/images/designer-getting-started.png b/doc/src/images/designer-getting-started.png new file mode 100644 index 0000000..7daea6c Binary files /dev/null and b/doc/src/images/designer-getting-started.png differ diff --git a/doc/src/images/designer-layout-inserting.png b/doc/src/images/designer-layout-inserting.png new file mode 100644 index 0000000..2c3a8ce Binary files /dev/null and b/doc/src/images/designer-layout-inserting.png differ diff --git a/doc/src/images/designer-main-window.png b/doc/src/images/designer-main-window.png new file mode 100644 index 0000000..99a6592 Binary files /dev/null and b/doc/src/images/designer-main-window.png differ diff --git a/doc/src/images/designer-making-connection.png b/doc/src/images/designer-making-connection.png new file mode 100644 index 0000000..b311536 Binary files /dev/null and b/doc/src/images/designer-making-connection.png differ diff --git a/doc/src/images/designer-manual-containerextension.png b/doc/src/images/designer-manual-containerextension.png new file mode 100644 index 0000000..1a82251 Binary files /dev/null and b/doc/src/images/designer-manual-containerextension.png differ diff --git a/doc/src/images/designer-manual-membersheetextension.png b/doc/src/images/designer-manual-membersheetextension.png new file mode 100644 index 0000000..7634d63 Binary files /dev/null and b/doc/src/images/designer-manual-membersheetextension.png differ diff --git a/doc/src/images/designer-manual-propertysheetextension.png b/doc/src/images/designer-manual-propertysheetextension.png new file mode 100644 index 0000000..a8d2d42 Binary files /dev/null and b/doc/src/images/designer-manual-propertysheetextension.png differ diff --git a/doc/src/images/designer-manual-taskmenuextension.png b/doc/src/images/designer-manual-taskmenuextension.png new file mode 100644 index 0000000..cf949bc Binary files /dev/null and b/doc/src/images/designer-manual-taskmenuextension.png differ diff --git a/doc/src/images/designer-multiple-screenshot.png b/doc/src/images/designer-multiple-screenshot.png new file mode 100644 index 0000000..1531903 Binary files /dev/null and b/doc/src/images/designer-multiple-screenshot.png differ diff --git a/doc/src/images/designer-object-inspector.png b/doc/src/images/designer-object-inspector.png new file mode 100644 index 0000000..c7f3180 Binary files /dev/null and b/doc/src/images/designer-object-inspector.png differ diff --git a/doc/src/images/designer-palette-brush-editor.png b/doc/src/images/designer-palette-brush-editor.png new file mode 100644 index 0000000..b4a9e0f Binary files /dev/null and b/doc/src/images/designer-palette-brush-editor.png differ diff --git a/doc/src/images/designer-palette-editor.png b/doc/src/images/designer-palette-editor.png new file mode 100644 index 0000000..7333abe Binary files /dev/null and b/doc/src/images/designer-palette-editor.png differ diff --git a/doc/src/images/designer-palette-gradient-editor.png b/doc/src/images/designer-palette-gradient-editor.png new file mode 100644 index 0000000..d4b4d66 Binary files /dev/null and b/doc/src/images/designer-palette-gradient-editor.png differ diff --git a/doc/src/images/designer-palette-pattern-editor.png b/doc/src/images/designer-palette-pattern-editor.png new file mode 100644 index 0000000..8117e0e Binary files /dev/null and b/doc/src/images/designer-palette-pattern-editor.png differ diff --git a/doc/src/images/designer-preview-device-skin.png b/doc/src/images/designer-preview-device-skin.png new file mode 100644 index 0000000..5fc7836 Binary files /dev/null and b/doc/src/images/designer-preview-device-skin.png differ diff --git a/doc/src/images/designer-preview-deviceskin-selection.png b/doc/src/images/designer-preview-deviceskin-selection.png new file mode 100644 index 0000000..3b6aec4 Binary files /dev/null and b/doc/src/images/designer-preview-deviceskin-selection.png differ diff --git a/doc/src/images/designer-preview-style-selection.png b/doc/src/images/designer-preview-style-selection.png new file mode 100644 index 0000000..e64cf6e Binary files /dev/null and b/doc/src/images/designer-preview-style-selection.png differ diff --git a/doc/src/images/designer-preview-style.png b/doc/src/images/designer-preview-style.png new file mode 100644 index 0000000..54a243a Binary files /dev/null and b/doc/src/images/designer-preview-style.png differ diff --git a/doc/src/images/designer-preview-stylesheet.png b/doc/src/images/designer-preview-stylesheet.png new file mode 100644 index 0000000..ef9ef4f Binary files /dev/null and b/doc/src/images/designer-preview-stylesheet.png differ diff --git a/doc/src/images/designer-promoting-widgets.png b/doc/src/images/designer-promoting-widgets.png new file mode 100644 index 0000000..2377560 Binary files /dev/null and b/doc/src/images/designer-promoting-widgets.png differ diff --git a/doc/src/images/designer-property-editor-add-dynamic.png b/doc/src/images/designer-property-editor-add-dynamic.png new file mode 100644 index 0000000..c7f4cf1 Binary files /dev/null and b/doc/src/images/designer-property-editor-add-dynamic.png differ diff --git a/doc/src/images/designer-property-editor-configure.png b/doc/src/images/designer-property-editor-configure.png new file mode 100644 index 0000000..2a96fe3 Binary files /dev/null and b/doc/src/images/designer-property-editor-configure.png differ diff --git a/doc/src/images/designer-property-editor-link.png b/doc/src/images/designer-property-editor-link.png new file mode 100644 index 0000000..e43a530 Binary files /dev/null and b/doc/src/images/designer-property-editor-link.png differ diff --git a/doc/src/images/designer-property-editor-remove-dynamic.png b/doc/src/images/designer-property-editor-remove-dynamic.png new file mode 100644 index 0000000..cb6ccaa Binary files /dev/null and b/doc/src/images/designer-property-editor-remove-dynamic.png differ diff --git a/doc/src/images/designer-property-editor-toolbar.png b/doc/src/images/designer-property-editor-toolbar.png new file mode 100644 index 0000000..ae6345e Binary files /dev/null and b/doc/src/images/designer-property-editor-toolbar.png differ diff --git a/doc/src/images/designer-property-editor.png b/doc/src/images/designer-property-editor.png new file mode 100644 index 0000000..fad2309 Binary files /dev/null and b/doc/src/images/designer-property-editor.png differ diff --git a/doc/src/images/designer-reload-resources-button.png b/doc/src/images/designer-reload-resources-button.png new file mode 100644 index 0000000..c101e76 Binary files /dev/null and b/doc/src/images/designer-reload-resources-button.png differ diff --git a/doc/src/images/designer-remove-custom-toolbar.png b/doc/src/images/designer-remove-custom-toolbar.png new file mode 100644 index 0000000..3fecfc2 Binary files /dev/null and b/doc/src/images/designer-remove-custom-toolbar.png differ diff --git a/doc/src/images/designer-remove-resource-entry-button.png b/doc/src/images/designer-remove-resource-entry-button.png new file mode 100644 index 0000000..aa3b9d6 Binary files /dev/null and b/doc/src/images/designer-remove-resource-entry-button.png differ diff --git a/doc/src/images/designer-resource-browser.png b/doc/src/images/designer-resource-browser.png new file mode 100644 index 0000000..213a58b Binary files /dev/null and b/doc/src/images/designer-resource-browser.png differ diff --git a/doc/src/images/designer-resource-selector.png b/doc/src/images/designer-resource-selector.png new file mode 100644 index 0000000..31a4cb1 Binary files /dev/null and b/doc/src/images/designer-resource-selector.png differ diff --git a/doc/src/images/designer-resource-tool.png b/doc/src/images/designer-resource-tool.png new file mode 100644 index 0000000..7ef511c Binary files /dev/null and b/doc/src/images/designer-resource-tool.png differ diff --git a/doc/src/images/designer-resources-adding.png b/doc/src/images/designer-resources-adding.png new file mode 100644 index 0000000..a417bbd Binary files /dev/null and b/doc/src/images/designer-resources-adding.png differ diff --git a/doc/src/images/designer-resources-editing.png b/doc/src/images/designer-resources-editing.png new file mode 100644 index 0000000..6b8aee7 Binary files /dev/null and b/doc/src/images/designer-resources-editing.png differ diff --git a/doc/src/images/designer-resources-empty.png b/doc/src/images/designer-resources-empty.png new file mode 100644 index 0000000..47a45d0 Binary files /dev/null and b/doc/src/images/designer-resources-empty.png differ diff --git a/doc/src/images/designer-resources-using.png b/doc/src/images/designer-resources-using.png new file mode 100644 index 0000000..4ce9ca2 Binary files /dev/null and b/doc/src/images/designer-resources-using.png differ diff --git a/doc/src/images/designer-screenshot-small.png b/doc/src/images/designer-screenshot-small.png new file mode 100644 index 0000000..ad4096b Binary files /dev/null and b/doc/src/images/designer-screenshot-small.png differ diff --git a/doc/src/images/designer-screenshot.png b/doc/src/images/designer-screenshot.png new file mode 100644 index 0000000..1700b06 Binary files /dev/null and b/doc/src/images/designer-screenshot.png differ diff --git a/doc/src/images/designer-selecting-widget.png b/doc/src/images/designer-selecting-widget.png new file mode 100644 index 0000000..a358d30 Binary files /dev/null and b/doc/src/images/designer-selecting-widget.png differ diff --git a/doc/src/images/designer-selecting-widgets.png b/doc/src/images/designer-selecting-widgets.png new file mode 100644 index 0000000..93d315f Binary files /dev/null and b/doc/src/images/designer-selecting-widgets.png differ diff --git a/doc/src/images/designer-set-layout.png b/doc/src/images/designer-set-layout.png new file mode 100644 index 0000000..86b4ecc Binary files /dev/null and b/doc/src/images/designer-set-layout.png differ diff --git a/doc/src/images/designer-set-layout2.png b/doc/src/images/designer-set-layout2.png new file mode 100644 index 0000000..e93f4dc Binary files /dev/null and b/doc/src/images/designer-set-layout2.png differ diff --git a/doc/src/images/designer-splitter-layout.png b/doc/src/images/designer-splitter-layout.png new file mode 100644 index 0000000..2646c28 Binary files /dev/null and b/doc/src/images/designer-splitter-layout.png differ diff --git a/doc/src/images/designer-stylesheet-options.png b/doc/src/images/designer-stylesheet-options.png new file mode 100644 index 0000000..a6893e7 Binary files /dev/null and b/doc/src/images/designer-stylesheet-options.png differ diff --git a/doc/src/images/designer-stylesheet-usage.png b/doc/src/images/designer-stylesheet-usage.png new file mode 100644 index 0000000..f687590 Binary files /dev/null and b/doc/src/images/designer-stylesheet-usage.png differ diff --git a/doc/src/images/designer-tab-order-mode.png b/doc/src/images/designer-tab-order-mode.png new file mode 100644 index 0000000..8135f3b Binary files /dev/null and b/doc/src/images/designer-tab-order-mode.png differ diff --git a/doc/src/images/designer-tab-order-tool.png b/doc/src/images/designer-tab-order-tool.png new file mode 100644 index 0000000..f54faf9 Binary files /dev/null and b/doc/src/images/designer-tab-order-tool.png differ diff --git a/doc/src/images/designer-validator-highlighter.png b/doc/src/images/designer-validator-highlighter.png new file mode 100644 index 0000000..a6661d5 Binary files /dev/null and b/doc/src/images/designer-validator-highlighter.png differ diff --git a/doc/src/images/designer-widget-box.png b/doc/src/images/designer-widget-box.png new file mode 100644 index 0000000..bfbc5b7 Binary files /dev/null and b/doc/src/images/designer-widget-box.png differ diff --git a/doc/src/images/designer-widget-filter.png b/doc/src/images/designer-widget-filter.png new file mode 100644 index 0000000..ac13a0a Binary files /dev/null and b/doc/src/images/designer-widget-filter.png differ diff --git a/doc/src/images/designer-widget-final.png b/doc/src/images/designer-widget-final.png new file mode 100644 index 0000000..f8acd9f Binary files /dev/null and b/doc/src/images/designer-widget-final.png differ diff --git a/doc/src/images/designer-widget-initial.png b/doc/src/images/designer-widget-initial.png new file mode 100644 index 0000000..d564fbe Binary files /dev/null and b/doc/src/images/designer-widget-initial.png differ diff --git a/doc/src/images/designer-widget-layout.png b/doc/src/images/designer-widget-layout.png new file mode 100644 index 0000000..4788170 Binary files /dev/null and b/doc/src/images/designer-widget-layout.png differ diff --git a/doc/src/images/designer-widget-morph.png b/doc/src/images/designer-widget-morph.png new file mode 100644 index 0000000..974bc0e Binary files /dev/null and b/doc/src/images/designer-widget-morph.png differ diff --git a/doc/src/images/designer-widget-preview.png b/doc/src/images/designer-widget-preview.png new file mode 100644 index 0000000..e456564 Binary files /dev/null and b/doc/src/images/designer-widget-preview.png differ diff --git a/doc/src/images/designer-widget-tool.png b/doc/src/images/designer-widget-tool.png new file mode 100644 index 0000000..e1aa353 Binary files /dev/null and b/doc/src/images/designer-widget-tool.png differ diff --git a/doc/src/images/desktop-examples.png b/doc/src/images/desktop-examples.png new file mode 100644 index 0000000..86b16b4 Binary files /dev/null and b/doc/src/images/desktop-examples.png differ diff --git a/doc/src/images/diagonalGradient.png b/doc/src/images/diagonalGradient.png new file mode 100644 index 0000000..623d362 Binary files /dev/null and b/doc/src/images/diagonalGradient.png differ diff --git a/doc/src/images/diagramscene.png b/doc/src/images/diagramscene.png new file mode 100644 index 0000000..c84fc81 Binary files /dev/null and b/doc/src/images/diagramscene.png differ diff --git a/doc/src/images/dialog-examples.png b/doc/src/images/dialog-examples.png new file mode 100644 index 0000000..26537b5 Binary files /dev/null and b/doc/src/images/dialog-examples.png differ diff --git a/doc/src/images/dialogbuttonboxexample.png b/doc/src/images/dialogbuttonboxexample.png new file mode 100644 index 0000000..baa62d3 Binary files /dev/null and b/doc/src/images/dialogbuttonboxexample.png differ diff --git a/doc/src/images/dialogs-examples.png b/doc/src/images/dialogs-examples.png new file mode 100644 index 0000000..45bf0ab Binary files /dev/null and b/doc/src/images/dialogs-examples.png differ diff --git a/doc/src/images/digitalclock-example.png b/doc/src/images/digitalclock-example.png new file mode 100644 index 0000000..4739866 Binary files /dev/null and b/doc/src/images/digitalclock-example.png differ diff --git a/doc/src/images/directapproach-calculatorform.png b/doc/src/images/directapproach-calculatorform.png new file mode 100644 index 0000000..2b87ed1 Binary files /dev/null and b/doc/src/images/directapproach-calculatorform.png differ diff --git a/doc/src/images/dirview-example.png b/doc/src/images/dirview-example.png new file mode 100644 index 0000000..6412ead Binary files /dev/null and b/doc/src/images/dirview-example.png differ diff --git a/doc/src/images/dockwidget-cross.png b/doc/src/images/dockwidget-cross.png new file mode 100644 index 0000000..35db6a2 Binary files /dev/null and b/doc/src/images/dockwidget-cross.png differ diff --git a/doc/src/images/dockwidget-neighbors.png b/doc/src/images/dockwidget-neighbors.png new file mode 100644 index 0000000..d299ce6 Binary files /dev/null and b/doc/src/images/dockwidget-neighbors.png differ diff --git a/doc/src/images/dockwidgets-example.png b/doc/src/images/dockwidgets-example.png new file mode 100644 index 0000000..2a2d6f8 Binary files /dev/null and b/doc/src/images/dockwidgets-example.png differ diff --git a/doc/src/images/dombookmarks-example.png b/doc/src/images/dombookmarks-example.png new file mode 100644 index 0000000..abacacb Binary files /dev/null and b/doc/src/images/dombookmarks-example.png differ diff --git a/doc/src/images/draganddrop-examples.png b/doc/src/images/draganddrop-examples.png new file mode 100644 index 0000000..89d9e50 Binary files /dev/null and b/doc/src/images/draganddrop-examples.png differ diff --git a/doc/src/images/draganddroppuzzle-example.png b/doc/src/images/draganddroppuzzle-example.png new file mode 100644 index 0000000..8122782 Binary files /dev/null and b/doc/src/images/draganddroppuzzle-example.png differ diff --git a/doc/src/images/dragdroprobot-example.png b/doc/src/images/dragdroprobot-example.png new file mode 100644 index 0000000..53aae77 Binary files /dev/null and b/doc/src/images/dragdroprobot-example.png differ diff --git a/doc/src/images/draggableicons-example.png b/doc/src/images/draggableicons-example.png new file mode 100644 index 0000000..003ce13 Binary files /dev/null and b/doc/src/images/draggableicons-example.png differ diff --git a/doc/src/images/draggabletext-example.png b/doc/src/images/draggabletext-example.png new file mode 100644 index 0000000..f9b2281 Binary files /dev/null and b/doc/src/images/draggabletext-example.png differ diff --git a/doc/src/images/draw_arc.png b/doc/src/images/draw_arc.png new file mode 100644 index 0000000..6e72108 Binary files /dev/null and b/doc/src/images/draw_arc.png differ diff --git a/doc/src/images/draw_chord.png b/doc/src/images/draw_chord.png new file mode 100644 index 0000000..4d4ab50 Binary files /dev/null and b/doc/src/images/draw_chord.png differ diff --git a/doc/src/images/drilldown-example.png b/doc/src/images/drilldown-example.png new file mode 100644 index 0000000..68353f7 Binary files /dev/null and b/doc/src/images/drilldown-example.png differ diff --git a/doc/src/images/dropsite-example.png b/doc/src/images/dropsite-example.png new file mode 100644 index 0000000..42b988d Binary files /dev/null and b/doc/src/images/dropsite-example.png differ diff --git a/doc/src/images/dynamiclayouts-example.png b/doc/src/images/dynamiclayouts-example.png new file mode 100644 index 0000000..65d8150 Binary files /dev/null and b/doc/src/images/dynamiclayouts-example.png differ diff --git a/doc/src/images/echopluginexample.png b/doc/src/images/echopluginexample.png new file mode 100644 index 0000000..7cb1e4d Binary files /dev/null and b/doc/src/images/echopluginexample.png differ diff --git a/doc/src/images/effectwidget.png b/doc/src/images/effectwidget.png new file mode 100644 index 0000000..d4a0fc4 Binary files /dev/null and b/doc/src/images/effectwidget.png differ diff --git a/doc/src/images/elasticnodes-example.png b/doc/src/images/elasticnodes-example.png new file mode 100644 index 0000000..840f74fe Binary files /dev/null and b/doc/src/images/elasticnodes-example.png differ diff --git a/doc/src/images/embedded-demo-launcher.png b/doc/src/images/embedded-demo-launcher.png new file mode 100644 index 0000000..deafc7b Binary files /dev/null and b/doc/src/images/embedded-demo-launcher.png differ diff --git a/doc/src/images/embedded-simpledecoration-example-styles.png b/doc/src/images/embedded-simpledecoration-example-styles.png new file mode 100644 index 0000000..b2ad83c Binary files /dev/null and b/doc/src/images/embedded-simpledecoration-example-styles.png differ diff --git a/doc/src/images/embedded-simpledecoration-example.png b/doc/src/images/embedded-simpledecoration-example.png new file mode 100644 index 0000000..bfd0450 Binary files /dev/null and b/doc/src/images/embedded-simpledecoration-example.png differ diff --git a/doc/src/images/embeddeddialogs-demo.png b/doc/src/images/embeddeddialogs-demo.png new file mode 100644 index 0000000..d0da4b6 Binary files /dev/null and b/doc/src/images/embeddeddialogs-demo.png differ diff --git a/doc/src/images/extension-example.png b/doc/src/images/extension-example.png new file mode 100644 index 0000000..dfaacc0 Binary files /dev/null and b/doc/src/images/extension-example.png differ diff --git a/doc/src/images/extension_more.png b/doc/src/images/extension_more.png new file mode 100644 index 0000000..2b06809 Binary files /dev/null and b/doc/src/images/extension_more.png differ diff --git a/doc/src/images/fetchmore-example.png b/doc/src/images/fetchmore-example.png new file mode 100644 index 0000000..d2359dc Binary files /dev/null and b/doc/src/images/fetchmore-example.png differ diff --git a/doc/src/images/filedialogurls.png b/doc/src/images/filedialogurls.png new file mode 100644 index 0000000..7d22ef3 Binary files /dev/null and b/doc/src/images/filedialogurls.png differ diff --git a/doc/src/images/filetree_1-example.png b/doc/src/images/filetree_1-example.png new file mode 100644 index 0000000..7e19174 Binary files /dev/null and b/doc/src/images/filetree_1-example.png differ diff --git a/doc/src/images/filetree_2-example.png b/doc/src/images/filetree_2-example.png new file mode 100644 index 0000000..cb794c5 Binary files /dev/null and b/doc/src/images/filetree_2-example.png differ diff --git a/doc/src/images/findfiles-example.png b/doc/src/images/findfiles-example.png new file mode 100644 index 0000000..acb5ea1 Binary files /dev/null and b/doc/src/images/findfiles-example.png differ diff --git a/doc/src/images/findfiles_progress_dialog.png b/doc/src/images/findfiles_progress_dialog.png new file mode 100644 index 0000000..05eda2c Binary files /dev/null and b/doc/src/images/findfiles_progress_dialog.png differ diff --git a/doc/src/images/flowlayout-example.png b/doc/src/images/flowlayout-example.png new file mode 100644 index 0000000..27660d6 Binary files /dev/null and b/doc/src/images/flowlayout-example.png differ diff --git a/doc/src/images/fontsampler-example.png b/doc/src/images/fontsampler-example.png new file mode 100644 index 0000000..7df4a50 Binary files /dev/null and b/doc/src/images/fontsampler-example.png differ diff --git a/doc/src/images/foreignkeys.png b/doc/src/images/foreignkeys.png new file mode 100644 index 0000000..7a6a19b Binary files /dev/null and b/doc/src/images/foreignkeys.png differ diff --git a/doc/src/images/formextractor-example.png b/doc/src/images/formextractor-example.png new file mode 100644 index 0000000..155cdaa Binary files /dev/null and b/doc/src/images/formextractor-example.png differ diff --git a/doc/src/images/fortuneclient-example.png b/doc/src/images/fortuneclient-example.png new file mode 100644 index 0000000..b34a987 Binary files /dev/null and b/doc/src/images/fortuneclient-example.png differ diff --git a/doc/src/images/fortuneserver-example.png b/doc/src/images/fortuneserver-example.png new file mode 100644 index 0000000..73f27d5 Binary files /dev/null and b/doc/src/images/fortuneserver-example.png differ diff --git a/doc/src/images/framebufferobject-example.png b/doc/src/images/framebufferobject-example.png new file mode 100644 index 0000000..df9b6db Binary files /dev/null and b/doc/src/images/framebufferobject-example.png differ diff --git a/doc/src/images/framebufferobject2-example.png b/doc/src/images/framebufferobject2-example.png new file mode 100644 index 0000000..bafb05a Binary files /dev/null and b/doc/src/images/framebufferobject2-example.png differ diff --git a/doc/src/images/frames.png b/doc/src/images/frames.png new file mode 100644 index 0000000..13c0850 Binary files /dev/null and b/doc/src/images/frames.png differ diff --git a/doc/src/images/fridgemagnets-example.png b/doc/src/images/fridgemagnets-example.png new file mode 100644 index 0000000..9adb572 Binary files /dev/null and b/doc/src/images/fridgemagnets-example.png differ diff --git a/doc/src/images/ftp-example.png b/doc/src/images/ftp-example.png new file mode 100644 index 0000000..504c658 Binary files /dev/null and b/doc/src/images/ftp-example.png differ diff --git a/doc/src/images/geometry.png b/doc/src/images/geometry.png new file mode 100644 index 0000000..c69e11d Binary files /dev/null and b/doc/src/images/geometry.png differ diff --git a/doc/src/images/grabber-example.png b/doc/src/images/grabber-example.png new file mode 100644 index 0000000..6a05b94 Binary files /dev/null and b/doc/src/images/grabber-example.png differ diff --git a/doc/src/images/gradientText.png b/doc/src/images/gradientText.png new file mode 100644 index 0000000..9ee7164 Binary files /dev/null and b/doc/src/images/gradientText.png differ diff --git a/doc/src/images/gradients-demo.png b/doc/src/images/gradients-demo.png new file mode 100644 index 0000000..d80708e Binary files /dev/null and b/doc/src/images/gradients-demo.png differ diff --git a/doc/src/images/graphicsview-ellipseitem-pie.png b/doc/src/images/graphicsview-ellipseitem-pie.png new file mode 100644 index 0000000..136175a Binary files /dev/null and b/doc/src/images/graphicsview-ellipseitem-pie.png differ diff --git a/doc/src/images/graphicsview-ellipseitem.png b/doc/src/images/graphicsview-ellipseitem.png new file mode 100644 index 0000000..7c7a8e5 Binary files /dev/null and b/doc/src/images/graphicsview-ellipseitem.png differ diff --git a/doc/src/images/graphicsview-examples.png b/doc/src/images/graphicsview-examples.png new file mode 100644 index 0000000..b58bdc3 Binary files /dev/null and b/doc/src/images/graphicsview-examples.png differ diff --git a/doc/src/images/graphicsview-items.png b/doc/src/images/graphicsview-items.png new file mode 100644 index 0000000..73be2dd Binary files /dev/null and b/doc/src/images/graphicsview-items.png differ diff --git a/doc/src/images/graphicsview-lineitem.png b/doc/src/images/graphicsview-lineitem.png new file mode 100644 index 0000000..952a3c2 Binary files /dev/null and b/doc/src/images/graphicsview-lineitem.png differ diff --git a/doc/src/images/graphicsview-map.png b/doc/src/images/graphicsview-map.png new file mode 100644 index 0000000..e7f5ac6 Binary files /dev/null and b/doc/src/images/graphicsview-map.png differ diff --git a/doc/src/images/graphicsview-parentchild.png b/doc/src/images/graphicsview-parentchild.png new file mode 100644 index 0000000..0fc2dbf Binary files /dev/null and b/doc/src/images/graphicsview-parentchild.png differ diff --git a/doc/src/images/graphicsview-pathitem.png b/doc/src/images/graphicsview-pathitem.png new file mode 100644 index 0000000..c1ddd56 Binary files /dev/null and b/doc/src/images/graphicsview-pathitem.png differ diff --git a/doc/src/images/graphicsview-pixmapitem.png b/doc/src/images/graphicsview-pixmapitem.png new file mode 100644 index 0000000..d14fac5 Binary files /dev/null and b/doc/src/images/graphicsview-pixmapitem.png differ diff --git a/doc/src/images/graphicsview-polygonitem.png b/doc/src/images/graphicsview-polygonitem.png new file mode 100644 index 0000000..3cd2232 Binary files /dev/null and b/doc/src/images/graphicsview-polygonitem.png differ diff --git a/doc/src/images/graphicsview-rectitem.png b/doc/src/images/graphicsview-rectitem.png new file mode 100644 index 0000000..a5917e5 Binary files /dev/null and b/doc/src/images/graphicsview-rectitem.png differ diff --git a/doc/src/images/graphicsview-shapes.png b/doc/src/images/graphicsview-shapes.png new file mode 100644 index 0000000..466eb33 Binary files /dev/null and b/doc/src/images/graphicsview-shapes.png differ diff --git a/doc/src/images/graphicsview-simpletextitem.png b/doc/src/images/graphicsview-simpletextitem.png new file mode 100644 index 0000000..908d67f Binary files /dev/null and b/doc/src/images/graphicsview-simpletextitem.png differ diff --git a/doc/src/images/graphicsview-text.png b/doc/src/images/graphicsview-text.png new file mode 100644 index 0000000..e7441df Binary files /dev/null and b/doc/src/images/graphicsview-text.png differ diff --git a/doc/src/images/graphicsview-textitem.png b/doc/src/images/graphicsview-textitem.png new file mode 100644 index 0000000..f1ae3c0 Binary files /dev/null and b/doc/src/images/graphicsview-textitem.png differ diff --git a/doc/src/images/graphicsview-view.png b/doc/src/images/graphicsview-view.png new file mode 100644 index 0000000..212195f Binary files /dev/null and b/doc/src/images/graphicsview-view.png differ diff --git a/doc/src/images/graphicsview-zorder.png b/doc/src/images/graphicsview-zorder.png new file mode 100644 index 0000000..a1cc3d0 Binary files /dev/null and b/doc/src/images/graphicsview-zorder.png differ diff --git a/doc/src/images/gridlayout.png b/doc/src/images/gridlayout.png new file mode 100644 index 0000000..ae76c04 Binary files /dev/null and b/doc/src/images/gridlayout.png differ diff --git a/doc/src/images/groupbox-example.png b/doc/src/images/groupbox-example.png new file mode 100644 index 0000000..443f812 Binary files /dev/null and b/doc/src/images/groupbox-example.png differ diff --git a/doc/src/images/gtk-calendarwidget.png b/doc/src/images/gtk-calendarwidget.png new file mode 100644 index 0000000..568cd1a Binary files /dev/null and b/doc/src/images/gtk-calendarwidget.png differ diff --git a/doc/src/images/gtk-checkbox.png b/doc/src/images/gtk-checkbox.png new file mode 100644 index 0000000..1fd5fc7 Binary files /dev/null and b/doc/src/images/gtk-checkbox.png differ diff --git a/doc/src/images/gtk-columnview.png b/doc/src/images/gtk-columnview.png new file mode 100644 index 0000000..548ce8b Binary files /dev/null and b/doc/src/images/gtk-columnview.png differ diff --git a/doc/src/images/gtk-combobox.png b/doc/src/images/gtk-combobox.png new file mode 100644 index 0000000..3b4544d Binary files /dev/null and b/doc/src/images/gtk-combobox.png differ diff --git a/doc/src/images/gtk-dateedit.png b/doc/src/images/gtk-dateedit.png new file mode 100644 index 0000000..25229f0 Binary files /dev/null and b/doc/src/images/gtk-dateedit.png differ diff --git a/doc/src/images/gtk-datetimeedit.png b/doc/src/images/gtk-datetimeedit.png new file mode 100644 index 0000000..0c934a4 Binary files /dev/null and b/doc/src/images/gtk-datetimeedit.png differ diff --git a/doc/src/images/gtk-dial.png b/doc/src/images/gtk-dial.png new file mode 100644 index 0000000..18e14b3 Binary files /dev/null and b/doc/src/images/gtk-dial.png differ diff --git a/doc/src/images/gtk-doublespinbox.png b/doc/src/images/gtk-doublespinbox.png new file mode 100644 index 0000000..3a69043 Binary files /dev/null and b/doc/src/images/gtk-doublespinbox.png differ diff --git a/doc/src/images/gtk-fontcombobox.png b/doc/src/images/gtk-fontcombobox.png new file mode 100644 index 0000000..4cb1bc1 Binary files /dev/null and b/doc/src/images/gtk-fontcombobox.png differ diff --git a/doc/src/images/gtk-frame.png b/doc/src/images/gtk-frame.png new file mode 100644 index 0000000..c1bf52f Binary files /dev/null and b/doc/src/images/gtk-frame.png differ diff --git a/doc/src/images/gtk-groupbox.png b/doc/src/images/gtk-groupbox.png new file mode 100644 index 0000000..6d217c8 Binary files /dev/null and b/doc/src/images/gtk-groupbox.png differ diff --git a/doc/src/images/gtk-horizontalscrollbar.png b/doc/src/images/gtk-horizontalscrollbar.png new file mode 100644 index 0000000..2887730 Binary files /dev/null and b/doc/src/images/gtk-horizontalscrollbar.png differ diff --git a/doc/src/images/gtk-label.png b/doc/src/images/gtk-label.png new file mode 100644 index 0000000..006d013 Binary files /dev/null and b/doc/src/images/gtk-label.png differ diff --git a/doc/src/images/gtk-lcdnumber.png b/doc/src/images/gtk-lcdnumber.png new file mode 100644 index 0000000..142d298 Binary files /dev/null and b/doc/src/images/gtk-lcdnumber.png differ diff --git a/doc/src/images/gtk-lineedit.png b/doc/src/images/gtk-lineedit.png new file mode 100644 index 0000000..8fb513c Binary files /dev/null and b/doc/src/images/gtk-lineedit.png differ diff --git a/doc/src/images/gtk-listview.png b/doc/src/images/gtk-listview.png new file mode 100644 index 0000000..d32f8e8 Binary files /dev/null and b/doc/src/images/gtk-listview.png differ diff --git a/doc/src/images/gtk-progressbar.png b/doc/src/images/gtk-progressbar.png new file mode 100644 index 0000000..6162484 Binary files /dev/null and b/doc/src/images/gtk-progressbar.png differ diff --git a/doc/src/images/gtk-pushbutton.png b/doc/src/images/gtk-pushbutton.png new file mode 100644 index 0000000..f4f4d7c Binary files /dev/null and b/doc/src/images/gtk-pushbutton.png differ diff --git a/doc/src/images/gtk-radiobutton.png b/doc/src/images/gtk-radiobutton.png new file mode 100644 index 0000000..b3620fa Binary files /dev/null and b/doc/src/images/gtk-radiobutton.png differ diff --git a/doc/src/images/gtk-slider.png b/doc/src/images/gtk-slider.png new file mode 100644 index 0000000..3d8e0ee Binary files /dev/null and b/doc/src/images/gtk-slider.png differ diff --git a/doc/src/images/gtk-spinbox.png b/doc/src/images/gtk-spinbox.png new file mode 100644 index 0000000..a39eb3a Binary files /dev/null and b/doc/src/images/gtk-spinbox.png differ diff --git a/doc/src/images/gtk-style-screenshot.png b/doc/src/images/gtk-style-screenshot.png new file mode 100644 index 0000000..2d493a0 Binary files /dev/null and b/doc/src/images/gtk-style-screenshot.png differ diff --git a/doc/src/images/gtk-tableview.png b/doc/src/images/gtk-tableview.png new file mode 100644 index 0000000..a025193 Binary files /dev/null and b/doc/src/images/gtk-tableview.png differ diff --git a/doc/src/images/gtk-tabwidget.png b/doc/src/images/gtk-tabwidget.png new file mode 100644 index 0000000..089c76d Binary files /dev/null and b/doc/src/images/gtk-tabwidget.png differ diff --git a/doc/src/images/gtk-textedit.png b/doc/src/images/gtk-textedit.png new file mode 100644 index 0000000..e4b91c0 Binary files /dev/null and b/doc/src/images/gtk-textedit.png differ diff --git a/doc/src/images/gtk-timeedit.png b/doc/src/images/gtk-timeedit.png new file mode 100644 index 0000000..acf6730 Binary files /dev/null and b/doc/src/images/gtk-timeedit.png differ diff --git a/doc/src/images/gtk-toolbox.png b/doc/src/images/gtk-toolbox.png new file mode 100644 index 0000000..25e6137 Binary files /dev/null and b/doc/src/images/gtk-toolbox.png differ diff --git a/doc/src/images/gtk-toolbutton.png b/doc/src/images/gtk-toolbutton.png new file mode 100644 index 0000000..f0eb86e Binary files /dev/null and b/doc/src/images/gtk-toolbutton.png differ diff --git a/doc/src/images/gtk-treeview.png b/doc/src/images/gtk-treeview.png new file mode 100644 index 0000000..7b4e304 Binary files /dev/null and b/doc/src/images/gtk-treeview.png differ diff --git a/doc/src/images/hellogl-es-example.png b/doc/src/images/hellogl-es-example.png new file mode 100644 index 0000000..7e55f09 Binary files /dev/null and b/doc/src/images/hellogl-es-example.png differ diff --git a/doc/src/images/hellogl-example.png b/doc/src/images/hellogl-example.png new file mode 100644 index 0000000..ecb3a3a Binary files /dev/null and b/doc/src/images/hellogl-example.png differ diff --git a/doc/src/images/http-example.png b/doc/src/images/http-example.png new file mode 100644 index 0000000..16b0539 Binary files /dev/null and b/doc/src/images/http-example.png differ diff --git a/doc/src/images/httpstack.png b/doc/src/images/httpstack.png new file mode 100644 index 0000000..658927b Binary files /dev/null and b/doc/src/images/httpstack.png differ diff --git a/doc/src/images/i18n-example.png b/doc/src/images/i18n-example.png new file mode 100644 index 0000000..20c46c9 Binary files /dev/null and b/doc/src/images/i18n-example.png differ diff --git a/doc/src/images/icon.png b/doc/src/images/icon.png new file mode 100644 index 0000000..cc2b6ac Binary files /dev/null and b/doc/src/images/icon.png differ diff --git a/doc/src/images/icons-example.png b/doc/src/images/icons-example.png new file mode 100644 index 0000000..ae4b1d3 Binary files /dev/null and b/doc/src/images/icons-example.png differ diff --git a/doc/src/images/icons-view-menu.png b/doc/src/images/icons-view-menu.png new file mode 100644 index 0000000..7fc02a0 Binary files /dev/null and b/doc/src/images/icons-view-menu.png differ diff --git a/doc/src/images/icons_find_normal.png b/doc/src/images/icons_find_normal.png new file mode 100644 index 0000000..c92c7e1 Binary files /dev/null and b/doc/src/images/icons_find_normal.png differ diff --git a/doc/src/images/icons_find_normal_disabled.png b/doc/src/images/icons_find_normal_disabled.png new file mode 100644 index 0000000..534d6de Binary files /dev/null and b/doc/src/images/icons_find_normal_disabled.png differ diff --git a/doc/src/images/icons_images_groupbox.png b/doc/src/images/icons_images_groupbox.png new file mode 100644 index 0000000..f4942f7 Binary files /dev/null and b/doc/src/images/icons_images_groupbox.png differ diff --git a/doc/src/images/icons_monkey.png b/doc/src/images/icons_monkey.png new file mode 100644 index 0000000..141a87c Binary files /dev/null and b/doc/src/images/icons_monkey.png differ diff --git a/doc/src/images/icons_monkey_active.png b/doc/src/images/icons_monkey_active.png new file mode 100644 index 0000000..edb5132 Binary files /dev/null and b/doc/src/images/icons_monkey_active.png differ diff --git a/doc/src/images/icons_monkey_mess.png b/doc/src/images/icons_monkey_mess.png new file mode 100644 index 0000000..c23eed6 Binary files /dev/null and b/doc/src/images/icons_monkey_mess.png differ diff --git a/doc/src/images/icons_preview_area.png b/doc/src/images/icons_preview_area.png new file mode 100644 index 0000000..098afae Binary files /dev/null and b/doc/src/images/icons_preview_area.png differ diff --git a/doc/src/images/icons_qt_extended_16x16.png b/doc/src/images/icons_qt_extended_16x16.png new file mode 100644 index 0000000..9274369 Binary files /dev/null and b/doc/src/images/icons_qt_extended_16x16.png differ diff --git a/doc/src/images/icons_qt_extended_17x17.png b/doc/src/images/icons_qt_extended_17x17.png new file mode 100644 index 0000000..e9bb24a Binary files /dev/null and b/doc/src/images/icons_qt_extended_17x17.png differ diff --git a/doc/src/images/icons_qt_extended_32x32.png b/doc/src/images/icons_qt_extended_32x32.png new file mode 100644 index 0000000..cd3d0f3 Binary files /dev/null and b/doc/src/images/icons_qt_extended_32x32.png differ diff --git a/doc/src/images/icons_qt_extended_33x33.png b/doc/src/images/icons_qt_extended_33x33.png new file mode 100644 index 0000000..a67565c Binary files /dev/null and b/doc/src/images/icons_qt_extended_33x33.png differ diff --git a/doc/src/images/icons_qt_extended_48x48.png b/doc/src/images/icons_qt_extended_48x48.png new file mode 100644 index 0000000..5aa2d73 Binary files /dev/null and b/doc/src/images/icons_qt_extended_48x48.png differ diff --git a/doc/src/images/icons_qt_extended_64x64.png b/doc/src/images/icons_qt_extended_64x64.png new file mode 100644 index 0000000..5aa2d73 Binary files /dev/null and b/doc/src/images/icons_qt_extended_64x64.png differ diff --git a/doc/src/images/icons_qt_extended_8x8.png b/doc/src/images/icons_qt_extended_8x8.png new file mode 100644 index 0000000..8de7fce Binary files /dev/null and b/doc/src/images/icons_qt_extended_8x8.png differ diff --git a/doc/src/images/icons_size_groupbox.png b/doc/src/images/icons_size_groupbox.png new file mode 100644 index 0000000..1360280 Binary files /dev/null and b/doc/src/images/icons_size_groupbox.png differ diff --git a/doc/src/images/icons_size_spinbox.png b/doc/src/images/icons_size_spinbox.png new file mode 100644 index 0000000..a23ee9f Binary files /dev/null and b/doc/src/images/icons_size_spinbox.png differ diff --git a/doc/src/images/imagecomposition-example.png b/doc/src/images/imagecomposition-example.png new file mode 100644 index 0000000..697c980 Binary files /dev/null and b/doc/src/images/imagecomposition-example.png differ diff --git a/doc/src/images/imageviewer-example.png b/doc/src/images/imageviewer-example.png new file mode 100644 index 0000000..69b4f7a Binary files /dev/null and b/doc/src/images/imageviewer-example.png differ diff --git a/doc/src/images/imageviewer-fit_to_window_1.png b/doc/src/images/imageviewer-fit_to_window_1.png new file mode 100644 index 0000000..0fe1ba1 Binary files /dev/null and b/doc/src/images/imageviewer-fit_to_window_1.png differ diff --git a/doc/src/images/imageviewer-fit_to_window_2.png b/doc/src/images/imageviewer-fit_to_window_2.png new file mode 100644 index 0000000..29e3a93 Binary files /dev/null and b/doc/src/images/imageviewer-fit_to_window_2.png differ diff --git a/doc/src/images/imageviewer-original_size.png b/doc/src/images/imageviewer-original_size.png new file mode 100644 index 0000000..c0443eb Binary files /dev/null and b/doc/src/images/imageviewer-original_size.png differ diff --git a/doc/src/images/imageviewer-zoom_in_1.png b/doc/src/images/imageviewer-zoom_in_1.png new file mode 100644 index 0000000..05b0fff Binary files /dev/null and b/doc/src/images/imageviewer-zoom_in_1.png differ diff --git a/doc/src/images/imageviewer-zoom_in_2.png b/doc/src/images/imageviewer-zoom_in_2.png new file mode 100644 index 0000000..0c36111 Binary files /dev/null and b/doc/src/images/imageviewer-zoom_in_2.png differ diff --git a/doc/src/images/inputdialogs.png b/doc/src/images/inputdialogs.png new file mode 100644 index 0000000..135c2f6 Binary files /dev/null and b/doc/src/images/inputdialogs.png differ diff --git a/doc/src/images/insertrowinmodelview.png b/doc/src/images/insertrowinmodelview.png new file mode 100644 index 0000000..bddc401 Binary files /dev/null and b/doc/src/images/insertrowinmodelview.png differ diff --git a/doc/src/images/interview-demo.png b/doc/src/images/interview-demo.png new file mode 100644 index 0000000..d4a1956 Binary files /dev/null and b/doc/src/images/interview-demo.png differ diff --git a/doc/src/images/interview-shareddirmodel.png b/doc/src/images/interview-shareddirmodel.png new file mode 100644 index 0000000..0213a8d Binary files /dev/null and b/doc/src/images/interview-shareddirmodel.png differ diff --git a/doc/src/images/itemview-examples.png b/doc/src/images/itemview-examples.png new file mode 100644 index 0000000..71d29fe Binary files /dev/null and b/doc/src/images/itemview-examples.png differ diff --git a/doc/src/images/itemviews-editabletreemodel-indexes.png b/doc/src/images/itemviews-editabletreemodel-indexes.png new file mode 100644 index 0000000..4c66e88 Binary files /dev/null and b/doc/src/images/itemviews-editabletreemodel-indexes.png differ diff --git a/doc/src/images/itemviews-editabletreemodel-items.png b/doc/src/images/itemviews-editabletreemodel-items.png new file mode 100644 index 0000000..35fcb75 Binary files /dev/null and b/doc/src/images/itemviews-editabletreemodel-items.png differ diff --git a/doc/src/images/itemviews-editabletreemodel-model.png b/doc/src/images/itemviews-editabletreemodel-model.png new file mode 100644 index 0000000..592e0ff Binary files /dev/null and b/doc/src/images/itemviews-editabletreemodel-model.png differ diff --git a/doc/src/images/itemviews-editabletreemodel-values.png b/doc/src/images/itemviews-editabletreemodel-values.png new file mode 100644 index 0000000..0ace1cc Binary files /dev/null and b/doc/src/images/itemviews-editabletreemodel-values.png differ diff --git a/doc/src/images/itemviews-editabletreemodel.png b/doc/src/images/itemviews-editabletreemodel.png new file mode 100644 index 0000000..a151ea8 Binary files /dev/null and b/doc/src/images/itemviews-editabletreemodel.png differ diff --git a/doc/src/images/itemviews-examples.png b/doc/src/images/itemviews-examples.png new file mode 100644 index 0000000..7c026c2 Binary files /dev/null and b/doc/src/images/itemviews-examples.png differ diff --git a/doc/src/images/itemviewspuzzle-example.png b/doc/src/images/itemviewspuzzle-example.png new file mode 100644 index 0000000..05ae28b Binary files /dev/null and b/doc/src/images/itemviewspuzzle-example.png differ diff --git a/doc/src/images/javaiterators1.png b/doc/src/images/javaiterators1.png new file mode 100644 index 0000000..7dfcde0 Binary files /dev/null and b/doc/src/images/javaiterators1.png differ diff --git a/doc/src/images/javaiterators2.png b/doc/src/images/javaiterators2.png new file mode 100644 index 0000000..c04e3cc Binary files /dev/null and b/doc/src/images/javaiterators2.png differ diff --git a/doc/src/images/javastyle/branchindicatorimage.png b/doc/src/images/javastyle/branchindicatorimage.png new file mode 100644 index 0000000..f2cfc4b Binary files /dev/null and b/doc/src/images/javastyle/branchindicatorimage.png differ diff --git a/doc/src/images/javastyle/button.png b/doc/src/images/javastyle/button.png new file mode 100644 index 0000000..c3a9742 Binary files /dev/null and b/doc/src/images/javastyle/button.png differ diff --git a/doc/src/images/javastyle/checkbox.png b/doc/src/images/javastyle/checkbox.png new file mode 100644 index 0000000..bc841a6 Binary files /dev/null and b/doc/src/images/javastyle/checkbox.png differ diff --git a/doc/src/images/javastyle/checkboxexample.png b/doc/src/images/javastyle/checkboxexample.png new file mode 100644 index 0000000..69217fb Binary files /dev/null and b/doc/src/images/javastyle/checkboxexample.png differ diff --git a/doc/src/images/javastyle/checkingsomestuff.png b/doc/src/images/javastyle/checkingsomestuff.png new file mode 100644 index 0000000..88e8cad Binary files /dev/null and b/doc/src/images/javastyle/checkingsomestuff.png differ diff --git a/doc/src/images/javastyle/combobox.png b/doc/src/images/javastyle/combobox.png new file mode 100644 index 0000000..de9745a Binary files /dev/null and b/doc/src/images/javastyle/combobox.png differ diff --git a/doc/src/images/javastyle/comboboximage.png b/doc/src/images/javastyle/comboboximage.png new file mode 100644 index 0000000..1f05e5f Binary files /dev/null and b/doc/src/images/javastyle/comboboximage.png differ diff --git a/doc/src/images/javastyle/conceptualpushbuttontree.png b/doc/src/images/javastyle/conceptualpushbuttontree.png new file mode 100644 index 0000000..910000a Binary files /dev/null and b/doc/src/images/javastyle/conceptualpushbuttontree.png differ diff --git a/doc/src/images/javastyle/dockwidget.png b/doc/src/images/javastyle/dockwidget.png new file mode 100644 index 0000000..4bfec14 Binary files /dev/null and b/doc/src/images/javastyle/dockwidget.png differ diff --git a/doc/src/images/javastyle/dockwidgetimage.png b/doc/src/images/javastyle/dockwidgetimage.png new file mode 100644 index 0000000..eefe171 Binary files /dev/null and b/doc/src/images/javastyle/dockwidgetimage.png differ diff --git a/doc/src/images/javastyle/groupbox.png b/doc/src/images/javastyle/groupbox.png new file mode 100644 index 0000000..a39cd42 Binary files /dev/null and b/doc/src/images/javastyle/groupbox.png differ diff --git a/doc/src/images/javastyle/groupboximage.png b/doc/src/images/javastyle/groupboximage.png new file mode 100644 index 0000000..5baf609 Binary files /dev/null and b/doc/src/images/javastyle/groupboximage.png differ diff --git a/doc/src/images/javastyle/header.png b/doc/src/images/javastyle/header.png new file mode 100644 index 0000000..b4546d8 Binary files /dev/null and b/doc/src/images/javastyle/header.png differ diff --git a/doc/src/images/javastyle/headerimage.png b/doc/src/images/javastyle/headerimage.png new file mode 100644 index 0000000..4117149 Binary files /dev/null and b/doc/src/images/javastyle/headerimage.png differ diff --git a/doc/src/images/javastyle/menu.png b/doc/src/images/javastyle/menu.png new file mode 100644 index 0000000..8d44da4 Binary files /dev/null and b/doc/src/images/javastyle/menu.png differ diff --git a/doc/src/images/javastyle/menubar.png b/doc/src/images/javastyle/menubar.png new file mode 100644 index 0000000..e68e4a3 Binary files /dev/null and b/doc/src/images/javastyle/menubar.png differ diff --git a/doc/src/images/javastyle/menubarimage.png b/doc/src/images/javastyle/menubarimage.png new file mode 100644 index 0000000..b0cf28e Binary files /dev/null and b/doc/src/images/javastyle/menubarimage.png differ diff --git a/doc/src/images/javastyle/menuimage.png b/doc/src/images/javastyle/menuimage.png new file mode 100644 index 0000000..282dde7 Binary files /dev/null and b/doc/src/images/javastyle/menuimage.png differ diff --git a/doc/src/images/javastyle/plastiquetabimage.png b/doc/src/images/javastyle/plastiquetabimage.png new file mode 100644 index 0000000..56491ff Binary files /dev/null and b/doc/src/images/javastyle/plastiquetabimage.png differ diff --git a/doc/src/images/javastyle/plastiquetabtest.png b/doc/src/images/javastyle/plastiquetabtest.png new file mode 100644 index 0000000..e537773 Binary files /dev/null and b/doc/src/images/javastyle/plastiquetabtest.png differ diff --git a/doc/src/images/javastyle/progressbar.png b/doc/src/images/javastyle/progressbar.png new file mode 100644 index 0000000..de3a838 Binary files /dev/null and b/doc/src/images/javastyle/progressbar.png differ diff --git a/doc/src/images/javastyle/progressbarimage.png b/doc/src/images/javastyle/progressbarimage.png new file mode 100644 index 0000000..433b900 Binary files /dev/null and b/doc/src/images/javastyle/progressbarimage.png differ diff --git a/doc/src/images/javastyle/pushbutton.png b/doc/src/images/javastyle/pushbutton.png new file mode 100644 index 0000000..e5f92be Binary files /dev/null and b/doc/src/images/javastyle/pushbutton.png differ diff --git a/doc/src/images/javastyle/rubberband.png b/doc/src/images/javastyle/rubberband.png new file mode 100644 index 0000000..087424a Binary files /dev/null and b/doc/src/images/javastyle/rubberband.png differ diff --git a/doc/src/images/javastyle/rubberbandimage.png b/doc/src/images/javastyle/rubberbandimage.png new file mode 100644 index 0000000..2794638 Binary files /dev/null and b/doc/src/images/javastyle/rubberbandimage.png differ diff --git a/doc/src/images/javastyle/scrollbar.png b/doc/src/images/javastyle/scrollbar.png new file mode 100644 index 0000000..c1ecb5d Binary files /dev/null and b/doc/src/images/javastyle/scrollbar.png differ diff --git a/doc/src/images/javastyle/scrollbarimage.png b/doc/src/images/javastyle/scrollbarimage.png new file mode 100644 index 0000000..6d3e29d Binary files /dev/null and b/doc/src/images/javastyle/scrollbarimage.png differ diff --git a/doc/src/images/javastyle/sizegrip.png b/doc/src/images/javastyle/sizegrip.png new file mode 100644 index 0000000..667e6fb Binary files /dev/null and b/doc/src/images/javastyle/sizegrip.png differ diff --git a/doc/src/images/javastyle/sizegripimage.png b/doc/src/images/javastyle/sizegripimage.png new file mode 100644 index 0000000..ccbf525 Binary files /dev/null and b/doc/src/images/javastyle/sizegripimage.png differ diff --git a/doc/src/images/javastyle/slider.png b/doc/src/images/javastyle/slider.png new file mode 100644 index 0000000..a382233 Binary files /dev/null and b/doc/src/images/javastyle/slider.png differ diff --git a/doc/src/images/javastyle/sliderhandle.png b/doc/src/images/javastyle/sliderhandle.png new file mode 100644 index 0000000..28b7544 Binary files /dev/null and b/doc/src/images/javastyle/sliderhandle.png differ diff --git a/doc/src/images/javastyle/sliderimage.png b/doc/src/images/javastyle/sliderimage.png new file mode 100644 index 0000000..df700dd Binary files /dev/null and b/doc/src/images/javastyle/sliderimage.png differ diff --git a/doc/src/images/javastyle/slidertroubble.png b/doc/src/images/javastyle/slidertroubble.png new file mode 100644 index 0000000..79eee81 Binary files /dev/null and b/doc/src/images/javastyle/slidertroubble.png differ diff --git a/doc/src/images/javastyle/spinbox.png b/doc/src/images/javastyle/spinbox.png new file mode 100644 index 0000000..ec9d6e0 Binary files /dev/null and b/doc/src/images/javastyle/spinbox.png differ diff --git a/doc/src/images/javastyle/spinboximage.png b/doc/src/images/javastyle/spinboximage.png new file mode 100644 index 0000000..d0d57c8 Binary files /dev/null and b/doc/src/images/javastyle/spinboximage.png differ diff --git a/doc/src/images/javastyle/splitter.png b/doc/src/images/javastyle/splitter.png new file mode 100644 index 0000000..5983804 Binary files /dev/null and b/doc/src/images/javastyle/splitter.png differ diff --git a/doc/src/images/javastyle/tab.png b/doc/src/images/javastyle/tab.png new file mode 100644 index 0000000..616580c Binary files /dev/null and b/doc/src/images/javastyle/tab.png differ diff --git a/doc/src/images/javastyle/tabwidget.png b/doc/src/images/javastyle/tabwidget.png new file mode 100644 index 0000000..737155c Binary files /dev/null and b/doc/src/images/javastyle/tabwidget.png differ diff --git a/doc/src/images/javastyle/titlebar.png b/doc/src/images/javastyle/titlebar.png new file mode 100644 index 0000000..5d7ecc4 Binary files /dev/null and b/doc/src/images/javastyle/titlebar.png differ diff --git a/doc/src/images/javastyle/titlebarimage.png b/doc/src/images/javastyle/titlebarimage.png new file mode 100644 index 0000000..50287ae Binary files /dev/null and b/doc/src/images/javastyle/titlebarimage.png differ diff --git a/doc/src/images/javastyle/toolbar.png b/doc/src/images/javastyle/toolbar.png new file mode 100644 index 0000000..e69e8df Binary files /dev/null and b/doc/src/images/javastyle/toolbar.png differ diff --git a/doc/src/images/javastyle/toolbarimage.png b/doc/src/images/javastyle/toolbarimage.png new file mode 100644 index 0000000..b9025f5 Binary files /dev/null and b/doc/src/images/javastyle/toolbarimage.png differ diff --git a/doc/src/images/javastyle/toolbox.png b/doc/src/images/javastyle/toolbox.png new file mode 100644 index 0000000..c5f61ec Binary files /dev/null and b/doc/src/images/javastyle/toolbox.png differ diff --git a/doc/src/images/javastyle/toolboximage.png b/doc/src/images/javastyle/toolboximage.png new file mode 100644 index 0000000..7bcbd26 Binary files /dev/null and b/doc/src/images/javastyle/toolboximage.png differ diff --git a/doc/src/images/javastyle/toolbutton.png b/doc/src/images/javastyle/toolbutton.png new file mode 100644 index 0000000..9167e83 Binary files /dev/null and b/doc/src/images/javastyle/toolbutton.png differ diff --git a/doc/src/images/javastyle/toolbuttonimage.png b/doc/src/images/javastyle/toolbuttonimage.png new file mode 100644 index 0000000..3217172 Binary files /dev/null and b/doc/src/images/javastyle/toolbuttonimage.png differ diff --git a/doc/src/images/javastyle/windowstabimage.png b/doc/src/images/javastyle/windowstabimage.png new file mode 100644 index 0000000..485e847 Binary files /dev/null and b/doc/src/images/javastyle/windowstabimage.png differ diff --git a/doc/src/images/layout-examples.png b/doc/src/images/layout-examples.png new file mode 100644 index 0000000..eb28127 Binary files /dev/null and b/doc/src/images/layout-examples.png differ diff --git a/doc/src/images/layout1.png b/doc/src/images/layout1.png new file mode 100644 index 0000000..98cee45 Binary files /dev/null and b/doc/src/images/layout1.png differ diff --git a/doc/src/images/layout2.png b/doc/src/images/layout2.png new file mode 100644 index 0000000..dfa2815 Binary files /dev/null and b/doc/src/images/layout2.png differ diff --git a/doc/src/images/layouts-examples.png b/doc/src/images/layouts-examples.png new file mode 100644 index 0000000..a7121a9 Binary files /dev/null and b/doc/src/images/layouts-examples.png differ diff --git a/doc/src/images/licensewizard-example.png b/doc/src/images/licensewizard-example.png new file mode 100644 index 0000000..97b3aaa Binary files /dev/null and b/doc/src/images/licensewizard-example.png differ diff --git a/doc/src/images/licensewizard-flow.png b/doc/src/images/licensewizard-flow.png new file mode 100644 index 0000000..76df63a Binary files /dev/null and b/doc/src/images/licensewizard-flow.png differ diff --git a/doc/src/images/licensewizard.png b/doc/src/images/licensewizard.png new file mode 100644 index 0000000..40925cc Binary files /dev/null and b/doc/src/images/licensewizard.png differ diff --git a/doc/src/images/lineedits-example.png b/doc/src/images/lineedits-example.png new file mode 100644 index 0000000..ff5e318 Binary files /dev/null and b/doc/src/images/lineedits-example.png differ diff --git a/doc/src/images/linguist-arrowpad_en.png b/doc/src/images/linguist-arrowpad_en.png new file mode 100644 index 0000000..9a95eb2 Binary files /dev/null and b/doc/src/images/linguist-arrowpad_en.png differ diff --git a/doc/src/images/linguist-arrowpad_fr.png b/doc/src/images/linguist-arrowpad_fr.png new file mode 100644 index 0000000..fc33f9f Binary files /dev/null and b/doc/src/images/linguist-arrowpad_fr.png differ diff --git a/doc/src/images/linguist-arrowpad_nl.png b/doc/src/images/linguist-arrowpad_nl.png new file mode 100644 index 0000000..f2645a8 Binary files /dev/null and b/doc/src/images/linguist-arrowpad_nl.png differ diff --git a/doc/src/images/linguist-auxlanguages.png b/doc/src/images/linguist-auxlanguages.png new file mode 100644 index 0000000..634605e Binary files /dev/null and b/doc/src/images/linguist-auxlanguages.png differ diff --git a/doc/src/images/linguist-batchtranslation.png b/doc/src/images/linguist-batchtranslation.png new file mode 100644 index 0000000..2423e9e Binary files /dev/null and b/doc/src/images/linguist-batchtranslation.png differ diff --git a/doc/src/images/linguist-check-empty.png b/doc/src/images/linguist-check-empty.png new file mode 100644 index 0000000..759a41b Binary files /dev/null and b/doc/src/images/linguist-check-empty.png differ diff --git a/doc/src/images/linguist-check-obsolete.png b/doc/src/images/linguist-check-obsolete.png new file mode 100644 index 0000000..b852b63 Binary files /dev/null and b/doc/src/images/linguist-check-obsolete.png differ diff --git a/doc/src/images/linguist-check-off.png b/doc/src/images/linguist-check-off.png new file mode 100644 index 0000000..640b689 Binary files /dev/null and b/doc/src/images/linguist-check-off.png differ diff --git a/doc/src/images/linguist-check-on.png b/doc/src/images/linguist-check-on.png new file mode 100644 index 0000000..afcaf63 Binary files /dev/null and b/doc/src/images/linguist-check-on.png differ diff --git a/doc/src/images/linguist-check-warning.png b/doc/src/images/linguist-check-warning.png new file mode 100644 index 0000000..f689c33 Binary files /dev/null and b/doc/src/images/linguist-check-warning.png differ diff --git a/doc/src/images/linguist-danger.png b/doc/src/images/linguist-danger.png new file mode 100644 index 0000000..e101577 Binary files /dev/null and b/doc/src/images/linguist-danger.png differ diff --git a/doc/src/images/linguist-doneandnext.png b/doc/src/images/linguist-doneandnext.png new file mode 100644 index 0000000..18f2fb6 Binary files /dev/null and b/doc/src/images/linguist-doneandnext.png differ diff --git a/doc/src/images/linguist-editcopy.png b/doc/src/images/linguist-editcopy.png new file mode 100644 index 0000000..d542c3b Binary files /dev/null and b/doc/src/images/linguist-editcopy.png differ diff --git a/doc/src/images/linguist-editcut.png b/doc/src/images/linguist-editcut.png new file mode 100644 index 0000000..38e55f7 Binary files /dev/null and b/doc/src/images/linguist-editcut.png differ diff --git a/doc/src/images/linguist-editfind.png b/doc/src/images/linguist-editfind.png new file mode 100644 index 0000000..6ea35e9 Binary files /dev/null and b/doc/src/images/linguist-editfind.png differ diff --git a/doc/src/images/linguist-editpaste.png b/doc/src/images/linguist-editpaste.png new file mode 100644 index 0000000..717dd86 Binary files /dev/null and b/doc/src/images/linguist-editpaste.png differ diff --git a/doc/src/images/linguist-editredo.png b/doc/src/images/linguist-editredo.png new file mode 100644 index 0000000..9d679fe Binary files /dev/null and b/doc/src/images/linguist-editredo.png differ diff --git a/doc/src/images/linguist-editundo.png b/doc/src/images/linguist-editundo.png new file mode 100644 index 0000000..eee23d2 Binary files /dev/null and b/doc/src/images/linguist-editundo.png differ diff --git a/doc/src/images/linguist-examples.png b/doc/src/images/linguist-examples.png new file mode 100644 index 0000000..c39ed5d Binary files /dev/null and b/doc/src/images/linguist-examples.png differ diff --git a/doc/src/images/linguist-fileopen.png b/doc/src/images/linguist-fileopen.png new file mode 100644 index 0000000..1b3e69f Binary files /dev/null and b/doc/src/images/linguist-fileopen.png differ diff --git a/doc/src/images/linguist-fileprint.png b/doc/src/images/linguist-fileprint.png new file mode 100644 index 0000000..2afb769 Binary files /dev/null and b/doc/src/images/linguist-fileprint.png differ diff --git a/doc/src/images/linguist-filesave.png b/doc/src/images/linguist-filesave.png new file mode 100644 index 0000000..46eac82 Binary files /dev/null and b/doc/src/images/linguist-filesave.png differ diff --git a/doc/src/images/linguist-finddialog.png b/doc/src/images/linguist-finddialog.png new file mode 100644 index 0000000..831a393 Binary files /dev/null and b/doc/src/images/linguist-finddialog.png differ diff --git a/doc/src/images/linguist-hellotr_en.png b/doc/src/images/linguist-hellotr_en.png new file mode 100644 index 0000000..6b3d807 Binary files /dev/null and b/doc/src/images/linguist-hellotr_en.png differ diff --git a/doc/src/images/linguist-hellotr_la.png b/doc/src/images/linguist-hellotr_la.png new file mode 100644 index 0000000..f1ecdb0 Binary files /dev/null and b/doc/src/images/linguist-hellotr_la.png differ diff --git a/doc/src/images/linguist-linguist.png b/doc/src/images/linguist-linguist.png new file mode 100644 index 0000000..303d20b Binary files /dev/null and b/doc/src/images/linguist-linguist.png differ diff --git a/doc/src/images/linguist-linguist_2.png b/doc/src/images/linguist-linguist_2.png new file mode 100644 index 0000000..9ef1c2c Binary files /dev/null and b/doc/src/images/linguist-linguist_2.png differ diff --git a/doc/src/images/linguist-menubar.png b/doc/src/images/linguist-menubar.png new file mode 100644 index 0000000..bc510be Binary files /dev/null and b/doc/src/images/linguist-menubar.png differ diff --git a/doc/src/images/linguist-next.png b/doc/src/images/linguist-next.png new file mode 100644 index 0000000..7700d6f Binary files /dev/null and b/doc/src/images/linguist-next.png differ diff --git a/doc/src/images/linguist-nextunfinished.png b/doc/src/images/linguist-nextunfinished.png new file mode 100644 index 0000000..05c92bd Binary files /dev/null and b/doc/src/images/linguist-nextunfinished.png differ diff --git a/doc/src/images/linguist-phrasebookdialog.png b/doc/src/images/linguist-phrasebookdialog.png new file mode 100644 index 0000000..eb5da70 Binary files /dev/null and b/doc/src/images/linguist-phrasebookdialog.png differ diff --git a/doc/src/images/linguist-phrasebookopen.png b/doc/src/images/linguist-phrasebookopen.png new file mode 100644 index 0000000..1b35455 Binary files /dev/null and b/doc/src/images/linguist-phrasebookopen.png differ diff --git a/doc/src/images/linguist-prev.png b/doc/src/images/linguist-prev.png new file mode 100644 index 0000000..99dc873 Binary files /dev/null and b/doc/src/images/linguist-prev.png differ diff --git a/doc/src/images/linguist-previewtool.png b/doc/src/images/linguist-previewtool.png new file mode 100644 index 0000000..c4fca3c Binary files /dev/null and b/doc/src/images/linguist-previewtool.png differ diff --git a/doc/src/images/linguist-prevunfinished.png b/doc/src/images/linguist-prevunfinished.png new file mode 100644 index 0000000..15c13ea Binary files /dev/null and b/doc/src/images/linguist-prevunfinished.png differ diff --git a/doc/src/images/linguist-toolbar.png b/doc/src/images/linguist-toolbar.png new file mode 100644 index 0000000..b45c31b Binary files /dev/null and b/doc/src/images/linguist-toolbar.png differ diff --git a/doc/src/images/linguist-translationfilesettings.png b/doc/src/images/linguist-translationfilesettings.png new file mode 100644 index 0000000..e524c05 Binary files /dev/null and b/doc/src/images/linguist-translationfilesettings.png differ diff --git a/doc/src/images/linguist-trollprint_10_en.png b/doc/src/images/linguist-trollprint_10_en.png new file mode 100644 index 0000000..e460481 Binary files /dev/null and b/doc/src/images/linguist-trollprint_10_en.png differ diff --git a/doc/src/images/linguist-trollprint_10_pt_bad.png b/doc/src/images/linguist-trollprint_10_pt_bad.png new file mode 100644 index 0000000..b96d477 Binary files /dev/null and b/doc/src/images/linguist-trollprint_10_pt_bad.png differ diff --git a/doc/src/images/linguist-trollprint_10_pt_good.png b/doc/src/images/linguist-trollprint_10_pt_good.png new file mode 100644 index 0000000..293c44a Binary files /dev/null and b/doc/src/images/linguist-trollprint_10_pt_good.png differ diff --git a/doc/src/images/linguist-trollprint_11_en.png b/doc/src/images/linguist-trollprint_11_en.png new file mode 100644 index 0000000..f718c99 Binary files /dev/null and b/doc/src/images/linguist-trollprint_11_en.png differ diff --git a/doc/src/images/linguist-trollprint_11_pt.png b/doc/src/images/linguist-trollprint_11_pt.png new file mode 100644 index 0000000..0ff8c39 Binary files /dev/null and b/doc/src/images/linguist-trollprint_11_pt.png differ diff --git a/doc/src/images/linguist-validateaccelerators.png b/doc/src/images/linguist-validateaccelerators.png new file mode 100644 index 0000000..4f72648 Binary files /dev/null and b/doc/src/images/linguist-validateaccelerators.png differ diff --git a/doc/src/images/linguist-validatephrases.png b/doc/src/images/linguist-validatephrases.png new file mode 100644 index 0000000..30c3ee6 Binary files /dev/null and b/doc/src/images/linguist-validatephrases.png differ diff --git a/doc/src/images/linguist-validateplacemarkers.png b/doc/src/images/linguist-validateplacemarkers.png new file mode 100644 index 0000000..cc127fd Binary files /dev/null and b/doc/src/images/linguist-validateplacemarkers.png differ diff --git a/doc/src/images/linguist-validatepunctuation.png b/doc/src/images/linguist-validatepunctuation.png new file mode 100644 index 0000000..3492f95 Binary files /dev/null and b/doc/src/images/linguist-validatepunctuation.png differ diff --git a/doc/src/images/linguist-whatsthis.png b/doc/src/images/linguist-whatsthis.png new file mode 100644 index 0000000..0b5d46a Binary files /dev/null and b/doc/src/images/linguist-whatsthis.png differ diff --git a/doc/src/images/localfortuneclient-example.png b/doc/src/images/localfortuneclient-example.png new file mode 100644 index 0000000..614784b Binary files /dev/null and b/doc/src/images/localfortuneclient-example.png differ diff --git a/doc/src/images/localfortuneserver-example.png b/doc/src/images/localfortuneserver-example.png new file mode 100644 index 0000000..2f04c75 Binary files /dev/null and b/doc/src/images/localfortuneserver-example.png differ diff --git a/doc/src/images/loopback-example.png b/doc/src/images/loopback-example.png new file mode 100644 index 0000000..2b1bd4a Binary files /dev/null and b/doc/src/images/loopback-example.png differ diff --git a/doc/src/images/mac-cocoa.png b/doc/src/images/mac-cocoa.png new file mode 100644 index 0000000..06c0ba0 Binary files /dev/null and b/doc/src/images/mac-cocoa.png differ diff --git a/doc/src/images/macintosh-calendarwidget.png b/doc/src/images/macintosh-calendarwidget.png new file mode 100644 index 0000000..2f74350 Binary files /dev/null and b/doc/src/images/macintosh-calendarwidget.png differ diff --git a/doc/src/images/macintosh-checkbox.png b/doc/src/images/macintosh-checkbox.png new file mode 100644 index 0000000..d0130e3 Binary files /dev/null and b/doc/src/images/macintosh-checkbox.png differ diff --git a/doc/src/images/macintosh-combobox.png b/doc/src/images/macintosh-combobox.png new file mode 100644 index 0000000..c1dc3c0 Binary files /dev/null and b/doc/src/images/macintosh-combobox.png differ diff --git a/doc/src/images/macintosh-dateedit.png b/doc/src/images/macintosh-dateedit.png new file mode 100644 index 0000000..45aee90 Binary files /dev/null and b/doc/src/images/macintosh-dateedit.png differ diff --git a/doc/src/images/macintosh-datetimeedit.png b/doc/src/images/macintosh-datetimeedit.png new file mode 100644 index 0000000..62af02d Binary files /dev/null and b/doc/src/images/macintosh-datetimeedit.png differ diff --git a/doc/src/images/macintosh-dial.png b/doc/src/images/macintosh-dial.png new file mode 100644 index 0000000..df0ffe2 Binary files /dev/null and b/doc/src/images/macintosh-dial.png differ diff --git a/doc/src/images/macintosh-doublespinbox.png b/doc/src/images/macintosh-doublespinbox.png new file mode 100644 index 0000000..a0695ff Binary files /dev/null and b/doc/src/images/macintosh-doublespinbox.png differ diff --git a/doc/src/images/macintosh-fontcombobox.png b/doc/src/images/macintosh-fontcombobox.png new file mode 100644 index 0000000..8a5a3c7 Binary files /dev/null and b/doc/src/images/macintosh-fontcombobox.png differ diff --git a/doc/src/images/macintosh-frame.png b/doc/src/images/macintosh-frame.png new file mode 100644 index 0000000..fee61a3 Binary files /dev/null and b/doc/src/images/macintosh-frame.png differ diff --git a/doc/src/images/macintosh-groupbox.png b/doc/src/images/macintosh-groupbox.png new file mode 100644 index 0000000..f6c7bce Binary files /dev/null and b/doc/src/images/macintosh-groupbox.png differ diff --git a/doc/src/images/macintosh-horizontalscrollbar.png b/doc/src/images/macintosh-horizontalscrollbar.png new file mode 100644 index 0000000..8b63572 Binary files /dev/null and b/doc/src/images/macintosh-horizontalscrollbar.png differ diff --git a/doc/src/images/macintosh-label.png b/doc/src/images/macintosh-label.png new file mode 100644 index 0000000..753aa4d Binary files /dev/null and b/doc/src/images/macintosh-label.png differ diff --git a/doc/src/images/macintosh-lcdnumber.png b/doc/src/images/macintosh-lcdnumber.png new file mode 100644 index 0000000..2ea9ea0 Binary files /dev/null and b/doc/src/images/macintosh-lcdnumber.png differ diff --git a/doc/src/images/macintosh-lineedit.png b/doc/src/images/macintosh-lineedit.png new file mode 100644 index 0000000..0e992c7 Binary files /dev/null and b/doc/src/images/macintosh-lineedit.png differ diff --git a/doc/src/images/macintosh-listview.png b/doc/src/images/macintosh-listview.png new file mode 100644 index 0000000..346e6427 Binary files /dev/null and b/doc/src/images/macintosh-listview.png differ diff --git a/doc/src/images/macintosh-menu.png b/doc/src/images/macintosh-menu.png new file mode 100644 index 0000000..59bdcea Binary files /dev/null and b/doc/src/images/macintosh-menu.png differ diff --git a/doc/src/images/macintosh-progressbar.png b/doc/src/images/macintosh-progressbar.png new file mode 100644 index 0000000..2dfc8ab Binary files /dev/null and b/doc/src/images/macintosh-progressbar.png differ diff --git a/doc/src/images/macintosh-pushbutton.png b/doc/src/images/macintosh-pushbutton.png new file mode 100644 index 0000000..7ec1491 Binary files /dev/null and b/doc/src/images/macintosh-pushbutton.png differ diff --git a/doc/src/images/macintosh-radiobutton.png b/doc/src/images/macintosh-radiobutton.png new file mode 100644 index 0000000..8b02f50 Binary files /dev/null and b/doc/src/images/macintosh-radiobutton.png differ diff --git a/doc/src/images/macintosh-slider.png b/doc/src/images/macintosh-slider.png new file mode 100644 index 0000000..bf0c546 Binary files /dev/null and b/doc/src/images/macintosh-slider.png differ diff --git a/doc/src/images/macintosh-spinbox.png b/doc/src/images/macintosh-spinbox.png new file mode 100644 index 0000000..4196c37 Binary files /dev/null and b/doc/src/images/macintosh-spinbox.png differ diff --git a/doc/src/images/macintosh-tableview.png b/doc/src/images/macintosh-tableview.png new file mode 100644 index 0000000..e651249 Binary files /dev/null and b/doc/src/images/macintosh-tableview.png differ diff --git a/doc/src/images/macintosh-tabwidget.png b/doc/src/images/macintosh-tabwidget.png new file mode 100644 index 0000000..1d174a4 Binary files /dev/null and b/doc/src/images/macintosh-tabwidget.png differ diff --git a/doc/src/images/macintosh-textedit.png b/doc/src/images/macintosh-textedit.png new file mode 100644 index 0000000..4f0ce36 Binary files /dev/null and b/doc/src/images/macintosh-textedit.png differ diff --git a/doc/src/images/macintosh-timeedit.png b/doc/src/images/macintosh-timeedit.png new file mode 100644 index 0000000..4bcfce3 Binary files /dev/null and b/doc/src/images/macintosh-timeedit.png differ diff --git a/doc/src/images/macintosh-toolbox.png b/doc/src/images/macintosh-toolbox.png new file mode 100644 index 0000000..18d41ea Binary files /dev/null and b/doc/src/images/macintosh-toolbox.png differ diff --git a/doc/src/images/macintosh-toolbutton.png b/doc/src/images/macintosh-toolbutton.png new file mode 100644 index 0000000..f91331c Binary files /dev/null and b/doc/src/images/macintosh-toolbutton.png differ diff --git a/doc/src/images/macintosh-treeview.png b/doc/src/images/macintosh-treeview.png new file mode 100644 index 0000000..afda6d8 Binary files /dev/null and b/doc/src/images/macintosh-treeview.png differ diff --git a/doc/src/images/macintosh-unified-toolbar.png b/doc/src/images/macintosh-unified-toolbar.png new file mode 100644 index 0000000..dadd836 Binary files /dev/null and b/doc/src/images/macintosh-unified-toolbar.png differ diff --git a/doc/src/images/macmainwindow.png b/doc/src/images/macmainwindow.png new file mode 100644 index 0000000..84eb11c Binary files /dev/null and b/doc/src/images/macmainwindow.png differ diff --git a/doc/src/images/mainwindow-contextmenu.png b/doc/src/images/mainwindow-contextmenu.png new file mode 100644 index 0000000..439ab21 Binary files /dev/null and b/doc/src/images/mainwindow-contextmenu.png differ diff --git a/doc/src/images/mainwindow-custom-dock.png b/doc/src/images/mainwindow-custom-dock.png new file mode 100644 index 0000000..ca86471 Binary files /dev/null and b/doc/src/images/mainwindow-custom-dock.png differ diff --git a/doc/src/images/mainwindow-demo.png b/doc/src/images/mainwindow-demo.png new file mode 100644 index 0000000..5799dc0 Binary files /dev/null and b/doc/src/images/mainwindow-demo.png differ diff --git a/doc/src/images/mainwindow-docks-example.png b/doc/src/images/mainwindow-docks-example.png new file mode 100644 index 0000000..a5641fd Binary files /dev/null and b/doc/src/images/mainwindow-docks-example.png differ diff --git a/doc/src/images/mainwindow-docks.png b/doc/src/images/mainwindow-docks.png new file mode 100644 index 0000000..24f42a2 Binary files /dev/null and b/doc/src/images/mainwindow-docks.png differ diff --git a/doc/src/images/mainwindow-examples.png b/doc/src/images/mainwindow-examples.png new file mode 100644 index 0000000..3e946a6 Binary files /dev/null and b/doc/src/images/mainwindow-examples.png differ diff --git a/doc/src/images/mainwindow-vertical-dock.png b/doc/src/images/mainwindow-vertical-dock.png new file mode 100644 index 0000000..b6996ec Binary files /dev/null and b/doc/src/images/mainwindow-vertical-dock.png differ diff --git a/doc/src/images/mainwindow-vertical-tabs.png b/doc/src/images/mainwindow-vertical-tabs.png new file mode 100644 index 0000000..fcb901a Binary files /dev/null and b/doc/src/images/mainwindow-vertical-tabs.png differ diff --git a/doc/src/images/mainwindowlayout.png b/doc/src/images/mainwindowlayout.png new file mode 100644 index 0000000..4776ce4 Binary files /dev/null and b/doc/src/images/mainwindowlayout.png differ diff --git a/doc/src/images/mainwindows-examples.png b/doc/src/images/mainwindows-examples.png new file mode 100644 index 0000000..45bf0ab Binary files /dev/null and b/doc/src/images/mainwindows-examples.png differ diff --git a/doc/src/images/mandelbrot-example.png b/doc/src/images/mandelbrot-example.png new file mode 100644 index 0000000..f581783 Binary files /dev/null and b/doc/src/images/mandelbrot-example.png differ diff --git a/doc/src/images/mandelbrot_scroll1.png b/doc/src/images/mandelbrot_scroll1.png new file mode 100644 index 0000000..b800455 Binary files /dev/null and b/doc/src/images/mandelbrot_scroll1.png differ diff --git a/doc/src/images/mandelbrot_scroll2.png b/doc/src/images/mandelbrot_scroll2.png new file mode 100644 index 0000000..704ea0a Binary files /dev/null and b/doc/src/images/mandelbrot_scroll2.png differ diff --git a/doc/src/images/mandelbrot_scroll3.png b/doc/src/images/mandelbrot_scroll3.png new file mode 100644 index 0000000..8b48211 Binary files /dev/null and b/doc/src/images/mandelbrot_scroll3.png differ diff --git a/doc/src/images/mandelbrot_zoom1.png b/doc/src/images/mandelbrot_zoom1.png new file mode 100644 index 0000000..30190e4 Binary files /dev/null and b/doc/src/images/mandelbrot_zoom1.png differ diff --git a/doc/src/images/mandelbrot_zoom2.png b/doc/src/images/mandelbrot_zoom2.png new file mode 100644 index 0000000..148ac77 Binary files /dev/null and b/doc/src/images/mandelbrot_zoom2.png differ diff --git a/doc/src/images/mandelbrot_zoom3.png b/doc/src/images/mandelbrot_zoom3.png new file mode 100644 index 0000000..a669f4b Binary files /dev/null and b/doc/src/images/mandelbrot_zoom3.png differ diff --git a/doc/src/images/masterdetail-example.png b/doc/src/images/masterdetail-example.png new file mode 100644 index 0000000..bc282b7 Binary files /dev/null and b/doc/src/images/masterdetail-example.png differ diff --git a/doc/src/images/mdi-cascade.png b/doc/src/images/mdi-cascade.png new file mode 100644 index 0000000..ca55a5b Binary files /dev/null and b/doc/src/images/mdi-cascade.png differ diff --git a/doc/src/images/mdi-example.png b/doc/src/images/mdi-example.png new file mode 100644 index 0000000..240f9e2 Binary files /dev/null and b/doc/src/images/mdi-example.png differ diff --git a/doc/src/images/mdi-tile.png b/doc/src/images/mdi-tile.png new file mode 100644 index 0000000..1486d96 Binary files /dev/null and b/doc/src/images/mdi-tile.png differ diff --git a/doc/src/images/mediaplayer-demo.png b/doc/src/images/mediaplayer-demo.png new file mode 100644 index 0000000..2c1f9b4 Binary files /dev/null and b/doc/src/images/mediaplayer-demo.png differ diff --git a/doc/src/images/menus-example.png b/doc/src/images/menus-example.png new file mode 100644 index 0000000..81e6e0d Binary files /dev/null and b/doc/src/images/menus-example.png differ diff --git a/doc/src/images/modelindex-no-parent.png b/doc/src/images/modelindex-no-parent.png new file mode 100644 index 0000000..9c6258e Binary files /dev/null and b/doc/src/images/modelindex-no-parent.png differ diff --git a/doc/src/images/modelindex-parent.png b/doc/src/images/modelindex-parent.png new file mode 100644 index 0000000..26d4158 Binary files /dev/null and b/doc/src/images/modelindex-parent.png differ diff --git a/doc/src/images/modelview-begin-append-columns.png b/doc/src/images/modelview-begin-append-columns.png new file mode 100644 index 0000000..8d13b17 Binary files /dev/null and b/doc/src/images/modelview-begin-append-columns.png differ diff --git a/doc/src/images/modelview-begin-append-rows.png b/doc/src/images/modelview-begin-append-rows.png new file mode 100644 index 0000000..50d04c3 Binary files /dev/null and b/doc/src/images/modelview-begin-append-rows.png differ diff --git a/doc/src/images/modelview-begin-insert-columns.png b/doc/src/images/modelview-begin-insert-columns.png new file mode 100644 index 0000000..30eeb82 Binary files /dev/null and b/doc/src/images/modelview-begin-insert-columns.png differ diff --git a/doc/src/images/modelview-begin-insert-rows.png b/doc/src/images/modelview-begin-insert-rows.png new file mode 100644 index 0000000..b4d6eda Binary files /dev/null and b/doc/src/images/modelview-begin-insert-rows.png differ diff --git a/doc/src/images/modelview-begin-remove-columns.png b/doc/src/images/modelview-begin-remove-columns.png new file mode 100644 index 0000000..aee60e0 Binary files /dev/null and b/doc/src/images/modelview-begin-remove-columns.png differ diff --git a/doc/src/images/modelview-begin-remove-rows.png b/doc/src/images/modelview-begin-remove-rows.png new file mode 100644 index 0000000..8e95187 Binary files /dev/null and b/doc/src/images/modelview-begin-remove-rows.png differ diff --git a/doc/src/images/modelview-listmodel.png b/doc/src/images/modelview-listmodel.png new file mode 100644 index 0000000..6be5e15 Binary files /dev/null and b/doc/src/images/modelview-listmodel.png differ diff --git a/doc/src/images/modelview-models.png b/doc/src/images/modelview-models.png new file mode 100644 index 0000000..183a7cf Binary files /dev/null and b/doc/src/images/modelview-models.png differ diff --git a/doc/src/images/modelview-overview.png b/doc/src/images/modelview-overview.png new file mode 100644 index 0000000..41e3a68 Binary files /dev/null and b/doc/src/images/modelview-overview.png differ diff --git a/doc/src/images/modelview-roles.png b/doc/src/images/modelview-roles.png new file mode 100644 index 0000000..2a60ce7 Binary files /dev/null and b/doc/src/images/modelview-roles.png differ diff --git a/doc/src/images/modelview-tablemodel.png b/doc/src/images/modelview-tablemodel.png new file mode 100644 index 0000000..9a9ea2f Binary files /dev/null and b/doc/src/images/modelview-tablemodel.png differ diff --git a/doc/src/images/modelview-treemodel.png b/doc/src/images/modelview-treemodel.png new file mode 100644 index 0000000..f7b02eb Binary files /dev/null and b/doc/src/images/modelview-treemodel.png differ diff --git a/doc/src/images/motif-calendarwidget.png b/doc/src/images/motif-calendarwidget.png new file mode 100644 index 0000000..4ce6aeb Binary files /dev/null and b/doc/src/images/motif-calendarwidget.png differ diff --git a/doc/src/images/motif-checkbox.png b/doc/src/images/motif-checkbox.png new file mode 100644 index 0000000..2a26327 Binary files /dev/null and b/doc/src/images/motif-checkbox.png differ diff --git a/doc/src/images/motif-combobox.png b/doc/src/images/motif-combobox.png new file mode 100644 index 0000000..2a288d9 Binary files /dev/null and b/doc/src/images/motif-combobox.png differ diff --git a/doc/src/images/motif-dateedit.png b/doc/src/images/motif-dateedit.png new file mode 100644 index 0000000..d00c45f Binary files /dev/null and b/doc/src/images/motif-dateedit.png differ diff --git a/doc/src/images/motif-datetimeedit.png b/doc/src/images/motif-datetimeedit.png new file mode 100644 index 0000000..cc43ef8 Binary files /dev/null and b/doc/src/images/motif-datetimeedit.png differ diff --git a/doc/src/images/motif-dial.png b/doc/src/images/motif-dial.png new file mode 100644 index 0000000..36b3ff7 Binary files /dev/null and b/doc/src/images/motif-dial.png differ diff --git a/doc/src/images/motif-doublespinbox.png b/doc/src/images/motif-doublespinbox.png new file mode 100644 index 0000000..6092913 Binary files /dev/null and b/doc/src/images/motif-doublespinbox.png differ diff --git a/doc/src/images/motif-fontcombobox.png b/doc/src/images/motif-fontcombobox.png new file mode 100644 index 0000000..c07452d Binary files /dev/null and b/doc/src/images/motif-fontcombobox.png differ diff --git a/doc/src/images/motif-frame.png b/doc/src/images/motif-frame.png new file mode 100644 index 0000000..55dcc32 Binary files /dev/null and b/doc/src/images/motif-frame.png differ diff --git a/doc/src/images/motif-groupbox.png b/doc/src/images/motif-groupbox.png new file mode 100644 index 0000000..13742b1 Binary files /dev/null and b/doc/src/images/motif-groupbox.png differ diff --git a/doc/src/images/motif-horizontalscrollbar.png b/doc/src/images/motif-horizontalscrollbar.png new file mode 100644 index 0000000..dab1d3f Binary files /dev/null and b/doc/src/images/motif-horizontalscrollbar.png differ diff --git a/doc/src/images/motif-label.png b/doc/src/images/motif-label.png new file mode 100644 index 0000000..7ae6674 Binary files /dev/null and b/doc/src/images/motif-label.png differ diff --git a/doc/src/images/motif-lcdnumber.png b/doc/src/images/motif-lcdnumber.png new file mode 100644 index 0000000..e2cc9a8 Binary files /dev/null and b/doc/src/images/motif-lcdnumber.png differ diff --git a/doc/src/images/motif-lineedit.png b/doc/src/images/motif-lineedit.png new file mode 100644 index 0000000..a335c8c Binary files /dev/null and b/doc/src/images/motif-lineedit.png differ diff --git a/doc/src/images/motif-listview.png b/doc/src/images/motif-listview.png new file mode 100644 index 0000000..47bd3ea Binary files /dev/null and b/doc/src/images/motif-listview.png differ diff --git a/doc/src/images/motif-menubar.png b/doc/src/images/motif-menubar.png new file mode 100644 index 0000000..f1d9f4b Binary files /dev/null and b/doc/src/images/motif-menubar.png differ diff --git a/doc/src/images/motif-progressbar.png b/doc/src/images/motif-progressbar.png new file mode 100644 index 0000000..f6d6979 Binary files /dev/null and b/doc/src/images/motif-progressbar.png differ diff --git a/doc/src/images/motif-pushbutton.png b/doc/src/images/motif-pushbutton.png new file mode 100644 index 0000000..9dc6a9d Binary files /dev/null and b/doc/src/images/motif-pushbutton.png differ diff --git a/doc/src/images/motif-radiobutton.png b/doc/src/images/motif-radiobutton.png new file mode 100644 index 0000000..468e54c Binary files /dev/null and b/doc/src/images/motif-radiobutton.png differ diff --git a/doc/src/images/motif-slider.png b/doc/src/images/motif-slider.png new file mode 100644 index 0000000..6301e2b Binary files /dev/null and b/doc/src/images/motif-slider.png differ diff --git a/doc/src/images/motif-spinbox.png b/doc/src/images/motif-spinbox.png new file mode 100644 index 0000000..9acc282 Binary files /dev/null and b/doc/src/images/motif-spinbox.png differ diff --git a/doc/src/images/motif-tableview.png b/doc/src/images/motif-tableview.png new file mode 100644 index 0000000..a1d205a Binary files /dev/null and b/doc/src/images/motif-tableview.png differ diff --git a/doc/src/images/motif-tabwidget.png b/doc/src/images/motif-tabwidget.png new file mode 100644 index 0000000..19da66a Binary files /dev/null and b/doc/src/images/motif-tabwidget.png differ diff --git a/doc/src/images/motif-textedit.png b/doc/src/images/motif-textedit.png new file mode 100644 index 0000000..205bc19 Binary files /dev/null and b/doc/src/images/motif-textedit.png differ diff --git a/doc/src/images/motif-timeedit.png b/doc/src/images/motif-timeedit.png new file mode 100644 index 0000000..1ad459b Binary files /dev/null and b/doc/src/images/motif-timeedit.png differ diff --git a/doc/src/images/motif-todo.png b/doc/src/images/motif-todo.png new file mode 100644 index 0000000..be39c48 Binary files /dev/null and b/doc/src/images/motif-todo.png differ diff --git a/doc/src/images/motif-toolbox.png b/doc/src/images/motif-toolbox.png new file mode 100644 index 0000000..4bc3c37 Binary files /dev/null and b/doc/src/images/motif-toolbox.png differ diff --git a/doc/src/images/motif-toolbutton.png b/doc/src/images/motif-toolbutton.png new file mode 100644 index 0000000..8ef51dd Binary files /dev/null and b/doc/src/images/motif-toolbutton.png differ diff --git a/doc/src/images/motif-treeview.png b/doc/src/images/motif-treeview.png new file mode 100644 index 0000000..a7dd0f2 Binary files /dev/null and b/doc/src/images/motif-treeview.png differ diff --git a/doc/src/images/movie-example.png b/doc/src/images/movie-example.png new file mode 100644 index 0000000..713f563 Binary files /dev/null and b/doc/src/images/movie-example.png differ diff --git a/doc/src/images/msgbox1.png b/doc/src/images/msgbox1.png new file mode 100644 index 0000000..1380e20 Binary files /dev/null and b/doc/src/images/msgbox1.png differ diff --git a/doc/src/images/msgbox2.png b/doc/src/images/msgbox2.png new file mode 100644 index 0000000..e794699 Binary files /dev/null and b/doc/src/images/msgbox2.png differ diff --git a/doc/src/images/msgbox3.png b/doc/src/images/msgbox3.png new file mode 100644 index 0000000..bd81f4d Binary files /dev/null and b/doc/src/images/msgbox3.png differ diff --git a/doc/src/images/msgbox4.png b/doc/src/images/msgbox4.png new file mode 100644 index 0000000..dbe6701 Binary files /dev/null and b/doc/src/images/msgbox4.png differ diff --git a/doc/src/images/multipleinheritance-example.png b/doc/src/images/multipleinheritance-example.png new file mode 100644 index 0000000..9e89292 Binary files /dev/null and b/doc/src/images/multipleinheritance-example.png differ diff --git a/doc/src/images/musicplayer.png b/doc/src/images/musicplayer.png new file mode 100644 index 0000000..4f3ebf7 Binary files /dev/null and b/doc/src/images/musicplayer.png differ diff --git a/doc/src/images/network-chat-example.png b/doc/src/images/network-chat-example.png new file mode 100644 index 0000000..949bb07 Binary files /dev/null and b/doc/src/images/network-chat-example.png differ diff --git a/doc/src/images/network-examples.png b/doc/src/images/network-examples.png new file mode 100644 index 0000000..15dfba8 Binary files /dev/null and b/doc/src/images/network-examples.png differ diff --git a/doc/src/images/noforeignkeys.png b/doc/src/images/noforeignkeys.png new file mode 100644 index 0000000..62a4452 Binary files /dev/null and b/doc/src/images/noforeignkeys.png differ diff --git a/doc/src/images/opengl-examples.png b/doc/src/images/opengl-examples.png new file mode 100644 index 0000000..8acdf8c Binary files /dev/null and b/doc/src/images/opengl-examples.png differ diff --git a/doc/src/images/orderform-example-detailsdialog.png b/doc/src/images/orderform-example-detailsdialog.png new file mode 100644 index 0000000..8826369 Binary files /dev/null and b/doc/src/images/orderform-example-detailsdialog.png differ diff --git a/doc/src/images/orderform-example.png b/doc/src/images/orderform-example.png new file mode 100644 index 0000000..c8545ad Binary files /dev/null and b/doc/src/images/orderform-example.png differ diff --git a/doc/src/images/overpainting-example.png b/doc/src/images/overpainting-example.png new file mode 100644 index 0000000..0368dca Binary files /dev/null and b/doc/src/images/overpainting-example.png differ diff --git a/doc/src/images/padnavigator-example.png b/doc/src/images/padnavigator-example.png new file mode 100644 index 0000000..d766557 Binary files /dev/null and b/doc/src/images/padnavigator-example.png differ diff --git a/doc/src/images/painterpaths-example.png b/doc/src/images/painterpaths-example.png new file mode 100644 index 0000000..7e1220d Binary files /dev/null and b/doc/src/images/painterpaths-example.png differ diff --git a/doc/src/images/painting-examples.png b/doc/src/images/painting-examples.png new file mode 100644 index 0000000..214004c Binary files /dev/null and b/doc/src/images/painting-examples.png differ diff --git a/doc/src/images/paintsystem-antialiasing.png b/doc/src/images/paintsystem-antialiasing.png new file mode 100644 index 0000000..1275841 Binary files /dev/null and b/doc/src/images/paintsystem-antialiasing.png differ diff --git a/doc/src/images/paintsystem-core.png b/doc/src/images/paintsystem-core.png new file mode 100644 index 0000000..7d6a8e5 Binary files /dev/null and b/doc/src/images/paintsystem-core.png differ diff --git a/doc/src/images/paintsystem-devices.png b/doc/src/images/paintsystem-devices.png new file mode 100644 index 0000000..7b81b7c Binary files /dev/null and b/doc/src/images/paintsystem-devices.png differ diff --git a/doc/src/images/paintsystem-fancygradient.png b/doc/src/images/paintsystem-fancygradient.png new file mode 100644 index 0000000..701df29 Binary files /dev/null and b/doc/src/images/paintsystem-fancygradient.png differ diff --git a/doc/src/images/paintsystem-gradients.png b/doc/src/images/paintsystem-gradients.png new file mode 100644 index 0000000..50b2ed3 Binary files /dev/null and b/doc/src/images/paintsystem-gradients.png differ diff --git a/doc/src/images/paintsystem-icon.png b/doc/src/images/paintsystem-icon.png new file mode 100644 index 0000000..4623db0 Binary files /dev/null and b/doc/src/images/paintsystem-icon.png differ diff --git a/doc/src/images/paintsystem-movie.png b/doc/src/images/paintsystem-movie.png new file mode 100644 index 0000000..992ea9e Binary files /dev/null and b/doc/src/images/paintsystem-movie.png differ diff --git a/doc/src/images/paintsystem-painterpath.png b/doc/src/images/paintsystem-painterpath.png new file mode 100644 index 0000000..f8154f2 Binary files /dev/null and b/doc/src/images/paintsystem-painterpath.png differ diff --git a/doc/src/images/paintsystem-stylepainter.png b/doc/src/images/paintsystem-stylepainter.png new file mode 100644 index 0000000..a67c6c5 Binary files /dev/null and b/doc/src/images/paintsystem-stylepainter.png differ diff --git a/doc/src/images/paintsystem-svg.png b/doc/src/images/paintsystem-svg.png new file mode 100644 index 0000000..ecc8ef8 Binary files /dev/null and b/doc/src/images/paintsystem-svg.png differ diff --git a/doc/src/images/palette.png b/doc/src/images/palette.png new file mode 100644 index 0000000..832a5a5 Binary files /dev/null and b/doc/src/images/palette.png differ diff --git a/doc/src/images/parent-child-widgets.png b/doc/src/images/parent-child-widgets.png new file mode 100644 index 0000000..094e2e9 Binary files /dev/null and b/doc/src/images/parent-child-widgets.png differ diff --git a/doc/src/images/pathexample.png b/doc/src/images/pathexample.png new file mode 100644 index 0000000..7a07db3 Binary files /dev/null and b/doc/src/images/pathexample.png differ diff --git a/doc/src/images/pathstroke-demo.png b/doc/src/images/pathstroke-demo.png new file mode 100644 index 0000000..2df765f Binary files /dev/null and b/doc/src/images/pathstroke-demo.png differ diff --git a/doc/src/images/patternist-importFlow.png b/doc/src/images/patternist-importFlow.png new file mode 100644 index 0000000..cca5fa0 Binary files /dev/null and b/doc/src/images/patternist-importFlow.png differ diff --git a/doc/src/images/patternist-wordProcessor.png b/doc/src/images/patternist-wordProcessor.png new file mode 100644 index 0000000..0901330 Binary files /dev/null and b/doc/src/images/patternist-wordProcessor.png differ diff --git a/doc/src/images/pbuffers-example.png b/doc/src/images/pbuffers-example.png new file mode 100644 index 0000000..bafb05a Binary files /dev/null and b/doc/src/images/pbuffers-example.png differ diff --git a/doc/src/images/pbuffers2-example.png b/doc/src/images/pbuffers2-example.png new file mode 100644 index 0000000..4a9c717 Binary files /dev/null and b/doc/src/images/pbuffers2-example.png differ diff --git a/doc/src/images/phonon-examples.png b/doc/src/images/phonon-examples.png new file mode 100644 index 0000000..56b5137 Binary files /dev/null and b/doc/src/images/phonon-examples.png differ diff --git a/doc/src/images/pixelator-example.png b/doc/src/images/pixelator-example.png new file mode 100644 index 0000000..b6273c7 Binary files /dev/null and b/doc/src/images/pixelator-example.png differ diff --git a/doc/src/images/pixmapfilter-example.png b/doc/src/images/pixmapfilter-example.png new file mode 100644 index 0000000..29a6ddc Binary files /dev/null and b/doc/src/images/pixmapfilter-example.png differ diff --git a/doc/src/images/pixmapfilterexample-colorize.png b/doc/src/images/pixmapfilterexample-colorize.png new file mode 100644 index 0000000..0e023a5 Binary files /dev/null and b/doc/src/images/pixmapfilterexample-colorize.png differ diff --git a/doc/src/images/pixmapfilterexample-dropshadow.png b/doc/src/images/pixmapfilterexample-dropshadow.png new file mode 100644 index 0000000..be43659 Binary files /dev/null and b/doc/src/images/pixmapfilterexample-dropshadow.png differ diff --git a/doc/src/images/plaintext-layout.png b/doc/src/images/plaintext-layout.png new file mode 100644 index 0000000..9172d7a Binary files /dev/null and b/doc/src/images/plaintext-layout.png differ diff --git a/doc/src/images/plastique-calendarwidget.png b/doc/src/images/plastique-calendarwidget.png new file mode 100644 index 0000000..5e65945 Binary files /dev/null and b/doc/src/images/plastique-calendarwidget.png differ diff --git a/doc/src/images/plastique-checkbox.png b/doc/src/images/plastique-checkbox.png new file mode 100644 index 0000000..91a5109 Binary files /dev/null and b/doc/src/images/plastique-checkbox.png differ diff --git a/doc/src/images/plastique-colordialog.png b/doc/src/images/plastique-colordialog.png new file mode 100644 index 0000000..68bf4d0 Binary files /dev/null and b/doc/src/images/plastique-colordialog.png differ diff --git a/doc/src/images/plastique-combobox.png b/doc/src/images/plastique-combobox.png new file mode 100644 index 0000000..e3bf8a3 Binary files /dev/null and b/doc/src/images/plastique-combobox.png differ diff --git a/doc/src/images/plastique-dateedit.png b/doc/src/images/plastique-dateedit.png new file mode 100644 index 0000000..2e28a40 Binary files /dev/null and b/doc/src/images/plastique-dateedit.png differ diff --git a/doc/src/images/plastique-datetimeedit.png b/doc/src/images/plastique-datetimeedit.png new file mode 100644 index 0000000..810bf16 Binary files /dev/null and b/doc/src/images/plastique-datetimeedit.png differ diff --git a/doc/src/images/plastique-dial.png b/doc/src/images/plastique-dial.png new file mode 100644 index 0000000..b65e7c7 Binary files /dev/null and b/doc/src/images/plastique-dial.png differ diff --git a/doc/src/images/plastique-dialogbuttonbox.png b/doc/src/images/plastique-dialogbuttonbox.png new file mode 100644 index 0000000..823b352 Binary files /dev/null and b/doc/src/images/plastique-dialogbuttonbox.png differ diff --git a/doc/src/images/plastique-doublespinbox.png b/doc/src/images/plastique-doublespinbox.png new file mode 100644 index 0000000..627c4a2 Binary files /dev/null and b/doc/src/images/plastique-doublespinbox.png differ diff --git a/doc/src/images/plastique-filedialog.png b/doc/src/images/plastique-filedialog.png new file mode 100644 index 0000000..60f3c4b Binary files /dev/null and b/doc/src/images/plastique-filedialog.png differ diff --git a/doc/src/images/plastique-fontcombobox-open.png b/doc/src/images/plastique-fontcombobox-open.png new file mode 100644 index 0000000..37816c4 Binary files /dev/null and b/doc/src/images/plastique-fontcombobox-open.png differ diff --git a/doc/src/images/plastique-fontcombobox.png b/doc/src/images/plastique-fontcombobox.png new file mode 100644 index 0000000..d382308 Binary files /dev/null and b/doc/src/images/plastique-fontcombobox.png differ diff --git a/doc/src/images/plastique-fontdialog.png b/doc/src/images/plastique-fontdialog.png new file mode 100644 index 0000000..7e799a8 Binary files /dev/null and b/doc/src/images/plastique-fontdialog.png differ diff --git a/doc/src/images/plastique-frame.png b/doc/src/images/plastique-frame.png new file mode 100644 index 0000000..9f81f6c Binary files /dev/null and b/doc/src/images/plastique-frame.png differ diff --git a/doc/src/images/plastique-groupbox.png b/doc/src/images/plastique-groupbox.png new file mode 100644 index 0000000..d353c40 Binary files /dev/null and b/doc/src/images/plastique-groupbox.png differ diff --git a/doc/src/images/plastique-horizontalscrollbar.png b/doc/src/images/plastique-horizontalscrollbar.png new file mode 100644 index 0000000..d20300c Binary files /dev/null and b/doc/src/images/plastique-horizontalscrollbar.png differ diff --git a/doc/src/images/plastique-label.png b/doc/src/images/plastique-label.png new file mode 100644 index 0000000..d2a55a8 Binary files /dev/null and b/doc/src/images/plastique-label.png differ diff --git a/doc/src/images/plastique-lcdnumber.png b/doc/src/images/plastique-lcdnumber.png new file mode 100644 index 0000000..74149ee Binary files /dev/null and b/doc/src/images/plastique-lcdnumber.png differ diff --git a/doc/src/images/plastique-lineedit.png b/doc/src/images/plastique-lineedit.png new file mode 100644 index 0000000..f455383 Binary files /dev/null and b/doc/src/images/plastique-lineedit.png differ diff --git a/doc/src/images/plastique-listview.png b/doc/src/images/plastique-listview.png new file mode 100644 index 0000000..64bd00f Binary files /dev/null and b/doc/src/images/plastique-listview.png differ diff --git a/doc/src/images/plastique-menu.png b/doc/src/images/plastique-menu.png new file mode 100644 index 0000000..88df249 Binary files /dev/null and b/doc/src/images/plastique-menu.png differ diff --git a/doc/src/images/plastique-menubar.png b/doc/src/images/plastique-menubar.png new file mode 100644 index 0000000..642f95d Binary files /dev/null and b/doc/src/images/plastique-menubar.png differ diff --git a/doc/src/images/plastique-messagebox.png b/doc/src/images/plastique-messagebox.png new file mode 100644 index 0000000..89178fc Binary files /dev/null and b/doc/src/images/plastique-messagebox.png differ diff --git a/doc/src/images/plastique-printdialog-properties.png b/doc/src/images/plastique-printdialog-properties.png new file mode 100644 index 0000000..38c1ae7 Binary files /dev/null and b/doc/src/images/plastique-printdialog-properties.png differ diff --git a/doc/src/images/plastique-printdialog.png b/doc/src/images/plastique-printdialog.png new file mode 100644 index 0000000..3f8af01 Binary files /dev/null and b/doc/src/images/plastique-printdialog.png differ diff --git a/doc/src/images/plastique-progressbar.png b/doc/src/images/plastique-progressbar.png new file mode 100644 index 0000000..fe8dd90 Binary files /dev/null and b/doc/src/images/plastique-progressbar.png differ diff --git a/doc/src/images/plastique-progressdialog.png b/doc/src/images/plastique-progressdialog.png new file mode 100644 index 0000000..4373bca Binary files /dev/null and b/doc/src/images/plastique-progressdialog.png differ diff --git a/doc/src/images/plastique-pushbutton-menu.png b/doc/src/images/plastique-pushbutton-menu.png new file mode 100644 index 0000000..d090033 Binary files /dev/null and b/doc/src/images/plastique-pushbutton-menu.png differ diff --git a/doc/src/images/plastique-pushbutton.png b/doc/src/images/plastique-pushbutton.png new file mode 100644 index 0000000..83c44fd Binary files /dev/null and b/doc/src/images/plastique-pushbutton.png differ diff --git a/doc/src/images/plastique-radiobutton.png b/doc/src/images/plastique-radiobutton.png new file mode 100644 index 0000000..a2c820d Binary files /dev/null and b/doc/src/images/plastique-radiobutton.png differ diff --git a/doc/src/images/plastique-sizegrip.png b/doc/src/images/plastique-sizegrip.png new file mode 100644 index 0000000..09a551e Binary files /dev/null and b/doc/src/images/plastique-sizegrip.png differ diff --git a/doc/src/images/plastique-slider.png b/doc/src/images/plastique-slider.png new file mode 100644 index 0000000..492f0fd Binary files /dev/null and b/doc/src/images/plastique-slider.png differ diff --git a/doc/src/images/plastique-spinbox.png b/doc/src/images/plastique-spinbox.png new file mode 100644 index 0000000..af15db3 Binary files /dev/null and b/doc/src/images/plastique-spinbox.png differ diff --git a/doc/src/images/plastique-statusbar.png b/doc/src/images/plastique-statusbar.png new file mode 100644 index 0000000..c8f9792 Binary files /dev/null and b/doc/src/images/plastique-statusbar.png differ diff --git a/doc/src/images/plastique-tabbar-truncated.png b/doc/src/images/plastique-tabbar-truncated.png new file mode 100644 index 0000000..8e906d9 Binary files /dev/null and b/doc/src/images/plastique-tabbar-truncated.png differ diff --git a/doc/src/images/plastique-tabbar.png b/doc/src/images/plastique-tabbar.png new file mode 100644 index 0000000..3371dda Binary files /dev/null and b/doc/src/images/plastique-tabbar.png differ diff --git a/doc/src/images/plastique-tableview.png b/doc/src/images/plastique-tableview.png new file mode 100644 index 0000000..b20c1cc Binary files /dev/null and b/doc/src/images/plastique-tableview.png differ diff --git a/doc/src/images/plastique-tabwidget.png b/doc/src/images/plastique-tabwidget.png new file mode 100644 index 0000000..92ae398 Binary files /dev/null and b/doc/src/images/plastique-tabwidget.png differ diff --git a/doc/src/images/plastique-textedit.png b/doc/src/images/plastique-textedit.png new file mode 100644 index 0000000..a802d75 Binary files /dev/null and b/doc/src/images/plastique-textedit.png differ diff --git a/doc/src/images/plastique-timeedit.png b/doc/src/images/plastique-timeedit.png new file mode 100644 index 0000000..2d70b84 Binary files /dev/null and b/doc/src/images/plastique-timeedit.png differ diff --git a/doc/src/images/plastique-toolbox.png b/doc/src/images/plastique-toolbox.png new file mode 100644 index 0000000..10bcd7a Binary files /dev/null and b/doc/src/images/plastique-toolbox.png differ diff --git a/doc/src/images/plastique-toolbutton.png b/doc/src/images/plastique-toolbutton.png new file mode 100644 index 0000000..4e51831 Binary files /dev/null and b/doc/src/images/plastique-toolbutton.png differ diff --git a/doc/src/images/plastique-treeview.png b/doc/src/images/plastique-treeview.png new file mode 100644 index 0000000..db0bc01 Binary files /dev/null and b/doc/src/images/plastique-treeview.png differ diff --git a/doc/src/images/plugandpaint-plugindialog.png b/doc/src/images/plugandpaint-plugindialog.png new file mode 100644 index 0000000..4b601bd Binary files /dev/null and b/doc/src/images/plugandpaint-plugindialog.png differ diff --git a/doc/src/images/plugandpaint.png b/doc/src/images/plugandpaint.png new file mode 100644 index 0000000..bd5d001 Binary files /dev/null and b/doc/src/images/plugandpaint.png differ diff --git a/doc/src/images/portedasteroids-example.png b/doc/src/images/portedasteroids-example.png new file mode 100644 index 0000000..8dbe673 Binary files /dev/null and b/doc/src/images/portedasteroids-example.png differ diff --git a/doc/src/images/portedcanvas-example.png b/doc/src/images/portedcanvas-example.png new file mode 100644 index 0000000..b5fce51 Binary files /dev/null and b/doc/src/images/portedcanvas-example.png differ diff --git a/doc/src/images/previewer-example.png b/doc/src/images/previewer-example.png new file mode 100644 index 0000000..d930250 Binary files /dev/null and b/doc/src/images/previewer-example.png differ diff --git a/doc/src/images/previewer-ui.png b/doc/src/images/previewer-ui.png new file mode 100644 index 0000000..c92d136 Binary files /dev/null and b/doc/src/images/previewer-ui.png differ diff --git a/doc/src/images/printer-rects.png b/doc/src/images/printer-rects.png new file mode 100644 index 0000000..8ebea60 Binary files /dev/null and b/doc/src/images/printer-rects.png differ diff --git a/doc/src/images/progressBar-stylesheet.png b/doc/src/images/progressBar-stylesheet.png new file mode 100644 index 0000000..b4bf755 Binary files /dev/null and b/doc/src/images/progressBar-stylesheet.png differ diff --git a/doc/src/images/progressBar2-stylesheet.png b/doc/src/images/progressBar2-stylesheet.png new file mode 100644 index 0000000..8b5ecc0 Binary files /dev/null and b/doc/src/images/progressBar2-stylesheet.png differ diff --git a/doc/src/images/propagation-custom.png b/doc/src/images/propagation-custom.png new file mode 100644 index 0000000..866b44d Binary files /dev/null and b/doc/src/images/propagation-custom.png differ diff --git a/doc/src/images/propagation-standard.png b/doc/src/images/propagation-standard.png new file mode 100644 index 0000000..b010fcc Binary files /dev/null and b/doc/src/images/propagation-standard.png differ diff --git a/doc/src/images/q3painter_rationale.png b/doc/src/images/q3painter_rationale.png new file mode 100644 index 0000000..3c4835b Binary files /dev/null and b/doc/src/images/q3painter_rationale.png differ diff --git a/doc/src/images/qactiongroup-align.png b/doc/src/images/qactiongroup-align.png new file mode 100644 index 0000000..65683e0 Binary files /dev/null and b/doc/src/images/qactiongroup-align.png differ diff --git a/doc/src/images/qcalendarwidget-grid.png b/doc/src/images/qcalendarwidget-grid.png new file mode 100644 index 0000000..3df4dd9 Binary files /dev/null and b/doc/src/images/qcalendarwidget-grid.png differ diff --git a/doc/src/images/qcalendarwidget-maximum.png b/doc/src/images/qcalendarwidget-maximum.png new file mode 100644 index 0000000..1e78d20 Binary files /dev/null and b/doc/src/images/qcalendarwidget-maximum.png differ diff --git a/doc/src/images/qcalendarwidget-minimum.png b/doc/src/images/qcalendarwidget-minimum.png new file mode 100644 index 0000000..f860429 Binary files /dev/null and b/doc/src/images/qcalendarwidget-minimum.png differ diff --git a/doc/src/images/qcalendarwidget.png b/doc/src/images/qcalendarwidget.png new file mode 100644 index 0000000..354a67a Binary files /dev/null and b/doc/src/images/qcalendarwidget.png differ diff --git a/doc/src/images/qcanvasellipse.png b/doc/src/images/qcanvasellipse.png new file mode 100644 index 0000000..1fe82d0 Binary files /dev/null and b/doc/src/images/qcanvasellipse.png differ diff --git a/doc/src/images/qcdestyle.png b/doc/src/images/qcdestyle.png new file mode 100644 index 0000000..74fb332 Binary files /dev/null and b/doc/src/images/qcdestyle.png differ diff --git a/doc/src/images/qcolor-cmyk.png b/doc/src/images/qcolor-cmyk.png new file mode 100644 index 0000000..dfe8f67 Binary files /dev/null and b/doc/src/images/qcolor-cmyk.png differ diff --git a/doc/src/images/qcolor-hsv.png b/doc/src/images/qcolor-hsv.png new file mode 100644 index 0000000..49fdf77 Binary files /dev/null and b/doc/src/images/qcolor-hsv.png differ diff --git a/doc/src/images/qcolor-hue.png b/doc/src/images/qcolor-hue.png new file mode 100644 index 0000000..144b27c Binary files /dev/null and b/doc/src/images/qcolor-hue.png differ diff --git a/doc/src/images/qcolor-rgb.png b/doc/src/images/qcolor-rgb.png new file mode 100644 index 0000000..fea4c63 Binary files /dev/null and b/doc/src/images/qcolor-rgb.png differ diff --git a/doc/src/images/qcolor-saturation.png b/doc/src/images/qcolor-saturation.png new file mode 100644 index 0000000..f28776a Binary files /dev/null and b/doc/src/images/qcolor-saturation.png differ diff --git a/doc/src/images/qcolor-value.png b/doc/src/images/qcolor-value.png new file mode 100644 index 0000000..0e06912 Binary files /dev/null and b/doc/src/images/qcolor-value.png differ diff --git a/doc/src/images/qcolumnview.png b/doc/src/images/qcolumnview.png new file mode 100644 index 0000000..1d312bf Binary files /dev/null and b/doc/src/images/qcolumnview.png differ diff --git a/doc/src/images/qconicalgradient.png b/doc/src/images/qconicalgradient.png new file mode 100644 index 0000000..8260306 Binary files /dev/null and b/doc/src/images/qconicalgradient.png differ diff --git a/doc/src/images/qdatawidgetmapper-simple.png b/doc/src/images/qdatawidgetmapper-simple.png new file mode 100644 index 0000000..784a433 Binary files /dev/null and b/doc/src/images/qdatawidgetmapper-simple.png differ diff --git a/doc/src/images/qdesktopwidget.png b/doc/src/images/qdesktopwidget.png new file mode 100644 index 0000000..02f8e8b Binary files /dev/null and b/doc/src/images/qdesktopwidget.png differ diff --git a/doc/src/images/qdockwindow.png b/doc/src/images/qdockwindow.png new file mode 100644 index 0000000..98d2502 Binary files /dev/null and b/doc/src/images/qdockwindow.png differ diff --git a/doc/src/images/qerrormessage.png b/doc/src/images/qerrormessage.png new file mode 100644 index 0000000..b905f8a Binary files /dev/null and b/doc/src/images/qerrormessage.png differ diff --git a/doc/src/images/qfiledialog-expanded.png b/doc/src/images/qfiledialog-expanded.png new file mode 100644 index 0000000..07d2606 Binary files /dev/null and b/doc/src/images/qfiledialog-expanded.png differ diff --git a/doc/src/images/qfiledialog-small.png b/doc/src/images/qfiledialog-small.png new file mode 100644 index 0000000..94d7aa5 Binary files /dev/null and b/doc/src/images/qfiledialog-small.png differ diff --git a/doc/src/images/qformlayout-kde.png b/doc/src/images/qformlayout-kde.png new file mode 100644 index 0000000..c32bb12 Binary files /dev/null and b/doc/src/images/qformlayout-kde.png differ diff --git a/doc/src/images/qformlayout-mac.png b/doc/src/images/qformlayout-mac.png new file mode 100644 index 0000000..0a0824e Binary files /dev/null and b/doc/src/images/qformlayout-mac.png differ diff --git a/doc/src/images/qformlayout-qpe.png b/doc/src/images/qformlayout-qpe.png new file mode 100644 index 0000000..3abecc5 Binary files /dev/null and b/doc/src/images/qformlayout-qpe.png differ diff --git a/doc/src/images/qformlayout-win.png b/doc/src/images/qformlayout-win.png new file mode 100644 index 0000000..1ed44bd Binary files /dev/null and b/doc/src/images/qformlayout-win.png differ diff --git a/doc/src/images/qformlayout-with-6-children.png b/doc/src/images/qformlayout-with-6-children.png new file mode 100644 index 0000000..f743599 Binary files /dev/null and b/doc/src/images/qformlayout-with-6-children.png differ diff --git a/doc/src/images/qgradient-conical.png b/doc/src/images/qgradient-conical.png new file mode 100644 index 0000000..cf06b70 Binary files /dev/null and b/doc/src/images/qgradient-conical.png differ diff --git a/doc/src/images/qgradient-linear.png b/doc/src/images/qgradient-linear.png new file mode 100644 index 0000000..5a5e880 Binary files /dev/null and b/doc/src/images/qgradient-linear.png differ diff --git a/doc/src/images/qgradient-radial.png b/doc/src/images/qgradient-radial.png new file mode 100644 index 0000000..95b9e9c Binary files /dev/null and b/doc/src/images/qgradient-radial.png differ diff --git a/doc/src/images/qgraphicsproxywidget-embed.png b/doc/src/images/qgraphicsproxywidget-embed.png new file mode 100644 index 0000000..10d8f6f Binary files /dev/null and b/doc/src/images/qgraphicsproxywidget-embed.png differ diff --git a/doc/src/images/qgridlayout-with-5-children.png b/doc/src/images/qgridlayout-with-5-children.png new file mode 100644 index 0000000..8d0c296 Binary files /dev/null and b/doc/src/images/qgridlayout-with-5-children.png differ diff --git a/doc/src/images/qhbox-m.png b/doc/src/images/qhbox-m.png new file mode 100644 index 0000000..4f0bc57 Binary files /dev/null and b/doc/src/images/qhbox-m.png differ diff --git a/doc/src/images/qhboxlayout-with-5-children.png b/doc/src/images/qhboxlayout-with-5-children.png new file mode 100644 index 0000000..9b48dc5 Binary files /dev/null and b/doc/src/images/qhboxlayout-with-5-children.png differ diff --git a/doc/src/images/qimage-32bit.png b/doc/src/images/qimage-32bit.png new file mode 100644 index 0000000..2a76d40 Binary files /dev/null and b/doc/src/images/qimage-32bit.png differ diff --git a/doc/src/images/qimage-32bit_scaled.png b/doc/src/images/qimage-32bit_scaled.png new file mode 100644 index 0000000..6932327 Binary files /dev/null and b/doc/src/images/qimage-32bit_scaled.png differ diff --git a/doc/src/images/qimage-8bit.png b/doc/src/images/qimage-8bit.png new file mode 100644 index 0000000..454e501 Binary files /dev/null and b/doc/src/images/qimage-8bit.png differ diff --git a/doc/src/images/qimage-8bit_scaled.png b/doc/src/images/qimage-8bit_scaled.png new file mode 100644 index 0000000..7cbf0f1 Binary files /dev/null and b/doc/src/images/qimage-8bit_scaled.png differ diff --git a/doc/src/images/qimage-scaling.png b/doc/src/images/qimage-scaling.png new file mode 100644 index 0000000..fcd7144 Binary files /dev/null and b/doc/src/images/qimage-scaling.png differ diff --git a/doc/src/images/qline-coordinates.png b/doc/src/images/qline-coordinates.png new file mode 100644 index 0000000..ac4fb98 Binary files /dev/null and b/doc/src/images/qline-coordinates.png differ diff --git a/doc/src/images/qline-point.png b/doc/src/images/qline-point.png new file mode 100644 index 0000000..3bc3664 Binary files /dev/null and b/doc/src/images/qline-point.png differ diff --git a/doc/src/images/qlineargradient-pad.png b/doc/src/images/qlineargradient-pad.png new file mode 100644 index 0000000..d77eb3d Binary files /dev/null and b/doc/src/images/qlineargradient-pad.png differ diff --git a/doc/src/images/qlineargradient-reflect.png b/doc/src/images/qlineargradient-reflect.png new file mode 100644 index 0000000..dd12665 Binary files /dev/null and b/doc/src/images/qlineargradient-reflect.png differ diff --git a/doc/src/images/qlineargradient-repeat.png b/doc/src/images/qlineargradient-repeat.png new file mode 100644 index 0000000..e38203c Binary files /dev/null and b/doc/src/images/qlineargradient-repeat.png differ diff --git a/doc/src/images/qlinef-angle-identicaldirection.png b/doc/src/images/qlinef-angle-identicaldirection.png new file mode 100644 index 0000000..18d6323 Binary files /dev/null and b/doc/src/images/qlinef-angle-identicaldirection.png differ diff --git a/doc/src/images/qlinef-angle-oppositedirection.png b/doc/src/images/qlinef-angle-oppositedirection.png new file mode 100644 index 0000000..bf52cfe Binary files /dev/null and b/doc/src/images/qlinef-angle-oppositedirection.png differ diff --git a/doc/src/images/qlinef-bounded.png b/doc/src/images/qlinef-bounded.png new file mode 100644 index 0000000..136dd50 Binary files /dev/null and b/doc/src/images/qlinef-bounded.png differ diff --git a/doc/src/images/qlinef-normalvector.png b/doc/src/images/qlinef-normalvector.png new file mode 100644 index 0000000..b7d944f Binary files /dev/null and b/doc/src/images/qlinef-normalvector.png differ diff --git a/doc/src/images/qlinef-unbounded.png b/doc/src/images/qlinef-unbounded.png new file mode 100644 index 0000000..75ead98 Binary files /dev/null and b/doc/src/images/qlinef-unbounded.png differ diff --git a/doc/src/images/qlistbox-m.png b/doc/src/images/qlistbox-m.png new file mode 100644 index 0000000..5b956bc Binary files /dev/null and b/doc/src/images/qlistbox-m.png differ diff --git a/doc/src/images/qlistbox-w.png b/doc/src/images/qlistbox-w.png new file mode 100644 index 0000000..19798ea Binary files /dev/null and b/doc/src/images/qlistbox-w.png differ diff --git a/doc/src/images/qlistviewitems.png b/doc/src/images/qlistviewitems.png new file mode 100644 index 0000000..fe862c7 Binary files /dev/null and b/doc/src/images/qlistviewitems.png differ diff --git a/doc/src/images/qmacstyle.png b/doc/src/images/qmacstyle.png new file mode 100644 index 0000000..dda3c35 Binary files /dev/null and b/doc/src/images/qmacstyle.png differ diff --git a/doc/src/images/qmainwindow-qdockareas.png b/doc/src/images/qmainwindow-qdockareas.png new file mode 100644 index 0000000..0eff42d Binary files /dev/null and b/doc/src/images/qmainwindow-qdockareas.png differ diff --git a/doc/src/images/qmatrix-combinedtransformation.png b/doc/src/images/qmatrix-combinedtransformation.png new file mode 100644 index 0000000..f791bfa Binary files /dev/null and b/doc/src/images/qmatrix-combinedtransformation.png differ diff --git a/doc/src/images/qmatrix-representation.png b/doc/src/images/qmatrix-representation.png new file mode 100644 index 0000000..2e3efd3 Binary files /dev/null and b/doc/src/images/qmatrix-representation.png differ diff --git a/doc/src/images/qmatrix-simpletransformation.png b/doc/src/images/qmatrix-simpletransformation.png new file mode 100644 index 0000000..dde8f4b Binary files /dev/null and b/doc/src/images/qmatrix-simpletransformation.png differ diff --git a/doc/src/images/qmdiarea-arrange.png b/doc/src/images/qmdiarea-arrange.png new file mode 100644 index 0000000..14b0af5 Binary files /dev/null and b/doc/src/images/qmdiarea-arrange.png differ diff --git a/doc/src/images/qmdisubwindowlayout.png b/doc/src/images/qmdisubwindowlayout.png new file mode 100644 index 0000000..ffe5cc3 Binary files /dev/null and b/doc/src/images/qmdisubwindowlayout.png differ diff --git a/doc/src/images/qmessagebox-crit.png b/doc/src/images/qmessagebox-crit.png new file mode 100644 index 0000000..f30d3ee Binary files /dev/null and b/doc/src/images/qmessagebox-crit.png differ diff --git a/doc/src/images/qmessagebox-info.png b/doc/src/images/qmessagebox-info.png new file mode 100644 index 0000000..1399406 Binary files /dev/null and b/doc/src/images/qmessagebox-info.png differ diff --git a/doc/src/images/qmessagebox-quest.png b/doc/src/images/qmessagebox-quest.png new file mode 100644 index 0000000..5943fdd Binary files /dev/null and b/doc/src/images/qmessagebox-quest.png differ diff --git a/doc/src/images/qmessagebox-warn.png b/doc/src/images/qmessagebox-warn.png new file mode 100644 index 0000000..26a212e Binary files /dev/null and b/doc/src/images/qmessagebox-warn.png differ diff --git a/doc/src/images/qmotifstyle.png b/doc/src/images/qmotifstyle.png new file mode 100644 index 0000000..b0a6d86 Binary files /dev/null and b/doc/src/images/qmotifstyle.png differ diff --git a/doc/src/images/qobjectxmlmodel-example.png b/doc/src/images/qobjectxmlmodel-example.png new file mode 100644 index 0000000..e40ba15 Binary files /dev/null and b/doc/src/images/qobjectxmlmodel-example.png differ diff --git a/doc/src/images/qpainter-affinetransformations.png b/doc/src/images/qpainter-affinetransformations.png new file mode 100644 index 0000000..fe2f9a0 Binary files /dev/null and b/doc/src/images/qpainter-affinetransformations.png differ diff --git a/doc/src/images/qpainter-angles.png b/doc/src/images/qpainter-angles.png new file mode 100644 index 0000000..00bd7d4 Binary files /dev/null and b/doc/src/images/qpainter-angles.png differ diff --git a/doc/src/images/qpainter-arc.png b/doc/src/images/qpainter-arc.png new file mode 100644 index 0000000..8cb9cec Binary files /dev/null and b/doc/src/images/qpainter-arc.png differ diff --git a/doc/src/images/qpainter-basicdrawing.png b/doc/src/images/qpainter-basicdrawing.png new file mode 100644 index 0000000..3be48c8 Binary files /dev/null and b/doc/src/images/qpainter-basicdrawing.png differ diff --git a/doc/src/images/qpainter-chord.png b/doc/src/images/qpainter-chord.png new file mode 100644 index 0000000..a809086 Binary files /dev/null and b/doc/src/images/qpainter-chord.png differ diff --git a/doc/src/images/qpainter-clock.png b/doc/src/images/qpainter-clock.png new file mode 100644 index 0000000..3634754 Binary files /dev/null and b/doc/src/images/qpainter-clock.png differ diff --git a/doc/src/images/qpainter-compositiondemo.png b/doc/src/images/qpainter-compositiondemo.png new file mode 100644 index 0000000..40f62c7 Binary files /dev/null and b/doc/src/images/qpainter-compositiondemo.png differ diff --git a/doc/src/images/qpainter-compositionmode.png b/doc/src/images/qpainter-compositionmode.png new file mode 100644 index 0000000..1557720 Binary files /dev/null and b/doc/src/images/qpainter-compositionmode.png differ diff --git a/doc/src/images/qpainter-compositionmode1.png b/doc/src/images/qpainter-compositionmode1.png new file mode 100644 index 0000000..6753093 Binary files /dev/null and b/doc/src/images/qpainter-compositionmode1.png differ diff --git a/doc/src/images/qpainter-compositionmode2.png b/doc/src/images/qpainter-compositionmode2.png new file mode 100644 index 0000000..fc05afb Binary files /dev/null and b/doc/src/images/qpainter-compositionmode2.png differ diff --git a/doc/src/images/qpainter-concentriccircles.png b/doc/src/images/qpainter-concentriccircles.png new file mode 100644 index 0000000..4889dcd Binary files /dev/null and b/doc/src/images/qpainter-concentriccircles.png differ diff --git a/doc/src/images/qpainter-ellipse.png b/doc/src/images/qpainter-ellipse.png new file mode 100644 index 0000000..e7e78c3 Binary files /dev/null and b/doc/src/images/qpainter-ellipse.png differ diff --git a/doc/src/images/qpainter-gradients.png b/doc/src/images/qpainter-gradients.png new file mode 100644 index 0000000..b7bc6a3 Binary files /dev/null and b/doc/src/images/qpainter-gradients.png differ diff --git a/doc/src/images/qpainter-line.png b/doc/src/images/qpainter-line.png new file mode 100644 index 0000000..5f1cd97 Binary files /dev/null and b/doc/src/images/qpainter-line.png differ diff --git a/doc/src/images/qpainter-painterpaths.png b/doc/src/images/qpainter-painterpaths.png new file mode 100644 index 0000000..0762ca9 Binary files /dev/null and b/doc/src/images/qpainter-painterpaths.png differ diff --git a/doc/src/images/qpainter-path.png b/doc/src/images/qpainter-path.png new file mode 100644 index 0000000..3570b16 Binary files /dev/null and b/doc/src/images/qpainter-path.png differ diff --git a/doc/src/images/qpainter-pathstroking.png b/doc/src/images/qpainter-pathstroking.png new file mode 100644 index 0000000..ab73c6a Binary files /dev/null and b/doc/src/images/qpainter-pathstroking.png differ diff --git a/doc/src/images/qpainter-pie.png b/doc/src/images/qpainter-pie.png new file mode 100644 index 0000000..7803901 Binary files /dev/null and b/doc/src/images/qpainter-pie.png differ diff --git a/doc/src/images/qpainter-polygon.png b/doc/src/images/qpainter-polygon.png new file mode 100644 index 0000000..3b6ea3c Binary files /dev/null and b/doc/src/images/qpainter-polygon.png differ diff --git a/doc/src/images/qpainter-rectangle.png b/doc/src/images/qpainter-rectangle.png new file mode 100644 index 0000000..05fdc88 Binary files /dev/null and b/doc/src/images/qpainter-rectangle.png differ diff --git a/doc/src/images/qpainter-rotation.png b/doc/src/images/qpainter-rotation.png new file mode 100644 index 0000000..6e24a0e Binary files /dev/null and b/doc/src/images/qpainter-rotation.png differ diff --git a/doc/src/images/qpainter-roundrect.png b/doc/src/images/qpainter-roundrect.png new file mode 100644 index 0000000..876a277 Binary files /dev/null and b/doc/src/images/qpainter-roundrect.png differ diff --git a/doc/src/images/qpainter-scale.png b/doc/src/images/qpainter-scale.png new file mode 100644 index 0000000..4fe582e Binary files /dev/null and b/doc/src/images/qpainter-scale.png differ diff --git a/doc/src/images/qpainter-text.png b/doc/src/images/qpainter-text.png new file mode 100644 index 0000000..af7821c Binary files /dev/null and b/doc/src/images/qpainter-text.png differ diff --git a/doc/src/images/qpainter-translation.png b/doc/src/images/qpainter-translation.png new file mode 100644 index 0000000..b3716ca Binary files /dev/null and b/doc/src/images/qpainter-translation.png differ diff --git a/doc/src/images/qpainter-vectordeformation.png b/doc/src/images/qpainter-vectordeformation.png new file mode 100644 index 0000000..aff95f4 Binary files /dev/null and b/doc/src/images/qpainter-vectordeformation.png differ diff --git a/doc/src/images/qpainterpath-addellipse.png b/doc/src/images/qpainterpath-addellipse.png new file mode 100644 index 0000000..98f8517 Binary files /dev/null and b/doc/src/images/qpainterpath-addellipse.png differ diff --git a/doc/src/images/qpainterpath-addpolygon.png b/doc/src/images/qpainterpath-addpolygon.png new file mode 100644 index 0000000..d36bde8 Binary files /dev/null and b/doc/src/images/qpainterpath-addpolygon.png differ diff --git a/doc/src/images/qpainterpath-addrectangle.png b/doc/src/images/qpainterpath-addrectangle.png new file mode 100644 index 0000000..be9283e Binary files /dev/null and b/doc/src/images/qpainterpath-addrectangle.png differ diff --git a/doc/src/images/qpainterpath-addtext.png b/doc/src/images/qpainterpath-addtext.png new file mode 100644 index 0000000..803a958 Binary files /dev/null and b/doc/src/images/qpainterpath-addtext.png differ diff --git a/doc/src/images/qpainterpath-arcto.png b/doc/src/images/qpainterpath-arcto.png new file mode 100644 index 0000000..fe60b08 Binary files /dev/null and b/doc/src/images/qpainterpath-arcto.png differ diff --git a/doc/src/images/qpainterpath-construction.png b/doc/src/images/qpainterpath-construction.png new file mode 100644 index 0000000..4beeba1 Binary files /dev/null and b/doc/src/images/qpainterpath-construction.png differ diff --git a/doc/src/images/qpainterpath-cubicto.png b/doc/src/images/qpainterpath-cubicto.png new file mode 100644 index 0000000..465bfec Binary files /dev/null and b/doc/src/images/qpainterpath-cubicto.png differ diff --git a/doc/src/images/qpainterpath-demo.png b/doc/src/images/qpainterpath-demo.png new file mode 100644 index 0000000..ceeed2f Binary files /dev/null and b/doc/src/images/qpainterpath-demo.png differ diff --git a/doc/src/images/qpainterpath-example.png b/doc/src/images/qpainterpath-example.png new file mode 100644 index 0000000..f2bd359 Binary files /dev/null and b/doc/src/images/qpainterpath-example.png differ diff --git a/doc/src/images/qpen-bevel.png b/doc/src/images/qpen-bevel.png new file mode 100644 index 0000000..8a30779 Binary files /dev/null and b/doc/src/images/qpen-bevel.png differ diff --git a/doc/src/images/qpen-custom.png b/doc/src/images/qpen-custom.png new file mode 100644 index 0000000..a2a038a Binary files /dev/null and b/doc/src/images/qpen-custom.png differ diff --git a/doc/src/images/qpen-dash.png b/doc/src/images/qpen-dash.png new file mode 100644 index 0000000..67082c3 Binary files /dev/null and b/doc/src/images/qpen-dash.png differ diff --git a/doc/src/images/qpen-dashdot.png b/doc/src/images/qpen-dashdot.png new file mode 100644 index 0000000..64b3846 Binary files /dev/null and b/doc/src/images/qpen-dashdot.png differ diff --git a/doc/src/images/qpen-dashdotdot.png b/doc/src/images/qpen-dashdotdot.png new file mode 100644 index 0000000..ff1b2e6 Binary files /dev/null and b/doc/src/images/qpen-dashdotdot.png differ diff --git a/doc/src/images/qpen-dashpattern.png b/doc/src/images/qpen-dashpattern.png new file mode 100644 index 0000000..e33cf58 Binary files /dev/null and b/doc/src/images/qpen-dashpattern.png differ diff --git a/doc/src/images/qpen-demo.png b/doc/src/images/qpen-demo.png new file mode 100644 index 0000000..3ea5108 Binary files /dev/null and b/doc/src/images/qpen-demo.png differ diff --git a/doc/src/images/qpen-dot.png b/doc/src/images/qpen-dot.png new file mode 100644 index 0000000..54e81c9 Binary files /dev/null and b/doc/src/images/qpen-dot.png differ diff --git a/doc/src/images/qpen-flat.png b/doc/src/images/qpen-flat.png new file mode 100644 index 0000000..06e2195 Binary files /dev/null and b/doc/src/images/qpen-flat.png differ diff --git a/doc/src/images/qpen-miter.png b/doc/src/images/qpen-miter.png new file mode 100644 index 0000000..025e003 Binary files /dev/null and b/doc/src/images/qpen-miter.png differ diff --git a/doc/src/images/qpen-miterlimit.png b/doc/src/images/qpen-miterlimit.png new file mode 100644 index 0000000..17a9072 Binary files /dev/null and b/doc/src/images/qpen-miterlimit.png differ diff --git a/doc/src/images/qpen-roundcap.png b/doc/src/images/qpen-roundcap.png new file mode 100644 index 0000000..77b22b2 Binary files /dev/null and b/doc/src/images/qpen-roundcap.png differ diff --git a/doc/src/images/qpen-roundjoin.png b/doc/src/images/qpen-roundjoin.png new file mode 100644 index 0000000..155e2aa Binary files /dev/null and b/doc/src/images/qpen-roundjoin.png differ diff --git a/doc/src/images/qpen-solid.png b/doc/src/images/qpen-solid.png new file mode 100644 index 0000000..e042b18 Binary files /dev/null and b/doc/src/images/qpen-solid.png differ diff --git a/doc/src/images/qpen-square.png b/doc/src/images/qpen-square.png new file mode 100644 index 0000000..ebc5d1e Binary files /dev/null and b/doc/src/images/qpen-square.png differ diff --git a/doc/src/images/qplastiquestyle.png b/doc/src/images/qplastiquestyle.png new file mode 100644 index 0000000..519f01d Binary files /dev/null and b/doc/src/images/qplastiquestyle.png differ diff --git a/doc/src/images/qprintpreviewdialog.png b/doc/src/images/qprintpreviewdialog.png new file mode 100644 index 0000000..a78a3f1 Binary files /dev/null and b/doc/src/images/qprintpreviewdialog.png differ diff --git a/doc/src/images/qprogbar-m.png b/doc/src/images/qprogbar-m.png new file mode 100644 index 0000000..dbe9b0a Binary files /dev/null and b/doc/src/images/qprogbar-m.png differ diff --git a/doc/src/images/qprogbar-w.png b/doc/src/images/qprogbar-w.png new file mode 100644 index 0000000..3a85ffe Binary files /dev/null and b/doc/src/images/qprogbar-w.png differ diff --git a/doc/src/images/qprogdlg-m.png b/doc/src/images/qprogdlg-m.png new file mode 100644 index 0000000..bc83ece Binary files /dev/null and b/doc/src/images/qprogdlg-m.png differ diff --git a/doc/src/images/qprogdlg-w.png b/doc/src/images/qprogdlg-w.png new file mode 100644 index 0000000..eda1f5c Binary files /dev/null and b/doc/src/images/qprogdlg-w.png differ diff --git a/doc/src/images/qradialgradient-pad.png b/doc/src/images/qradialgradient-pad.png new file mode 100644 index 0000000..6c1a6cb Binary files /dev/null and b/doc/src/images/qradialgradient-pad.png differ diff --git a/doc/src/images/qradialgradient-reflect.png b/doc/src/images/qradialgradient-reflect.png new file mode 100644 index 0000000..5122b18 Binary files /dev/null and b/doc/src/images/qradialgradient-reflect.png differ diff --git a/doc/src/images/qradialgradient-repeat.png b/doc/src/images/qradialgradient-repeat.png new file mode 100644 index 0000000..aa639b7 Binary files /dev/null and b/doc/src/images/qradialgradient-repeat.png differ diff --git a/doc/src/images/qrect-coordinates.png b/doc/src/images/qrect-coordinates.png new file mode 100644 index 0000000..2a2dae2 Binary files /dev/null and b/doc/src/images/qrect-coordinates.png differ diff --git a/doc/src/images/qrect-diagram-one.png b/doc/src/images/qrect-diagram-one.png new file mode 100644 index 0000000..a893be2 Binary files /dev/null and b/doc/src/images/qrect-diagram-one.png differ diff --git a/doc/src/images/qrect-diagram-three.png b/doc/src/images/qrect-diagram-three.png new file mode 100644 index 0000000..84fb35b Binary files /dev/null and b/doc/src/images/qrect-diagram-three.png differ diff --git a/doc/src/images/qrect-diagram-two.png b/doc/src/images/qrect-diagram-two.png new file mode 100644 index 0000000..e19caac Binary files /dev/null and b/doc/src/images/qrect-diagram-two.png differ diff --git a/doc/src/images/qrect-diagram-zero.png b/doc/src/images/qrect-diagram-zero.png new file mode 100644 index 0000000..90e3db0 Binary files /dev/null and b/doc/src/images/qrect-diagram-zero.png differ diff --git a/doc/src/images/qrect-intersect.png b/doc/src/images/qrect-intersect.png new file mode 100644 index 0000000..db68cd5 Binary files /dev/null and b/doc/src/images/qrect-intersect.png differ diff --git a/doc/src/images/qrect-unite.png b/doc/src/images/qrect-unite.png new file mode 100644 index 0000000..3f6239f Binary files /dev/null and b/doc/src/images/qrect-unite.png differ diff --git a/doc/src/images/qrectf-coordinates.png b/doc/src/images/qrectf-coordinates.png new file mode 100644 index 0000000..ccc6d82 Binary files /dev/null and b/doc/src/images/qrectf-coordinates.png differ diff --git a/doc/src/images/qrectf-diagram-one.png b/doc/src/images/qrectf-diagram-one.png new file mode 100644 index 0000000..842289c Binary files /dev/null and b/doc/src/images/qrectf-diagram-one.png differ diff --git a/doc/src/images/qrectf-diagram-three.png b/doc/src/images/qrectf-diagram-three.png new file mode 100644 index 0000000..e05106a Binary files /dev/null and b/doc/src/images/qrectf-diagram-three.png differ diff --git a/doc/src/images/qrectf-diagram-two.png b/doc/src/images/qrectf-diagram-two.png new file mode 100644 index 0000000..192d00d Binary files /dev/null and b/doc/src/images/qrectf-diagram-two.png differ diff --git a/doc/src/images/qscrollarea-noscrollbars.png b/doc/src/images/qscrollarea-noscrollbars.png new file mode 100644 index 0000000..a1520f3 Binary files /dev/null and b/doc/src/images/qscrollarea-noscrollbars.png differ diff --git a/doc/src/images/qscrollarea-onescrollbar.png b/doc/src/images/qscrollarea-onescrollbar.png new file mode 100644 index 0000000..b4f7976 Binary files /dev/null and b/doc/src/images/qscrollarea-onescrollbar.png differ diff --git a/doc/src/images/qscrollarea-twoscrollbars.png b/doc/src/images/qscrollarea-twoscrollbars.png new file mode 100644 index 0000000..bf720e4 Binary files /dev/null and b/doc/src/images/qscrollarea-twoscrollbars.png differ diff --git a/doc/src/images/qscrollbar-picture.png b/doc/src/images/qscrollbar-picture.png new file mode 100644 index 0000000..898e014 Binary files /dev/null and b/doc/src/images/qscrollbar-picture.png differ diff --git a/doc/src/images/qscrollbar-values.png b/doc/src/images/qscrollbar-values.png new file mode 100644 index 0000000..cea744b Binary files /dev/null and b/doc/src/images/qscrollbar-values.png differ diff --git a/doc/src/images/qscrollview-cl.png b/doc/src/images/qscrollview-cl.png new file mode 100644 index 0000000..a5cb0db Binary files /dev/null and b/doc/src/images/qscrollview-cl.png differ diff --git a/doc/src/images/qscrollview-vp.png b/doc/src/images/qscrollview-vp.png new file mode 100644 index 0000000..fc8b022 Binary files /dev/null and b/doc/src/images/qscrollview-vp.png differ diff --git a/doc/src/images/qscrollview-vp2.png b/doc/src/images/qscrollview-vp2.png new file mode 100644 index 0000000..8d1c3a3 Binary files /dev/null and b/doc/src/images/qscrollview-vp2.png differ diff --git a/doc/src/images/qsortfilterproxymodel-sorting.png b/doc/src/images/qsortfilterproxymodel-sorting.png new file mode 100644 index 0000000..de99d41 Binary files /dev/null and b/doc/src/images/qsortfilterproxymodel-sorting.png differ diff --git a/doc/src/images/qspinbox-plusminus.png b/doc/src/images/qspinbox-plusminus.png new file mode 100644 index 0000000..3b35a40 Binary files /dev/null and b/doc/src/images/qspinbox-plusminus.png differ diff --git a/doc/src/images/qspinbox-updown.png b/doc/src/images/qspinbox-updown.png new file mode 100644 index 0000000..a6caa44 Binary files /dev/null and b/doc/src/images/qspinbox-updown.png differ diff --git a/doc/src/images/qstatustipevent-action.png b/doc/src/images/qstatustipevent-action.png new file mode 100644 index 0000000..c5dcfd2 Binary files /dev/null and b/doc/src/images/qstatustipevent-action.png differ diff --git a/doc/src/images/qstatustipevent-widget.png b/doc/src/images/qstatustipevent-widget.png new file mode 100644 index 0000000..3cc0a1f Binary files /dev/null and b/doc/src/images/qstatustipevent-widget.png differ diff --git a/doc/src/images/qstyle-comboboxes.png b/doc/src/images/qstyle-comboboxes.png new file mode 100644 index 0000000..aecec91 Binary files /dev/null and b/doc/src/images/qstyle-comboboxes.png differ diff --git a/doc/src/images/qstyleoptiontoolbar-position.png b/doc/src/images/qstyleoptiontoolbar-position.png new file mode 100644 index 0000000..5eaae7e Binary files /dev/null and b/doc/src/images/qstyleoptiontoolbar-position.png differ diff --git a/doc/src/images/qt-colors.png b/doc/src/images/qt-colors.png new file mode 100644 index 0000000..524123f Binary files /dev/null and b/doc/src/images/qt-colors.png differ diff --git a/doc/src/images/qt-embedded-accelerateddriver.png b/doc/src/images/qt-embedded-accelerateddriver.png new file mode 100644 index 0000000..c44d0b6 Binary files /dev/null and b/doc/src/images/qt-embedded-accelerateddriver.png differ diff --git a/doc/src/images/qt-embedded-architecture.png b/doc/src/images/qt-embedded-architecture.png new file mode 100644 index 0000000..97a29d0 Binary files /dev/null and b/doc/src/images/qt-embedded-architecture.png differ diff --git a/doc/src/images/qt-embedded-architecture2.png b/doc/src/images/qt-embedded-architecture2.png new file mode 100644 index 0000000..f8c7fb1 Binary files /dev/null and b/doc/src/images/qt-embedded-architecture2.png differ diff --git a/doc/src/images/qt-embedded-characterinputlayer.png b/doc/src/images/qt-embedded-characterinputlayer.png new file mode 100644 index 0000000..bedc2b8 Binary files /dev/null and b/doc/src/images/qt-embedded-characterinputlayer.png differ diff --git a/doc/src/images/qt-embedded-clamshellphone-closed.png b/doc/src/images/qt-embedded-clamshellphone-closed.png new file mode 100644 index 0000000..2070f88 Binary files /dev/null and b/doc/src/images/qt-embedded-clamshellphone-closed.png differ diff --git a/doc/src/images/qt-embedded-clamshellphone-pressed.png b/doc/src/images/qt-embedded-clamshellphone-pressed.png new file mode 100644 index 0000000..e728bea Binary files /dev/null and b/doc/src/images/qt-embedded-clamshellphone-pressed.png differ diff --git a/doc/src/images/qt-embedded-clamshellphone.png b/doc/src/images/qt-embedded-clamshellphone.png new file mode 100644 index 0000000..dd3bd60 Binary files /dev/null and b/doc/src/images/qt-embedded-clamshellphone.png differ diff --git a/doc/src/images/qt-embedded-client.png b/doc/src/images/qt-embedded-client.png new file mode 100644 index 0000000..da64203 Binary files /dev/null and b/doc/src/images/qt-embedded-client.png differ diff --git a/doc/src/images/qt-embedded-clientrendering.png b/doc/src/images/qt-embedded-clientrendering.png new file mode 100644 index 0000000..49ae8f1 Binary files /dev/null and b/doc/src/images/qt-embedded-clientrendering.png differ diff --git a/doc/src/images/qt-embedded-clientservercommunication.png b/doc/src/images/qt-embedded-clientservercommunication.png new file mode 100644 index 0000000..0bdcb60 Binary files /dev/null and b/doc/src/images/qt-embedded-clientservercommunication.png differ diff --git a/doc/src/images/qt-embedded-drawingonscreen.png b/doc/src/images/qt-embedded-drawingonscreen.png new file mode 100644 index 0000000..fca1eba Binary files /dev/null and b/doc/src/images/qt-embedded-drawingonscreen.png differ diff --git a/doc/src/images/qt-embedded-examples.png b/doc/src/images/qt-embedded-examples.png new file mode 100644 index 0000000..7fc6965 Binary files /dev/null and b/doc/src/images/qt-embedded-examples.png differ diff --git a/doc/src/images/qt-embedded-fontfeatures.png b/doc/src/images/qt-embedded-fontfeatures.png new file mode 100644 index 0000000..c339171 Binary files /dev/null and b/doc/src/images/qt-embedded-fontfeatures.png differ diff --git a/doc/src/images/qt-embedded-opengl1.png b/doc/src/images/qt-embedded-opengl1.png new file mode 100644 index 0000000..28e2a5f Binary files /dev/null and b/doc/src/images/qt-embedded-opengl1.png differ diff --git a/doc/src/images/qt-embedded-opengl2.png b/doc/src/images/qt-embedded-opengl2.png new file mode 100644 index 0000000..3547cd7 Binary files /dev/null and b/doc/src/images/qt-embedded-opengl2.png differ diff --git a/doc/src/images/qt-embedded-opengl3.png b/doc/src/images/qt-embedded-opengl3.png new file mode 100644 index 0000000..0316b71 Binary files /dev/null and b/doc/src/images/qt-embedded-opengl3.png differ diff --git a/doc/src/images/qt-embedded-pda.png b/doc/src/images/qt-embedded-pda.png new file mode 100644 index 0000000..2bd9881 Binary files /dev/null and b/doc/src/images/qt-embedded-pda.png differ diff --git a/doc/src/images/qt-embedded-phone.png b/doc/src/images/qt-embedded-phone.png new file mode 100644 index 0000000..29df579 Binary files /dev/null and b/doc/src/images/qt-embedded-phone.png differ diff --git a/doc/src/images/qt-embedded-pointerhandlinglayer.png b/doc/src/images/qt-embedded-pointerhandlinglayer.png new file mode 100644 index 0000000..b82fb3b Binary files /dev/null and b/doc/src/images/qt-embedded-pointerhandlinglayer.png differ diff --git a/doc/src/images/qt-embedded-qconfigtool.png b/doc/src/images/qt-embedded-qconfigtool.png new file mode 100644 index 0000000..fbab4d6 Binary files /dev/null and b/doc/src/images/qt-embedded-qconfigtool.png differ diff --git a/doc/src/images/qt-embedded-qvfbfilemenu.png b/doc/src/images/qt-embedded-qvfbfilemenu.png new file mode 100644 index 0000000..e82287b Binary files /dev/null and b/doc/src/images/qt-embedded-qvfbfilemenu.png differ diff --git a/doc/src/images/qt-embedded-qvfbviewmenu.png b/doc/src/images/qt-embedded-qvfbviewmenu.png new file mode 100644 index 0000000..403bc66 Binary files /dev/null and b/doc/src/images/qt-embedded-qvfbviewmenu.png differ diff --git a/doc/src/images/qt-embedded-reserveregion.png b/doc/src/images/qt-embedded-reserveregion.png new file mode 100644 index 0000000..e20a748 Binary files /dev/null and b/doc/src/images/qt-embedded-reserveregion.png differ diff --git a/doc/src/images/qt-embedded-runningapplication.png b/doc/src/images/qt-embedded-runningapplication.png new file mode 100644 index 0000000..d7f9a51 Binary files /dev/null and b/doc/src/images/qt-embedded-runningapplication.png differ diff --git a/doc/src/images/qt-embedded-setwindowattribute.png b/doc/src/images/qt-embedded-setwindowattribute.png new file mode 100644 index 0000000..44daba9 Binary files /dev/null and b/doc/src/images/qt-embedded-setwindowattribute.png differ diff --git a/doc/src/images/qt-embedded-virtualframebuffer.png b/doc/src/images/qt-embedded-virtualframebuffer.png new file mode 100644 index 0000000..d5a5221 Binary files /dev/null and b/doc/src/images/qt-embedded-virtualframebuffer.png differ diff --git a/doc/src/images/qt-embedded-vnc-screen.png b/doc/src/images/qt-embedded-vnc-screen.png new file mode 100644 index 0000000..da06387 Binary files /dev/null and b/doc/src/images/qt-embedded-vnc-screen.png differ diff --git a/doc/src/images/qt-fillrule-oddeven.png b/doc/src/images/qt-fillrule-oddeven.png new file mode 100644 index 0000000..f39d105 Binary files /dev/null and b/doc/src/images/qt-fillrule-oddeven.png differ diff --git a/doc/src/images/qt-fillrule-winding.png b/doc/src/images/qt-fillrule-winding.png new file mode 100644 index 0000000..8018248 Binary files /dev/null and b/doc/src/images/qt-fillrule-winding.png differ diff --git a/doc/src/images/qt-for-wince-landscape.png b/doc/src/images/qt-for-wince-landscape.png new file mode 100644 index 0000000..127f799 Binary files /dev/null and b/doc/src/images/qt-for-wince-landscape.png differ diff --git a/doc/src/images/qt-logo.png b/doc/src/images/qt-logo.png new file mode 100644 index 0000000..14ddf2a Binary files /dev/null and b/doc/src/images/qt-logo.png differ diff --git a/doc/src/images/qt.png b/doc/src/images/qt.png new file mode 100644 index 0000000..cbed1a9 Binary files /dev/null and b/doc/src/images/qt.png differ diff --git a/doc/src/images/qtableitems.png b/doc/src/images/qtableitems.png new file mode 100644 index 0000000..c62813a Binary files /dev/null and b/doc/src/images/qtableitems.png differ diff --git a/doc/src/images/qtabletevent-tilt.png b/doc/src/images/qtabletevent-tilt.png new file mode 100644 index 0000000..546d7da Binary files /dev/null and b/doc/src/images/qtabletevent-tilt.png differ diff --git a/doc/src/images/qtableview-resized.png b/doc/src/images/qtableview-resized.png new file mode 100644 index 0000000..813256e Binary files /dev/null and b/doc/src/images/qtableview-resized.png differ diff --git a/doc/src/images/qtconcurrent-progressdialog.png b/doc/src/images/qtconcurrent-progressdialog.png new file mode 100644 index 0000000..2e8b773 Binary files /dev/null and b/doc/src/images/qtconcurrent-progressdialog.png differ diff --git a/doc/src/images/qtconfig-appearance.png b/doc/src/images/qtconfig-appearance.png new file mode 100644 index 0000000..27f7f2f Binary files /dev/null and b/doc/src/images/qtconfig-appearance.png differ diff --git a/doc/src/images/qtdemo-small.png b/doc/src/images/qtdemo-small.png new file mode 100644 index 0000000..d987ffa Binary files /dev/null and b/doc/src/images/qtdemo-small.png differ diff --git a/doc/src/images/qtdemo.png b/doc/src/images/qtdemo.png new file mode 100644 index 0000000..e7267a9 Binary files /dev/null and b/doc/src/images/qtdemo.png differ diff --git a/doc/src/images/qtdesignerextensions.png b/doc/src/images/qtdesignerextensions.png new file mode 100644 index 0000000..d48701e Binary files /dev/null and b/doc/src/images/qtdesignerextensions.png differ diff --git a/doc/src/images/qtdesignerscreenshot.png b/doc/src/images/qtdesignerscreenshot.png new file mode 100644 index 0000000..d71c986 Binary files /dev/null and b/doc/src/images/qtdesignerscreenshot.png differ diff --git a/doc/src/images/qtextblock-fragments.png b/doc/src/images/qtextblock-fragments.png new file mode 100644 index 0000000..777fba0 Binary files /dev/null and b/doc/src/images/qtextblock-fragments.png differ diff --git a/doc/src/images/qtextblock-sequence.png b/doc/src/images/qtextblock-sequence.png new file mode 100644 index 0000000..85f208e Binary files /dev/null and b/doc/src/images/qtextblock-sequence.png differ diff --git a/doc/src/images/qtextdocument-frames.png b/doc/src/images/qtextdocument-frames.png new file mode 100644 index 0000000..96a2dbb Binary files /dev/null and b/doc/src/images/qtextdocument-frames.png differ diff --git a/doc/src/images/qtextfragment-split.png b/doc/src/images/qtextfragment-split.png new file mode 100644 index 0000000..c232c40 Binary files /dev/null and b/doc/src/images/qtextfragment-split.png differ diff --git a/doc/src/images/qtextframe-style.png b/doc/src/images/qtextframe-style.png new file mode 100644 index 0000000..6151307 Binary files /dev/null and b/doc/src/images/qtextframe-style.png differ diff --git a/doc/src/images/qtexttable-cells.png b/doc/src/images/qtexttable-cells.png new file mode 100644 index 0000000..8460e60 Binary files /dev/null and b/doc/src/images/qtexttable-cells.png differ diff --git a/doc/src/images/qtexttableformat-cell.png b/doc/src/images/qtexttableformat-cell.png new file mode 100644 index 0000000..bbf85ff Binary files /dev/null and b/doc/src/images/qtexttableformat-cell.png differ diff --git a/doc/src/images/qtransform-combinedtransformation.png b/doc/src/images/qtransform-combinedtransformation.png new file mode 100644 index 0000000..df1e226 Binary files /dev/null and b/doc/src/images/qtransform-combinedtransformation.png differ diff --git a/doc/src/images/qtransform-combinedtransformation2.png b/doc/src/images/qtransform-combinedtransformation2.png new file mode 100644 index 0000000..c037a0d Binary files /dev/null and b/doc/src/images/qtransform-combinedtransformation2.png differ diff --git a/doc/src/images/qtransform-representation.png b/doc/src/images/qtransform-representation.png new file mode 100644 index 0000000..2608872 Binary files /dev/null and b/doc/src/images/qtransform-representation.png differ diff --git a/doc/src/images/qtransform-simpletransformation.png b/doc/src/images/qtransform-simpletransformation.png new file mode 100644 index 0000000..743e4e3 Binary files /dev/null and b/doc/src/images/qtransform-simpletransformation.png differ diff --git a/doc/src/images/qtscript-calculator-example.png b/doc/src/images/qtscript-calculator-example.png new file mode 100644 index 0000000..f2db906 Binary files /dev/null and b/doc/src/images/qtscript-calculator-example.png differ diff --git a/doc/src/images/qtscript-calculator.png b/doc/src/images/qtscript-calculator.png new file mode 100644 index 0000000..113c46b Binary files /dev/null and b/doc/src/images/qtscript-calculator.png differ diff --git a/doc/src/images/qtscript-context2d.png b/doc/src/images/qtscript-context2d.png new file mode 100644 index 0000000..05eaf6e Binary files /dev/null and b/doc/src/images/qtscript-context2d.png differ diff --git a/doc/src/images/qtscript-debugger-small.png b/doc/src/images/qtscript-debugger-small.png new file mode 100644 index 0000000..ffa60f4 Binary files /dev/null and b/doc/src/images/qtscript-debugger-small.png differ diff --git a/doc/src/images/qtscript-debugger.png b/doc/src/images/qtscript-debugger.png new file mode 100644 index 0000000..c417d0b Binary files /dev/null and b/doc/src/images/qtscript-debugger.png differ diff --git a/doc/src/images/qtscript-examples.png b/doc/src/images/qtscript-examples.png new file mode 100644 index 0000000..d2e9179 Binary files /dev/null and b/doc/src/images/qtscript-examples.png differ diff --git a/doc/src/images/qtscripttools-examples.png b/doc/src/images/qtscripttools-examples.png new file mode 100644 index 0000000..369f32e Binary files /dev/null and b/doc/src/images/qtscripttools-examples.png differ diff --git a/doc/src/images/qtwizard-aero1.png b/doc/src/images/qtwizard-aero1.png new file mode 100644 index 0000000..fe9e9bc Binary files /dev/null and b/doc/src/images/qtwizard-aero1.png differ diff --git a/doc/src/images/qtwizard-aero2.png b/doc/src/images/qtwizard-aero2.png new file mode 100644 index 0000000..261c065 Binary files /dev/null and b/doc/src/images/qtwizard-aero2.png differ diff --git a/doc/src/images/qtwizard-classic1.png b/doc/src/images/qtwizard-classic1.png new file mode 100644 index 0000000..be3edbe Binary files /dev/null and b/doc/src/images/qtwizard-classic1.png differ diff --git a/doc/src/images/qtwizard-classic2.png b/doc/src/images/qtwizard-classic2.png new file mode 100644 index 0000000..165f569 Binary files /dev/null and b/doc/src/images/qtwizard-classic2.png differ diff --git a/doc/src/images/qtwizard-mac1.png b/doc/src/images/qtwizard-mac1.png new file mode 100644 index 0000000..bc8cd9b Binary files /dev/null and b/doc/src/images/qtwizard-mac1.png differ diff --git a/doc/src/images/qtwizard-mac2.png b/doc/src/images/qtwizard-mac2.png new file mode 100644 index 0000000..850f6b8 Binary files /dev/null and b/doc/src/images/qtwizard-mac2.png differ diff --git a/doc/src/images/qtwizard-macpage.png b/doc/src/images/qtwizard-macpage.png new file mode 100644 index 0000000..1ba3122 Binary files /dev/null and b/doc/src/images/qtwizard-macpage.png differ diff --git a/doc/src/images/qtwizard-modern1.png b/doc/src/images/qtwizard-modern1.png new file mode 100644 index 0000000..223e3dd Binary files /dev/null and b/doc/src/images/qtwizard-modern1.png differ diff --git a/doc/src/images/qtwizard-modern2.png b/doc/src/images/qtwizard-modern2.png new file mode 100644 index 0000000..d66c374 Binary files /dev/null and b/doc/src/images/qtwizard-modern2.png differ diff --git a/doc/src/images/qtwizard-nonmacpage.png b/doc/src/images/qtwizard-nonmacpage.png new file mode 100644 index 0000000..cbe464d Binary files /dev/null and b/doc/src/images/qtwizard-nonmacpage.png differ diff --git a/doc/src/images/querymodel-example.png b/doc/src/images/querymodel-example.png new file mode 100644 index 0000000..908d500 Binary files /dev/null and b/doc/src/images/querymodel-example.png differ diff --git a/doc/src/images/queuedcustomtype-example.png b/doc/src/images/queuedcustomtype-example.png new file mode 100644 index 0000000..4399b63 Binary files /dev/null and b/doc/src/images/queuedcustomtype-example.png differ diff --git a/doc/src/images/qundoview.png b/doc/src/images/qundoview.png new file mode 100644 index 0000000..3bdb1cf Binary files /dev/null and b/doc/src/images/qundoview.png differ diff --git a/doc/src/images/qurl-authority.png b/doc/src/images/qurl-authority.png new file mode 100644 index 0000000..54de2a7 Binary files /dev/null and b/doc/src/images/qurl-authority.png differ diff --git a/doc/src/images/qurl-authority2.png b/doc/src/images/qurl-authority2.png new file mode 100644 index 0000000..fe8d4d8 Binary files /dev/null and b/doc/src/images/qurl-authority2.png differ diff --git a/doc/src/images/qurl-authority3.png b/doc/src/images/qurl-authority3.png new file mode 100644 index 0000000..242063e Binary files /dev/null and b/doc/src/images/qurl-authority3.png differ diff --git a/doc/src/images/qurl-fragment.png b/doc/src/images/qurl-fragment.png new file mode 100644 index 0000000..e93a252 Binary files /dev/null and b/doc/src/images/qurl-fragment.png differ diff --git a/doc/src/images/qurl-ftppath.png b/doc/src/images/qurl-ftppath.png new file mode 100644 index 0000000..d88df49 Binary files /dev/null and b/doc/src/images/qurl-ftppath.png differ diff --git a/doc/src/images/qurl-mailtopath.png b/doc/src/images/qurl-mailtopath.png new file mode 100644 index 0000000..34ec153 Binary files /dev/null and b/doc/src/images/qurl-mailtopath.png differ diff --git a/doc/src/images/qurl-querystring.png b/doc/src/images/qurl-querystring.png new file mode 100644 index 0000000..7c3309a Binary files /dev/null and b/doc/src/images/qurl-querystring.png differ diff --git a/doc/src/images/qvbox-m.png b/doc/src/images/qvbox-m.png new file mode 100644 index 0000000..2a2a595 Binary files /dev/null and b/doc/src/images/qvbox-m.png differ diff --git a/doc/src/images/qvboxlayout-with-5-children.png b/doc/src/images/qvboxlayout-with-5-children.png new file mode 100644 index 0000000..57c37d7 Binary files /dev/null and b/doc/src/images/qvboxlayout-with-5-children.png differ diff --git a/doc/src/images/qwebview-diagram.png b/doc/src/images/qwebview-diagram.png new file mode 100644 index 0000000..ada865e Binary files /dev/null and b/doc/src/images/qwebview-diagram.png differ diff --git a/doc/src/images/qwebview-url.png b/doc/src/images/qwebview-url.png new file mode 100644 index 0000000..3c40080 Binary files /dev/null and b/doc/src/images/qwebview-url.png differ diff --git a/doc/src/images/qwindowsstyle.png b/doc/src/images/qwindowsstyle.png new file mode 100644 index 0000000..6b387a7 Binary files /dev/null and b/doc/src/images/qwindowsstyle.png differ diff --git a/doc/src/images/qwindowsxpstyle.png b/doc/src/images/qwindowsxpstyle.png new file mode 100644 index 0000000..b24bdeb Binary files /dev/null and b/doc/src/images/qwindowsxpstyle.png differ diff --git a/doc/src/images/qwsserver_keyboardfilter.png b/doc/src/images/qwsserver_keyboardfilter.png new file mode 100644 index 0000000..9efc080 Binary files /dev/null and b/doc/src/images/qwsserver_keyboardfilter.png differ diff --git a/doc/src/images/radialGradient.png b/doc/src/images/radialGradient.png new file mode 100644 index 0000000..b6ab6c8 Binary files /dev/null and b/doc/src/images/radialGradient.png differ diff --git a/doc/src/images/recentfiles-example.png b/doc/src/images/recentfiles-example.png new file mode 100644 index 0000000..8a1f2e5 Binary files /dev/null and b/doc/src/images/recentfiles-example.png differ diff --git a/doc/src/images/recipes-example.png b/doc/src/images/recipes-example.png new file mode 100644 index 0000000..21ebc9b Binary files /dev/null and b/doc/src/images/recipes-example.png differ diff --git a/doc/src/images/regexp-example.png b/doc/src/images/regexp-example.png new file mode 100644 index 0000000..0f31a2f Binary files /dev/null and b/doc/src/images/regexp-example.png differ diff --git a/doc/src/images/relationaltable.png b/doc/src/images/relationaltable.png new file mode 100644 index 0000000..bdfd40f Binary files /dev/null and b/doc/src/images/relationaltable.png differ diff --git a/doc/src/images/relationaltablemodel-example.png b/doc/src/images/relationaltablemodel-example.png new file mode 100644 index 0000000..44fc858 Binary files /dev/null and b/doc/src/images/relationaltablemodel-example.png differ diff --git a/doc/src/images/remotecontrolledcar-car-example.png b/doc/src/images/remotecontrolledcar-car-example.png new file mode 100644 index 0000000..7e08340 Binary files /dev/null and b/doc/src/images/remotecontrolledcar-car-example.png differ diff --git a/doc/src/images/remotecontrolledcar-controller-example.png b/doc/src/images/remotecontrolledcar-controller-example.png new file mode 100644 index 0000000..cae1ab8 Binary files /dev/null and b/doc/src/images/remotecontrolledcar-controller-example.png differ diff --git a/doc/src/images/resources.png b/doc/src/images/resources.png new file mode 100644 index 0000000..eb7af96 Binary files /dev/null and b/doc/src/images/resources.png differ diff --git a/doc/src/images/richtext-document.png b/doc/src/images/richtext-document.png new file mode 100644 index 0000000..4ae5d16 Binary files /dev/null and b/doc/src/images/richtext-document.png differ diff --git a/doc/src/images/richtext-examples.png b/doc/src/images/richtext-examples.png new file mode 100644 index 0000000..1091c20 Binary files /dev/null and b/doc/src/images/richtext-examples.png differ diff --git a/doc/src/images/rintersect.png b/doc/src/images/rintersect.png new file mode 100644 index 0000000..025ea93 Binary files /dev/null and b/doc/src/images/rintersect.png differ diff --git a/doc/src/images/rsslistingexample.png b/doc/src/images/rsslistingexample.png new file mode 100644 index 0000000..6bac295 Binary files /dev/null and b/doc/src/images/rsslistingexample.png differ diff --git a/doc/src/images/rsubtract.png b/doc/src/images/rsubtract.png new file mode 100644 index 0000000..add6405 Binary files /dev/null and b/doc/src/images/rsubtract.png differ diff --git a/doc/src/images/runion.png b/doc/src/images/runion.png new file mode 100644 index 0000000..5b11e8c Binary files /dev/null and b/doc/src/images/runion.png differ diff --git a/doc/src/images/rxor.png b/doc/src/images/rxor.png new file mode 100644 index 0000000..f86e6d6 Binary files /dev/null and b/doc/src/images/rxor.png differ diff --git a/doc/src/images/samplebuffers-example.png b/doc/src/images/samplebuffers-example.png new file mode 100644 index 0000000..b751c14 Binary files /dev/null and b/doc/src/images/samplebuffers-example.png differ diff --git a/doc/src/images/saxbookmarks-example.png b/doc/src/images/saxbookmarks-example.png new file mode 100644 index 0000000..54d793b Binary files /dev/null and b/doc/src/images/saxbookmarks-example.png differ diff --git a/doc/src/images/screenshot-example.png b/doc/src/images/screenshot-example.png new file mode 100644 index 0000000..8689486 Binary files /dev/null and b/doc/src/images/screenshot-example.png differ diff --git a/doc/src/images/scribble-example.png b/doc/src/images/scribble-example.png new file mode 100644 index 0000000..a2cb1de Binary files /dev/null and b/doc/src/images/scribble-example.png differ diff --git a/doc/src/images/sdi-example.png b/doc/src/images/sdi-example.png new file mode 100644 index 0000000..8cd7aa0 Binary files /dev/null and b/doc/src/images/sdi-example.png differ diff --git a/doc/src/images/securesocketclient.png b/doc/src/images/securesocketclient.png new file mode 100644 index 0000000..8736cbc Binary files /dev/null and b/doc/src/images/securesocketclient.png differ diff --git a/doc/src/images/securesocketclient2.png b/doc/src/images/securesocketclient2.png new file mode 100644 index 0000000..23db851 Binary files /dev/null and b/doc/src/images/securesocketclient2.png differ diff --git a/doc/src/images/selected-items1.png b/doc/src/images/selected-items1.png new file mode 100644 index 0000000..12b572d Binary files /dev/null and b/doc/src/images/selected-items1.png differ diff --git a/doc/src/images/selected-items2.png b/doc/src/images/selected-items2.png new file mode 100644 index 0000000..ad247d9 Binary files /dev/null and b/doc/src/images/selected-items2.png differ diff --git a/doc/src/images/selected-items3.png b/doc/src/images/selected-items3.png new file mode 100644 index 0000000..d7aa7be Binary files /dev/null and b/doc/src/images/selected-items3.png differ diff --git a/doc/src/images/selection-extended.png b/doc/src/images/selection-extended.png new file mode 100644 index 0000000..8ca488d Binary files /dev/null and b/doc/src/images/selection-extended.png differ diff --git a/doc/src/images/selection-multi.png b/doc/src/images/selection-multi.png new file mode 100644 index 0000000..766e4a1 Binary files /dev/null and b/doc/src/images/selection-multi.png differ diff --git a/doc/src/images/selection-single.png b/doc/src/images/selection-single.png new file mode 100644 index 0000000..d9d0655 Binary files /dev/null and b/doc/src/images/selection-single.png differ diff --git a/doc/src/images/session.png b/doc/src/images/session.png new file mode 100644 index 0000000..b9159ae Binary files /dev/null and b/doc/src/images/session.png differ diff --git a/doc/src/images/settingseditor-example.png b/doc/src/images/settingseditor-example.png new file mode 100644 index 0000000..7a5be05 Binary files /dev/null and b/doc/src/images/settingseditor-example.png differ diff --git a/doc/src/images/shapedclock-dragging.png b/doc/src/images/shapedclock-dragging.png new file mode 100644 index 0000000..1b25afb Binary files /dev/null and b/doc/src/images/shapedclock-dragging.png differ diff --git a/doc/src/images/shapedclock-example.png b/doc/src/images/shapedclock-example.png new file mode 100644 index 0000000..31ceeca Binary files /dev/null and b/doc/src/images/shapedclock-example.png differ diff --git a/doc/src/images/shareddirmodel.png b/doc/src/images/shareddirmodel.png new file mode 100644 index 0000000..6daa9d3 Binary files /dev/null and b/doc/src/images/shareddirmodel.png differ diff --git a/doc/src/images/sharedmemory-example_1.png b/doc/src/images/sharedmemory-example_1.png new file mode 100644 index 0000000..53244d3 Binary files /dev/null and b/doc/src/images/sharedmemory-example_1.png differ diff --git a/doc/src/images/sharedmemory-example_2.png b/doc/src/images/sharedmemory-example_2.png new file mode 100644 index 0000000..fc71aed Binary files /dev/null and b/doc/src/images/sharedmemory-example_2.png differ diff --git a/doc/src/images/sharedmodel-tableviews.png b/doc/src/images/sharedmodel-tableviews.png new file mode 100644 index 0000000..d241e4c Binary files /dev/null and b/doc/src/images/sharedmodel-tableviews.png differ diff --git a/doc/src/images/sharedselection-tableviews.png b/doc/src/images/sharedselection-tableviews.png new file mode 100644 index 0000000..ccbda25 Binary files /dev/null and b/doc/src/images/sharedselection-tableviews.png differ diff --git a/doc/src/images/signals-n-slots-aw-nat.png b/doc/src/images/signals-n-slots-aw-nat.png new file mode 100644 index 0000000..8ab545b Binary files /dev/null and b/doc/src/images/signals-n-slots-aw-nat.png differ diff --git a/doc/src/images/simpledommodel-example.png b/doc/src/images/simpledommodel-example.png new file mode 100644 index 0000000..b8e3f92 Binary files /dev/null and b/doc/src/images/simpledommodel-example.png differ diff --git a/doc/src/images/simpletextviewer-example.png b/doc/src/images/simpletextviewer-example.png new file mode 100644 index 0000000..95d2905 Binary files /dev/null and b/doc/src/images/simpletextviewer-example.png differ diff --git a/doc/src/images/simpletextviewer-findfiledialog.png b/doc/src/images/simpletextviewer-findfiledialog.png new file mode 100644 index 0000000..f6e55f0 Binary files /dev/null and b/doc/src/images/simpletextviewer-findfiledialog.png differ diff --git a/doc/src/images/simpletextviewer-mainwindow.png b/doc/src/images/simpletextviewer-mainwindow.png new file mode 100644 index 0000000..98c1c61 Binary files /dev/null and b/doc/src/images/simpletextviewer-mainwindow.png differ diff --git a/doc/src/images/simpletreemodel-example.png b/doc/src/images/simpletreemodel-example.png new file mode 100644 index 0000000..9655d10 Binary files /dev/null and b/doc/src/images/simpletreemodel-example.png differ diff --git a/doc/src/images/simplewidgetmapper-example.png b/doc/src/images/simplewidgetmapper-example.png new file mode 100644 index 0000000..f85ad0e Binary files /dev/null and b/doc/src/images/simplewidgetmapper-example.png differ diff --git a/doc/src/images/simplewizard-page1.png b/doc/src/images/simplewizard-page1.png new file mode 100644 index 0000000..d6f701a Binary files /dev/null and b/doc/src/images/simplewizard-page1.png differ diff --git a/doc/src/images/simplewizard-page2.png b/doc/src/images/simplewizard-page2.png new file mode 100644 index 0000000..f065d85 Binary files /dev/null and b/doc/src/images/simplewizard-page2.png differ diff --git a/doc/src/images/simplewizard-page3.png b/doc/src/images/simplewizard-page3.png new file mode 100644 index 0000000..e200808 Binary files /dev/null and b/doc/src/images/simplewizard-page3.png differ diff --git a/doc/src/images/simplewizard.png b/doc/src/images/simplewizard.png new file mode 100644 index 0000000..5a7f0c7 Binary files /dev/null and b/doc/src/images/simplewizard.png differ diff --git a/doc/src/images/sipdialog-closed.png b/doc/src/images/sipdialog-closed.png new file mode 100644 index 0000000..50408ed Binary files /dev/null and b/doc/src/images/sipdialog-closed.png differ diff --git a/doc/src/images/sipdialog-opened.png b/doc/src/images/sipdialog-opened.png new file mode 100644 index 0000000..981587d Binary files /dev/null and b/doc/src/images/sipdialog-opened.png differ diff --git a/doc/src/images/sliders-example.png b/doc/src/images/sliders-example.png new file mode 100644 index 0000000..a67ce1d Binary files /dev/null and b/doc/src/images/sliders-example.png differ diff --git a/doc/src/images/smooth.png b/doc/src/images/smooth.png new file mode 100644 index 0000000..0d53e55 Binary files /dev/null and b/doc/src/images/smooth.png differ diff --git a/doc/src/images/sortingmodel-example.png b/doc/src/images/sortingmodel-example.png new file mode 100644 index 0000000..a23febe Binary files /dev/null and b/doc/src/images/sortingmodel-example.png differ diff --git a/doc/src/images/spinboxdelegate-example.png b/doc/src/images/spinboxdelegate-example.png new file mode 100644 index 0000000..5e57a9c Binary files /dev/null and b/doc/src/images/spinboxdelegate-example.png differ diff --git a/doc/src/images/spinboxes-example.png b/doc/src/images/spinboxes-example.png new file mode 100644 index 0000000..14c42d2 Binary files /dev/null and b/doc/src/images/spinboxes-example.png differ diff --git a/doc/src/images/spreadsheet-demo.png b/doc/src/images/spreadsheet-demo.png new file mode 100644 index 0000000..ae7dde2 Binary files /dev/null and b/doc/src/images/spreadsheet-demo.png differ diff --git a/doc/src/images/sql-examples.png b/doc/src/images/sql-examples.png new file mode 100644 index 0000000..e8d2b35 Binary files /dev/null and b/doc/src/images/sql-examples.png differ diff --git a/doc/src/images/sql-widget-mapper.png b/doc/src/images/sql-widget-mapper.png new file mode 100644 index 0000000..dfa64ab Binary files /dev/null and b/doc/src/images/sql-widget-mapper.png differ diff --git a/doc/src/images/sqlbrowser-demo.png b/doc/src/images/sqlbrowser-demo.png new file mode 100644 index 0000000..101ec5a Binary files /dev/null and b/doc/src/images/sqlbrowser-demo.png differ diff --git a/doc/src/images/standard-views.png b/doc/src/images/standard-views.png new file mode 100644 index 0000000..836ae36 Binary files /dev/null and b/doc/src/images/standard-views.png differ diff --git a/doc/src/images/standarddialogs-example.png b/doc/src/images/standarddialogs-example.png new file mode 100644 index 0000000..b6b8a07 Binary files /dev/null and b/doc/src/images/standarddialogs-example.png differ diff --git a/doc/src/images/stardelegate.png b/doc/src/images/stardelegate.png new file mode 100644 index 0000000..24fa9fb Binary files /dev/null and b/doc/src/images/stardelegate.png differ diff --git a/doc/src/images/stliterators1.png b/doc/src/images/stliterators1.png new file mode 100644 index 0000000..6d71e47 Binary files /dev/null and b/doc/src/images/stliterators1.png differ diff --git a/doc/src/images/stringlistmodel.png b/doc/src/images/stringlistmodel.png new file mode 100644 index 0000000..eedbff3 Binary files /dev/null and b/doc/src/images/stringlistmodel.png differ diff --git a/doc/src/images/stylepluginexample.png b/doc/src/images/stylepluginexample.png new file mode 100644 index 0000000..05d8c6b Binary files /dev/null and b/doc/src/images/stylepluginexample.png differ diff --git a/doc/src/images/styles-3d.png b/doc/src/images/styles-3d.png new file mode 100644 index 0000000..8344b4c Binary files /dev/null and b/doc/src/images/styles-3d.png differ diff --git a/doc/src/images/styles-aliasing.png b/doc/src/images/styles-aliasing.png new file mode 100644 index 0000000..c351446 Binary files /dev/null and b/doc/src/images/styles-aliasing.png differ diff --git a/doc/src/images/styles-disabledwood.png b/doc/src/images/styles-disabledwood.png new file mode 100644 index 0000000..261bbae Binary files /dev/null and b/doc/src/images/styles-disabledwood.png differ diff --git a/doc/src/images/styles-enabledwood.png b/doc/src/images/styles-enabledwood.png new file mode 100644 index 0000000..168c1d2 Binary files /dev/null and b/doc/src/images/styles-enabledwood.png differ diff --git a/doc/src/images/styles-woodbuttons.png b/doc/src/images/styles-woodbuttons.png new file mode 100644 index 0000000..176d7df Binary files /dev/null and b/doc/src/images/styles-woodbuttons.png differ diff --git a/doc/src/images/stylesheet-border-image-normal.png b/doc/src/images/stylesheet-border-image-normal.png new file mode 100644 index 0000000..8afe3c9 Binary files /dev/null and b/doc/src/images/stylesheet-border-image-normal.png differ diff --git a/doc/src/images/stylesheet-border-image-stretched.png b/doc/src/images/stylesheet-border-image-stretched.png new file mode 100644 index 0000000..3f9ca92 Binary files /dev/null and b/doc/src/images/stylesheet-border-image-stretched.png differ diff --git a/doc/src/images/stylesheet-border-image-wrong.png b/doc/src/images/stylesheet-border-image-wrong.png new file mode 100644 index 0000000..19d6e44 Binary files /dev/null and b/doc/src/images/stylesheet-border-image-wrong.png differ diff --git a/doc/src/images/stylesheet-boxmodel.png b/doc/src/images/stylesheet-boxmodel.png new file mode 100644 index 0000000..a0249d7 Binary files /dev/null and b/doc/src/images/stylesheet-boxmodel.png differ diff --git a/doc/src/images/stylesheet-branch-closed.png b/doc/src/images/stylesheet-branch-closed.png new file mode 100644 index 0000000..213ffdd Binary files /dev/null and b/doc/src/images/stylesheet-branch-closed.png differ diff --git a/doc/src/images/stylesheet-branch-end.png b/doc/src/images/stylesheet-branch-end.png new file mode 100644 index 0000000..54915b3 Binary files /dev/null and b/doc/src/images/stylesheet-branch-end.png differ diff --git a/doc/src/images/stylesheet-branch-more.png b/doc/src/images/stylesheet-branch-more.png new file mode 100644 index 0000000..664ad44 Binary files /dev/null and b/doc/src/images/stylesheet-branch-more.png differ diff --git a/doc/src/images/stylesheet-branch-open.png b/doc/src/images/stylesheet-branch-open.png new file mode 100644 index 0000000..e8cad95 Binary files /dev/null and b/doc/src/images/stylesheet-branch-open.png differ diff --git a/doc/src/images/stylesheet-coffee-cleanlooks.png b/doc/src/images/stylesheet-coffee-cleanlooks.png new file mode 100644 index 0000000..e75df0d Binary files /dev/null and b/doc/src/images/stylesheet-coffee-cleanlooks.png differ diff --git a/doc/src/images/stylesheet-coffee-plastique.png b/doc/src/images/stylesheet-coffee-plastique.png new file mode 100644 index 0000000..d3bbe27 Binary files /dev/null and b/doc/src/images/stylesheet-coffee-plastique.png differ diff --git a/doc/src/images/stylesheet-coffee-xp.png b/doc/src/images/stylesheet-coffee-xp.png new file mode 100644 index 0000000..8bedd80 Binary files /dev/null and b/doc/src/images/stylesheet-coffee-xp.png differ diff --git a/doc/src/images/stylesheet-designer-options.png b/doc/src/images/stylesheet-designer-options.png new file mode 100644 index 0000000..446ce10 Binary files /dev/null and b/doc/src/images/stylesheet-designer-options.png differ diff --git a/doc/src/images/stylesheet-pagefold-mac.png b/doc/src/images/stylesheet-pagefold-mac.png new file mode 100644 index 0000000..5c061b9 Binary files /dev/null and b/doc/src/images/stylesheet-pagefold-mac.png differ diff --git a/doc/src/images/stylesheet-pagefold.png b/doc/src/images/stylesheet-pagefold.png new file mode 100644 index 0000000..5ccb4ed Binary files /dev/null and b/doc/src/images/stylesheet-pagefold.png differ diff --git a/doc/src/images/stylesheet-redbutton1.png b/doc/src/images/stylesheet-redbutton1.png new file mode 100644 index 0000000..cb03375 Binary files /dev/null and b/doc/src/images/stylesheet-redbutton1.png differ diff --git a/doc/src/images/stylesheet-redbutton2.png b/doc/src/images/stylesheet-redbutton2.png new file mode 100644 index 0000000..5325708 Binary files /dev/null and b/doc/src/images/stylesheet-redbutton2.png differ diff --git a/doc/src/images/stylesheet-redbutton3.png b/doc/src/images/stylesheet-redbutton3.png new file mode 100644 index 0000000..dd976f0 Binary files /dev/null and b/doc/src/images/stylesheet-redbutton3.png differ diff --git a/doc/src/images/stylesheet-scrollbar1.png b/doc/src/images/stylesheet-scrollbar1.png new file mode 100644 index 0000000..666ff11 Binary files /dev/null and b/doc/src/images/stylesheet-scrollbar1.png differ diff --git a/doc/src/images/stylesheet-scrollbar2.png b/doc/src/images/stylesheet-scrollbar2.png new file mode 100644 index 0000000..439cf80 Binary files /dev/null and b/doc/src/images/stylesheet-scrollbar2.png differ diff --git a/doc/src/images/stylesheet-treeview.png b/doc/src/images/stylesheet-treeview.png new file mode 100644 index 0000000..883d190 Binary files /dev/null and b/doc/src/images/stylesheet-treeview.png differ diff --git a/doc/src/images/stylesheet-vline.png b/doc/src/images/stylesheet-vline.png new file mode 100644 index 0000000..8f0c336 Binary files /dev/null and b/doc/src/images/stylesheet-vline.png differ diff --git a/doc/src/images/svg-image.png b/doc/src/images/svg-image.png new file mode 100644 index 0000000..5a71ea7 Binary files /dev/null and b/doc/src/images/svg-image.png differ diff --git a/doc/src/images/svgviewer-example.png b/doc/src/images/svgviewer-example.png new file mode 100644 index 0000000..14f1377 Binary files /dev/null and b/doc/src/images/svgviewer-example.png differ diff --git a/doc/src/images/syntaxhighlighter-example.png b/doc/src/images/syntaxhighlighter-example.png new file mode 100644 index 0000000..d0e7f12 Binary files /dev/null and b/doc/src/images/syntaxhighlighter-example.png differ diff --git a/doc/src/images/system-tray.png b/doc/src/images/system-tray.png new file mode 100644 index 0000000..298b193 Binary files /dev/null and b/doc/src/images/system-tray.png differ diff --git a/doc/src/images/systemtray-editor.png b/doc/src/images/systemtray-editor.png new file mode 100644 index 0000000..fb15dea Binary files /dev/null and b/doc/src/images/systemtray-editor.png differ diff --git a/doc/src/images/systemtray-example.png b/doc/src/images/systemtray-example.png new file mode 100644 index 0000000..98b5c81 Binary files /dev/null and b/doc/src/images/systemtray-example.png differ diff --git a/doc/src/images/t1.png b/doc/src/images/t1.png new file mode 100644 index 0000000..744721f Binary files /dev/null and b/doc/src/images/t1.png differ diff --git a/doc/src/images/t10.png b/doc/src/images/t10.png new file mode 100644 index 0000000..54aa587 Binary files /dev/null and b/doc/src/images/t10.png differ diff --git a/doc/src/images/t11.png b/doc/src/images/t11.png new file mode 100644 index 0000000..64b25fa Binary files /dev/null and b/doc/src/images/t11.png differ diff --git a/doc/src/images/t12.png b/doc/src/images/t12.png new file mode 100644 index 0000000..7a23230 Binary files /dev/null and b/doc/src/images/t12.png differ diff --git a/doc/src/images/t13.png b/doc/src/images/t13.png new file mode 100644 index 0000000..8734249 Binary files /dev/null and b/doc/src/images/t13.png differ diff --git a/doc/src/images/t14.png b/doc/src/images/t14.png new file mode 100644 index 0000000..f947dbe Binary files /dev/null and b/doc/src/images/t14.png differ diff --git a/doc/src/images/t2.png b/doc/src/images/t2.png new file mode 100644 index 0000000..4b24119 Binary files /dev/null and b/doc/src/images/t2.png differ diff --git a/doc/src/images/t3.png b/doc/src/images/t3.png new file mode 100644 index 0000000..79c6413 Binary files /dev/null and b/doc/src/images/t3.png differ diff --git a/doc/src/images/t4.png b/doc/src/images/t4.png new file mode 100644 index 0000000..34c6c75 Binary files /dev/null and b/doc/src/images/t4.png differ diff --git a/doc/src/images/t5.png b/doc/src/images/t5.png new file mode 100644 index 0000000..46b3d75 Binary files /dev/null and b/doc/src/images/t5.png differ diff --git a/doc/src/images/t6.png b/doc/src/images/t6.png new file mode 100644 index 0000000..75c2c7e Binary files /dev/null and b/doc/src/images/t6.png differ diff --git a/doc/src/images/t7.png b/doc/src/images/t7.png new file mode 100644 index 0000000..b0518df Binary files /dev/null and b/doc/src/images/t7.png differ diff --git a/doc/src/images/t8.png b/doc/src/images/t8.png new file mode 100644 index 0000000..13b1b00 Binary files /dev/null and b/doc/src/images/t8.png differ diff --git a/doc/src/images/t9.png b/doc/src/images/t9.png new file mode 100644 index 0000000..54c3941 Binary files /dev/null and b/doc/src/images/t9.png differ diff --git a/doc/src/images/t9_1.png b/doc/src/images/t9_1.png new file mode 100644 index 0000000..bdcc640 Binary files /dev/null and b/doc/src/images/t9_1.png differ diff --git a/doc/src/images/t9_2.png b/doc/src/images/t9_2.png new file mode 100644 index 0000000..c1e23ca Binary files /dev/null and b/doc/src/images/t9_2.png differ diff --git a/doc/src/images/tabWidget-stylesheet1.png b/doc/src/images/tabWidget-stylesheet1.png new file mode 100644 index 0000000..fc8fc19 Binary files /dev/null and b/doc/src/images/tabWidget-stylesheet1.png differ diff --git a/doc/src/images/tabWidget-stylesheet2.png b/doc/src/images/tabWidget-stylesheet2.png new file mode 100644 index 0000000..2cbf2bf Binary files /dev/null and b/doc/src/images/tabWidget-stylesheet2.png differ diff --git a/doc/src/images/tabWidget-stylesheet3.png b/doc/src/images/tabWidget-stylesheet3.png new file mode 100644 index 0000000..f57a9c9 Binary files /dev/null and b/doc/src/images/tabWidget-stylesheet3.png differ diff --git a/doc/src/images/tabdialog-example.png b/doc/src/images/tabdialog-example.png new file mode 100644 index 0000000..219a85f Binary files /dev/null and b/doc/src/images/tabdialog-example.png differ diff --git a/doc/src/images/tableWidget-stylesheet.png b/doc/src/images/tableWidget-stylesheet.png new file mode 100644 index 0000000..e99e7a9 Binary files /dev/null and b/doc/src/images/tableWidget-stylesheet.png differ diff --git a/doc/src/images/tablemodel-example.png b/doc/src/images/tablemodel-example.png new file mode 100644 index 0000000..3ae2a8c Binary files /dev/null and b/doc/src/images/tablemodel-example.png differ diff --git a/doc/src/images/tabletexample.png b/doc/src/images/tabletexample.png new file mode 100644 index 0000000..a9b098d Binary files /dev/null and b/doc/src/images/tabletexample.png differ diff --git a/doc/src/images/taskmenuextension-dialog.png b/doc/src/images/taskmenuextension-dialog.png new file mode 100644 index 0000000..7ad6d40 Binary files /dev/null and b/doc/src/images/taskmenuextension-dialog.png differ diff --git a/doc/src/images/taskmenuextension-example-faded.png b/doc/src/images/taskmenuextension-example-faded.png new file mode 100644 index 0000000..7e96f3a Binary files /dev/null and b/doc/src/images/taskmenuextension-example-faded.png differ diff --git a/doc/src/images/taskmenuextension-example.png b/doc/src/images/taskmenuextension-example.png new file mode 100644 index 0000000..f1d46d2 Binary files /dev/null and b/doc/src/images/taskmenuextension-example.png differ diff --git a/doc/src/images/taskmenuextension-menu.png b/doc/src/images/taskmenuextension-menu.png new file mode 100644 index 0000000..d626c81 Binary files /dev/null and b/doc/src/images/taskmenuextension-menu.png differ diff --git a/doc/src/images/tcpstream.png b/doc/src/images/tcpstream.png new file mode 100644 index 0000000..7975376 Binary files /dev/null and b/doc/src/images/tcpstream.png differ diff --git a/doc/src/images/tetrix-example.png b/doc/src/images/tetrix-example.png new file mode 100644 index 0000000..c9764dc Binary files /dev/null and b/doc/src/images/tetrix-example.png differ diff --git a/doc/src/images/textedit-demo.png b/doc/src/images/textedit-demo.png new file mode 100644 index 0000000..3cf2883 Binary files /dev/null and b/doc/src/images/textedit-demo.png differ diff --git a/doc/src/images/textfinder-example-find.png b/doc/src/images/textfinder-example-find.png new file mode 100644 index 0000000..886bbc1 Binary files /dev/null and b/doc/src/images/textfinder-example-find.png differ diff --git a/doc/src/images/textfinder-example-find2.png b/doc/src/images/textfinder-example-find2.png new file mode 100644 index 0000000..908f114 Binary files /dev/null and b/doc/src/images/textfinder-example-find2.png differ diff --git a/doc/src/images/textfinder-example-userinterface.png b/doc/src/images/textfinder-example-userinterface.png new file mode 100644 index 0000000..2bebe2e Binary files /dev/null and b/doc/src/images/textfinder-example-userinterface.png differ diff --git a/doc/src/images/textfinder-example.png b/doc/src/images/textfinder-example.png new file mode 100644 index 0000000..87322df Binary files /dev/null and b/doc/src/images/textfinder-example.png differ diff --git a/doc/src/images/textobject-example.png b/doc/src/images/textobject-example.png new file mode 100644 index 0000000..626c102 Binary files /dev/null and b/doc/src/images/textobject-example.png differ diff --git a/doc/src/images/texttable-merge.png b/doc/src/images/texttable-merge.png new file mode 100644 index 0000000..3b32239 Binary files /dev/null and b/doc/src/images/texttable-merge.png differ diff --git a/doc/src/images/texttable-split.png b/doc/src/images/texttable-split.png new file mode 100644 index 0000000..2fa17b8 Binary files /dev/null and b/doc/src/images/texttable-split.png differ diff --git a/doc/src/images/textures-example.png b/doc/src/images/textures-example.png new file mode 100644 index 0000000..b583ede Binary files /dev/null and b/doc/src/images/textures-example.png differ diff --git a/doc/src/images/thread-examples.png b/doc/src/images/thread-examples.png new file mode 100644 index 0000000..4f4dbac Binary files /dev/null and b/doc/src/images/thread-examples.png differ diff --git a/doc/src/images/threadedfortuneserver-example.png b/doc/src/images/threadedfortuneserver-example.png new file mode 100644 index 0000000..57c66a5 Binary files /dev/null and b/doc/src/images/threadedfortuneserver-example.png differ diff --git a/doc/src/images/threadsandobjects.png b/doc/src/images/threadsandobjects.png new file mode 100644 index 0000000..8357d25 Binary files /dev/null and b/doc/src/images/threadsandobjects.png differ diff --git a/doc/src/images/tool-examples.png b/doc/src/images/tool-examples.png new file mode 100644 index 0000000..592602a Binary files /dev/null and b/doc/src/images/tool-examples.png differ diff --git a/doc/src/images/tooltips-example.png b/doc/src/images/tooltips-example.png new file mode 100644 index 0000000..f2236b4 Binary files /dev/null and b/doc/src/images/tooltips-example.png differ diff --git a/doc/src/images/torrent-example.png b/doc/src/images/torrent-example.png new file mode 100644 index 0000000..1032716 Binary files /dev/null and b/doc/src/images/torrent-example.png differ diff --git a/doc/src/images/trafficinfo-example.png b/doc/src/images/trafficinfo-example.png new file mode 100644 index 0000000..1717e40 Binary files /dev/null and b/doc/src/images/trafficinfo-example.png differ diff --git a/doc/src/images/transformations-example.png b/doc/src/images/transformations-example.png new file mode 100644 index 0000000..0fa185b Binary files /dev/null and b/doc/src/images/transformations-example.png differ diff --git a/doc/src/images/treemodel-structure.png b/doc/src/images/treemodel-structure.png new file mode 100644 index 0000000..778841b Binary files /dev/null and b/doc/src/images/treemodel-structure.png differ diff --git a/doc/src/images/treemodelcompleter-example.png b/doc/src/images/treemodelcompleter-example.png new file mode 100644 index 0000000..000405f Binary files /dev/null and b/doc/src/images/treemodelcompleter-example.png differ diff --git a/doc/src/images/trivialwizard-example-conclusion.png b/doc/src/images/trivialwizard-example-conclusion.png new file mode 100644 index 0000000..c625ae4 Binary files /dev/null and b/doc/src/images/trivialwizard-example-conclusion.png differ diff --git a/doc/src/images/trivialwizard-example-flow.png b/doc/src/images/trivialwizard-example-flow.png new file mode 100644 index 0000000..79b6fce Binary files /dev/null and b/doc/src/images/trivialwizard-example-flow.png differ diff --git a/doc/src/images/trivialwizard-example-introduction.png b/doc/src/images/trivialwizard-example-introduction.png new file mode 100644 index 0000000..0bbceed Binary files /dev/null and b/doc/src/images/trivialwizard-example-introduction.png differ diff --git a/doc/src/images/trivialwizard-example-registration.png b/doc/src/images/trivialwizard-example-registration.png new file mode 100644 index 0000000..30b985e Binary files /dev/null and b/doc/src/images/trivialwizard-example-registration.png differ diff --git a/doc/src/images/trolltech-logo.png b/doc/src/images/trolltech-logo.png new file mode 100644 index 0000000..19e3789 Binary files /dev/null and b/doc/src/images/trolltech-logo.png differ diff --git a/doc/src/images/tutorial8-layout.png b/doc/src/images/tutorial8-layout.png new file mode 100644 index 0000000..190a9f8 Binary files /dev/null and b/doc/src/images/tutorial8-layout.png differ diff --git a/doc/src/images/tutorial8-reallayout.png b/doc/src/images/tutorial8-reallayout.png new file mode 100644 index 0000000..4f6eb60 Binary files /dev/null and b/doc/src/images/tutorial8-reallayout.png differ diff --git a/doc/src/images/udppackets.png b/doc/src/images/udppackets.png new file mode 100644 index 0000000..bd66c3f Binary files /dev/null and b/doc/src/images/udppackets.png differ diff --git a/doc/src/images/uitools-examples.png b/doc/src/images/uitools-examples.png new file mode 100644 index 0000000..8c85cdb Binary files /dev/null and b/doc/src/images/uitools-examples.png differ diff --git a/doc/src/images/undodemo.png b/doc/src/images/undodemo.png new file mode 100644 index 0000000..85c3622 Binary files /dev/null and b/doc/src/images/undodemo.png differ diff --git a/doc/src/images/undoframeworkexample.png b/doc/src/images/undoframeworkexample.png new file mode 100644 index 0000000..7e0a1df Binary files /dev/null and b/doc/src/images/undoframeworkexample.png differ diff --git a/doc/src/images/unsmooth.png b/doc/src/images/unsmooth.png new file mode 100644 index 0000000..2e1bdbe Binary files /dev/null and b/doc/src/images/unsmooth.png differ diff --git a/doc/src/images/wVista-Cert-border-small.png b/doc/src/images/wVista-Cert-border-small.png new file mode 100644 index 0000000..ea78525 Binary files /dev/null and b/doc/src/images/wVista-Cert-border-small.png differ diff --git a/doc/src/images/webkit-examples.png b/doc/src/images/webkit-examples.png new file mode 100644 index 0000000..55bbd92 Binary files /dev/null and b/doc/src/images/webkit-examples.png differ diff --git a/doc/src/images/webkit-netscape-plugin.png b/doc/src/images/webkit-netscape-plugin.png new file mode 100644 index 0000000..df15123 Binary files /dev/null and b/doc/src/images/webkit-netscape-plugin.png differ diff --git a/doc/src/images/whatsthis.png b/doc/src/images/whatsthis.png new file mode 100644 index 0000000..2267c3d Binary files /dev/null and b/doc/src/images/whatsthis.png differ diff --git a/doc/src/images/widget-examples.png b/doc/src/images/widget-examples.png new file mode 100644 index 0000000..1e4e97c Binary files /dev/null and b/doc/src/images/widget-examples.png differ diff --git a/doc/src/images/widgetdelegate.png b/doc/src/images/widgetdelegate.png new file mode 100644 index 0000000..3df4c4b Binary files /dev/null and b/doc/src/images/widgetdelegate.png differ diff --git a/doc/src/images/widgetmapper-combo-mapping.png b/doc/src/images/widgetmapper-combo-mapping.png new file mode 100644 index 0000000..f87cfaf Binary files /dev/null and b/doc/src/images/widgetmapper-combo-mapping.png differ diff --git a/doc/src/images/widgetmapper-simple-mapping.png b/doc/src/images/widgetmapper-simple-mapping.png new file mode 100644 index 0000000..3ef3f29 Binary files /dev/null and b/doc/src/images/widgetmapper-simple-mapping.png differ diff --git a/doc/src/images/widgetmapper-sql-mapping-table.png b/doc/src/images/widgetmapper-sql-mapping-table.png new file mode 100644 index 0000000..98734b3 Binary files /dev/null and b/doc/src/images/widgetmapper-sql-mapping-table.png differ diff --git a/doc/src/images/widgetmapper-sql-mapping.png b/doc/src/images/widgetmapper-sql-mapping.png new file mode 100644 index 0000000..88718c6 Binary files /dev/null and b/doc/src/images/widgetmapper-sql-mapping.png differ diff --git a/doc/src/images/widgets-examples.png b/doc/src/images/widgets-examples.png new file mode 100644 index 0000000..2b314d1 Binary files /dev/null and b/doc/src/images/widgets-examples.png differ diff --git a/doc/src/images/widgets-tutorial-childwidget.png b/doc/src/images/widgets-tutorial-childwidget.png new file mode 100644 index 0000000..0d42d70 Binary files /dev/null and b/doc/src/images/widgets-tutorial-childwidget.png differ diff --git a/doc/src/images/widgets-tutorial-nestedlayouts.png b/doc/src/images/widgets-tutorial-nestedlayouts.png new file mode 100644 index 0000000..1e2a9f4 Binary files /dev/null and b/doc/src/images/widgets-tutorial-nestedlayouts.png differ diff --git a/doc/src/images/widgets-tutorial-toplevel.png b/doc/src/images/widgets-tutorial-toplevel.png new file mode 100644 index 0000000..a80d13c Binary files /dev/null and b/doc/src/images/widgets-tutorial-toplevel.png differ diff --git a/doc/src/images/widgets-tutorial-windowlayout.png b/doc/src/images/widgets-tutorial-windowlayout.png new file mode 100644 index 0000000..fce52cd Binary files /dev/null and b/doc/src/images/widgets-tutorial-windowlayout.png differ diff --git a/doc/src/images/wiggly-example.png b/doc/src/images/wiggly-example.png new file mode 100644 index 0000000..b20fbc4 Binary files /dev/null and b/doc/src/images/wiggly-example.png differ diff --git a/doc/src/images/windowflags-example.png b/doc/src/images/windowflags-example.png new file mode 100644 index 0000000..9028b9b Binary files /dev/null and b/doc/src/images/windowflags-example.png differ diff --git a/doc/src/images/windowflags_controllerwindow.png b/doc/src/images/windowflags_controllerwindow.png new file mode 100644 index 0000000..d8ce239 Binary files /dev/null and b/doc/src/images/windowflags_controllerwindow.png differ diff --git a/doc/src/images/windowflags_previewwindow.png b/doc/src/images/windowflags_previewwindow.png new file mode 100644 index 0000000..cafcd37 Binary files /dev/null and b/doc/src/images/windowflags_previewwindow.png differ diff --git a/doc/src/images/windows-calendarwidget.png b/doc/src/images/windows-calendarwidget.png new file mode 100644 index 0000000..ad01623 Binary files /dev/null and b/doc/src/images/windows-calendarwidget.png differ diff --git a/doc/src/images/windows-checkbox.png b/doc/src/images/windows-checkbox.png new file mode 100644 index 0000000..eb1be4b Binary files /dev/null and b/doc/src/images/windows-checkbox.png differ diff --git a/doc/src/images/windows-combobox.png b/doc/src/images/windows-combobox.png new file mode 100644 index 0000000..d6bc483 Binary files /dev/null and b/doc/src/images/windows-combobox.png differ diff --git a/doc/src/images/windows-dateedit.png b/doc/src/images/windows-dateedit.png new file mode 100644 index 0000000..95587ec Binary files /dev/null and b/doc/src/images/windows-dateedit.png differ diff --git a/doc/src/images/windows-datetimeedit.png b/doc/src/images/windows-datetimeedit.png new file mode 100644 index 0000000..6aa1766 Binary files /dev/null and b/doc/src/images/windows-datetimeedit.png differ diff --git a/doc/src/images/windows-dial.png b/doc/src/images/windows-dial.png new file mode 100644 index 0000000..0aa3a26 Binary files /dev/null and b/doc/src/images/windows-dial.png differ diff --git a/doc/src/images/windows-doublespinbox.png b/doc/src/images/windows-doublespinbox.png new file mode 100644 index 0000000..244b5f6 Binary files /dev/null and b/doc/src/images/windows-doublespinbox.png differ diff --git a/doc/src/images/windows-fontcombobox.png b/doc/src/images/windows-fontcombobox.png new file mode 100644 index 0000000..bf98cad Binary files /dev/null and b/doc/src/images/windows-fontcombobox.png differ diff --git a/doc/src/images/windows-frame.png b/doc/src/images/windows-frame.png new file mode 100644 index 0000000..5979b31 Binary files /dev/null and b/doc/src/images/windows-frame.png differ diff --git a/doc/src/images/windows-groupbox.png b/doc/src/images/windows-groupbox.png new file mode 100644 index 0000000..88f46a3 Binary files /dev/null and b/doc/src/images/windows-groupbox.png differ diff --git a/doc/src/images/windows-horizontalscrollbar.png b/doc/src/images/windows-horizontalscrollbar.png new file mode 100644 index 0000000..1f36b9a Binary files /dev/null and b/doc/src/images/windows-horizontalscrollbar.png differ diff --git a/doc/src/images/windows-label.png b/doc/src/images/windows-label.png new file mode 100644 index 0000000..a1c3a39 Binary files /dev/null and b/doc/src/images/windows-label.png differ diff --git a/doc/src/images/windows-lcdnumber.png b/doc/src/images/windows-lcdnumber.png new file mode 100644 index 0000000..b463511 Binary files /dev/null and b/doc/src/images/windows-lcdnumber.png differ diff --git a/doc/src/images/windows-lineedit.png b/doc/src/images/windows-lineedit.png new file mode 100644 index 0000000..270e451 Binary files /dev/null and b/doc/src/images/windows-lineedit.png differ diff --git a/doc/src/images/windows-listview.png b/doc/src/images/windows-listview.png new file mode 100644 index 0000000..2884fae Binary files /dev/null and b/doc/src/images/windows-listview.png differ diff --git a/doc/src/images/windows-progressbar.png b/doc/src/images/windows-progressbar.png new file mode 100644 index 0000000..361799a Binary files /dev/null and b/doc/src/images/windows-progressbar.png differ diff --git a/doc/src/images/windows-pushbutton.png b/doc/src/images/windows-pushbutton.png new file mode 100644 index 0000000..14528d6 Binary files /dev/null and b/doc/src/images/windows-pushbutton.png differ diff --git a/doc/src/images/windows-radiobutton.png b/doc/src/images/windows-radiobutton.png new file mode 100644 index 0000000..db328cb Binary files /dev/null and b/doc/src/images/windows-radiobutton.png differ diff --git a/doc/src/images/windows-slider.png b/doc/src/images/windows-slider.png new file mode 100644 index 0000000..fde8502 Binary files /dev/null and b/doc/src/images/windows-slider.png differ diff --git a/doc/src/images/windows-spinbox.png b/doc/src/images/windows-spinbox.png new file mode 100644 index 0000000..d4e93c5 Binary files /dev/null and b/doc/src/images/windows-spinbox.png differ diff --git a/doc/src/images/windows-tableview.png b/doc/src/images/windows-tableview.png new file mode 100644 index 0000000..89da89f Binary files /dev/null and b/doc/src/images/windows-tableview.png differ diff --git a/doc/src/images/windows-tabwidget.png b/doc/src/images/windows-tabwidget.png new file mode 100644 index 0000000..8622f7e Binary files /dev/null and b/doc/src/images/windows-tabwidget.png differ diff --git a/doc/src/images/windows-textedit.png b/doc/src/images/windows-textedit.png new file mode 100644 index 0000000..fd21ade Binary files /dev/null and b/doc/src/images/windows-textedit.png differ diff --git a/doc/src/images/windows-timeedit.png b/doc/src/images/windows-timeedit.png new file mode 100644 index 0000000..6ae0e40 Binary files /dev/null and b/doc/src/images/windows-timeedit.png differ diff --git a/doc/src/images/windows-toolbox.png b/doc/src/images/windows-toolbox.png new file mode 100644 index 0000000..99b471e Binary files /dev/null and b/doc/src/images/windows-toolbox.png differ diff --git a/doc/src/images/windows-toolbutton.png b/doc/src/images/windows-toolbutton.png new file mode 100644 index 0000000..9ceb846 Binary files /dev/null and b/doc/src/images/windows-toolbutton.png differ diff --git a/doc/src/images/windows-treeview.png b/doc/src/images/windows-treeview.png new file mode 100644 index 0000000..f55cd69 Binary files /dev/null and b/doc/src/images/windows-treeview.png differ diff --git a/doc/src/images/windowsvista-calendarwidget.png b/doc/src/images/windowsvista-calendarwidget.png new file mode 100644 index 0000000..3cb1ab7 Binary files /dev/null and b/doc/src/images/windowsvista-calendarwidget.png differ diff --git a/doc/src/images/windowsvista-checkbox.png b/doc/src/images/windowsvista-checkbox.png new file mode 100644 index 0000000..b9bc909 Binary files /dev/null and b/doc/src/images/windowsvista-checkbox.png differ diff --git a/doc/src/images/windowsvista-combobox.png b/doc/src/images/windowsvista-combobox.png new file mode 100644 index 0000000..f53192f Binary files /dev/null and b/doc/src/images/windowsvista-combobox.png differ diff --git a/doc/src/images/windowsvista-dateedit.png b/doc/src/images/windowsvista-dateedit.png new file mode 100644 index 0000000..bb79482 Binary files /dev/null and b/doc/src/images/windowsvista-dateedit.png differ diff --git a/doc/src/images/windowsvista-datetimeedit.png b/doc/src/images/windowsvista-datetimeedit.png new file mode 100644 index 0000000..0a104de Binary files /dev/null and b/doc/src/images/windowsvista-datetimeedit.png differ diff --git a/doc/src/images/windowsvista-dial.png b/doc/src/images/windowsvista-dial.png new file mode 100644 index 0000000..7081269 Binary files /dev/null and b/doc/src/images/windowsvista-dial.png differ diff --git a/doc/src/images/windowsvista-doublespinbox.png b/doc/src/images/windowsvista-doublespinbox.png new file mode 100644 index 0000000..6efa937 Binary files /dev/null and b/doc/src/images/windowsvista-doublespinbox.png differ diff --git a/doc/src/images/windowsvista-fontcombobox.png b/doc/src/images/windowsvista-fontcombobox.png new file mode 100644 index 0000000..3771e84 Binary files /dev/null and b/doc/src/images/windowsvista-fontcombobox.png differ diff --git a/doc/src/images/windowsvista-frame.png b/doc/src/images/windowsvista-frame.png new file mode 100644 index 0000000..63b8422 Binary files /dev/null and b/doc/src/images/windowsvista-frame.png differ diff --git a/doc/src/images/windowsvista-groupbox.png b/doc/src/images/windowsvista-groupbox.png new file mode 100644 index 0000000..967d887 Binary files /dev/null and b/doc/src/images/windowsvista-groupbox.png differ diff --git a/doc/src/images/windowsvista-horizontalscrollbar.png b/doc/src/images/windowsvista-horizontalscrollbar.png new file mode 100644 index 0000000..996865d Binary files /dev/null and b/doc/src/images/windowsvista-horizontalscrollbar.png differ diff --git a/doc/src/images/windowsvista-label.png b/doc/src/images/windowsvista-label.png new file mode 100644 index 0000000..caef8d8 Binary files /dev/null and b/doc/src/images/windowsvista-label.png differ diff --git a/doc/src/images/windowsvista-lcdnumber.png b/doc/src/images/windowsvista-lcdnumber.png new file mode 100644 index 0000000..911438e Binary files /dev/null and b/doc/src/images/windowsvista-lcdnumber.png differ diff --git a/doc/src/images/windowsvista-lineedit.png b/doc/src/images/windowsvista-lineedit.png new file mode 100644 index 0000000..9fcde3a Binary files /dev/null and b/doc/src/images/windowsvista-lineedit.png differ diff --git a/doc/src/images/windowsvista-listview.png b/doc/src/images/windowsvista-listview.png new file mode 100644 index 0000000..36a0343 Binary files /dev/null and b/doc/src/images/windowsvista-listview.png differ diff --git a/doc/src/images/windowsvista-progressbar.png b/doc/src/images/windowsvista-progressbar.png new file mode 100644 index 0000000..0bda010 Binary files /dev/null and b/doc/src/images/windowsvista-progressbar.png differ diff --git a/doc/src/images/windowsvista-pushbutton.png b/doc/src/images/windowsvista-pushbutton.png new file mode 100644 index 0000000..3bc438d Binary files /dev/null and b/doc/src/images/windowsvista-pushbutton.png differ diff --git a/doc/src/images/windowsvista-radiobutton.png b/doc/src/images/windowsvista-radiobutton.png new file mode 100644 index 0000000..fdfd2d6 Binary files /dev/null and b/doc/src/images/windowsvista-radiobutton.png differ diff --git a/doc/src/images/windowsvista-slider.png b/doc/src/images/windowsvista-slider.png new file mode 100644 index 0000000..be2fffb Binary files /dev/null and b/doc/src/images/windowsvista-slider.png differ diff --git a/doc/src/images/windowsvista-spinbox.png b/doc/src/images/windowsvista-spinbox.png new file mode 100644 index 0000000..4a2293e Binary files /dev/null and b/doc/src/images/windowsvista-spinbox.png differ diff --git a/doc/src/images/windowsvista-tableview.png b/doc/src/images/windowsvista-tableview.png new file mode 100644 index 0000000..96f4937 Binary files /dev/null and b/doc/src/images/windowsvista-tableview.png differ diff --git a/doc/src/images/windowsvista-tabwidget.png b/doc/src/images/windowsvista-tabwidget.png new file mode 100644 index 0000000..259c4f1 Binary files /dev/null and b/doc/src/images/windowsvista-tabwidget.png differ diff --git a/doc/src/images/windowsvista-textedit.png b/doc/src/images/windowsvista-textedit.png new file mode 100644 index 0000000..5e56966 Binary files /dev/null and b/doc/src/images/windowsvista-textedit.png differ diff --git a/doc/src/images/windowsvista-timeedit.png b/doc/src/images/windowsvista-timeedit.png new file mode 100644 index 0000000..e24fdd2 Binary files /dev/null and b/doc/src/images/windowsvista-timeedit.png differ diff --git a/doc/src/images/windowsvista-toolbox.png b/doc/src/images/windowsvista-toolbox.png new file mode 100644 index 0000000..8cfe5f9 Binary files /dev/null and b/doc/src/images/windowsvista-toolbox.png differ diff --git a/doc/src/images/windowsvista-toolbutton.png b/doc/src/images/windowsvista-toolbutton.png new file mode 100644 index 0000000..0baa980 Binary files /dev/null and b/doc/src/images/windowsvista-toolbutton.png differ diff --git a/doc/src/images/windowsvista-treeview.png b/doc/src/images/windowsvista-treeview.png new file mode 100644 index 0000000..db211e4 Binary files /dev/null and b/doc/src/images/windowsvista-treeview.png differ diff --git a/doc/src/images/windowsxp-calendarwidget.png b/doc/src/images/windowsxp-calendarwidget.png new file mode 100644 index 0000000..9a5fa6e Binary files /dev/null and b/doc/src/images/windowsxp-calendarwidget.png differ diff --git a/doc/src/images/windowsxp-checkbox.png b/doc/src/images/windowsxp-checkbox.png new file mode 100644 index 0000000..505d3a3 Binary files /dev/null and b/doc/src/images/windowsxp-checkbox.png differ diff --git a/doc/src/images/windowsxp-combobox.png b/doc/src/images/windowsxp-combobox.png new file mode 100644 index 0000000..2363c84 Binary files /dev/null and b/doc/src/images/windowsxp-combobox.png differ diff --git a/doc/src/images/windowsxp-dateedit.png b/doc/src/images/windowsxp-dateedit.png new file mode 100644 index 0000000..060ba07 Binary files /dev/null and b/doc/src/images/windowsxp-dateedit.png differ diff --git a/doc/src/images/windowsxp-datetimeedit.png b/doc/src/images/windowsxp-datetimeedit.png new file mode 100644 index 0000000..4e41f0f Binary files /dev/null and b/doc/src/images/windowsxp-datetimeedit.png differ diff --git a/doc/src/images/windowsxp-dial.png b/doc/src/images/windowsxp-dial.png new file mode 100644 index 0000000..0aa3a26 Binary files /dev/null and b/doc/src/images/windowsxp-dial.png differ diff --git a/doc/src/images/windowsxp-doublespinbox.png b/doc/src/images/windowsxp-doublespinbox.png new file mode 100644 index 0000000..3165a61 Binary files /dev/null and b/doc/src/images/windowsxp-doublespinbox.png differ diff --git a/doc/src/images/windowsxp-fontcombobox.png b/doc/src/images/windowsxp-fontcombobox.png new file mode 100644 index 0000000..96292b8 Binary files /dev/null and b/doc/src/images/windowsxp-fontcombobox.png differ diff --git a/doc/src/images/windowsxp-frame.png b/doc/src/images/windowsxp-frame.png new file mode 100644 index 0000000..5979b31 Binary files /dev/null and b/doc/src/images/windowsxp-frame.png differ diff --git a/doc/src/images/windowsxp-groupbox.png b/doc/src/images/windowsxp-groupbox.png new file mode 100644 index 0000000..0b6f7e2 Binary files /dev/null and b/doc/src/images/windowsxp-groupbox.png differ diff --git a/doc/src/images/windowsxp-horizontalscrollbar.png b/doc/src/images/windowsxp-horizontalscrollbar.png new file mode 100644 index 0000000..38812ec Binary files /dev/null and b/doc/src/images/windowsxp-horizontalscrollbar.png differ diff --git a/doc/src/images/windowsxp-label.png b/doc/src/images/windowsxp-label.png new file mode 100644 index 0000000..a1c3a39 Binary files /dev/null and b/doc/src/images/windowsxp-label.png differ diff --git a/doc/src/images/windowsxp-lcdnumber.png b/doc/src/images/windowsxp-lcdnumber.png new file mode 100644 index 0000000..102023c Binary files /dev/null and b/doc/src/images/windowsxp-lcdnumber.png differ diff --git a/doc/src/images/windowsxp-lineedit.png b/doc/src/images/windowsxp-lineedit.png new file mode 100644 index 0000000..9102b53 Binary files /dev/null and b/doc/src/images/windowsxp-lineedit.png differ diff --git a/doc/src/images/windowsxp-listview.png b/doc/src/images/windowsxp-listview.png new file mode 100644 index 0000000..b0fc9bd Binary files /dev/null and b/doc/src/images/windowsxp-listview.png differ diff --git a/doc/src/images/windowsxp-menu.png b/doc/src/images/windowsxp-menu.png new file mode 100644 index 0000000..b8ca947 Binary files /dev/null and b/doc/src/images/windowsxp-menu.png differ diff --git a/doc/src/images/windowsxp-progressbar.png b/doc/src/images/windowsxp-progressbar.png new file mode 100644 index 0000000..c8a73d6 Binary files /dev/null and b/doc/src/images/windowsxp-progressbar.png differ diff --git a/doc/src/images/windowsxp-pushbutton.png b/doc/src/images/windowsxp-pushbutton.png new file mode 100644 index 0000000..bf6b7bf Binary files /dev/null and b/doc/src/images/windowsxp-pushbutton.png differ diff --git a/doc/src/images/windowsxp-radiobutton.png b/doc/src/images/windowsxp-radiobutton.png new file mode 100644 index 0000000..ad8a908 Binary files /dev/null and b/doc/src/images/windowsxp-radiobutton.png differ diff --git a/doc/src/images/windowsxp-slider.png b/doc/src/images/windowsxp-slider.png new file mode 100644 index 0000000..9e2fca7 Binary files /dev/null and b/doc/src/images/windowsxp-slider.png differ diff --git a/doc/src/images/windowsxp-spinbox.png b/doc/src/images/windowsxp-spinbox.png new file mode 100644 index 0000000..e42073c Binary files /dev/null and b/doc/src/images/windowsxp-spinbox.png differ diff --git a/doc/src/images/windowsxp-tableview.png b/doc/src/images/windowsxp-tableview.png new file mode 100644 index 0000000..5d12137 Binary files /dev/null and b/doc/src/images/windowsxp-tableview.png differ diff --git a/doc/src/images/windowsxp-tabwidget.png b/doc/src/images/windowsxp-tabwidget.png new file mode 100644 index 0000000..3c8e777 Binary files /dev/null and b/doc/src/images/windowsxp-tabwidget.png differ diff --git a/doc/src/images/windowsxp-textedit.png b/doc/src/images/windowsxp-textedit.png new file mode 100644 index 0000000..d89c75c Binary files /dev/null and b/doc/src/images/windowsxp-textedit.png differ diff --git a/doc/src/images/windowsxp-timeedit.png b/doc/src/images/windowsxp-timeedit.png new file mode 100644 index 0000000..751cca9 Binary files /dev/null and b/doc/src/images/windowsxp-timeedit.png differ diff --git a/doc/src/images/windowsxp-toolbox.png b/doc/src/images/windowsxp-toolbox.png new file mode 100644 index 0000000..99b471e Binary files /dev/null and b/doc/src/images/windowsxp-toolbox.png differ diff --git a/doc/src/images/windowsxp-toolbutton.png b/doc/src/images/windowsxp-toolbutton.png new file mode 100644 index 0000000..ea63e16 Binary files /dev/null and b/doc/src/images/windowsxp-toolbutton.png differ diff --git a/doc/src/images/windowsxp-treeview.png b/doc/src/images/windowsxp-treeview.png new file mode 100644 index 0000000..050cc2f Binary files /dev/null and b/doc/src/images/windowsxp-treeview.png differ diff --git a/doc/src/images/worldtimeclock-connection.png b/doc/src/images/worldtimeclock-connection.png new file mode 100644 index 0000000..42c2560 Binary files /dev/null and b/doc/src/images/worldtimeclock-connection.png differ diff --git a/doc/src/images/worldtimeclock-signalandslot.png b/doc/src/images/worldtimeclock-signalandslot.png new file mode 100644 index 0000000..d9d3271 Binary files /dev/null and b/doc/src/images/worldtimeclock-signalandslot.png differ diff --git a/doc/src/images/worldtimeclockbuilder-example.png b/doc/src/images/worldtimeclockbuilder-example.png new file mode 100644 index 0000000..4b91af3 Binary files /dev/null and b/doc/src/images/worldtimeclockbuilder-example.png differ diff --git a/doc/src/images/worldtimeclockplugin-example.png b/doc/src/images/worldtimeclockplugin-example.png new file mode 100644 index 0000000..89481ad Binary files /dev/null and b/doc/src/images/worldtimeclockplugin-example.png differ diff --git a/doc/src/images/x11_dependencies.png b/doc/src/images/x11_dependencies.png new file mode 100644 index 0000000..02bce1a Binary files /dev/null and b/doc/src/images/x11_dependencies.png differ diff --git a/doc/src/images/xform.png b/doc/src/images/xform.png new file mode 100644 index 0000000..8221a00 Binary files /dev/null and b/doc/src/images/xform.png differ diff --git a/doc/src/images/xml-examples.png b/doc/src/images/xml-examples.png new file mode 100644 index 0000000..617ffef Binary files /dev/null and b/doc/src/images/xml-examples.png differ diff --git a/doc/src/images/xmlstreamexample-filemenu.png b/doc/src/images/xmlstreamexample-filemenu.png new file mode 100644 index 0000000..e074fb7 Binary files /dev/null and b/doc/src/images/xmlstreamexample-filemenu.png differ diff --git a/doc/src/images/xmlstreamexample-helpmenu.png b/doc/src/images/xmlstreamexample-helpmenu.png new file mode 100644 index 0000000..0dc4392 Binary files /dev/null and b/doc/src/images/xmlstreamexample-helpmenu.png differ diff --git a/doc/src/images/xmlstreamexample-screenshot.png b/doc/src/images/xmlstreamexample-screenshot.png new file mode 100644 index 0000000..bbaa423 Binary files /dev/null and b/doc/src/images/xmlstreamexample-screenshot.png differ diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc new file mode 100644 index 0000000..49dfafd --- /dev/null +++ b/doc/src/index.qdoc @@ -0,0 +1,244 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page index.html + + \keyword Qt Reference Documentation + + \if defined(qtopiacore) + \if defined(opensourceedition) + \title Qt for Embedded Linux Reference Documentation (Open Source Edition) + \endif + + \if defined(desktoplightedition) + \title Qt for Embedded Linux Reference Documentation (GUI Framework Edition) + \endif + + \if defined(desktopedition) + \title Qt for Embedded Linux Reference Documentation (Full Framework Edition) + \endif + + \if !defined(opensourceedition) \ + && !defined(desktoplightedition) \ + && !defined(desktopedition) + \title Qt for Embedded Linux Reference Documentation + \endif + + \subtitle Qt for Embedded Linux + \endif + \if !defined(qtopiacore) + \if defined(opensourceedition) + \title Qt Reference Documentation (Open Source Edition) + \endif + + \if defined(desktoplightedition) + \title Qt Reference Documentation (GUI Framework Edition) + \endif + + \if defined(desktopedition) + \title Qt Reference Documentation (Full Framework Edition) + \endif + + \if !defined(opensourceedition) \ + && !defined(desktoplightedition) \ + && !defined(desktopedition) + \title Qt Reference Documentation + \endif + \endif + + \if defined(opensourceedition) + \bold{Note:} This edition is for the development of \l{Qt + Open Source Edition}{Free and Open Source} software only; see + \l{Qt Commercial Editions}. + \endif + + \raw HTML + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Getting Started +	+ General +	+ Developer Resources +
+ + What's New in Qt 4.5 + How to Learn Qt + Installation + Tutorials, Examples and Demonstrations + Porting from Qt 3 to Qt 4 + +	+ + About Qt + About Us + Commercial Edition + Open Source Edition + Supported Platforms + +	+ + Frequently Asked Questions + Qt Community Web Sites + Qt Quarterly + How to Report a Bug + Other Online Resources + +
+ API Reference +	+ Core Features +	+ Key Technologies +
+ + All Classes + Main Classes + Grouped Classes + Annotated Classes + Qt Classes by Module + All Namespaces + Inheritance Hierarchy + All Functions + Qt for Embedded Platforms + All Overviews and HOWTOs + Qt Widget Gallery + Class Chart + +	+ + Signals and Slots + Object Model + Layout Management + Main Window Architecture + Paint System + Graphics View + Accessibility + Tool and Container Classes + Rich Text Processing + Internationalization + Plugin System + Multithreaded Programming + Inter-Process Communication (IPC) + Unit Testing Framework + +	+ + Model/View Programming + Style Sheets + Help Module + Network Module + OpenGL Module + Script Module + SQL Module + SVG Module + WebKit Integration + XML Module + XML Patterns: XQuery & XPath + Phonon Multimedia Framework + Script Tools Module + ActiveQt Framework + +
+ Add-ons & Services +	+ Tools +	+ Licenses & Credits +
+ + Qt Solutions + Partner Add-ons + Third-Party Qt Components (qt-apps.org) + Support + Training + +	+ + Qt Designer + Qt Assistant + Qt Linguist + qmake + All Tools + +	+ + GNU GPL, GNU LGPL + Third-Party Licenses Used in Qt + Other Licenses Used in Qt + Trademark Information + Credits + +
+ \endraw + +*/ diff --git a/doc/src/installation.qdoc b/doc/src/installation.qdoc new file mode 100644 index 0000000..fb0314e --- /dev/null +++ b/doc/src/installation.qdoc @@ -0,0 +1,869 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/**************************************************************************** +** Please remember to update the corresponding INSTALL files. +****************************************************************************/ + +/*! +\group installation +\title Installation +\ingroup buildsystem +\ingroup topics +\brief Installing Qt on supported platforms. + +The installation procedure is different on each Qt platform. +Please follow the instructions for your platform from the following list. + +\generatelist{related} +*/ + +/*! \page install-x11.html +\title Installing Qt on X11 Platforms +\ingroup installation +\brief How to install Qt on platforms with X11. +\previouspage Installation + +\note Qt for X11 has some requirements that are given in more detail +in the \l{Qt for X11 Requirements} document. + +\list 1 +\o If you have the commercial edition of Qt, install your license + file as \c{$HOME/.qt-license}. + + For the open source version you do not need a license file. + +\o Unpack the archive if you have not done so already. For example, + if you have the \c{qt-x11-opensource-desktop-%VERSION%.tar.gz} + package, type the following commands at a command line prompt: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 0 + + This creates the directory \c{/tmp/qt-x11-opensource-desktop-%VERSION%} + containing the files from the archive. We only support the GNU version of + the tar archiving utility. Note that on some systems it is called gtar. + +\o Building + + To configure the Qt library for your machine type, run the + \c{./configure} script in the package directory. + + By default, Qt is configured for installation in the + \c{/usr/local/Trolltech/Qt-%VERSION%} directory, but this can be + changed by using the \c{-prefix} option. + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 1 + + Type \c{./configure -help} to get a list of all available options. + + To create the library and compile all the demos, examples, tools, + and tutorials, type: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 2 + + If \c{-prefix} is outside the build directory, you need to install + the library, demos, examples, tools, and tutorials in the appropriate + place. To do this, type: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 3 + + , as root if necessary. + + Note that on some systems the make utility is named differently, + e.g. gmake. The configure script tells you which make utility to + use. + + \bold{Note:} If you later need to reconfigure and rebuild Qt from the + same location, ensure that all traces of the previous configuration are + removed by entering the build directory and typing \c{make confclean} + before running \c configure again. + +\o Environment variables + + In order to use Qt, some environment variables needs to be + extended. + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 4 + + This is done like this: + + In \c{.profile} (if your shell is bash, ksh, zsh or sh), add the + following lines: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 5 + + In \c{.login} (in case your shell is csh or tcsh), add the following line: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 6 + + If you use a different shell, please modify your environment + variables accordingly. + + For compilers that do not support rpath you must also extended the + \c LD_LIBRARY_PATH environment variable to include + \c{/usr/local/Trolltech/Qt-%VERSION%/lib}. On Linux with GCC this step + is not needed. + +\o That's all. Qt is now installed. + + If you are new to Qt, we suggest that you take a look at the demos + and examples to see Qt in action. Run the Qt Examples and Demos + either by typing \c qtdemo on the command line or through the + desktop's Main menu. + + You might also want to try the following links: + + \list + \o \l{Configuring Qt} + \o \l{How to Learn Qt} + \o \l{Tutorials} + \o \l{Developer Zone} + \o \l{Deploying Qt Applications} + \endlist +\endlist + + We hope you will enjoy using Qt. Good luck! + +*/ + +/*! +\page install-win.html +\title Installing Qt on Windows +\ingroup installation +\brief How to install Qt on Windows. +\previouspage Installation + +\note Qt for Windows has some requirements that are given in more detail +in the \l{Qt for Windows Requirements} document. + +\table +\row \o \bold{Notes:} +\list +\o If you have obtained a binary package for this platform, +consult the installation instructions provided instead of the ones in +this document. +\o \l{Open Source Versions of Qt} is not officially supported for use with +any version of Visual Studio. Integration with Visual Studio is available +as part of the \l{Qt Commercial Editions}. + +\endlist +\endtable + +\list 1 +\o If you have the commercial edition of Qt, copy the license file + from your account on dist.trolltech.com into your home directory + (this may be known as the \c userprofile environment variable) and + rename it to \c{.qt-license}. This renaming process must be done + using a \e{command prompt} on Windows, \bold{not} with Windows Explorer. + For example on Windows 2000, \c{%USERPROFILE%} should be something + like \c{C:\Documents and Settings\username} + + For the open source version you do not need a license file. + +\o Uncompress the files into the directory you want Qt installed; + e.g. \c{C:\Qt\%VERSION%}. + + \note The install path must not contain any spaces or Windows specific + file system characters. + +\o Environment variables + + In order to build and use Qt, the \c PATH environment variable needs to be + extended: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 7 + + This is done by adding \c{c:\Qt\%VERSION%\bin} to the \c PATH variable. + + For newer versions of Windows, \c PATH can be extended through + the \menu{Control Panel|System|Advanced|Environment variables} menu. + + You may also need to ensure that the locations of your compiler and + other build tools are listed in the \c PATH variable. This will depend + on your choice of software development environment. + + \bold{Note}: If you don't use the configured shells, which is + available in the application menu, in the \l{Open Source Versions of Qt}, + \c configure requires that \c sh.exe is not in the path + or that it is run from \c msys. This also goes for mingw32-make. + +\o Building + + To configure the Qt library for your machine, type the following command + in a \bold{Visual Studio} command prompt: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 8 + + Type \c{configure -help} to get a list of all available options. + + If you have multiple compilers installed, and want to build the Qt library + using a specific compiler, you must specify a \c qmake specification. + This is done by pasing \c{-platform } to configure; for example: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 9 + + In some cases you need to set up the compilation environment before running + configure in order to use the right compiler. For instance, you need to do this + if you have Visual Studio 2005 installed and want to compile Qt using the x64 + compiler because the 32-bit and 64-bit compiler both use the same + \c qmake specification file. + This is usually done by selecting + \menu{Microsoft Visual Studio 2005|Visual Studio Tools|} + from the \gui Start menu. + + The actual commands needed to build Qt depends on your development + system. For Microsoft Visual Studio to create the library and + compile all the demos, examples, tools and tutorials type: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 10 + + \note If you later need to reconfigure and rebuild Qt from the + same location, ensure that all traces of the previous configuration are + removed by entering the build directory and typing \c{nmake distclean} + before running \c configure again. + +\o That's all. Qt is now installed. + + If you are new to Qt, we suggest that you take a look at the demos + and examples to see Qt in action. Run the Qt Examples and Demos + either by typing \c qtdemo on the command line or through the + desktop's Start menu. + + You might also want to try the following links: + + \list + \o \l{How to Learn Qt} + \o \l{Tutorials} + \o \l{Developer Zone} + \o \l{Deploying Qt Applications} + \endlist + +\endlist + + We hope you will enjoy using Qt. Good luck! + +*/ + +/*! \page install-mac.html +\title Installing Qt on Mac OS X +\ingroup installation +\brief How to install Qt on Mac OS X. +\previouspage Installation + +\note Qt for Mac OS X has some requirements that are given in more detail +in the \l{Qt for Mac OS X Requirements} document. + +\bold{Note for the binary package}: If you have the binary package, simply double-click on the Qt.mpkg +and follow the instructions to install Qt. You can later run the \c{uninstall-qt.py} +script to uninstall the binary package. The script is located in /Developer/Tools and +must be run as root. + +The following instructions describe how to install Qt from the source package. + +\list 1 +\o If you have the commercial edition of Qt, install your license + file as \c{$HOME/.qt-license}. + + For the open source version you do not need a license file. + +\o Unpack the archive if you have not done so already. For example, + if you have the \c{qt-mac-opensource-desktop-%VERSION%.tar.gz} + package, type the following commands at a command line prompt: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 11 + + This creates the directory \c{/tmp/qt-mac-opensource-desktop-%VERSION%} + containing the files from the archive. + +\o Building + + To configure the Qt library for your machine type, run the + \c{./configure} script in the package directory. + + By default, Qt is configured for installation in the + \c{/usr/local/Trolltech/Qt-%VERSION%} directory, but this can be + changed by using the \c{-prefix} option. + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 12 + + Type \c{./configure -help} to get a list of all available options. + + Note that you will need to specify \c{-universal} if you want to + build universal binaries, and also supply a path to the \c{-sdk} + option if your development machine has a PowerPC CPU. By default, + Qt is built as a framework, but you can built it as a set of + dynamic libraries (dylibs) by specifying the \c{-no-framework} + option. + + Qt can also be configured to be built with debugging symbols. This + process is described in detail in the \l{Debugging Techniques} + document. + + To create the library and compile all the demos, examples, tools, + and tutorials, type: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 13 + + If \c{-prefix} is outside the build directory, you need to install + the library, demos, examples, tools, and tutorials in the appropriate + place. To do this, type: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 14 + + as root, if neccessary (note that this requires that you have administrator access + to your machine). + + There is a potential race condition when running make install with multiple + jobs. It is best to only run one make job (-j1) for the install. + + \bold{Note:} If you later need to reconfigure and rebuild Qt from the + same location, ensure that all traces of the previous configuration are + removed by entering the build directory and typing \c{make confclean} + before running \c configure again. + +\o Environment variables + + In order to use Qt, some environment variables need to be + extended. + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 15 + + This is done like this: + + In \c{.profile} (if your shell is bash), add the following lines: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 16 + + In \c{.login} (in case your shell is csh or tcsh), add the following line: + +\snippet doc/src/snippets/code/doc_src_installation.qdoc 17 + + If you use a different shell, please modify your environment + variables accordingly. + +\o That's all. Qt is now installed. + + If you are new to Qt, we suggest that you take a look at the demos + and examples to see Qt in action. Run the Qt Examples and Demos + either by typing \c qtdemo on the command line or through the + desktop's Start menu. + + You might also want to try the following links: + + \list + \o \l{How to Learn Qt} + \o \l{Tutorials} + \o \l{Developer Zone} + \o \l{Deploying Qt Applications} + \endlist +\endlist + + We hope you will enjoy using Qt. Good luck! + +*/ + +/*! \page install-wince.html +\title Installing Qt on Windows CE +\ingroup installation +\ingroup qtce +\brief How to install Qt on Windows CE. +\previouspage Installation + +\note Qt for Windows CE has some requirements that are given in more detail +in the \l{Qt for Windows CE Requirements} document. + +\list 1 + \o Uncompress the files into the directory you want to install Qt into; + e.g., \c{C:\Qt\%VERSION%}. + + \note The install path must not contain any spaces. + + \o Environment variables + + In order to build and use Qt, the \c PATH environment variable needs + to be extended: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 18 + + This is done by adding \c{c:\Qt\%VERSION%\bin} to the \c PATH variable. + + For newer versions of Windows, \c PATH can be extended through + "Control Panel->System->Advanced->Environment variables" and for + older versions by editing \c{c:\autoexec.bat}. + + Make sure the enviroment variables for your compiler are set. + Visual Studio includes \c{vcvars32.bat} for that purpose - or simply + use the "Visual Studio Command Prompt" from the Start menu. + + \o Configuring Qt + + To configure Qt for Windows Mobile 5.0 for Pocket PC, type the + following: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 19 + + If you want to configure Qt for another platform or with other + options, type \c{configure -help} to get a list of all available + options. See the \c README file for the list of supported platforms. + + + \o Building Qt + + Now, to build Qt you first have to update your \c PATH, \c INCLUDE + and \c LIB paths to point to the correct resources for your target + platforms. For a default installation of the Windows Mobile 5.0 + Pocket PC SDK, this is done with the following commands: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 20 + + We provide a convenience script for this purpose, called \c{setcepaths}. + Simply type: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 21 + + Then to build Qt type: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 22 + + \o That's all. Qt is now installed. + + To get started with Qt, you can check out the examples found in the + \c{examples} directory of your Qt installation. The documentation can + be found in \c{doc\html}. + + \bold{Remember:} If you reconfigure Qt for a different platform, + make sure you start with a new clean console to get rid of the + platform dependent include directories. + + The links below provide further information for using Qt: + \list + \o \l{How to Learn Qt} + \o \l{Tutorials} + \o \l{Developer Zone} + \o \l{Deploying Qt Applications} + \endlist + + You might also want to try the following Windows CE specific links: + \list + \o \l{Windows CE - Introduction to using Qt} + \o \l{Windows CE - Working with Custom SDKs} + \o \l{Windows CE - Using shadow builds} + \endlist + + Information on feature and performance tuning for embedded builds can + be found on the following pages: + \list + \o \l{Fine-Tuning Features in Qt} + \o \l{Qt Performance Tuning} + \endlist +\endlist + + We hope you will enjoy using Qt. Good luck! +*/ + +/*! \page install-S60.html + +\title Installing Qt on S60 +\ingroup installation +\ingroup qts60 +\brief How to install Qt on S60. + +\list 1 + \o Install needed IDE and SDKs + + Make sure you have the following installed: + \list + \o \l{http://www.forum.nokia.com/main/resources/tools_and_sdks/carbide_cpp/}{Carbide.c++ v2.0.0 or higher} + \o \l{http://www.forum.nokia.com/main/resources/tools_and_sdks/S60SDK/}{S60 Platform SDK 3rd Edition FP1 or higher} + \o \l{http://www.forum.nokia.com/main/resources/technologies/openc_cpp/}{Open C/C++ for S60 3rd Edition} (automatically included in 3.2 and higher) + \endlist + + These instructions assume the above tools are installed and + that the enviroment variables for your compiler are set correctly. + + \note Users of \bold{S60 Platform SDK 3rd Edition FP1} also need special updates. The update can be found + \l{http://pepper.troll.no/s60prereleases/patches/}{here}. + + \note The wsini.ini provided with the \bold{S60 Platform SDK 5th Edition v0.9} + needs to be updated for correct font rendering in the emulator. The update can be found + \l{http://pepper.troll.no/s60prereleases/patches/}{here}. + + \o Install Qt + + Uncompress the package into the directory you want Qt installed, + e.g. \c{C:\Qt\%VERSION%}. + + \note Qt must be installed on the same drive as the S60 SDK you are + using, and the install path must not contain any spaces. + + \o Environment variables + + In order to build and use Qt, the \c PATH environment variable needs + to be extended: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 18 + + This is done by adding \c{c:\Qt\%VERSION%\bin} to the \c PATH variable. + + On Windows the PATH can be extended by navigating to + "Control Panel->System->Advanced->Environment variables". + + In addition, you must configure the environment for use with the S60 + emulator. This is done by locating the Carbide.c++ submenu on the Start + menu, and choosing "Configure environment for WINSCW command line". + + \o Configure Qt + + To configure Qt for S60, do: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 23 + + For other options, type \c{configure -help} to get a list of all available + options. + + \o Build Qt + + The Qt libraries comes pre-built for real devices. + If you are using a 3.x S60 SDK, install \c{qts60binaries\3.x\qtlibs-%VERSION%.exe} + into the S60 SDK root directory. For example: \c{C:\Symbian\9.2\S60_3rd_FP1_2\} + If you are using a 5.0 S60 SDK, install \c{qts60binaries\5.0\qtlibs-%VERSION%.exe} + into the S60 SDK root directory. For example: \c{C:\S60\devices\S60_5th_Edition_SDK_v0.9\} + + To build Qt for the emulator, type: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 24 + + Congratulations, Qt is now ready to use. + + \o Running Qt demos + + We've included a subset of the Qt demos in this package for you + to try out. An excellent starting point is the "fluidlauncher" + demo. To run the demo on a real device, you first have to install + the Qt libraries on the device. + For 3.x devices install \c{qts60binaries\3.x\qt_libs_armv5_udeb.sisx} + For 5.0 devices install \c{qts60binaries\5.0\qt_libs_armv5_udeb.sisx} + included in this package to the device. Then type: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 25 + + This will create a self-signed \c fluidlauncher_gcce_udeb.sisx and + install it to your device. + + \note You can specify your own certificate and key files as additional parameters to + \c createpackage if default ones are not suitable. + + To run the demos on the emulator simply run: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 27 + + Or, if you need to supply arguments to the program, navigate to + \c{%EPOCROOT%\Epoc32\release\winscw\udeb\} and start any of the + Qt demos located there, for example: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 26 + + For more information about building and running Qt programs on S60, + see \l{S60 - Introduction to using Qt}. + + We hope you will enjoy using Qt. + +\endlist + +*/ +/*! + \page requirements.html + \title General Qt Requirements + \ingroup installation + \brief Outlines the general requirements and dependencies needed to install Qt. + + This page describes the specific requirements of libraries and components on which + Qt depends. For information about installing Qt, see the \l{Installation} page. + + \section1 OpenSSL (version 0.9.7 or later) + + Support for \l{SSL}{Secure Sockets Layer (SSL)} communication is provided by the + \l{OpenSSL Toolkit}, which must be obtained separately. + + \section1 Platform-Specific Requirements + + Each platform has its own specific set of dependencies. Please see the relevant + page for more details about the components that are required to build and install + Qt on your platform. + + \list + \o \l{Qt for Embedded Linux Requirements} + \o \l{Qt for Mac OS X Requirements} + \o \l{Qt for Windows CE Requirements} + \o \l{Qt for Windows Requirements} + \o \l{Qt for X11 Requirements} + \endlist +*/ + +/*! + \page requirements-win.html + \title Qt for Windows Requirements + \ingroup installation + \brief Setting up the Windows environment for Qt. + \previouspage General Qt Requirements + + If you are using a binary version of Qt with Visual Studio 2005, you must + first install the Visual Studio Service Pack 1 available + \l{http://www.microsoft.com/downloads/details.aspx?FamilyId=BB4A75AB-E2D4-4C96-B39D-37BAF6B5B1DC&displaylang=en}{here} + to avoid runtime conflicts. + + To build Qt with Phonon on Windows, you require: + + \list + \o Microsoft's DirectX Software Development Kit which can be + downloaded + \l{http://msdn2.microsoft.com/en-us/directx/aa937788.aspx}{here}, and + \o Microsoft's Windows Server 2003 R2 Platform SDK which is available + \l{http://www.microsoft.com/downloads/details.aspx?FamilyID=0baf2b35-c656-4969-ace8-e4c0c0716adb&DisplayLang=en}{here}. + \endlist + + \sa {Known Issues in %VERSION%} +*/ + +/*! + \page requirements-mac.html + \title Qt for Mac OS X Requirements + \ingroup installation + \brief Setting up the Mac OS X environment for Qt. + \previouspage General Qt Requirements + + \sa {Known Issues in %VERSION%} +*/ + +/*! + \page requirements-x11.html + \title Qt for X11 Requirements + \ingroup installation + \brief Setting up the X11 environment for Qt. + \previouspage General Qt Requirements + + \tableofcontents + + \section1 QtGui Dependencies + + \image x11_dependencies.png Qt for X11 Dependencies + + \raw HTML + + \endraw + + The QtGui module and the QtCore module, which provides the non-GUI features required + by QtGui, depend on the libraries described in the following table. + + \table 90% + \header \o Name \o Library \o Notes \o Configuration options \o Minimum working version + \raw HTML + + XRender libXrender X Rendering Extension; used for anti-aliasing + -xrender or auto-detected0.9.0 + + Xrandr libXrandr X Resize and Rotate Extension + -xrandr or auto-detected1.0.2 + + Xcursor libXcursor X Cursor Extension + -xcursor or auto-detected1.1.4 + + Xfixes libXfixes X Fixes Extension + -xfixes or auto-detected3.0.0 + + Xinerama libXinerama Multi-head support + -xinerama or auto-detected1.1.0 + + Xi libXi X11 Input Extensions + auto-detected1.3.0 + + Xt libXt Xt Intrinsics0.99 + + Xext libXext X Extensions6.4.3 + + X11 libX11 X11 Client-Side Library6.2.1 + + SM libSM X Session Management + -sm or auto-detected6.0.4 + + ICE libICE Inter-Client Exchange + -sm or auto-detected6.3.5 + + glib libglib-2.0 Common event loop handling + -glib or auto-detected2.8.3 + + pthread libpthread Multithreading + 2.3.5 + + \endraw + \endtable + + \note You must compile with XRender support to get alpha transparency + support for pixmaps and images. + + \section1 Phonon Dependencies + + As described in the \l{Phonon Overview}, Phonon uses the GStreamer multimedia + framework as the backend for audio and video playback on X11. The minimum required + version of GStreamer is 0.10. + + To build Phonon, you need the GStreamer library, base plugins, and development + files for your system. The package names for GStreamer vary between Linux + distributions; try searching for \c gstreamer or \c libgstreamer in your + distribution's package repository to find suitable packages. + + \sa {Known Issues in %VERSION%} +*/ + +/*! + \page requirements-wince.html + \title Qt for Windows CE Requirements + \ingroup installation + \brief Setting up the Windows CE environment for Qt. + \previouspage General Qt Requirements + + Qt is known to work with Visual Studio 2005 and the following SDKs for + Windows CE development on Windows XP and Windows Vista: + + \list + \o Windows CE 5.0 Standard SDK for ARM, X86, and MIPS + \o Windows CE 6.0 SDKs for ARM generated using the defaults found in + Platform Builder + \o Windows Mobile 5.0 (\e{Pocket PC}, \e{Smartphone} and + \e{Pocket PC with Phone} editions) + \o Windows Mobile 6.0 (\e{Standard}, \e{Classic} and + \e{Professional} editions) + \endlist + + Below is a list of links to download the SDKs: + + \list + \o \l{http://www.microsoft.com/downloads/details.aspx?familyid=fa1a3d66-3f61-4ddc-9510-ae450e2318c3&displaylang=en} + {Windows CE 5 Standard SDK} + \o \l{http://www.microsoft.com/downloads/details.aspx?familyid=83A52AF2-F524-4EC5-9155-717CBE5D25ED&displaylang=en} + {Windows Mobile 5 Pocket PC} + \o \l{http://www.microsoft.com/downloads/details.aspx?familyid=DC6C00CB-738A-4B97-8910-5CD29AB5F8D9&displaylang=en} + {Windows Mobile 5 Smartphone} + \o \l{http://www.microsoft.com/downloads/details.aspx?familyid=06111A3A-A651-4745-88EF-3D48091A390B&displaylang=en } + {Windows Mobile 6 Professional/Standard} + \endlist + + \table + \row \bold{Note:} + \o + \list 1 + \o Currently, there is only compile support for Windows CE 5.0 + Standard SDK for SH-4. + \o There is currently no "out of the box" support for the + Windows CE Automotive or Portable Media SDKs from Microsoft. + \endlist + \endtable + + + Device manufacturers may prefer to make their own customized version of + Windows CE using Platform Builder. In order for Qt for Windows CE to + support a custom SDK, a build specification needs to be created. More + information on Windows CE Customization can be found + \l{Windows CE - Working with Custom SDKs}{here}. + + \sa {Known Issues in %VERSION%} +*/ + +/*! + \page requirements-embedded-linux.html + \title Qt for Embedded Linux Requirements + \ingroup installation + \brief Setting up the Embedded Linux environment for Qt. + \previouspage General Qt Requirements + + \sa {Known Issues in %VERSION%} + + \section1 Building Qt for Embedded Linux with uclibc + + If you intend to include the QtWebKit module in your Qt build then you should + use version \bold{uClibc 0.9.29 or greater} as that is the earliest version + with sufficient pthread support. + + \section1 Memory Requirements + + The memory and storage requirements for Qt for Embedded Linux depend on a + an variety of different factors, including the target architecture and the + features enabled in the Qt build. + + The following table shows typical library sizes for the most common Qt + libraries on different architectures, built in release mode with different + feature profiles. + + \table + \header \o{1,2} Architecture \o{1,2} Compiler \o{2,1} QtCore \o{2,1} QtGui \o{2,1} QtNetwork \o{2,1} QtWebKit + \header \o Minimal \o Normal \o Minimal \o Normal \o Minimal \o Normal \o Minimal \o Normal + \row \o linux-x86-g++ \o GCC 4.2.4 \o 1.7M \o 2.7M \o 3.3M \o 9.9M \o 653K \o 1.1M \o N/A \o 17M + \row \o linux-arm-g++ \o GCC 4.1.1 \o 1.9M \o 3.2M \o 4.1M \o 11M \o 507K \o 1.0M \o N/A \o 17M + \row \o linux-arm-g++ (thumb) + \o GCC 4.1.1 \o 1.7M \o 2.8M \o 4.0M \o 9.8M \o 409K \o 796K \o N/A \o 17M + \row \o linux-mips-g++ (MIPS32) + \o GCC 4.2.4 \o 2.0M \o 3.2M \o 4.5M \o 12M \o 505K \o 1003K \o N/A \o 21M + \endtable + + Library sizes are given in the following units: K = 1024 bytes; M = 1024K. + QtWebKit is excluded from the minimal configuration. + + The \l{Fine-Tuning Features in Qt} document covers the process of configuring + Qt builds to avoid the inclusion of unnecessary features. + + \section1 Additional X11 Libraries for QVFb + + The Virtual Framebuffer (QVFb) application requires the \c libxtst library + in addition to the libraries used to build Qt for X11. This library + enables the use of the Record extension to the X protocol to be used in + applications. +*/ diff --git a/doc/src/introtodbus.qdoc b/doc/src/introtodbus.qdoc new file mode 100644 index 0000000..71c65d5 --- /dev/null +++ b/doc/src/introtodbus.qdoc @@ -0,0 +1,212 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page intro-to-dbus.html + \title Introduction to D-Bus + + \keyword QtDBus + \ingroup architecture + \brief An introduction to Inter-Process Communication and Remote Procedure Calling with D-Bus. + + \section1 Introduction + + D-Bus is an Inter-Process Communication (IPC) and Remote Procedure + Calling (RPC) mechanism originally developed for Linux to replace + existing and competing IPC solutions with one unified protocol. It + has also been designed to allow communication between system-level + processes (such as printer and hardware driver services) and + normal user processes. + + It uses a fast, binary message-passing protocol, which is suitable + for same-machine communication due to its low latency and low + overhead. Its specification is currently defined by the + \tt{freedesktop.org} project, and is available to all parties. + + Communication in general happens through a central server + application, called the "bus" (hence the name), but direct + application-to-application communication is also possible. When + communicating on a bus, applications can query which other + applications and services are available, as well as activate one + on demand. + + \section1 The Buses + + D-Bus buses are used to when many-to-many communication is + desired. In order to achieve that, a central server is launched + before any applications can connect to the bus: this server is + responsible for keeping track of the applications that are + connected and for properly routing messages from their source to + their destination. + + In addition, D-Bus defines two well-known buses, called the + system bus and the session bus. These buses are special in the + sense that they have well-defined semantics: some services are + defined to be found in one or both of these buses. + + For example, an application wishing to query the list of hardware + devices attached to the computer will probably communicate to a + service available on the system bus, while the service providing + opening of the user's web browser will be probably found on the + session bus. + + On the system bus, one can also expect to find restrictions on + what services each application is allowed to offer. Therefore, one + can be reasonably certain that, if a certain service is present, + it is being offered by a trusted application. + + \section1 Concepts + + \section2 Messages + + On the low level, applications communicate over D-Bus by sending + messages to one another. Messages are used to relay the remote + procedure calls as well as the replies and errors associated + with them. When used over a bus, messages have a destination, + which means they are routed only to the interested parties, + avoiding congestion due to "swarming" or broadcasting. + + A special kind of message called a "signal message" + (a concept based on Qt's \l {Signals and Slots} mechanism), + however, does not have a pre-defined destination. Since its + purpose is to be used in a one-to-many context, signal messages + are designed to work over an "opt-in" mechanism. + + The QtDBus module fully encapsulates the low-level concept of + messages into a simpler, object-oriented approach familiar to Qt + developers. In most cases, the developer need not worry about + sending or receiving messages. + + \section2 Service Names + + When communicating over a bus, applications obtain what is + called a "service name": it is how that application chooses to be + known by other applications on the same bus. The service names + are brokered by the D-Bus bus daemon and are used to + route messages from one application to another. An analogous + concept to service names are IP addresses and hostnames: a + computer normally has one IP address and may have one or more + hostnames associated with it, according to the services that it + provides to the network. + + On the other hand, if a bus is not used, service names are also + not used. If we compare this to a computer network again, this + would equate to a point-to-point network: since the peer is + known, there is no need to use hostnames to find it or its IP + address. + + The format of a D-Bus service name is in fact very similar to a + host name: it is a dot-separated sequence of letters and + digits. The common practice is even to name one's service name + according to the domain name of the organization that defined + that service. + + For example, the D-Bus service is defined by + \tt{freedesktop.org} and can be found on the bus under the + service name: + + \snippet doc/src/snippets/code/doc_src_introtodbus.qdoc 0 + + \section2 Object Paths + + Like network hosts, applications provide specific services to + other applications by exporting objects. Those objects are + hierarchically organised, much like the parent-child + relationship that classes derived from QObject possess. One + difference, however, is that there is the concept of "root + object", that all objects have as ultimate parent. + + If we continue our analogy with Web services, object paths + equate to the path part of a URL: + + \img qurl-ftppath.png + + Like them, object paths in D-Bus are formed resembling path + names on the filesystem: they are slash-separated labels, each + consisting of letters, digits and the underscore character + ("_"). They must always start with a slash and must not end with + one. + + \section2 Interfaces + + Interfaces are similar to C++ abstract classes and Java's + \c interface keyword and declare the "contract" that is + established between caller and callee. That is, they establish + the names of the methods, signals and properties that are + available as well as the behavior that is expected from either + side when communication is established. + + Qt uses a very similar mechanism in its \l {How to Create Qt + Plugins}{Plugin system}: Base classes in C++ are associated + with a unique identifier by way of the Q_DECLARE_INTERFACE() + macro. + + D-Bus interface names are, in fact, named in a manner similar to + what is suggested by the Qt Plugin System: an identifier usually + constructed from the domain name of the entity that defined that + interface. + + \section2 Cheat Sheet + + To facilitate remembering of the naming formats and their + purposes, the following table can be used: + + \table 90% + \header \o D-Bus Concept \o Analogy \o Name format + \row \o Service name \o Network hostnames \o Dot-separated + ("looks like a hostname") + \row \o Object path \o URL path component \o Slash-separated + ("looks like a path") + \row \o Interface \o Plugin identifier \o Dot-separated + \endtable + + \section2 Further Reading + + The following documents contain information about Qt's D-Bus integration + features, and provide details about the mechanisms used to send and receive + type information over the bus: + + \list + \o \l{Using QtDBus Adaptors} + \o \l{The QtDBus Type System} + \o \l{QtDBus XML compiler (qdbusxml2cpp)} + \endlist +*/ diff --git a/doc/src/ipc.qdoc b/doc/src/ipc.qdoc new file mode 100644 index 0000000..97ed22e --- /dev/null +++ b/doc/src/ipc.qdoc @@ -0,0 +1,91 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group ipc + \title Inter-Process Communication in Qt + \ingroup groups + \ingroup architecture + \brief Inter-Process communication in Qt applications. + + Qt provides several ways to implement Inter-Process Communication + (IPC) in Qt applications. + + \section1 D-Bus + + The \l{QtDBus} module is a Unix-only library + you can use to implement IPC using the D-Bus protocol. It extends + Qt's \l{signalsandslots.html} {Signals and Slots} mechanism to the + IPC level, allowing a signal emitted by one process to be + connected to a slot in another process. This \l {Introduction to + D-Bus} page has detailed information on how to use the \l{QtDBus} + module. + + \section1 TCP/IP + + The cross-platform \l{QtNetwork} module + provides classes that make network programming portable and + easy. It offers high-level classes (e.g., QHttp, QFtp) that + communicate using specific application-level protocols, and + lower-level classes (e.g., QTcpSocket, QTcpServer, QSslSocket) for + implementing protocols. + + \section1 Shared Memory + + The cross-platform shared memory class, QSharedMemory, provides + access to the operating system's shared memory implementation. + It allows safe access to shared memory segments by multiple threads + and processes. Additionally, QSystemSemaphore can be used to control + access to resources shared by the system, as well as to communicate + between processes. + + \section1 Qt COmmunications Protocol (QCOP) + + The QCopChannel class implements a protocol for transferring messages + between client processes across named channels. QCopChannel is + only available in \l{Qt for Embedded Linux}. Like the \l{QtDBus} + module, QCOP extends Qt's \l{Signals and Slots} mechanism to the + IPC level, allowing a signal emitted by one process to be + connected to a slot in another process, but unlike QtDBus, QCOP + does not depend on a third party library. + +*/ + diff --git a/doc/src/known-issues.qdoc b/doc/src/known-issues.qdoc new file mode 100644 index 0000000..60fd63d --- /dev/null +++ b/doc/src/known-issues.qdoc @@ -0,0 +1,151 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page known-issues.html + \title Known Issues in %VERSION% + \ingroup platform-notes + \brief A summary of known issues in Qt %VERSION% at the time of release. + + An up-to-date list of known issues with Qt %VERSION% can be found via the + \l{Task Tracker} on the Qt website which provides additional information + about known issues and tasks related to Qt. + + \section1 General Issues + + When running Qt applications on Windows or with \c{-graphicssystem raster}, + any process that triggers a QWidget::update() from within a destructor + might result in a crash. + + + \section1 Issues with Third Party Software + + \section2 Intel Compiler Support + + Although it is possible to build applications against Qt 4.5.0 using Intel + CC 10, these applications will crash when run. A fix for this issue is + scheduled for Qt 4.5.1. We recommend that developers who rely on this + compiler wait until the fix is applied before upgrading to the Qt 4.5.x + series of releases. + + \section2 X11 Hardware Support + + \list + \o There is a bug in the 169.xx NVIDIA drivers on certain GeForce 8 series + cards that is triggered by the OpenGL paint engine when using QPainter + on a QGLWidget to draw paths and polygons. Some other painting + operations that end up in the path fallback are affected as well. The + bug causes the whole X server to repeatedly hang for several seconds at + a time. + \o There is an issue with NVIDIA's 9xxx driver series on X11 that causes a + crash in cases where there are several \l{QGLContext}s and the extended + composition modes are used (the composition modes between and including + QPainter::CompositionMode_Multiply and + QPainter::CompositionMode_Exclusion). This affects the composition mode + demo in Qt 4.5, for example. The crash does not occur in newer versions + of the drivers. + \endlist + + \section2 Windows Hardware Support + + \list + \o When using version 6.14.11.6921 of the NVIDIA drivers for the GeForce + 6600 GT under Windows XP, Qt applications which use drag and drop will + display reduced size drag and drop icons when run alongside + applications that use OpenGL. This problem can be worked around by + reducing the level of graphics acceleration provided by the driver, or + by disabling hardware acceleration completely. + \endlist + + \section2 Windows Software Issues + + \list + + \o When building Qt 4.5.0 with Windows 7, the build fails with an error + message regarding failing to embed manifest. This a known issue with + Windows 7, explained in the Windows 7 SDK Beta + \l{http://download.microsoft.com/download/8/8/0/8808A472-6450-4723-9C87-977069714B27/ReleaseNotes.Htm} + {release notes}. A workaround for this issue is to patch the + \bold{embed_manifest_exe.prf} file with the following: + + \code + diff --git a/mkspecs/features/win32/embed_manifest_exe.prf b/mkspecs/features/win32/embed_manifest_exe.prf + index e1747f1..05f116e 100644 + --- a/mkspecs/features/win32/embed_manifest_exe.prf + +++ b/mkspecs/features/win32/embed_manifest_exe.prf + @@ -8,4 +8,9 @@ if(win32-msvc2005|win32-msvc2008):!equals(TEMPLATE_PREFIX, "vc"):equals(TEMPLATE + QMAKE_POST_LINK = $$quote(mt.exe -nologo -manifest \"$$replace(OBJECTS_DIR,/,\\)\\$${NOPATH_TARGET}.intermediate.ma + nifest\" -outputresource:$(DESTDIR_TARGET);1$$escape_expand(\n\t)) + QMAKE_POST_LINK += $$QMAKE_PREV_POST_LINK + QMAKE_CLEAN += \"$$replace(OBJECTS_DIR,/,\\)\\$${NOPATH_TARGET}.intermediate.manifest\" + + isEmpty(RC_FILE) { + + system("echo.>$$replace(OUT_PWD,/,\\)\\$$replace(OBJECTS_DIR,/,\\)\\Windows7WorkAround.rc") + + RC_FILE = $$replace(OUT_PWD,/,\\)\\$$replace(OBJECTS_DIR,/,\\)\\Windows7WorkAround.rc + + } + + + } + \endcode + + \o Under certain circumstances Visual Studio Integration v1.4.0 will not + be able to install the integration for Visual Studio 2005 on Windows + Vista. An error message states that .NET Framework v2.0 Service Pack 1 + is not installed. This is due to a problem with the built-in + installation of this on Windows Vista. This issue can be fixed by + installing .NET Framework version 3.5. + + \o With NVIDIA GeForce 7950 GT (driver version 6.14.11.7824), a fullscreen + QGLWidget flickers when child widgets are shown/hidden. The workaround + for this is to use \l{QWidget::}{setGeometry()} with a width/height 1 + pixel bigger than your geometry and call \l{QWidget::}{show()}. + + \o A bug in the Firebird database can cause an application to crash when + \c{fbembed.dll} is unloaded. The bug is fixed in version 2.5. + + \endlist + + \section2 Mac OS X Software Support + + \list + \o If a sheet is opened for a given window, clicking the title bar of that + window will cause it to flash. This behavior has been reported to Apple + (bug number 5827676). + \endlist +*/ diff --git a/doc/src/layout.qdoc b/doc/src/layout.qdoc new file mode 100644 index 0000000..38163c8 --- /dev/null +++ b/doc/src/layout.qdoc @@ -0,0 +1,381 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page layout.html + + \title Layout Classes + \ingroup architecture + \ingroup classlists + \brief A tour of the standard layout managers and an introduction to custom + layouts. + + The Qt layout system provides a simple and powerful way of automatically + arranging child widgets within a widget to ensure that they make good use + of the available space. + + \tableofcontents + + \section1 Introduction + + Qt includes a set of layout management classes that are used to describe + how widgets are laid out in an application's user interface. These layouts + automatically position and resize widgets when the amount of space + available for them changes, ensuring that they are consistently arranged + and that the user interface as a whole remains usable. + + All QWidget subclasses can use layouts to manage their children. The + QWidget::setLayout() function applies a layout to a widget. When a layout + is set on a widget in this way, it takes charge of the following tasks: + + \list + \o Positioning of child widgets. + \o Sensible default sizes for windows. + \o Sensible minimum sizes for windows. + \o Resize handling. + \o Automatic updates when contents change: + \list + \o Font size, text or other contents of child widgets. + \o Hiding or showing a child widget. + \o Removal of child widgets. + \endlist + \endlist + + Qt's layout classes were designed for hand-written C++ code, allowing + measurements to be specified in pixels for simplicity, so they are easy to + understand and use. The code generated for forms created using \QD also + uses the layout classes. \QD is useful to use when experimenting with the + design of a form since it avoids the compile, link and run cycle usually + involved in user interface development. + + + \section1 Horizontal, Vertical, Grid, and Form Layouts + + The easiest way to give your widgets a good layout is to use the built-in + layout managers: QHBoxLayout, QVBoxLayout, QGridLayout, and QFormLayout. + These classes inherit from QLayout, which in turn derives from QObject (not + QWidget). They take care of geometry management for a set of widgets. To + create more complex layouts, you can nest layout managers inside each other. + + \list + \o A QHBoxLayout lays out widgets in a horizontal row, from left to + right (or right to left for right-to-left languages). + \image qhboxlayout-with-5-children.png + + \o A QVBoxLayout lays out widgets in a vertical column, from top to + bottom. + \image qvboxlayout-with-5-children.png + + \o A QGridLayout lays out widgets in a two-dimensional grid. Widgets + can occupy multiple cells. + \image qgridlayout-with-5-children.png + + \o A QFormLayout lays out widgets in a 2-column descriptive label- + field style. + \image qformlayout-with-6-children.png + \endlist + + + \section2 Laying Out Widgets in Code + + The following code creates a QHBoxLayout that manages the geometry of five + \l{QPushButton}s, as shown on the first screenshot above: + + \snippet doc/src/snippets/layouts/layouts.cpp 0 + \snippet doc/src/snippets/layouts/layouts.cpp 1 + \snippet doc/src/snippets/layouts/layouts.cpp 2 + \codeline + \snippet doc/src/snippets/layouts/layouts.cpp 3 + \snippet doc/src/snippets/layouts/layouts.cpp 4 + \snippet doc/src/snippets/layouts/layouts.cpp 5 + + The code for QVBoxLayout is identical, except the line where the layout is + created. The code for QGridLayout is a bit different, because we need to + specify the row and column position of the child widget: + + \snippet doc/src/snippets/layouts/layouts.cpp 12 + \snippet doc/src/snippets/layouts/layouts.cpp 13 + \snippet doc/src/snippets/layouts/layouts.cpp 14 + \codeline + \snippet doc/src/snippets/layouts/layouts.cpp 15 + \snippet doc/src/snippets/layouts/layouts.cpp 16 + \snippet doc/src/snippets/layouts/layouts.cpp 17 + + The third QPushButton spans 2 columns. This is possible by specifying 2 as + the fifth argument to QGridLayout::addWidget(). + + Finally, the code for QFormLayout is .. + + + \section2 Tips for Using Layouts + + When you use a layout, you do not need to pass a parent when constructing + the child widgets. The layout will automatically reparent the widgets + (using QWidget::setParent()) so that they are children of the widget on + which the layout is installed. + + \note Widgets in a layout are children of the widget on which the layout + is installed, \e not of the layout itself. Widgets can only have other + widgets as parent, not layouts. + + You can nest layouts using \c addLayout() on a layout; the inner layout + then becomes a child of the layout it is inserted into. + + + \section1 Adding Widgets to a Layout + + When you add widgets to a layout, the layout process works as follows: + + \list 1 + \o All the widgets will initially be allocated an amount of space in + accordance with their QWidget::sizePolicy() and + QWidget::sizeHint(). + + \o If any of the widgets have stretch factors set, with a value + greater than zero, then they are allocated space in proportion to + their stretch factor (explained below). + + \o If any of the widgets have stretch factors set to zero they will + only get more space if no other widgets want the space. Of these, + space is allocated to widgets with an + \l{QSizePolicy::Expanding}{Expanding} size policy first. + + \o Any widgets that are allocated less space than their minimum size + (or minimum size hint if no minimum size is specified) are + allocated this minimum size they require. (Widgets don't have to + have a minimum size or minimum size hint in which case the strech + factor is their determining factor.) + + \o Any widgets that are allocated more space than their maximum size + are allocated the maximum size space they require. (Widgets do not + have to have a maximum size in which case the strech factor is + their determining factor.) + \endlist + + + \section2 Stretch Factors + \keyword stretch factor + + Widgets are normally created without any stretch factor set. When they are + laid out in a layout the widgets are given a share of space in accordance + with their QWidget::sizePolicy() or their minimum size hint whichever is + the greater. Stretch factors are used to change how much space widgets are + given in proportion to one another. + + If we have three widgets laid out using a QHBoxLayout with no stretch + factors set we will get a layout like this: + + \img layout1.png Three widgets in a row + + If we apply stretch factors to each widget, they will be laid out in + proportion (but never less than their minimum size hint), e.g. + + \img layout2.png Three widgets with different stretch factors in a row + + + \section1 Custom Widgets in Layouts + + When you make your own widget class, you should also communicate its layout + properties. If the widget has a one of Qt's layouts, this is already taken + care of. If the widget does not have any child widgets, or uses manual + layout, you can change the behavior of the widget using any or all of the + following mechanisms: + + \list + \o Reimplement QWidget::sizeHint() to return the preferred size of the + widget. + \o Reimplement QWidget::minimumSizeHint() to return the smallest size + the widget can have. + \o Call QWidget::setSizePolicy() to specify the space requirements of + the widget. + \endlist + + Call QWidget::updateGeometry() whenever the size hint, minimum size hint or + size policy changes. This will cause a layout recalculation. Multiple + consecutive calls to QWidget::updateGeometry() will only cause one layout + recalculation. + + If the preferred height of your widget depends on its actual width (e.g., + a label with automatic word-breaking), set the + \l{QSizePolicy::hasHeightForWidth()}{height-for-width} flag in the + widget's \l{QWidget::sizePolicy}{size policy} and reimplement + QWidget::heightForWidth(). + + Even if you implement QWidget::heightForWidth(), it is still a good idea to + provide a reasonable sizeHint(). + + For further guidance when implementing these functions, see the + \e{Qt Quarterly} article + \l{http://doc.trolltech.com/qq/qq04-height-for-width.html} + {Trading Height for Width}. + + + \section1 Layout Issues + + The use of rich text in a label widget can introduce some problems to the + layout of its parent widget. Problems occur due to the way rich text is + handled by Qt's layout managers when the label is word wrapped. + + In certain cases the parent layout is put into QLayout::FreeResize mode, + meaning that it will not adapt the layout of its contents to fit inside + small sized windows, or even prevent the user from making the window too + small to be usable. This can be overcome by subclassing the problematic + widgets, and implementing suitable \l{QWidget::}{sizeHint()} and + \l{QWidget::}{minimumSizeHint()} functions. + + In some cases, it is relevant when a layout is added to a widget. When + you set the widget of a QDockWidget or a QScrollArea (with + QDockWidget::setWidget() and QScrollArea::setWidget()), the layout must + already have been set on the widget. If not, the widget will not be + visible. + + + \section1 Manual Layout + + If you are making a one-of-a-kind special layout, you can also make a + custom widget as described above. Reimplement QWidget::resizeEvent() to + calculate the required distribution of sizes and call + \l{QWidget::}{setGeometry()} on each child. + + The widget will get an event of type QEvent::LayoutRequest when the + layout needs to be recalculated. Reimplement QWidget::event() to handle + QEvent::LayoutRequest events. + + + \section1 How to Write A Custom Layout Manager + + An alternative to manual layout is to write your own layout manager by + subclassing QLayout. The \l{layouts/borderlayout}{Border Layout} and + \l{layouts/flowlayout}{Flow Layout} examples show how to do this. + + Here we present an example in detail. The \c CardLayout class is inspired + by the Java layout manager of the same name. It lays out the items (widgets + or nested layouts) on top of each other, each item offset by + QLayout::spacing(). + + To write your own layout class, you must define the following: + \list + \o A data structure to store the items handled by the layout. Each + item is a \link QLayoutItem QLayoutItem\endlink. We will use a + QList in this example. + \o \l{QLayout::}{addItem()}, how to add items to the layout. + \o \l{QLayout::}{setGeometry()}, how to perform the layout. + \o \l{QLayout::}{sizeHint()}, the preferred size of the layout. + \o \l{QLayout::}{itemAt()}, how to iterate over the layout. + \o \l{QLayout::}{takeAt()}, how to remove items from the layout. + \endlist + + In most cases, you will also implement \l{QLayout::}{minimumSize()}. + + + \section2 The Header File (\c card.h) + + \snippet doc/src/snippets/code/doc_src_layout.qdoc 0 + + + \section2 The Implementation File (\c card.cpp) + + \snippet doc/src/snippets/code/doc_src_layout.qdoc 1 + + First we define two functions that iterate over the layout: \c{itemAt()} + and \c{takeAt()}. These functions are used internally by the layout system + to handle deletion of widgets. They are also available for application + programmers. + + \c{itemAt()} returns the item at the given index. \c{takeAt()} removes the + item at the given index, and returns it. In this case we use the list index + as the layout index. In other cases where we have a more complex data + structure, we may have to spend more effort defining a linear order for the + items. + + \snippet doc/src/snippets/code/doc_src_layout.qdoc 2 + + \c{addItem()} implements the default placement strategy for layout items. + This function must be implemented. It is used by QLayout::add(), by the + QLayout constructor that takes a layout as parent. If your layout has + advanced placement options that require parameters, you must provide extra + access functions such as the row and column spanning overloads of + QGridLayout::addItem(), QGridLayout::addWidget(), and + QGridLayout::addLayout(). + + \snippet doc/src/snippets/code/doc_src_layout.qdoc 3 + + The layout takes over responsibility of the items added. Since QLayoutItem + does not inherit QObject, we must delete the items manually. The function + QLayout::deleteAllItems() uses \c{takeAt()} defined above to delete all the + items in the layout. + + \snippet doc/src/snippets/code/doc_src_layout.qdoc 4 + + The \c{setGeometry()} function actually performs the layout. The rectangle + supplied as an argument does not include \c{margin()}. If relevant, use + \c{spacing()} as the distance between items. + + \snippet doc/src/snippets/code/doc_src_layout.qdoc 5 + + \c{sizeHint()} and \c{minimumSize()} are normally very similar in + implementation. The sizes returned by both functions should include + \c{spacing()}, but not \c{margin()}. + + \snippet doc/src/snippets/code/doc_src_layout.qdoc 6 + + + \section2 Further Notes + + \list + \o This custom layout does not handle height for width. + \o We ignore QLayoutItem::isEmpty(); this means that the layout will + treat hidden widgets as visible. + \o For complex layouts, speed can be greatly increased by caching + calculated values. In that case, implement + QLayoutItem::invalidate() to mark the cached data is dirty. + \o Calling QLayoutItem::sizeHint(), etc. may be expensive. So, you + should store the value in a local variable if you need it again + later within in the same function. + \o You should not call QLayoutItem::setGeometry() twice on the same + item in the smae function. This call can be very expensive if the + item has several child widgets, because the layout manager must do + a complete layout every time. Instead, calculate the geometry and + then set it. (This does not only apply to layouts, you should do + the same if you implement your own resizeEvent(), for example.) + \endlist +*/ + diff --git a/doc/src/licenses.qdoc b/doc/src/licenses.qdoc new file mode 100644 index 0000000..b42b882 --- /dev/null +++ b/doc/src/licenses.qdoc @@ -0,0 +1,465 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page licenses.html + \title Other Licenses Used in Qt + \ingroup licensing + \brief Information about other licenses used for Qt components and third-party code. + + Qt contains some code that is not provided under the the + \l{GNU General Public License (GPL)}, + \l{GNU Lesser General Public License (LGPL)} or the + \l{Qt Commercial Editions}{Qt Commercial License Agreement}, but rather under + specific licenses from the original authors. Some pieces of code were developed + by Qt Software and others originated from third parties. + This page lists the licenses used, names the authors, and links + to the places where it is used. + + Nokia gratefully acknowledges these and other contributions + to Qt. We recommend that programs that use Qt also acknowledge + these contributions, and quote these license statements in an + appendix to the documentation. + + See also: \l{Licenses for Fonts Used in Qt for Embedded Linux} + + \generatelist legalese + + \hr + + Copyright (C) 2000-2004, International Business Machines\br + Corporation and others. All Rights Reserved.\br + Copyright (C) 2007 Apple Inc. All rights reserved. + + Permission is hereby granted, free of charge, to any person obtaining a copy of this + software and associated documentation files (the "Software"), to deal in the Software + without restriction, including without limitation the rights to use, copy, modify, + merge, publish, distribute, and/or sell copies of the Software, and to permit persons + to whom the Software is furnished to do so, provided that the above copyright notice(s) + and this permission notice appear in all copies of the Software and that both the above + copyright notice(s) and this permission notice appear in supporting documentation. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER + OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR + CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR + PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING + OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + + Except as contained in this notice, the name of a copyright holder shall not be used in + advertising or otherwise to promote the sale, use or other dealings in this Software + without prior written authorization of the copyright holder. + + \list + \o Parts of WebKit used by the QtWebKit module + \endlist + + \hr + + Copyright (c) 1998 by Bjorn Reese + + Permission to use, copy, modify, and distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED + WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF + MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE AUTHORS AND + CONTRIBUTORS ACCEPT NO RESPONSIBILITY IN ANY CONCEIVABLE MANNER. + + \list + \o Parts of the QCrashHandler class + \endlist + + \hr + + Parts of the FreeType projects have been modified and put into Qt + for use in the painting subsystem. These files are ftraster.h, + ftraster.c, ftgrays.h and ftgrays.c. The following modifications + has been made to these files: + + \list + \i Renamed FT_ and ft_ symbols to QT_FT_ and qt_ft_ to avoid name + conflicts in \c{qrasterdefs_p.h}. + \i Removed parts of code not relevant when compiled with + _STANDALONE_ defined. + \i Changed behavior in \c{ftraster.c} to follow X polygon filling + rules. + \i Implemented support in \c{ftraster.c} for winding / odd even + polygon fill rules. + \i Replaced bitmap generation with span generation in \c{ftraster.c}. + \i Renamed \c{ftraster.h} as \c{qblackraster_p.h}. + \i Renamed \c{ftraster.c} as \c{qblackraster.c}. + \i Renamed \c{ftgrays.h} as \c{qgrayraster_p.h}. + \i Renamed \c{ftgrays.c} as \c{qgrayraster.c}. + \endlist + + See \c src/3rdparty/freetype/docs/FTL.txt and \c + src/3rdparty/freetype/docs/GPL.txt for license details. + + \hr + + Copyright (c) 1985, 1986, 1987 X Consortium + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR + OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, + ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE. + + Except as contained in this notice, the name of the X Consortium shall + not be used in advertising or otherwise to promote the sale, use or + other dealings in this Software without prior written authorization + from the X Consortium. + + \list + \o Parts of the Q3PolygonScanner class used in Qt for Embedded Linux + \endlist + + \hr + + Copyright 1987 by Digital Equipment Corporation, Maynard, Massachusetts. + + All Rights Reserved + + Permission to use, copy, modify, and distribute this software and its + documentation for any purpose and without fee is hereby granted, + provided that the above copyright notice appear in all copies and that + both that copyright notice and this permission notice appear in + supporting documentation, and that the name of Digital not be + used in advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING + ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL + DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR + ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, + WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS + SOFTWARE. + + \list + \o Parts of the Q3PolygonScanner class used in Qt for Embedded Linux + \endlist + + \hr + + Copyright 1985, 1987, 1998 The Open Group + + Permission to use, copy, modify, distribute, and sell this software and its + documentation for any purpose is hereby granted without fee, provided that + the above copyright notice appear in all copies and that both that + copyright notice and this permission notice appear in supporting + documentation. + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN + AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + Except as contained in this notice, the name of The Open Group shall not be + used in advertising or otherwise to promote the sale, use or other dealings + in this Software without prior written authorization from The Open Group. + + \list + \o Parts of the internal QKeyMapper class on X11 platforms + \endlist + + \hr + + pnmscale.c - read a portable anymap and scale it + + Copyright (C) 1989, 1991 by Jef Poskanzer. + + Permission to use, copy, modify, and distribute this software and its + documentation for any purpose and without fee is hereby granted, provided + that the above copyright notice appear in all copies and that both that + copyright notice and this permission notice appear in supporting + documentation. This software is provided "as is" without express or + implied warranty. + + \list + \o Parts of the internal QImageSmoothScaler::scale() function use code + based on pnmscale.c by Jef Poskanzer. + \endlist +*/ + +/*! + \page licenses-fonts.html + \title Licenses for Fonts Used in Qt for Embedded Linux + \ingroup qt-embedded-linux + \ingroup licensing + \brief Information about the licenses of fonts supplied with Qt for Embedded Linux. + + The fonts supplied with Qt for Embedded Linux have been obtained under a + variety of different licenses listed below. + + \tableofcontents + + See also: \l{Other Licenses Used in Qt} + + \section1 Adobe Helvetica + + Copyright 1984-1989, 1994 Adobe Systems Incorporated. + Copyright 1988, 1994 Digital Equipment Corporation. + + Adobe is a trademark of Adobe Systems Incorporated which may be + registered in certain jurisdictions. + Permission to use these trademarks is hereby granted only in + association with the images described in this file. + + Permission to use, copy, modify, distribute and sell this software + and its documentation for any purpose and without fee is hereby + granted, provided that the above copyright notices appear in all + copies and that both those copyright notices and this permission + notice appear in supporting documentation, and that the names of + Adobe Systems and Digital Equipment Corporation not be used in + advertising or publicity pertaining to distribution of the software + without specific, written prior permission. Adobe Systems and + Digital Equipment Corporation make no representations about the + suitability of this software for any purpose. It is provided "as + is" without express or implied warranty. + + \section1 Adobe Utopia + + Permission to use, reproduce, display and distribute the listed + typefaces is hereby granted, provided that the Adobe Copyright notice + appears in all whole and partial copies of the software and that the + following trademark symbol and attribution appear in all unmodified + copies of the software: + + Copyright (c) 1989 Adobe Systems Incorporated + Utopia (R) + Utopia is a registered trademark of Adobe Systems Incorporated + + The Utopia font + Copyright (c) 1989, 1991 Adobe Systems Incorporated. All Rights + Reserved.Utopia is a registered trademark of Adobe Systems + Incorporated. + + \section1 Babelfish + + \snippet doc/src/snippets/code/doc_src_licenses.qdoc 1 + + \section1 Bigelow & Holmes Luxi + + Luxi fonts copyright (c) 2001 by Bigelow & Holmes Inc. Luxi font + instruction code copyright (c) 2001 by URW++ GmbH. All Rights + Reserved. Luxi is a registered trademark of Bigelow & Holmes Inc. + + Permission is hereby granted, free of charge, to any person obtaining + a copy of these Fonts and associated documentation files (the "Font + Software"), to deal in the Font Software, including without + limitation the rights to use, copy, merge, publish, distribute, + sublicense, and/or sell copies of the Font Software, and to permit + persons to whom the Font Software is furnished to do so, subject to + the following conditions: + + The above copyright and trademark notices and this permission notice + shall be included in all copies of one or more of the Font Software. + + The Font Software may not be modified, altered, or added to, and in + particular the designs of glyphs or characters in the Fonts may not + be modified nor may additional glyphs or characters be added to the + Fonts. This License becomes null and void when the Fonts or Font + Software have been modified. + + THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT + OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL + BIGELOW & HOLMES INC. OR URW++ GMBH. BE LIABLE FOR ANY CLAIM, DAMAGES + OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL, INDIRECT, + INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF + CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR + INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT + SOFTWARE. + + Except as contained in this notice, the names of Bigelow & Holmes + Inc. and URW++ GmbH. shall not be used in advertising or otherwise to + promote the sale, use or other dealings in this Font Software without + prior written authorization from Bigelow & Holmes Inc. and URW++ GmbH. + + For further information, contact: + + info@urwpp.de + or + design@bigelowandholmes.com + + \section1 Bitstream Charter and Courier + + (c) Copyright 1989-1992, Bitstream Inc., Cambridge, MA. + + You are hereby granted permission under all Bitstream propriety rights + to use, copy, modify, sublicense, sell, and redistribute the 4 Bitstream + Charter (r) Type 1 outline fonts and the 4 Courier Type 1 outline fonts + for any purpose and without restriction; provided, that this notice is + left intact on all copies of such fonts and that Bitstream's trademark + is acknowledged as shown below on all unmodified copies of the 4 Charter + Type 1 fonts. + + BITSTREAM CHARTER is a registered trademark of Bitstream Inc. + + \section1 Bitstream Vera + + Copyright (c) 2003 by Bitstream, Inc. + + All Rights Reserved. + + Bitstream Vera is a trademark of Bitstream, Inc. + + Permission is hereby granted, free of charge, to any person obtaining + a copy of the fonts accompanying this license ("Fonts") and associated + documentation files (the "Font Software"), to reproduce and distribute + the Font Software, including without limitation the rights to use, + copy, merge, publish, distribute, and/or sell copies of the Font + Software, and to permit persons to whom the Font Software is furnished + to do so, subject to the following conditions: + + The above copyright and trademark notices and this permission notice + shall be included in all copies of one or more of the Font Software + typefaces. + + The Font Software may be modified, altered, or added to, and in + particular the designs of glyphs or characters in the Fonts may be + modified and additional glyphs or characters may be added to the + Fonts, only if the fonts are renamed to names not containing either + the words "Bitstream" or the word "Vera". + + This License becomes null and void to the extent applicable to Fonts + or Font Software that has been modified and is distributed under the + "Bitstream Vera" names. + + The Font Software may be sold as part of a larger software package but + no copy of one or more of the Font Software typefaces may be sold by + itself. + + THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT + OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL + BITSTREAM OR THE GNOME FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR + OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, + OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR + OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE THE FONT + SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE. + + Except as contained in this notice, the names of Gnome, the Gnome + Foundation, and Bitstream Inc., shall not be used in advertising or + otherwise to promote the sale, use or other dealings in this Font + Software without prior written authorization from the Gnome Foundation + or Bitstream Inc., respectively. For further information, contact: + fonts at gnome dot org. + + \omit + http://www.gnome.org/fonts/#Final_Bitstream_Vera_Fonts + \endomit + + See also: + \l{http://www.bitstream.com/font_rendering/products/dev_fonts/vera.html}{Vera Open Source Fonts} + + \section1 Cursor + + The Cursor font is distributed with the following declaration: + + \e{Copyright (c) 2000 XFree86, Inc.} + + \section1 DejaVu Fonts + + DejaVu fonts come with the following copyright statement: + + Fonts are (c) Bitstream (see below). DejaVu changes are in public domain. Glyphs imported from Arev fonts are (c) Tavmjung Bah (see below) + + \snippet doc/src/snippets/code/doc_src_licenses.qdoc 2 + + \section1 Fixed Fonts + + The 5x7 and 6x13 fonts each contain the following copyright notice: + + \e{Public domain font. Share and enjoy.} + + \section1 IBM Courier + + IBM Courier - Copyright (c) IBM Corporation 1990, 1991 + + You are hereby granted permission under the terms of the IBM/MIT X Consortium + Courier Typefont agreement to execute, reproduce, distribute, display, market, + sell and otherwise transfer copies of the IBM Courier font to third parties. + + The font is provided "AS IS" without charge. NO WARRANTIES OR INDEMNIFICATION + ARE GIVEN, WHETHER EXPRESS OR IMPLIED INCLUDING, BUT LIMITED TO THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. + + \section1 Micro + + The Micro font contains the following copyright notice: + + \e{Public domain font. Share and enjoy.} + + \section1 Unifont + + The Unifont font was originally obtained from + \l{http://www.czyborra.com/}{Roman Czyborra} under the following license: + + \e{All of my works you find here are freeware. You may freely copy, use, quote, + modify or redistribute them as long as you properly attribute my contribution + and have given a quick thought about whether Roman might perhaps be interested + to read what you did with his stuff. Horizontal rules don't apply.} +*/ diff --git a/doc/src/linguist-manual.qdoc b/doc/src/linguist-manual.qdoc new file mode 100644 index 0000000..92e3bed --- /dev/null +++ b/doc/src/linguist-manual.qdoc @@ -0,0 +1,1513 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page linguist-manual.html + \title Qt Linguist Manual + \ingroup qttools + + \startpage {index.html}{Qt Reference Documentation} + \nextpage Qt Linguist Manual: Release Manager + + \keyword Qt Linguist + + Qt provides excellent support for translating applications into local + languages. This Guide explains how to use Qt's translation tools for + each of the roles involved in translating an application. The Guide + begins with a brief overview of the issues that must be considered, + followed by chapters devoted to each role and the supporting tools + provided. + + The \l{linguist-manager.html}{Release Manager} chapter is aimed + at the person with overall responsibility for the release of the + application. They will typically coordinate the work of the + software engineers and the translator. The chapter describes the + use of two tools. The \l{lupdate} tool is used to synchronize + source code and translations. The \l{lrelease} tool is used to + create runtime translation files for use by the released + application. + + The \l{linguist-translators.html}{Translators} chapter is for + translators. It describes the use of the \QL tool. + No computer knowledge beyond the ability to start a program and + use a text editor or word processor is required. + + The \l{linguist-programmers.html}{Programmers} chapter is for Qt + programmers. It explains how to create Qt applications that are + able to use translated text. It also provides guidance on how to + help the translator identify the context in which phrases appear. + This chapter's three short tutorials cover everything the + programmer needs to do. + + \section1 Overview of the Translation Process + + Most of the text that must be translated in an application program + consists of either single words or short phrases. These typically + appear as window titles, menu items, pop-up help text (balloon help), + and labels to buttons, check boxes and radio buttons. + + The phrases are entered into the source code by the programmer in + their native language using a simple but special syntax to identify + that the phrases require translation. The Qt tools provide context + information for each of the phrases to help the translator, and the + programmer is able to add additional context information to phrases + when necessary. The release manager generates a set of translation + files that are produced from the source files and passes these to the + translator. The translator opens the translation files using \QL, + enters their translations and saves the results back into + the translation files, which they pass back to the release manager. + The release manager then generates fast compact versions of these + translation files ready for use by the application. The tools are + designed to be used in repeated cycles as applications change and + evolve, preserving existing translations and making it easy to + identify which new translations are required. \QL also + provides a phrase book facility to help ensure consistent + translations across multiple applications and projects. + + Translators and programmers must address a number of issues because + of the subtleties and complexities of human language: + + \list + + \o A single phrase may need to be translated into several + different forms depending on context, e.g. \e open in English + might become \e{\ouml\c{}ffnen}, "open file", or \e aufbauen, + "open internet connection", in German. + + \o Keyboard accelerators may need to be changed but without + introducing conflicts, e.g. "\&Quit" in English becomes "Avslutt" + in Norwegian which doesn't contain a "Q". We cannot use a letter + that is already in use - unless we change several accelerators. + + \o Phrases that contain variables, for example, "The 25 files + selected will take 63 seconds to process", where the two numbers + are inserted programmatically at runtime may need to be reworded + because in a different language the word order and therefore the + placement of the variables may have to change. + + \endlist + + The Qt translation tools provide clear and simple solutions to these + issues. + + Chapters: + + \list + \o \l{Qt Linguist Manual: Release Manager}{Release Manager} + \o \l{Qt Linguist Manual: Translators}{Translators} + \o \l{Qt Linguist Manual: Programmers}{Programmers} + \o \l{Qt Linguist Manual: TS File Format}{TS File Format} + \endlist + + \QL and \c lupdate are able to import and export XML Localization + Interchange File Format (XLIFF) files, making it possible to take + advantage of tools and translation services that work with this + format. See the \l{Qt Linguist Manual: Translators} {Translators} + section for more information on working with these files. + + \table + + \row \o{1,2} \inlineimage wVista-Cert-border-small.png + \o \e{Qt Linguist 4.3 is Certified for Windows Vista} + + \row \o Windows Vista and the Windows Vista Start button are + trademarks or registered trademarks of Microsoft Corporation in + the United States and/or other countries. + + \endtable +*/ + +/*! + \page linguist-manager.html + \title Qt Linguist Manual: Release Manager + + \contentspage {Qt Linguist Manual}{Contents} + \previouspage Qt Linguist Manual + \nextpage Qt Linguist Manual: Translators + + \keyword lupdate + \keyword lrelease + + Two tools are provided for the release manager, \l lupdate and \l + lrelease. These tools can process \l qmake project files, or operate + directly on the file system. + + \section1 Qt Project Files + + The easiest method to use \l{#lupdate} {lupdate} and \l{#lrelease} + {lrelease} is by specifing a \c .pro Qt project file. There must + be an entry in the \c TRANSLATIONS section of the project file for + each language that is additional to the native language. A typical + entry looks like this: + + \snippet examples/linguist/arrowpad/arrowpad.pro 1 + + Using a locale within the translation file name is useful for + determining which language to load at runtime. This is explained + in the \l{linguist-programmers.html} {Programmers} chapter. + + An example of a complete \c .pro file with four translation source + files: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 0 + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1 + + QTextCodec::setCodecForTr() makes it possible to choose a 8-bit + encoding for literal strings that appear within \c tr() calls. + This is useful for applications whose source language is, for + example, Chinese or Japanese. If no encoding is set, \c tr() uses + Latin1. + + If you do use the QTextCodec::codecForTr() mechanism in your + application, \QL needs you to set the \c CODECFORTR + entry in the \c .pro file as well. For example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1 + + Also, if your compiler uses a different encoding for its runtime + system as for its source code and you want to use non-ASCII + characters in string literals, you will need to set the \c + CODECFORSRC. For example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 2 + + Microsoft Visual Studio 2005 .NET appears to be the only compiler + for which this is necessary. However, if you want to write + portable code, we recommend that you avoid non-ASCII characters + in your source files. You can still specify non-ASCII characters + portably using escape sequences, for example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 3 + + \target lupdate manual + \section1 lupdate + + Usage: \c {lupdate myproject.pro} + + \l lupdate is a command line tool that finds the translatable + strings in the specified source, header and \e {Qt Designer} + interface files, and produces or updates \c .ts translation + files. The files to process and the files to update can be set at + the command line, or provided in a \c .pro file specified as an + command line argument. The produced translation files are given to + the translator who uses \QL to read the files and insert the + translations. + + Companies that have their own translators in-house may find it + useful to run \l lupdate regularly, perhaps monthly, as the + application develops. This will lead to a fairly low volume of + translation work spread evenly over the life of the project and + will allow the translators to support a number of projects + simultaneously. + + Companies that hire in translators as required may prefer to run + \l lupdate only a few times in the application's life cycle, the + first time might be just before the first test phase. This will + provide the translator with a substantial single block of work and + any bugs that the translator detects may easily be included with + those found during the initial test phase. The second and any + subsequent \l lupdate runs would probably take place during the + final beta phase. + + The \c .ts file format is a simple human-readable XML format that + can be used with version control systems if required. \c lupdate + can also process Localization Interchange File Format (XLIFF) + format files; file in this format typically have file names that + end with the \c .xlf suffix. + + Pass the \c -help option to \c lupdate to obtain the list of + supported options: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 4 + + \QL is also able to import and export XLIFF files. See the + \l{Qt Linguist Manual: Translators}{Translators} section for more + information. + + \section1 lrelease + + Usage: \c {lrelease myproject.pro} + + \l lrelease is a command line tool that produces \c .qm files out + of \c .ts files. The \c .qm file format is a compact binary format + that is used by the localized application. It provides extremely + fast lookups for translations. The \c .ts files \l lrelease + processes can be specified at the command line, or given + indirectly by a Qt \c .pro project file. + + This tool is run whenever a release of the application is to be + made, from initial test version through to final release + version. If the \c .qm files are not created, e.g. because an + alpha release is required before any translation has been + undertaken, the application will run perfectly well using the text + the programmers placed in the source files. Once the \c .qm files + are available the application will detect them and use them + automatically. + + Note that lrelease will only incorporate translations that are + marked as "finished". Otherwise the original text will be used + instead. + + Pass the \c -help option to \c lrelease to obtain the list of + supported options: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 5 + + \section1 Missing Translations + + Both \l lupdate and \l lrelease may be used with \c .ts + translation source files which are incomplete. Missing + translations will be replaced with the native language phrases at + runtime. +*/ + +/*! + \page linguist-translators.html + \title Qt Linguist Manual: Translators + + \contentspage {Qt Linguist Manual}{Contents} + \previouspage Qt Linguist Manual: Release Manager + \nextpage Qt Linguist Manual: Programmers + + Contents + + \tableofcontents + + \section1 The One Minute Guide to Using Qt Linguist + + \QL is a tool for adding translations to Qt applications. Run \QL + from the taskbar menu, or by double clicking the desktop icon, or + by entering the command \c {linguist} at the command line. Once + \QL has started, choose \menu{File|Open} from the \l{menubar} + {menu bar} and select a translation source (\c{.ts} file) to + load. If you don't have a \c{.ts} file, see the \l {Qt Linguist + Manual: Release Manager} {release manager manual} to learn how to + generate one. + + The \QL main window is divided into several, dockable subwindows + arranged around a central \l{The Translation Area} {translation + area}. The \l{Context Window} {context list} is normally shown + on the left, and the \l{Sources and Forms Window} {source code}, + \l{Strings Window} {string list}, and either the \l{Phrases and + Guesses Window} {prhrases and guesses}, or the \l{Warnings Window} + {warnings} are shown above and below the \l{The Translation Area} + {translations area}. + + With a translation file loaded, select a context from the + \l{Context Window} {context list} on the left. Selecting a context + loads the translatable strings found in that context into the + \l{Strings Window} {string list}. Selecting one of the strings + copies that string as the \key{Source text} in the \l{The + Translation Area} {translation area}. Click in the text entry + widget below the copied string and type your translation for that + string. To accept the translation, either press the green + \key{tick mark} button on the toolbar, or click the icon to the + left of the selected source string in the string list. Repeat this + process until all strings in the string list are marked with + \inlineimage linguist-check-on.png + or + \inlineimage linguist-check-warning.png + . Then select the next context and continue. + + Translation options are shown in the \l{Phrases and Guesses + Window} {phrases and guesses window}. If the phrases and guesses + window is not visible, click the \key{Phrases and guesses} tab at + the bottom of the main window. The phrases and guesses window + shows possible translations for the current string. These + translation "guesses" have been read from phrase books + (\menu{Phrases|Open Phrase Book...}). The current string's + current translation is also shown here. To select a guess, double + click it in the prases and guesses window or use the keyboard + shortcut shown to the right of the guess. + + \QL can automatically check whether your translation strings pass + a list of \l{Validation Tests} {validation tests}. Validation test + failures are shown in the \l{Warnings Window} {warnings window}. + If the warnings window is not visible, click the \key{Warnings} + tab at the bottom of the main window. + + Finally, if the source code for the contexts is accessible, the + \l{Sources and Forms Window} {source code window} shows the + context where the current string is used. If the source code + window is not visible, click the \key{Sources and Forms} tab at + the bottom of the main window. + + At the end of the session choose \menu{File|Save} from the menu + bar and then \menu{File|Exit} to quit. + + \section1 The Qt Linguist Window + + \image linguist-linguist.png "Linguist UI Snapshot" + + This \QL main window is divided into dockable subwindows arranged + around a central \l{The Translation Area} {translation area}. The + subwindows are: \l{Context Window} {Context}, \l{Sources and Forms + Window} {Sources and Forms}, \l{Strings Window} {Strings}, + \l{Phrases and Guesses Window} {Phrases and guesses}, and + \l{Warnings Window} {Warnings} (hidden in the UI snapsot). The + translation area is always visible, but the dockable subwindows + can be activated or deactivated in the \menu{View|Views} menu, and + dragged around by their title bars and dropped in the translation + area or even outside the main window. + + \section2 Context Window + + The context window normally appears on the left side of the main + window. It lists the contexts in which strings to be translated + appear. The column labeled \e{Context} lists the context names in + alphabetical order. Each context is the name of a subclass of + QObject. There can also be a context for QObject itself, which + contains strings passed to the static function QObject::tr(). + There can also be an \e{}, which contains strings + that aren't in a subclass of QObject. + + To the left of the \e{Context} column is a column labeled + \inlineimage linguist-check-obsolete.png + . This column uses the following list of icons to summarize the + current translation state for each context: + + \list + + \o \inlineimage linguist-check-on.png + All strings in the context have been translated, and all the + translations passed the \l{Validation Tests} {validation tests}. + + \o \inlineimage linguist-check-warning.png + All strings in the context have been translated or marked as + translated, but at least one translation failed the \l{Validation + Tests} {validation tests}. + + \o \inlineimage linguist-check-off.png + At least one string in the context has not been translated or is + not marked as translated. + + \o \inlineimage linguist-check-obsolete.png + None of the translated strings still appears in the context. This + usually means the context itself no longer exists in the + application. + + \endlist + + To the right of the \e{Context} column is the \e{Items} column. + Each entry in the \e{Items} column is a pair of numbers separated + by a slash ("/"). The number to the right of the slash is the + number of translatable strings in the context. The number to the + left of the slash is the number of those strings that currently + have translations. i.e., if the numbers are equal, all the + translatable strings in the context have translations. + + In the UI snapshot above, the \bold{MessageEditor} context is + selected. Its \e{Items} entry shows \bold{18/18}, which means it + has 18 translatable strings and all 18 strings currently have + translations. However, the context has been marked with the + \inlineimage linguist-check-warning.png + icon, which means that at least one of the current translations + failed a \l{Validation Tests} {validation test}. In the + \l{Strings Window} {strings window} to the right, we see that one + of the strings is indeed marked with the + \inlineimage linguist-check-warning.png + icon. + + The context window is a dockable window. It can be dragged to + another position in the main window, or dragged out of the main + window to be a separate window. If you move the context window, + \QL remembers the new position and puts the context window there + whenever you start the program. If the context window has been + closed, it can be restored by pressing \key{F6}. + + \section2 Strings Window + + The strings window normally appears on the right in the main + window, above the \l{The Translation Area} {translation area}. Its + \e{Source text} column lists all the translatable strings found in + the current context. Selecting a string makes that string the + current string in the \l{The Translation Area} {translation area}. + + To the left of the \e{Source text} column is a column labeled + \inlineimage linguist-check-obsolete.png + . This column is similar to the one in the \l{Context Window} + {context window}, but here you can click on the icon to change the + translation acceptance state for each string in the list. A tick + mark, green or yellow, means the string has been translated and + the user has accepted the translation. A question mark means + either that the user has not accepted the string's translation or + that the string doesn't have a translation. The table below + explains the acceptance states and their icons: + + \target String Translation States + + \table + \header + \o State + \o Icon + \o Description + + \row + \o Accepted/Correct + \o \inlineimage linguist-check-on.png + \o The source string has a translation (possibly empty); the user + has accepted the translation, and the translation passes all the + \l{Validation Tests} {validation tests}. If the translation is + empty, the user has chosen to leave it empty. Click the icon to + revoke acceptance of the translation and decrement the number of + accepted translations in the \e{Items} column of the \l{Context + Window} {context list} by 1. The state is reset to + \inlineimage linguist-check-off.png + if the string has a translation, or to + \inlineimage linguist-check-empty.png + if the string's translation is empty. If \c{lupdate} changes the + contents of a string, its acceptance state is automatically reset + to \inlineimage linguist-check-off.png + . + + \row + \o Accepted/Warnings + \o \inlineimage linguist-check-warning.png + \o The user has accepted the translation, but the translation does + not pass all the \l{Validation Tests} {validation tests}. The + validation test failures are shown in the \l{Warnings Window} + {warnings window}. Click the icon to revoke acceptance of the + translation. The state is reset to \inlineimage linguist-danger.png + , and the number of accepted translations in the \e{Items} column + of the \l{Context Window} {context list} is decremented by 1. + + \row + \o Not Accepted + \o \inlineimage linguist-check-off.png + \o The string has a non-empty translation that passes all the + \l{Validation Tests} {validation tests}, but the user has not yet + accepted the translation. Click the icon or press \key{Ctrl+Enter} + to accept the translation. The state is reset to + \inlineimage linguist-check-on.png + , and the number of accepted translations in the \e{Items} column + of the \l{Context Window} {context list} is incremented by 1. + + \row + \o No Translation + \o \inlineimage linguist-check-empty.png + \o The string does not have a translation. Click the icon to + accpet the empty translation anyway. The state is reset to + \inlineimage linguist-check-on.png + , and the number of accepted translations in the \e{Items} column + of the \l{Context Window} {context list} is incremented by 1. + + \row + \o Validation Failures + \o \inlineimage linguist-danger.png + \o The string has a translation, but the translation does not + pass all the \l{Validation Tests} {validation tests}. Validation + test failures are shown in the \l{Warnings Window} {warnings} + window. Click on the icon or press \key{Ctrl+Return} to accept + the translation even with validation failures. The state is + reset to \inlineimage linguist-check-warning.png + . We recommended editing the translation to fix the causes of + the validation failures. The state will reset automatically to + \inlineimage linguist-check-off.png + , when all the failures have been fixed. + + \row + \o Obsolete + \o \inlineimage linguist-check-obsolete.png + \o The string is obsolete. It is no longer used in the context. + See the \l{Qt Linguist Manual: Release Manager} {Release Manager} + for instructions on how to remove obsolete messages from the file. + + \endtable + + The string list is a dockable subwindow. If it has been closed, + restored it by pressing \key{F7}. + + \section2 The Translation Area + + The translation area is in the middle of the main window, to the + right of the \l{Context Window} {context list}. It doesn't have a + title bar, so you can't drag it around. Instead, you drag and drop + the other subwindows to arrange them around the translation area. + The string currently selected in the \l{Strings Window} {string + list} appears at the top of the translation area, under the label + \menu{Source text}. Note that all blanks in the source text have + been replaced by "." so the translator can see the spacing + required within the text. + + If the developer provides a \l{QObject::tr()} {disambiguating + comment}, it will appear below the source text area, under the + label \menu{Developer comments}. + + Below the source text and optional developer comments are two text + entry widgets for the translator, one for entering the translation + of the current string, and one for the translator to enter an + optional comment to be read by other translators. + + When \l{Translating Multiple Languages Simultaneously} {multiple + languages} are being translated, this sequence of fields is + repeated for each language. See aso \l {Changing the Target + Locale}. + + \section2 Phrases and Guesses Window + + If the current string in the \l{Strings Window} {string list} + appears in one or more of the \l{Phrase Books} {phrase books} + that have been loaded, the current string and its phrase book + translation(s) will be listed in this window. If the current + string is the same as, or similar to, another string that has + already been translated, that other string and its translation + will also be listed in this window. + + To use a translation from the Phrases and Guesses Window, you can + double click the translation, and it will be copied into the + translation area, or you can use the translation's \e{Guess} + hotkey on the right. You can also press \key{F10} to move the + focus to the Phrases and Guesses Window, then use the up and down + arrow keys to find the desired translation, and and then press + \key{Enter} to copy it to the translation area. If you decide + that you don't want to copy a phrase after all, press \key{Esc} to + return the focus to the translation area. + + The Phrases and Guesses Window is a dockable window. If it has + been closed, it can be made visible by pressing the \e{Phrases and + guesses} tab at the bottom of the window, or by pressing + \key{F10}. + + \section2 Sources and Forms Window + + If the source files containing the translatable strings are + available to \QL, this window shows the source context of the + current string in the \l{Strings Window} {string list}. The source + code line containing the current string should be shown and + highlighted. If the file containing the source string is not + found, the expected absolute file path is shown. + + If the source context shows the wrong source line, it probably + means the translation file is out of sync with the source files. + To re-sync the translation file with the source files, see the + \l{lupdate manual} {lupdate manual}. + + The Sources and Forms window is a dockable window. If it has been + closed, it can be made visible again by pressing the \e{Sources + and Forms} tab at the bottom of the window, or by pressing + \key{F9}. + + \section2 Warnings Window + + If the translation you enter for the current string fails any of + the active \l{Validation Tests} {validation tests}, the failures + are listed in the warnings window. The first of these failure + messages is also shown in the status bar at the bottom of the main + window. Note that only \e{active} validation tests are + reported. To see which validation tests are currently active, or + to activate or deactivate tests, use the \menu{Validation} menu + from the \l{menubar}{menu bar}. + + The Warnings window is a dockable window. If it has been closed, + it can be made visible by pressing the \e{Warnings} tab at the + bottom of the window, or by pressing \key{F8}. + + \target multiple languages + \section2 Translating Multiple Languages Simultaneously + + Qt Linguist can now load and edit multiple translation files + simultaneously. One use for this is the case where you know two + languages better than you know English (Polish and Japanese, say), + and you are given an application's Polish translation file and + asked to update the application's Japanese translation file. You + are more comfortable translating Polish to Japanese than you are + translating English to Japanese. + + Below is the UI snapshot shown earlier, but this time with both + \e{Polish} and \e{Japanese} translation files loaded. + + \image linguist-linguist_2.png + + The first thing to notice is that the \l{The Translation Area} + {translation area} has text editing areas for both Polish and + Japanese, and these are color-coded for easier separation. + Second, the \l{Context Window} and the \l{Strings Window} both + have two clomuns labeled \inlineimage linguist-check-obsolete.png + instead of one, and although it may be hard to tell, these columns + are also color-coded with the same colors. The left-most column in + either case applies to the top-most language area (Polish above) + in the \l{The Translation Area} {translation area}, and the + right-most column applies to the bottom language area. + + The \e{Items} column in the \l{Context Window} combines the values + for both languages. The best way to see this is to look at the + value for the \bold{MessageEditor} context, which is the one + selected in the snapshot shown above. Recall that in the first UI + snapshot (Polish only), the numbers for this context were + \e{18/18}, meaning 18 translatable strings had been found in the + context, and all 18 strings had accepted translations. In the UI + snapshot above, the numbers for the \bold{MessageEditor} context + are now \e{1/18}, meaning that both languages have 18 translatable + strings for that context, but for Japanese, only 1 of the 18 + strings has an accepted translation. The + \inlineimage linguist-check-off.png + icon in the Japanese column means that at least one string in the + context doesn't have an accepted Japanese translation yet. In fact, + 17 of the 18 strings don't have accepted Japanese translations yet. + We will see \e{18/18} in the \e{Items} column when all 18 strings + have accepted translations for all the loaded translation files, + e.g., both Polish and Japanese in the snapshot. + + \section1 Common Tasks + + \section2 Leaving a Translation for Later + + If you wish to leave a translation press \key{Ctrl+L} (Next + Unfinished) to move to the next unfinished translation. To move to + the next translation (whether finished or unfinished) press + \key{Shift+Ctrl+L}. You can also navigate using the Translation + menu. If you want to go to a different context entirely, click the + context you want to work on in the Context list, then click the + source text in the \l{Strings Window} {string list}. + + \section2 Phrases That Require Multiple Translations Depending on Context + + The same phrase may occur in two or more contexts without conflict. Once + a phrase has been translated in one context, \QL notes + that the translation has been made and when the translator reaches a + later occurrence of the same phrase \QL will provide + the previous translation as a possible translation candidate in the + \l{Phrases and Guesses Window}. + + If a phrase occurs more than once in a particular context it will + only be shown once in \QL's \l{Context Window} {context list} and + the translation will be applied to every occurrence within the + context. If the same phrase needs to be translated differently + within the same context the programmer must provide a + distinguishing comment for each of the phrases concerned. If such + comments are used the duplicate phrases will appear in the + \l{Context Window} {context list}. The programmers comments will + appear in the \l{The Translation Area} {translation area} on a + light blue background. + + \section2 Changing Keyboard Accelerators + + A keyboard accelerator is a key combination that, when pressed, + causes an application to perform an action. There are two kinds of + keyboard accelerators: Alt key and Ctrl key accelerators. + + \section3 Alt Key Accellerators + + Alt key accelerators are used in menu selection and on buttons. + The underlined character in a menu item or button label signifies + that pressing the Alt key with the underlined character will + perform the same action as clicking the menu item or pressing the + button. For example, most applications have a \e{File} menu with + the "F" in the word "File" underlined. In these applications the + \e{File} menu can be invoked either by clicking the word "File" on + the menu bar or by pressing \e{Alt+F}. To identify an accelerator + key in the translation text ("File") precede it with an ampersand, + e.g. \e{\&File}. If a string to be translated has an ampersand in + it, then the translation for that string should also have an + ampersand in it, preferably in front of the same character. + + The meaning of an Alt key accelerator can be determined from the + phrase in which the ampersand is embedded. The translator can + change the character part of the Alt key accelerator, if the + translated phrase does not contain the same character or if that + character has already been used in the translation of some other + Alt key accelerator. Conflicts with other Alt key accelerators + must be avoided within a context. Note that some Alt key + accelerators, usually those on the menu bar, may apply in other + contexts. + + \section3 Ctrl Key Accelerators + + Ctrl key accelerators can exist independently of any visual + control. They are often used to invoke actions in menus that would + otherwise require multiple keystrokes or mouse clicks. They may + also be used to perform actions that do not appear in any menu or + on any button. For example, most applications that have a \e{File} + menu have a \e{New} submenu item in the \e{File} menu. The \e{New} + item might appear as "\underline{N}ew Ctrl+N" in the \e{File} + menu, meaning the \e{New} menu can be invoked by simply pressing + \key{Ctrl+N}, instead of either clicking \e{File} with the mouse + and then clicking \e{New} with the mouse, or by entering \e{Alt+F} + and \e{N}. + + Each Ctrl key accelerator is shown in the \l{Strings Window} + {string list} as a separte string, e.g. \key{Ctrl+Enter}. Since + the string doesn't have a context to give it meaning, e.g. like + the context of the phrase in which an Alt key accelerator appears, + the translator must rely on the UI developer to include a + \l{QObject::tr()} {disambiguation comment} to explain the action + the Ctrl key accelerator is meant to perform. This disambiguating + comment (if provided by the developer) will appear under + \e{Developer comments} in the \l{The Translation Area} + {translation area} under the \e{Source text} area. + + Ideally Ctrl key accelerators are translated simply by copying + them directly using \e {Copy from source text} in the + \menu{Translation} menu. However, in some cases the character will + not make sense in the target language, and it must be + changed. Whichever character (alpha or digit) is chosen, the + translation must be in the form "Ctrl+" followed by the upper case + character. \e{Qt} will automatically display the correct name at + runtime. As with Alt key accelerators, if the translator changes + the character, the new character must not conflict with any other + Ctrl key accelerator. + + \warning Do not translate the "Alt", "Ctrl" or "Shift" parts of + the accelerators. \e{Qt} relies on these strings being there. For + supported languages, \e {Qt} automatically translates these + strings. + + \section2 Handling Numbered Arguments + + Some phrases contain numbered arguments. A numbered argument is a + placeholder that will be replaced with text at runtime. A numbered + argument appears in a source string as a percent sign followed by + a digit. Consider an example: \c{After processing file %1, file %2 + is next in line}. In this string to be translated, \c{%1} and + \c{%2} are numbered arguments. At runtime, \c{%1} and \c{%2} will + be replaced with the first and next file names respectively. The + same numbered arguments must appear in the translation, but not + necessarily in the same order. A German translation of the string + might reverse the phrases, e.g. \c{Datei %2 wird bearbeitet, wenn + Datei %1 fertig ist}. Both numbered arguments appear in the + translation, but in the reverse order. \c{%i} will always be + replaced by the same text in the translation stringss, regardless + of where argument \e{i} appears in the argument sequence in the + source string. + + \section2 Reusing Translations + + If the translated text is similar to the source text, choose the + \e {Copy from source text} entry in the \menu Translation menu (press + \key{Ctrl+B}) which will copy the source text into the + \l{The Translation Area} {translation area}. + + \QL automatically lists possible translations from any open + \l{Phrase Books} {phrase books} in the \l{Phrases and Guesses + Window}, as well as similar or identical phrases that have already + been translated. + + \section2 Changing the Target Locale + + \QL displays the target language in the \l{The Translation Area} + {translation area}, and adapts the number of input fields for + plural forms accordingly. If not explicitly set, \QL guesses the + target language and country by evaluating the translation source + file name: E.g. \c app_de.ts sets the target language to German, + and \c app_de_ch.ts sets the target language to German and the + target country to Switzerland (this also helps loading + translations for the current locale automatically; see + \l{linguist-programmers.html}{Programmers Manual} for details). + If your files do not follow this convention, you can also set the + locale information explicitly using \e {Translation File Settings} + in the \menu Edit menu. + + \image linguist-translationfilesettings.png + + \section1 Phrase Books + + A \QL phrase book is a set of source phrases, target + (translated) phrases, and optional definitions. Typically one phrase book + will be created per language and family of applications. Phrase books + are used to provide a common set of translations to help ensure consistency. + They can also be used to avoid duplication of effort since the translations + for a family of applications can be produced once in the phrase book. + If the translator reaches an untranslated phrase that is the same as a + source phrase in a phrase book, \QL will show the + phrase book entry in the \l {Phrases and Guesses Window}. + + \section2 Creating and Editing Phrase Books + + \image linguist-phrasebookdialog.png + + Before a phrase book can be edited it must be created or, if it already + exists, opened. Create a new phrase book by selecting + \menu{Phrase|New Phrase Book} from the menu bar. You must enter a + filename and may change the location of the file if you wish. A newly + created phrase book is automatically opened. Open an existing phrase + book by choosing \menu{Phrase|Open Phrase Book} from the menu bar. + + The phrase book contents can be displayed and changed by selecting + \menu{Phrase|Edit Phrase Book}, and then activating the phrase book you + want to work on. This will pop up the Phrase Book Dialog as shown + in the image above. To add a new phrase click the \gui{New Phrase} + button (or press Alt+N) and type in a new source phrase. Press Tab and + type in the translation. Optionally press Tab and enter a definition -- + this is useful to distinguish different translations of the same source + phrase. This process may be repeated as often as necessary. You can delete + a phrase by selecting it in the phrases list and clicking + Remove Phrase. Click the \gui Close button (press Esc) once you've finished + adding (and removing) phrases. + + \section2 Shortcuts for Editing Phrase Books + + You can also create a new phrase book entry directly out of the translation you + are working on: Clicking \menu{Phrases|Add to Phrase Book} or pressing + \key{Ctrl+T} will add the source text and the content of the first translation + field to the current phrase book. If multiple phrase books are loaded, + you have to specify the phrase book to add the entry to in a dialogue. + If you detect an error in a phrase book entry that is shown in the + \l{Phrases and Guesses Window}, you can also edit it in place by right + clicking on the entry, and selecting \menu{Edit}. After fixing the error + press \key{Return} to leave the editing mode. + + \section2 Batch Translation + + \image linguist-batchtranslation.png + + Use the batch translation feature of \QL to automatically + translate source texts that are also in a phrase book. Selecting + \menu{Tools|Batch Translation} will show you the batch translation dialog, + which let you configure which phrase books to use in what order during the + batch translation process. Furthermore you can set whether only entries + with no present translation should be considered, and whether batch translated + entries should be set to finished (see also \l {String Translation States}). + + \section1 Validation Tests + + \QL provides four kinds of validation tests for translations. + + \list 1 + \o \e {Accelerator validation} detects translated phrases + that do not have an ampersand when the source phrase does and vice + versa. + \o \e {Punctuation validation} detects differences in the + terminating punctuation between source and translated phrases when this + may be significant, e.g. warns if the source phrase ends with an + ellipsis, exclamation mark or question mark, and the translated phrase + doesn't and vice versa. + \o \e {Phrases validation} detects source phrases that are + also in the phrase book but whose translation differs from that given in + the phrase book. + \o \e {Place marker validation} detects whether the same variables + (like \c %1, \c %2) are used both in the source text and in the translation. + \endlist + + Validation may be switched on or off from the menu bar's + Validation item or using the toolbar buttons. Unfinished phrases + that fail validation are marked with an exclamation mark in the + source text pane. Finished phrases will get a yellow tick + instead. If you switch validation off and then switch it on later, + \QL will recheck all phrases and mark any that fail + validation. See also \l{String Translation States}. + + \section1 Form Preview + + \image linguist-previewtool.png + + Forms created by \e{Qt Designer} are stored in special \c .ui files. + \QL can make use of these \c .ui files to show the translations + done so far on the form itself. This of course requires access to the \c .ui + files during the translation process. Activate + \menu{Tools|Open/Refresh Form Preview} to open the window shown above. + The list of \c .ui files \QL has detected are displayed in the Forms + List on the left hand. If the path to the files has changed, you can load + the files manually via \menu{File|Open Form...}. Double-click on an entry + in the Forms List to display the Form File. Select \e{} from + the toolbar to display the untranslated form. + + \section1 Qt Linguist Reference + + + \section2 File Types + + \QL makes use of four kinds of files: + + \list + \o \c .ts \e {translation source files} \BR are human-readable XML + files containing source phrases and their translations. These files are + usually created and updated by \l lupdate and are specific to an + application. + \o \c .xlf \e {XLIFF files} \BR are human-readable XML files that adhere + to the international XML Localization Interchange File Format. \QL + can be used to edit XLIFF files generated by other programs. For standard + Qt projects, however, only the \c .ts file format is used. + \o \c .qm \e {Qt message files} \BR are binary files that contain + translations used by an application at runtime. These files are + generated by \l lrelease, but can also be generated by \QL. + \o \c .qph \e {Qt phrase book files} \BR are human-readable XML + files containing standard phrases and their translations. These files + are created and updated by \QL and may be used by any + number of projects and applications. + \endlist + + \target menubar + \section2 The Menu Bar + + \image linguist-menubar.png + + \list + \o \gui {File} + \list + \o \gui {Open... Ctrl+O} \BR pops up an open file dialog from which a + translation source \c .ts or \c .xlf file can be chosen. + \o \gui {Recently opened files} \BR shows the \c .ts files that + have been opened recently, click one to open it. + \o \gui {Save Ctrl+S} \BR saves the current translation source file. + \o \gui {Save As...} \BR pops up a save as file dialog so that the + current translation source file may be saved with a different + name, format and/or put in a different location. + \o \gui {Release} \BR create a Qt message \c .qm file with the same base + name as the current translation source file. The release manager's + command line tool \l lrelease performs the same function on + \e all of an application's translation source files. + \o \gui {Release As...} \BR pops up a save as file dialog. The + filename entered will be a Qt message \c .qm file of the translation + based on the current translation source file. The release manager's + command line tool \l lrelease performs the same function on + \e all of an application's translation source files. + \o \gui {Print... Ctrl+P} \BR pops up a print dialog. If you click + OK the translation source and the translations will be printed. + \o \gui {Exit Ctrl+Q} \BR closes \QL. + \endlist + + \o \gui {Edit} + \list + \o \gui {Undo Ctrl+Z} \BR undoes the last editing action in the + translation pane. + \o \gui {Redo Ctrl+Y} \BR redoes the last editing action in the + translation pane. + \o \gui {Cut Ctrl+X} \BR deletes any highlighted text in the + translation pane and saves a copy to the clipboard. + \o \gui {Copy Ctrl+C} \BR copies the highlighted text in the + translation pane to the clipboard. + \o \gui {Paste Ctrl+V} \BR pastes the clipboard text into the + translation pane. + \omit + \o \gui {Delete} \BR deletes the highlighted text in the + translation pane. + \endomit + \o \gui {Select All Ctrl+A} \BR selects all the text in the + translation pane ready for copying or deleting. + \o \gui {Find... Ctrl+F} \BR pops up the + Find dialog. When the dialog pops up + enter the text to be found and click the \gui {Find Next} button. + Source phrases, translations and comments may be searched. + \o \gui {Find Next F3} \BR finds the next occurrence of the text that + was last entered in the Find dialog. + \o \gui {Search and Translate...} \BR pops up the Search and + Replace Dialog. Use this dialog to translate the same text in multiple items. + \o \gui {Translation File Settings...} \BR let you configure the target + language and the country/region of a translation source file. + \endlist + + \o \gui {Translation} + \list + \o \gui {Prev Unfinished Ctrl+K} \BR moves to the nearest previous + unfinished source phrase (unfinished means untranslated or + translated but failed validation). + \o \gui {Next Unfinished Ctrl+L} \BR moves to the next unfinished source + phrase. + \o \gui {Prev Shift+Ctrl+K} \BR moves to the previous source phrase. + \o \gui {Next Shift+Ctrl+L} \BR moves to the next source phrase. + \o \gui {Done \& Next Ctrl+Enter} \BR mark this phrase as 'done' + (translated) and move to the next unfinished source phrase. + \o \gui {Copy from source text Ctrl+B} \BR copies the source text into + the translation. + \endlist + + \o \gui {Validation} (See \l{Validation Tests}) + \list + \o \gui {Accelerators} \BR toggles validation on or off for Alt + accelerators. + \o \gui {Ending Punctuation} \BR switches validation on or off + for phrase ending punctuation, e.g. ellipsis, exclamation mark, + question mark, etc. + \o \gui {Phrase Matches} \BR sets validation on or off for + matching against translations that are in the current phrase book. + \o \gui {Place Marker Matches} \BR sets validation on or off for + the use of the same place markers in the source and translation. + \endlist + + \o \gui {Phrases} (See the section \l {Phrase Books} for details.) + \list + + \o \gui {New Phrase Book... Ctrl+N} \BR pops up a save as file + dialog. You must enter a filename to be used for the phrase + book and save the file. Once saved you should open the phrase + book to begin using it. + + \o \gui {Open Phrase Book... Ctrl+H} \BR pops up an open file + dialog. Find and choose a phrase book to open. + + \o \gui {Close Phrase Book} \BR displays the list of phrase + books currently opened. Clicking on one of the items will + close the phrase book. If the phrase book has been modified, a + dialog box asks whether \QL should save the changes. + + \o \gui {Edit Phrase Book...} \BR displays the list of phrase + books currently opened. Clicking on one of the items will open + the \l{Creating and Editing Phrase Books}{Phrase Book Dialog} + where you can add, edit or delete phrases. + + \o \gui {Print Phrase Book...} \BR displays the list of phrase + books currently opened. Clicking on one of the items pops up a + print dialog. If you click OK the phrase book will be + printed. + + \o \gui {Add to Phrase Book Ctrl+T} \BR Adds the source text + and translation currently shown in the \l{The Translation + Area} {translation area} to a phrase book. If multiple phrase + books are loaded, a dialog box let you specify select one. + + \endlist + + \o \gui {Tools} + \list + + \o \gui {Batch Translation...} \BR Opens a \l{Batch + Translation}{dialog} which let you automatically insert + translations for source texts which are in a phrase book. + + \o \gui {Open/Refresh Form Preview F3} \BR Opens the \l{Form + Preview}. This window let you instantly see translations for + forms created with \QD. \endlist + + \o \gui {View} + \list + + \o \gui {Revert Sorting} \BR puts the items in the \l{Context + Window} {context list} and in the \l{Strings Window} {string + list} into their original order. + + \o \gui {Display Guesses} \BR turns the display of phrases and + guesses on or off. + + \o \gui {Statistics} \BR toggles the visibility of the + Statistics dialog. + + \o \gui {Views} \BR toggles the visibility of the \l{Context + Window}, \l{Strings Window}, \l{Phrases and Guesses Window}, + \l{Warnings Window}, or \l{Sources and Forms Window}. + + \o \gui {Toolbars} \BR toggles the visibility of the different + toolbars. + + \endlist + + \o \gui {Help} + \list + \o \gui {Manual F1} \BR opens this manual. + \o \gui {About Qt Linguist} \BR Shows information about \QL. + \o \gui {About Qt} \BR Shows information about \e{Qt}. + \o \gui {What's This? Shift+F1} \BR Click on one item in the main window + to get additional information about it. + \endlist + + \endlist + + \section2 The Toolbar + + \image linguist-toolbar.png + + \list + \o \inlineimage linguist-fileopen.png + \BR + Pops up the open file dialog to open a new translation source \c .ts + file. + + \o \inlineimage linguist-filesave.png + \BR + Saves the current translation source \c .ts file. + + \o \inlineimage linguist-fileprint.png + \BR + Prints the current translation source \c .ts file. + + \o \inlineimage linguist-phrasebookopen.png + \BR + Pops up the file open dialog to open a new phrase book \c .qph file. + + \o \inlineimage linguist-editundo.png + \BR + Undoes the last editing action in the translation pane. + + \o \inlineimage linguist-editredo.png + \BR + Redoes the last editing action in the translation pane. + + \o \inlineimage linguist-editcut.png + \BR + Deletes any highlighted text in the translation pane and save a copy to + the clipboard. + + \o \inlineimage linguist-editcopy.png + \BR + Copies the highlighted text in the translation pane to the clipboard. + + \o \inlineimage linguist-editpaste.png + \BR + Pastes the clipboard text into the translation pane. + + \o \inlineimage linguist-editfind.png + \BR + Pops up the Find dialog . + + \o \inlineimage linguist-prev.png + \BR + Moves to the previous source phrase. + + \o \inlineimage linguist-next.png + \BR + Moves to the next source phrase. + + \o \inlineimage linguist-prevunfinished.png + \BR + Moves to the previous unfinished source phrase. + + \o \inlineimage linguist-nextunfinished.png + \BR + Moves to the next unfinished source phrase. + + \o \inlineimage linguist-doneandnext.png + \BR + Marks the phrase as 'done' (translated) and move to the next + unfinished source phrase. + + \o \inlineimage linguist-validateaccelerators.png + \BR + Toggles accelerator validation on and off. + + \o \inlineimage linguist-validatepunctuation.png + \BR + Toggles phrase ending punctuation validation on and off. + + \o \inlineimage linguist-validatephrases.png + \BR + Toggles phrase book validation on or off. + + \o \inlineimage linguist-validateplacemarkers.png + \BR + Toggles place marker validation on or off. + + \endlist + +*/ + +/*! + \page linguist-programmers.html + \title Qt Linguist Manual: Programmers + + \contentspage {Qt Linguist Manual}{Contents} + \previouspage Qt Linguist Manual: Translators + \nextpage Qt Linguist Manual: TS File Format + + Support for multiple languages is extremely simple in Qt + applications, and adds little overhead to the programmer's workload. + + Qt minimizes the performance cost of using translations by + translating the phrases for each window as they are created. In most + applications the main window is created just once. Dialogs are often + created once and then shown and hidden as required. Once the initial + translation has taken place there is no further runtime overhead for + the translated windows. Only those windows that are created, + destroyed and subsequently created will have a translation + performance cost. + + Creating applications that can switch language at runtime is possible + with Qt, but requires a certain amount of programmer intervention and + will of course incur some runtime performance cost. + + \section1 Making the Application Translation-Aware + + Programmers should make their application look for and load the + appropriate translation file and mark user-visible text and Ctrl + keyboard accelerators as targets for translation. + + Each piece of text that requires translating requires context to help + the translator identify where in the program the text occurs. In the + case of multiple identical texts that require different translations, + the translator also requires some information to disambiguate the + source texts. Marking text for translation will automatically cause + the class name to be used as basic context information. In some cases + the programmer may be required to add additional information to help + the translator. + + \section2 Creating Translation Files + + Translation files consist of all the user-visible text and Ctrl key + accelerators in an application and translations of that text. + Translation files are created as follows: + + \list 1 + \o Run \l lupdate initially to generate the first set of \c .ts + translation source files with all the user-visible text but no + translations. + \o The \c .ts files are given to the translator who adds translations + using \QL. \QL takes care of any changed + or deleted source text. + \o Run \l lupdate to incorporate any new text added to the + application. \l lupdate synchronizes the user-visible text from the + application with the translations; it does not destroy any data. + \o Steps 2 and 3 are repeated as often as necessary. + \o When a release of the application is needed \l lrelease is run to + read the \c .ts files and produce the \c .qm files used by the + application at runtime. + \endlist + + For \l lupdate to work successfully, it must know which translation + files to produce. The files are simply listed in the application's \c + .pro Qt project file, for example: + + \snippet examples/linguist/arrowpad/arrowpad.pro 1 + + If your sources contain genuine non-Latin1 strings, \l lupdate needs + to be told about it in the \c .pro file by using, for example, + the following line: + + \code + CODECFORTR = UTF-8 + \endcode + + See the \l lupdate and \l lrelease sections. + + \section2 Loading Translations + + \snippet examples/linguist/hellotr/main.cpp 1 + \snippet examples/linguist/hellotr/main.cpp 3 + + This is how a simple \c main() function of a Qt application begins. + + \snippet examples/linguist/hellotr/main.cpp 1 + \snippet examples/linguist/hellotr/main.cpp 4 + + For a translation-aware application a translator object is created, a + translation is loaded and the translator object installed into the + application. + + \snippet examples/linguist/arrowpad/main.cpp 0 + \snippet examples/linguist/arrowpad/main.cpp 1 + + For non-Latin1 strings in the sources you will also need for example: + + \code + QTextCodec::setCodecForTr(QTextCodec::codecForName("utf8")); + \endcode + + In production applications a more flexible approach, for example, + loading translations according to locale, might be more appropriate. If + the \c .ts files are all named according to a convention such as + \e appname_locale, e.g. \c tt2_fr, \c tt2_de etc, then the + code above will load the current locale's translation at runtime. + + If there is no translation file for the current locale the application + will fall back to using the original source text. + + Note that if you need to programmatically add translations at + runtime, you can reimplement QTranslator::translate(). + + \section2 Making the Application Translate User-Visible Strings + + User-visible strings are marked as translation targets by wrapping them + in a \c tr() call, for example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 6 + + would become + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 7 + + All QObject subclasses that use the \c Q_OBJECT macro implement + the \c tr() function. + + Although the \c tr() call is normally made directly since it is + usually called as a member function of a QObject subclass, in + other cases an explicit class name can be supplied, for example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 8 + + or + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 9 + + \section2 Distinguishing Identical Strings That Require Different Translations + + The \l lupdate program automatically provides a \e context for every + source text. This context is the class name of the class that contains + the \c tr() call. This is sufficient in the vast majority of cases. + Sometimes however, the translator will need further information to + uniquely identify a source text; for example, a dialog that contained + two separate frames, each of which contained an "Enabled" option would + need each identified because in some languages the translation would + differ between the two. This is easily achieved using the + two argument form of the \c tr() call, e.g. + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 10 + + and + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 11 + + Ctrl key accelerators are also translatable: + + \snippet examples/linguist/trollprint/mainwindow.cpp 2 + + It is strongly recommended that the two argument form of \c tr() is used + for Ctrl key accelerators. The second argument is the only clue the + translator has as to the function performed by the accelerator. + + \section2 Helping the Translator with Navigation Information + + In large complex applications it may be difficult for the translator to + see where a particular source text comes from. This problem can be + solved by adding a comment using the keyword \e TRANSLATOR which + describes the navigation steps to reach the text in question; e.g. + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 12 + + These comments are particularly useful for widget classes. + + \section2 Handling Plural Forms + + Qt includes a \c tr() overload that will make it very easy to + write "plural-aware" internationalized applications. This overload + has the following signature: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 17 + + Depending on the value of \c n, the \c tr() function will return a different + translation, with the correct grammatical number for the target language. + Also, any occurrence of \c %n is replaced with \c{n}'s value. For example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 18 + + If a French translation is loaded, this will expand to "0 item + remplac\unicode{233}", "1 item remplac\unicode{233}", "2 items + remplac\unicode{233}s", etc., depending on \c{n}'s value. + And if no translation is loaded, the orignal string is used, with \c %n + replaced with count's value (e.g., "6 item(s) replaced"). + + To handle plural forms in the native language, you need to load a + translation file for this language, too. \l lupdate has the + \c -pluralonly command line option, which allows the creation of + \c .ts files containing only entries with plural forms. + + See the \l{http://doc.trolltech.com/qq/}{Qt Quarterly} Article + \l{http://doc.trolltech.com/qq/qq19-plurals.html}{Plural Forms in Translations} + for further details on this issue. + + \section2 Coping With C++ Namespaces + + C++ namespaces and the \c {using namespace} statement can confuse + \l lupdate. It will interpret \c MyClass::tr() as meaning just + that, not as \c MyNamespace::MyClass::tr(), even if \c MyClass is + defined in the \c MyNamespace namespace. Runtime translation of + these strings will fail because of that. + + You can work around this limitation by putting a \e TRANSLATOR + comment at the beginning of the source files that use \c + MyClass::tr(): + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 13 + + After the comment, all references to \c MyClass::tr() will be + understood as meaning \c MyNamespace::MyClass::tr(). + + \section2 Translating Text That is Outside of a QObject Subclass + + \section3 Using QCoreApplication::translate() + + If the quoted text is not in a member function of a QObject subclass, + use either the tr() function of an appropriate class, or the + QCoreApplication::translate() function directly: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 14 + + \section3 Using QT_TR_NOOP() and QT_TRANSLATE_NOOP() + + If you need to have translatable text completely outside a function, + there are two macros to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP(). + These macros merely mark the text for extraction by \l{lupdate}. + The macros expand to just the text (without the context). + + Example of QT_TR_NOOP(): + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 15 + + Example of QT_TRANSLATE_NOOP(): + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 16 + + \section1 Tutorials + + Three tutorials are presented: + + \list 1 + \o \l{linguist/hellotr}{Hello tr()} demonstrates the creation of + a \l QTranslator object. It also shows the simplest use of + the \c tr() function to mark user-visible source text for + translation. + + \o \l{linguist/arrowpad}{Arrow Pad} explains how to make the application load the + translation file applicable to the current locale. It also shows the + use of the two-argument form of \c tr() which provides additional + information to the translator. + + \o \l{linguist/trollprint}{Troll Print} explains how + identical source texts can be distinguished even when they occur in + the same context. This tutorial also discusses how the translation + tools help minimize the translator's work when an application is + upgraded. + \endlist + + These tutorials cover all that you need to know to prepare your Qt + applications for translation. + + At the beginning of a project add the translation source files to be + used to the project file and add calls to \l lupdate and \l lrelease to + the makefile. + + During the project all the programmer must do is wrap any user-visible + text in \c tr() calls. They should also use the two argument form for + Ctrl key accelerators, or when asked by the translator for the cases + where the same text translates into two different forms in the same + context. The programmer should also include \c TRANSLATION comments to + help the translator navigate the application. +*/ + +/*! + \page linguist-ts-file-format.html + \title Qt Linguist Manual: TS File Format + + \contentspage {Qt Linguist Manual}{Contents} + \previouspage Qt Linguist Manual: Programmers + + The \c .ts file format used by \QL is described by the + \l{http://www.w3.org/TR/1998/REC-xml-19980210}{DTD} presented below, + which we include for your convenience. Be aware that the format + may change in future Qt releases. + + \quotefile tools/linguist/shared/ts.dtd + +*/ diff --git a/doc/src/mac-differences.qdoc b/doc/src/mac-differences.qdoc new file mode 100644 index 0000000..573e62d --- /dev/null +++ b/doc/src/mac-differences.qdoc @@ -0,0 +1,339 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page mac-differences.html + \title Qt for Mac OS X - Specific Issues + \brief A description of issues with Qt that are specific to Mac OS X. + \ingroup platform-notes + + This file outlines known issues and possible workarounds when + using Qt on Mac OS X. Contact Qt's technical support team if you find + additional issues which are not covered here. (See also the + document \l{qtmac-as-native.html} {Qt is Mac OS X Native}.) + + \tableofcontents + + \section1 GUI Applications + + Mac OS X handles most applications as "bundles". A bundle is a + directory structure that groups related files together (e.g., + widgets.app/). GUI applications in particular must be run from a + bundle or by using the open(1), because Mac OS X needs the bundle + to dispatch events correctly, as well as for accessing the menu + bar. + + If you are using older versions of GDB you must run with the full + path to the executable. Later versions allow you to pass the + bundle name on the command line. + + \section1 Painting + + Mac OS X always double buffers the screen so the + Qt::WA_PaintOnScreen attribute has no effect. Also it is + impossible to paint outside of a paint event so + Qt::WA_PaintOutsidePaintEvent has no effect either. + + \section1 Library Support + + \section2 Qt libraries as frameworks + + By default, Qt is built as a set of frameworks. Frameworks is the + Mac OS X "preferred" way of distributing libraries. There are + definite advantages to using them. See + \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html} + {Apple's Framework Programming Guide} for more information. + + In general, this shouldn't be an issue because qmake takes care of + the specifics for you. The + \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html} + {Framework Programming Guide} discusses issues to keep in mind + when choosing frameworks over the more typical, dynamic libraries. + However, one point to remember is: \bold {Frameworks always link + with "release" versions of libraries}. + + If you actually want to use a \e{debug} version of a Qt framework, + you must ensure that your application actually loads that debug + version. This is often done by using the DYLD_IMAGE_SUFFIX + environment variables, but that way often doesn't work so well. + Instead, you can temporarily swap your debug and release versions, + which is documented in + \l{http://developer.apple.com/technotes/tn2004/tn2124.html#SECJUSTONELIB} + {Apple's "Debugging Magic" technical note}. + + If you don't want to use frameworks, simply configure Qt with + \c{-no-framework}. + + \section2 Bundle-Based Libraries + + If you want to use some dynamic libraries in your Mac OS X + application bundle (the application directory), create a + subdirectory named "Frameworks" in the application bundle + directory and place your dynamic libraries there. The application + will find a dynamic library if it has the install name + \e{@executable_path/../Frameworks/libname.dylib}. + + If you use \c qmake and Makefiles, use the \c QMAKE_LFLAGS_SONAME setting: + + \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 0 + + Alternatively, you can modify the install name using the + install_name_tool(1) on the command line. See its manpage for more + information. + + Note that the \c DYLD_LIBRARY_PATH environment variable will + override these settings, and any other default paths, such as a + lookup of dynamic libraries inside \c /usr/lib and similar default + locations. + + \section2 Combining Libraries + + If you want to build a new dynamic library combining the Qt 4 + dynamic libraries, you need to introduce the \c{ld -r} flag. Then + relocation information is stored in the the output file, so that + this file could be the subject of another \c ld run. This is done + by setting the \c -r flag in the \c .pro file, and the \c LFLAGS + settings. + + \section2 Initialization Order + + dyld(1) calls global static initializers in the order they are + linked into your application. If a library links against Qt and + references globals in Qt (from global initializers in your own + library), be sure to link your application against Qt before + linking it against the library. Otherwise the result will be + undefined because Qt's global initializers have not been called + yet. + + \section1 Compile-Time Flags + + The follewing flags are helpful when you want to define Mac OS X specific + code: + + \list + + \o Q_OS_DARWIN is defined when Qt detects you are on a + Darwin-based system (including the Open Source version) + + \o Q_WS_MAC is defined when the Mac OS X GUI is present. + + \o QT_MAC_USE_COCOA is defined when Qt is built to use the Cocoa framework. + If it is not present, then Qt is using Carbon. + + \endlist + + A additional flag, Q_OS_MAC, is defined as a convenience whenever + Q_OS_DARWIN is defined. + + If you want to define code for specific versions of Mac OS X, use + the availability macros defined in /usr/include/AvailabilityMacros.h. + + See QSysInfo for information on runtime version checking. + + \section1 Mac OS X Native API Access + + \section2 Accessing the Bundle Path + + The Mac OS X application is actually a directory (ending with \c + .app). This directory contains sub-directories and files. It may + be useful to place items (e.g. plugins, online-documentation, + etc.) inside this bundle. You might then want to find out where + the bundle resides on the disk. The following code returns the + path of the application bundle: + + \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 1 + + Note: When OS X is set to use Japanese, a bug causes this sequence + to fail and return an empty string. Therefore, always test the + returned string. + + For more information about using the CFBundle API, see + \l{http://developer.apple.com/documentation/CoreFoundation/Reference/CFBundleRef/index.html} + {Apple's Developer Website}. + + \section2 Translating the Application Menu and Native Dialogs + + The items in the Application Menu will be merged correctly for + your localized application, but they will not show up translated + until you + \l{http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/Concepts/BundleAnatomy.html#//apple_ref/doc/uid/20001119-105003-BAJFDAAG} + {add a localized resource folder} to the application bundle. + The main thing you need to do is create a file called + locversion.plist. Here is an example for Norwegian: + + \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 2 + + Now when you run the application with your preferred language set + to Norwegian, you should see menu items like "Avslutt" instead of + "Quit". + + \section1 User Interface + + \section2 Right-Mouse Clicks + + If you want to provide right-mouse click support for Mac OS X, use + the QContextMenuEvent class. This will map to a context menu + event, i.e., a menu that will display a pop-up selection. This is + the most common use of right-mouse clicks, and maps to a + control-click with the Mac OS X one-button mouse support. + + \section2 Menu Bar + + Qt will automatically detect your menu bars for you and turn + them into Mac native menu bars. Fitting this into your existing Qt + application will normally be automatic. However, if you have + special needs, the Qt implementation currently selects a menu + bar by starting at the active window + (i.e. QApplication::activeWindow()) and applying the following + tests: + + \list 1 + + \i If the window has a QMenuBar, then it is used. + + \i If the window is modal, then its menu bar is used. If no menu + bar is specified, then a default menu bar is used (as + documented below). + + \i If the window has no parent, then the default menu bar is used + (as documented below). + + \endlist + + These tests are followed all the way up the parent window chain + until one of the above rules is satisifed. If all else fails, a + default menu bar will be created. Note the default menu bar on + Qt is an empty menu bar. However, you can create a different + default menu bar by creating a parentless QMenuBar. The first one + created will be designated the default menu bar and will be used + whenever a default menu bar is needed. + + Note that using native menu bars introduces certain limitations on + Qt classes. See the \l{#Limitations}{list of limitations} below + for more information about these. + + \section2 Special Keys + + To provide the expected behavior for Qt applications on Mac OS X, + the Qt::Meta, Qt::MetaModifier, and Qt::META enum values + correspond to the Control keys on the standard Macintosh keyboard, + and the Qt::Control, Qt::ControlModifier, and Qt::CTRL enum values + correspond to the Command keys. + + \section1 Limitations + + \section2 Menu Actions + + \list + + \o Actions in a QMenu with accelerators that have more than one + keystroke (QKeySequence) will not display correctly, when the + QMenu is translated into a Mac native menu bar. The first key + will be displayed. However, the shortcut will still be + activated as on all other platforms. + + \o QMenu objects used in the native menu bar are not able to + handle Qt events via the normal event handlers. + For Carbon, you will have to install a Carbon event handler on + the menu bar in order to receive Carbon events that are similar + to \l{QMenu::}{showEvent()}, \l{QMenu::}{hideEvent()}, and + \l{QMenu::}{mouseMoveEvent()}. For Cocoa, you will have to + install a delegate on the menu itself to be notified of these + changes. Alternatively, consider using the QMenu::aboutToShow() + and QMenu::aboutToHide() signals to keep track of menu visibility; + these provide a solution that should work on all platforms + supported by Qt. + + \endlist + + \section2 Native Widgets + + Qt has support for sheets and drawers, represented in the + window flags by Qt::Sheet and Qt::Drawer respectiviely. Brushed + metal windows can also be created by using the + Qt::WA_MacMetalStyle window attribute. + +*/ + +/*! + \page qt-mac-cocoa-licensing.html + + \title Contributions to the Following QtGui Files: qapplication_cocoa_p.h, qapplication_mac.mm, qdesktopwidget_mac.mm qeventdispatcher_mac.mm qeventdispatcher_mac_p.h qmacincludes_mac.h qt_cocoa_helpers.mm qt_cocoa_helpers_p.h qwidget_mac.mm qsystemtrayicon_mac.mm + + \contentspage {Other Licenses Used in Qt}{Contents} + + \ingroup licensing + \brief License information for contributions by Apple, Inc. to specific parts of the Qt/Mac Cocoa port. + + \legalese + + Copyright (C) 2007-2008, Apple, Inc. + + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + + \list + \o Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + \o Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + \o Neither the name of Apple, Inc. nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + \endlist + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + \endlegalese +*/ diff --git a/doc/src/mainclasses.qdoc b/doc/src/mainclasses.qdoc new file mode 100644 index 0000000..da041fa --- /dev/null +++ b/doc/src/mainclasses.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page mainclasses.html + \title Qt's Main Classes + \ingroup classlists + + These are the most frequently used Qt classes. For the complete + list see \link classes.html Qt's Classes \endlink. + + \generatelist mainclasses +*/ diff --git a/doc/src/metaobjects.qdoc b/doc/src/metaobjects.qdoc new file mode 100644 index 0000000..4c91a90 --- /dev/null +++ b/doc/src/metaobjects.qdoc @@ -0,0 +1,149 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page metaobjects.html + \title Meta-Object System + \brief An overview of Qt's meta-object system and introspection capabilities. + \ingroup architecture + \keyword meta-object + + Qt's meta-object system provides the signals and slots mechanism for + inter-object communication, run-time type information, and the dynamic + property system. + + The meta-object system is based on three things: + + \list 1 + \o The \l QObject class provides a base class for objects that can + take advantage of the meta-object system. + \o The Q_OBJECT macro inside the private section of the class + declaration is used to enable meta-object features, such as + dynamic properties, signals, and slots. + \o The \l{moc}{Meta-Object Compiler} (\c moc) supplies each + QObject subclass with the necessary code to implement + meta-object features. + \endlist + + The \c moc tool reads a C++ source file. If it finds one or more + class declarations that contain the Q_OBJECT macro, it + produces another C++ source file which contains the meta-object + code for each of those classes. This generated source file is + either \c{#include}'d into the class's source file or, more + usually, compiled and linked with the class's implementation. + + In addition to providing the \l{signals and slots} mechanism for + communication between objects (the main reason for introducing + the system), the meta-object code provides the following + additional features: + + \list + \o QObject::metaObject() returns the associated + \l{QMetaObject}{meta-object} for the class. + \o QMetaObject::className() returns the class name as a + string at run-time, without requiring native run-time type information + (RTTI) support through the C++ compiler. + \o QObject::inherits() function returns whether an object is an + instance of a class that inherits a specified class within the + QObject inheritance tree. + \o QObject::tr() and QObject::trUtf8() translate strings for + \l{Internationalization with Qt}{internationalization}. + \o QObject::setProperty() and QObject::property() + dynamically set and get properties by name. + \o QMetaObject::newInstance() constructs a new instance of the class. + \endlist + + \target qobjectcast + It is also possible to perform dynamic casts using qobject_cast() + on QObject classes. The qobject_cast() function behaves similarly + to the standard C++ \c dynamic_cast(), with the advantages + that it doesn't require RTTI support and it works across dynamic + library boundaries. It attempts to cast its argument to the pointer + type specified in angle-brackets, returning a non-zero pointer if the + object is of the correct type (determined at run-time), or 0 + if the object's type is incompatible. + + For example, let's assume \c MyWidget inherits from QWidget and + is declared with the Q_OBJECT macro: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 0 + + The \c obj variable, of type \c{QObject *}, actually refers to a + \c MyWidget object, so we can cast it appropriately: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 1 + + The cast from QObject to QWidget is successful, because the + object is actually a \c MyWidget, which is a subclass of QWidget. + Since we know that \c obj is a \c MyWidget, we can also cast it to + \c{MyWidget *}: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 2 + + The cast to \c MyWidget is successful because qobject_cast() + makes no distinction between built-in Qt types and custom types. + + \snippet doc/src/snippets/qtcast/qtcast.cpp 3 + \snippet doc/src/snippets/qtcast/qtcast.cpp 4 + + The cast to QLabel, on the other hand, fails. The pointer is then + set to 0. This makes it possible to handle objects of different + types differently at run-time, based on the type: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 5 + \snippet doc/src/snippets/qtcast/qtcast.cpp 6 + + While it is possible to use QObject as a base class without the + Q_OBJECT macro and without meta-object code, neither signals + and slots nor the other features described here will be available + if the Q_OBJECT macro is not used. From the meta-object + system's point of view, a QObject subclass without meta code is + equivalent to its closest ancestor with meta-object code. This + means for example, that QMetaObject::className() will not return + the actual name of your class, but the class name of this + ancestor. + + Therefore, we strongly recommend that all subclasses of QObject + use the Q_OBJECT macro regardless of whether or not they + actually use signals, slots, and properties. + + \sa QMetaObject, {Qt's Property System}, {Signals and Slots} +*/ diff --git a/doc/src/moc.qdoc b/doc/src/moc.qdoc new file mode 100644 index 0000000..b7283c4 --- /dev/null +++ b/doc/src/moc.qdoc @@ -0,0 +1,336 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page moc.html + \title Using the Meta-Object Compiler (moc) + \ingroup buildsystem + \ingroup qttools + \keyword moc + + The Meta-Object Compiler, \c moc, is the program that handles + \l{Meta-Object System}{Qt's C++ extensions}. + + The \c moc tool reads a C++ header file. If it finds one or more + class declarations that contain the Q_OBJECT macro, it + produces a C++ source file containing the meta-object code for + those classes. Among other things, meta-object code is required + for the signals and slots mechanism, the run-time type information, + and the dynamic property system. + + The C++ source file generated by \c moc must be compiled and + linked with the implementation of the class. + + If you use \l qmake to create your makefiles, build rules will be + included that call the moc when required, so you will not need to + use the moc directly. For more background information on \c moc, + see \l{Why Doesn't Qt Use Templates for Signals and Slots?} + + \section1 Usage + + \c moc is typically used with an input file containing class + declarations like this: + + \snippet doc/src/snippets/moc/myclass1.h 0 + + In addition to the signals and slots shown above, \c moc also + implements object properties as in the next example. The + Q_PROPERTY() macro declares an object property, while + Q_ENUMS() declares a list of enumeration types within the class + to be usable inside the \l{Qt's Property System}{property + system}. + + In the following example, we declare a property of the + enumeration type \c Priority that is also called \c priority and + has a get function \c priority() and a set function \c + setPriority(). + + \snippet doc/src/snippets/moc/myclass2.h 0 + + The Q_FLAGS() macro declares enums that are to be used + as flags, i.e. OR'd together. Another macro, Q_CLASSINFO(), + allows you to attach additional name/value pairs to the class's + meta-object: + + \snippet doc/src/snippets/moc/myclass3.h 0 + + The output produced by \c moc must be compiled and linked, just + like the other C++ code in your program; otherwise, the build + will fail in the final link phase. If you use \c qmake, this is + done automatically. Whenever \c qmake is run, it parses the + project's header files and generates make rules to invoke \c moc + for those files that contain a Q_OBJECT macro. + + If the class declaration is found in the file \c myclass.h, the + moc output should be put in a file called \c moc_myclass.cpp. + This file should then be compiled as usual, resulting in an + object file, e.g., \c moc_myclass.obj on Windows. This object + should then be included in the list of object files that are + linked together in the final building phase of the program. + + \section1 Writing Make Rules for Invoking \c moc + + For anything but the simplest test programs, it is recommended + that you automate running the \c{moc}. By adding some rules to + your program's makefile, \c make can take care of running moc + when necessary and handling the moc output. + + We recommend using the \l qmake makefile generation tool for + building your makefiles. This tool generates a makefile that does + all the necessary \c moc handling. + + If you want to create your makefiles yourself, here are some tips + on how to include moc handling. + + For Q_OBJECT class declarations in header files, here is a + useful makefile rule if you only use GNU make: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 0 + + If you want to write portably, you can use individual rules of + the following form: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 1 + + You must also remember to add \c moc_foo.cpp to your \c SOURCES + (substitute your favorite name) variable and \c moc_foo.o or \c + moc_foo.obj to your \c OBJECTS variable. + + Both examples assume that \c $(DEFINES) and \c $(INCPATH) expand + to the define and include path options that are passed to the C++ + compiler. These are required by \c moc to preprocess the source + files. + + While we prefer to name our C++ source files \c .cpp, you can use + any other extension, such as \c .C, \c .cc, \c .CC, \c .cxx, and + \c .c++, if you prefer. + + For Q_OBJECT class declarations in implementation (\c .cpp) + files, we suggest a makefile rule like this: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 2 + + This guarantees that make will run the moc before it compiles + \c foo.cpp. You can then put + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 3 + + at the end of \c foo.cpp, where all the classes declared in that + file are fully known. + + \section1 Command-Line Options + + Here are the command-line options supported by the moc: + + \table + \header \o Option \o Description + + \row + \o \c{-o} + \o Write output to \c rather than to standard output. + + \row + \o \c{-f[]} + \o Force the generation of an \c #include statement in the + output. This is the default for header files whose extension + starts with \c H or \c h. This option is useful if you have + header files that do not follow the standard naming conventions. + The \c part is optional. + + \row + \o \c -i + \o Do not generate an \c #include statement in the output. + This may be used to run the moc on on a C++ file containing one or + more class declarations. You should then \c #include the meta-object + code in the \c .cpp file. + + \row + \o \c -nw + \o Do not generate any warnings. (Not recommended.) + + \row + \o \c {-p} + \o Makes the moc prepend \c {/} to the file name in the + generated \c #include statement. + + \row + \o \c {-I} + \o Add dir to the include path for header files. + + \row + \o \c{-E} + \o Preprocess only; do not generate meta-object code. + + \row + \o \c {-D[=]} + \o Define macro, with optional definition. + + \row + \o \c{-U} + \o Undefine macro. + + \row + \o \c{@} + \o Read additional command-line options from \c{}. + Each line of the file is treated as a single option. Empty lines + are ignored. Note that this option is not supported within the + options file itself (i.e. an options file can't "include" another + file). + + \row + \o \c{-h} + \o Display the usage and the list of options. + + \row + \o \c {-v} + \o Display \c{moc}'s version number. + + \row + \o \c{-Fdir} + + \o Mac OS X. Add the framework directory \c{dir} to the head of + the list of directories to be searched for header files. These + directories are interleaved with those specified by -I options + and are scanned in a left-to-right order (see the manpage for + gcc). Normally, use -F /Library/Frameworks/ + + \endtable + + You can explicitly tell the moc not to parse parts of a header + file. \c moc defines the preprocessor symbol \c Q_MOC_RUN. Any + code surrounded by + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 4 + + is skipped by the \c moc. + + \section1 Diagnostics + + \c moc will warn you about a number of dangerous or illegal + constructs in the Q_OBJECT class declarations. + + If you get linkage errors in the final building phase of your + program, saying that \c YourClass::className() is undefined or + that \c YourClass lacks a vtable, something has been done wrong. + Most often, you have forgotten to compile or \c #include the + moc-generated C++ code, or (in the former case) include that + object file in the link command. If you use \c qmake, try + rerunning it to update your makefile. This should do the trick. + + \section1 Limitations + + \c moc does not handle all of C++. The main problem is that class + templates cannot have signals or slots. Here is an example: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 5 + + Another limitation is that moc does not expand macros, so you + for example cannot use a macro to declare a signal/slot + or use one to define a base class for a QObject. + + Less importantly, the following constructs are illegal. All of + them have alternatives which we think are usually better, so + removing these limitations is not a high priority for us. + + \section2 Multiple Inheritance Requires QObject to Be First + + If you are using multiple inheritance, \c moc assumes that the + first inherited class is a subclass of QObject. Also, be sure + that only the first inherited class is a QObject. + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 6 + + Virtual inheritance with QObject is \e not supported. + + \section2 Function Pointers Cannot Be Signal or Slot Parameters + + In most cases where you would consider using function pointers as + signal or slot parameters, we think inheritance is a better + alternative. Here is an example of illegal syntax: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 7 + + You can work around this restriction like this: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 8 + + It may sometimes be even better to replace the function pointer + with inheritance and virtual functions. + + \section2 Enums and Typedefs Must Be Fully Qualified for Signal and Slot Parameters + + When checking the signatures of its arguments, QObject::connect() + compares the data types literally. Thus, + \l{Qt::Alignment}{Alignment} and \l{Qt::Alignment} are treated as + two distinct types. To work around this limitation, make sure to + fully qualify the data types when declaring signals and slots, + and when establishing connections. For example: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 9 + + \section2 Type Macros Cannot Be Used for Signal and Slot Parameters + + Since \c moc doesn't expand \c{#define}s, type macros that take + an argument will not work in signals and slots. Here is an + illegal example: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 10 + + A macro without parameters will work. + + \section2 Nested Classes Cannot Have Signals or Slots + + Here's an example of the offending construct: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 11 + + \section2 Signal/Slot return types cannot be references + + Signals and slots can have return types, but signals or slots returning references + will be treated as returning void. + + \section2 Only Signals and Slots May Appear in the \c signals and \c slots Sections of a Class + + \c moc will complain if you try to put other constructs in the \c + signals or \c slots sections of a class than signals and slots. + + \sa {Meta-Object System}, {Signals and Slots}, {Qt's Property System} +*/ diff --git a/doc/src/model-view-programming.qdoc b/doc/src/model-view-programming.qdoc new file mode 100644 index 0000000..bf0c1c8 --- /dev/null +++ b/doc/src/model-view-programming.qdoc @@ -0,0 +1,2447 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page model-view-programming.html + \nextpage An Introduction to Model/View Programming + \startpage index.html Qt Reference Documentation + + \title Model/View Programming + \ingroup architecture + \brief A guide to the extensible model/view architecture used by Qt's + item view classes. + + \list + \o \l{An Introduction to Model/View Programming} + \tableofcontents{1 An Introduction to Model/View Programming} + \o \l{Using Models and Views} + \tableofcontents{1 Using Models and Views} + \o \l{Model Classes} + \tableofcontents{1 Model Classes} + \o \l{Creating New Models} + \tableofcontents{1 Creating New Models} + \o \l{View Classes} + \tableofcontents{1 View Classes} + \o \l{Handling Selections in Item Views} + \tableofcontents{1 Handling Selections in Item Views} + \o \l{Delegate Classes} + \tableofcontents{1 Delegate Classes} + \o \l{Item View Convenience Classes} + \tableofcontents{1 Item View Convenience Classes} + \o \l{Using Drag and Drop with Item Views} + \tableofcontents{1 Using Drag and Drop with Item Views} + \o \l{Proxy Models} + \tableofcontents{1 Proxy Models} + \o \l{Model Subclassing Reference} + \tableofcontents{1 Model Subclassing Reference} + \endlist + + See also the list of \l{Model/View Classes}. + + \section1 Related Examples + + \list + \o \l{itemviews/dirview}{Dir View} + \o \l{itemviews/spinboxdelegate}{Spin Box Delegate} + \o \l{itemviews/pixelator}{Pixelator} + \o \l{itemviews/simpletreemodel}{Simple Tree Model} + \o \l{itemviews/chart}{Chart} + \endlist +*/ + +/*! + \page model-view-introduction.html + \previouspage Model/View Programming + \nextpage Using Models and Views + \startpage index.html Qt Reference Documentation + + \title An Introduction to Model/View Programming + + \tableofcontents + + Qt 4 introduces a new set of item view classes that use a model/view + architecture to manage the relationship between data and the way it + is presented to the user. The separation of functionality introduced by + this architecture gives developers greater flexibility to customize the + presentation of items, and provides a standard model interface to allow + a wide range of data sources to be used with existing item views. + In this document, we give a brief introduction to the model/view paradigm, + outline the concepts involved, and describe the architecture of the item + view system. Each of the components in the architecture is explained, + and examples are given that show how to use the classes provided. + + \section1 The Model/View Architecture + + Model-View-Controller (MVC) is a design pattern originating from + Smalltalk that is often used when building user interfaces. + In \l{Design Patterns}, Gamma et al. write: + + \quotation + MVC consists of three kinds of objects. The Model is the application + object, the View is its screen presentation, and the Controller defines + the way the user interface reacts to user input. Before MVC, user + interface designs tended to lump these objects together. MVC decouples + them to increase flexibility and reuse. + \endquotation + + If the view and the controller objects are combined, the result is + the model/view architecture. This still separates the way that data + is stored from the way that it is presented to the user, but provides + a simpler framework based on the same principles. This separation + makes it possible to display the same data in several different views, + and to implement new types of views, without changing the underlying + data structures. + To allow flexible handling of user input, we introduce the concept of + the \e delegate. The advantage of having a delegate in this framework + is that it allows the way items of data are rendered and edited to be + customized. + + \table + \row \i \inlineimage modelview-overview.png + \i \bold{The model/view architecture} + + The model communicates with a source of data, providing an \e interface + for the other components in the architecture. The nature of the + communication depends on the type of data source, and the way the model + is implemented. + + The view obtains \e{model indexes} from the model; these are references + to items of data. By supplying model indexes to the model, the view can + retrieve items of data from the data source. + + In standard views, a \e delegate renders the items of data. When an item + is edited, the delegate communicates with the model directly using + model indexes. + \endtable + + Generally, the model/view classes can be separated into the three groups + described above: models, views, and delegates. Each of these components + is defined by \e abstract classes that provide common interfaces and, + in some cases, default implementations of features. + Abstract classes are meant to be subclassed in order to provide the full + set of functionality expected by other components; this also allows + specialized components to be written. + + Models, views, and delegates communicate with each other using \e{signals + and slots}: + + \list + \o Signals from the model inform the view about changes to the data + held by the data source. + \o Signals from the view provide information about the user's interaction + with the items being displayed. + \o Signals from the delegate are used during editing to tell the + model and view about the state of the editor. + \endlist + + \section2 Models + + All item models are based on the QAbstractItemModel class. This class + defines an interface that is used by views and delegates to access data. + The data itself does not have to be stored in the model; it can be held + in a data structure or repository provided by a separate class, a file, + a database, or some other application component. + + The basic concepts surrounding models are presented in the section + on \l{Model Classes}. + + QAbstractItemModel + provides an interface to data that is flexible enough to handle views + that represent data in the form of tables, lists, and trees. However, + when implementing new models for list and table-like data structures, + the QAbstractListModel and QAbstractTableModel classes are better + starting points because they provide appropriate default implementations + of common functions. Each of these classes can be subclassed to provide + models that support specialized kinds of lists and tables. + + The process of subclassing models is discussed in the section on + \l{Creating New Models}. + + Qt provides some ready-made models that can be used to handle items of + data: + + \list + \o QStringListModel is used to store a simple list of QString items. + \o QStandardItemModel manages more complex tree structures of items, each + of which can contain arbitrary data. + \o QDirModel provides information about files and directories in the local + filing system. + \o QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel are used + to access databases using model/view conventions. + \endlist + + If these standard models do not meet your requirements, you can subclass + QAbstractItemModel, QAbstractListModel, or QAbstractTableModel to create + your own custom models. + + \section2 Views + + Complete implementations are provided for different kinds of + views: QListView displays a list of items, QTableView displays data + from a model in a table, and QTreeView shows model items of data in a + hierarchical list. Each of these classes is based on the + QAbstractItemView abstract base class. Although these classes are + ready-to-use implementations, they can also be subclassed to provide + customized views. + + The available views are examined in the section on \l{View Classes}. + + \section2 Delegates + + QAbstractItemDelegate is the abstract base class for delegates in the + model/view framework. Since Qt 4.4, the default delegate implementation is + provided by QStyledItemDelegate, and this is used as the default delegate + by Qt's standard views. However, QStyledItemDelegate and QItemDelegate are + independent alternatives to painting and providing editors for items in + views. The difference between them is that QStyledItemDelegate uses the + current style to paint its items. We therefore recommend using + QStyledItemDelegate as the base class when implementing custom delegates or + when working with Qt style sheets. + + Delegates are described in the section on \l{Delegate Classes}. + + \section2 Sorting + + There are two ways of approaching sorting in the model/view + architecture; which approach to choose depends on your underlying + model. + + If your model is sortable, i.e, if it reimplements the + QAbstractItemModel::sort() function, both QTableView and QTreeView + provide an API that allows you to sort your model data + programmatically. In addition, you can enable interactive sorting + (i.e. allowing the users to sort the data by clicking the view's + headers), by connecting the QHeaderView::sectionClicked() signal + to the QTableView::sortByColumn() slot or the + QTreeView::sortByColumn() slot, respectively. + + The alternative approach, if your model do not have the required + interface or if you want to use a list view to present your data, + is to use a proxy model to transform the structure of your model + before presenting the data in the view. This is covered in detail + in the section on \l {Proxy Models}. + + \section2 Convenience Classes + + A number of \e convenience classes are derived from the standard view + classes for the benefit of applications that rely on Qt's item-based + item view and table classes. They are not intended to be subclassed, + but simply exist to provide a familiar interface to the equivalent classes + in Qt 3. + Examples of such classes include \l QListWidget, \l QTreeWidget, and + \l QTableWidget; these provide similar behavior to the \c QListBox, + \c QListView, and \c QTable classes in Qt 3. + + These classes are less flexible than the view classes, and cannot be + used with arbitrary models. We recommend that you use a model/view + approach to handling data in item views unless you strongly need an + item-based set of classes. + + If you wish to take advantage of the features provided by the model/view + approach while still using an item-based interface, consider using view + classes, such as QListView, QTableView, and QTreeView with + QStandardItemModel. + + \section1 The Model/View Components + + The following sections describe the way in which the model/view pattern + is used in Qt. Each section provides an example of use, and is followed + by a section showing how you can create new components. +*/ + +/*! + \page model-view-using.html + \contentspage model-view-programming.html Contents + \previouspage An Introduction to Model/View Programming + \nextpage Model Classes + + \title Using Models and Views + + \tableofcontents + + \section1 Introduction + + Two of the standard models provided by Qt are QStandardItemModel and + QDirModel. QStandardItemModel is a multi-purpose model that can be used + to represent various different data structures needed by list, table, + and tree views. This model also holds the items of data. + QDirModel is a model that maintains information about the contents of a + directory. As a result, it does not hold any items of data itself, but + simply represents files and directories on the local filing system. + + QDirModel provides a ready-to-use model to experiment with, and can be + easily configured to use existing data. Using this model, we can show how + to set up a model for use with ready-made views, and explore how to + manipulate data using model indexes. + + \section1 Using Views with an Existing Model + + The QListView and QTreeView classes are the most suitable views + to use with QDirModel. The example presented below displays the + contents of a directory in a tree view next to the same information in + a list view. The views share the user's selection so that the selected + items are highlighted in both views. + + \img shareddirmodel.png + + We set up a QDirModel so that it is ready for use, and create some + views to display the contents of a directory. This shows the simplest + way to use a model. The construction and use of the model is + performed from within a single \c main() function: + + \snippet doc/src/snippets/shareddirmodel/main.cpp 0 + + The model is set up to use data from a default directory. We create two + views so that we can examine the items held in the model in two + different ways: + + \snippet doc/src/snippets/shareddirmodel/main.cpp 5 + + The views are constructed in the same way as other widgets. Setting up + a view to display the items in the model is simply a matter of calling its + \l{QAbstractItemView::setModel()}{setModel()} function with the directory + model as the argument. The calls to + \l{QAbstractItemView::setRootIndex()}{setRootIndex()} tell the views which + directory to display by supplying a \e{model index} that we obtain from + the directory model. + + The \c index() function used in this case is unique to QDirModel; we supply + it with a directory and it returns a model index. Model indexes are + discussed in the \l{Model Classes} chapter. + + The rest of the function just displays the views within a splitter + widget, and runs the application's event loop: + + \snippet doc/src/snippets/shareddirmodel/main.cpp 8 + + In the above example, we neglected to mention how to handle selections + of items. This subject is covered in more detail in the chapter on + \l{Handling Selections in Item Views}. Before examining how selections + are handled, you may find it useful to read the \l{Model Classes} chapter + which describes the concepts used in the model/view framework. +*/ + +/*! + \page model-view-model.html + \contentspage model-view-programming.html Contents + \previouspage Using Models and Views + \nextpage Creating New Models + + \title Model Classes + + \tableofcontents + + \section1 Basic Concepts + + In the model/view architecture, the model provides a standard interface + that views and delegates use to access data. In Qt, the standard + interface is defined by the QAbstractItemModel class. No matter how + the items of data are stored in any underlying data structure, all + subclasses of QAbstractItemModel represent the data as a hierarchical + structure containing tables of items. + Views use this \e convention to access items of data in the model, but + they are not restricted in the way that they present this information + to the user. + + \image modelview-models.png + + Models also notify any attached views about changes to data through the + signals and slots mechanism. + + This chapter describes some basic concepts that are central to the way + item of data are accessed by other components via a model class. More + advanced concepts are discussed in later chapters. + + \section2 Model Indexes + + To ensure that the representation of the data is kept separate from the + way it is accessed, the concept of a \e{model index} is introduced. + Each piece of information that can be obtained via a model is + represented by a model index. Views and delegates use these indexes to + request items of data to display. + + As a result, only the model needs to know how to obtain data, and the + type of data managed by the model can be defined fairly generally. + Model indexes contain a pointer to the model that created them, and + this prevents confusion when working with more than one model. + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 0 + + Model indexes provide \e temporary references to pieces of information, + and can be used to retrieve or modify data via the model. Since models + may reorganize their internal structures from time to time, model + indexes may become invalid, and \e{should not be stored}. If a + long-term reference to a piece of information is required, a + \e{persistent model index} must be created. This provides a reference + to the information that the model keeps up-to-date. + Temporary model indexes are provided by the QModelIndex class, and + persistent model indexes are provided by the QPersistentModelIndex + class. + + To obtain a model index that corresponds to an item of data, three + properties must be specified to the model: a row number, a column number, + and the model index of a parent item. The following sections describe + and explain these properties in detail. + + \section2 Rows and Columns + + In its most basic form, a model can be accessed as a simple table + in which items are located by their row and column numbers. \e{This does + not mean that the underlying pieces of data are stored in an array + structure}; the use of row and column numbers is only a convention to + allow components to communicate with each other. + We can retrieve information about any given item by specifying its row + and column numbers to the model, and we receive an index that + represents the item: + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 1 + + Models that provide interfaces to simple, single level data structures + like lists and tables do not need any other information to be provided + but, as the above code indicates, we need to supply more information + when obtaining a model index. + + \table + \row \i \inlineimage modelview-tablemodel.png + \i \bold{Rows and columns} + + The diagram shows a representation of a basic table model in which each + item is located by a pair of row and column numbers. + By passing the relevant row and column numbers to the model we + obtain a model index that refers to an item of data. + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 2 + + Top level items in a model are always referenced by specifying + \c QModelIndex() as their parent item. This is discussed in the next + section. + \endtable + + \section2 Parents of Items + + The table-like interface to item data provided by models is ideal when + using data in a table or list view; the row and column number system + maps exactly to the way the views display items. + However, structures such as tree views require the model to expose a more + flexible interface to the items within. As a result, each item can also be + the parent of another table of items, in much the same way that a top-level + item in a tree view can contain another list of items. + + When requesting an index for a model item, we must provide some + information about the item's parent. Outside the model, the only way to + refer to an item is through a model index, so a parent model index must + also be given: + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 3 + + \table + \row \i \inlineimage modelview-treemodel.png + \i \bold{Parents, rows, and columns} + + The diagram shows a representation of a tree model in which each item + is referred to by a parent, a row number, and a column number. + + Items "A" and "C" are represented as top-level siblings in the model: + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 4 + + Item "A" has a number of children. A model index for item "B" is + obtained with the following code: + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 5 + \endtable + + \section2 Item Roles + + Items in a model can perform various \e roles for other components, + allowing different kinds of data to be supplied for different situations. + For example, Qt::DisplayRole is used to access a string that can be + displayed as text in a view. + Typically, items contain data for a number of different roles, and the + standard roles are defined by Qt::ItemDataRole. + + We can ask the model for the item's data by passing it the model index + corresponding to the item, and by specifying a role to obtain the type + of data we want: + + \snippet doc/src/snippets/code/doc_src_model-view-programming.qdoc 6 + + \table + \row \i \inlineimage modelview-roles.png + \i \bold{Item roles} + + The role indicates to the model which type of data is being referred to. + Views can display the roles in different ways, so it is important to + supply appropriate information for each role. + + The \l{Creating New Models} section covers some specific uses of roles + in more detail. + \endtable + + Most common uses for item data are covered by the standard roles defined + in Qt::ItemDataRole. By supplying appropriate item data for each role, + models can provide hints to views and delegates about how items should be + presented to the user. Different kinds of views have the freedom to + interpret or ignore this information as required. It is also possible to + define additional roles for application-specific purposes. + + \section2 Summary of Concepts + + \list + \o Model indexes give views and delegates information about the location + of items provided by models in a way that is independent of any + underlying data structures. + \o Items are referred to by their row and column numbers, and by the model + index of their parent items. + \o Model indexes are constructed by models at the request of other + components, such as views and delegates. + \o If a valid model index is specified for the parent item when an index is + requested using \l{QAbstractItemModel::index()}{index()}, the index + returned will refer to an item beneath that parent item in the + model. + The index obtained refers to a child of that item. + \o If an invalid model index is specified for the parent item when an index + is requested using \l{QAbstractItemModel::index()}{index()}, the index + returned will refer to a top-level item in the model. + \o The \l{Qt::ItemDataRole}{role} distinguishes between the + different kinds of data associated with an item. + \endlist + + \section2 Using Model Indexes + + To demonstrate how data can be retrieved from a model, using model + indexes, we set up a QDirModel without a view and display the + names of files and directories in a widget. + Although this does not show a normal way of using a model, it demonstrates + the conventions used by models when dealing with model indexes. + + We construct a directory model in the following way: + + \snippet doc/src/snippets/simplemodel-use/main.cpp 0 + + In this case, we set up a default QDirModel, obtain a parent index using + a specific implementation of \l{QDirModel::index()}{index()} provided by + that model, and we count the number of rows in the model using the + \l{QDirModel::rowCount()}{rowCount()} function. + + For simplicity, we are only interested in the items in the first column + of the model. We examine each row in turn, obtaining a model index for + the first item in each row, and read the data stored for that item + in the model. + + \snippet doc/src/snippets/simplemodel-use/main.cpp 1 + + To obtain a model index, we specify the row number, column number (zero + for the first column), and the appropriate model index for the parent + of all the items that we want. + The text stored in each item is retrieved using the model's + \l{QDirModel::data()}{data()} function. We specify the model index and + the \l{Qt::ItemDataRole}{DisplayRole} to obtain data for the + item in the form of a string. + + \snippet doc/src/snippets/simplemodel-use/main.cpp 2 + \codeline + \snippet doc/src/snippets/simplemodel-use/main.cpp 3 + + The above example demonstrates the basic principles used to retrieve + data from a model: + + \list + \i The dimensions of a model can be found using + \l{QAbstractItemModel::rowCount()}{rowCount()} and + \l{QAbstractItemModel::columnCount()}{columnCount()}. + These functions generally require a parent model index to be + specified. + \i Model indexes are used to access items in the model. The row, column, + and parent model index are needed to specify the item. + \i To access top-level items in a model, specify a null model index + as the parent index with \c QModelIndex(). + \i Items contain data for different roles. To obtain the data for a + particular role, both the model index and the role must be supplied + to the model. + \endlist + + + \section1 Further Reading + + New models can be created by implementing the standard interface provided + by QAbstractItemModel. In the \l{Creating New Models} chapter, we will + demonstrate this by creating a convenient ready-to-use model for holding + lists of strings. +*/ + +/*! + \page model-view-view.html + \contentspage model-view-programming.html Contents + \previouspage Creating New Models + \nextpage Handling Selections in Item Views + + \title View Classes + + \tableofcontents + + \section1 Concepts + + In the model/view architecture, the view obtains items of data from the + model and presents them to the user. The way that the data is + presented need not resemble the representation of the data provided by + the model, and may be \e{completely different} from the underlying data + structure used to store items of data. + + The separation of content and presentation is achieved by the use of a + standard model interface provided by QAbstractItemModel, a standard view + interface provided by QAbstractItemView, and the use of model indexes + that represent items of data in a general way. + Views typically manage the overall layout of the data obtained from + models. They may render individual items of data themselves, or use + \l{Delegate Classes}{delegates} to handle both rendering and editing + features. + + As well as presenting data, views handle navigation between items, + and some aspects of item selection. The views also implement basic + user interface features, such as context menus and drag and drop. + A view can provide default editing facilities for items, or it may + work with a \l{Delegate Classes}{delegate} to provide a custom + editor. + + A view can be constructed without a model, but a model must be + provided before it can display useful information. Views keep track of + the items that the user has selected through the use of + \l{Handling Selections in Item Views}{selections} which can be maintained + separately for each view, or shared between multiple views. + + Some views, such as QTableView and QTreeView, display headers as well + as items. These are also implemented by a view class, QHeaderView. + Headers usually access the same model as the view that contains them. + They retrieve data from the model using the + \l{QAbstractItemModel::headerData()} function, and usually display + header information in the form of a label. New headers can be + subclassed from the QHeaderView class to provide more specialized + labels for views. + + \section1 Using an Existing View + + Qt provides three ready-to-use view classes that present data from + models in ways that are familiar to most users. + QListView can display items from a model as a simple list, or in the + form of a classic icon view. QTreeView displays items from a + model as a hierarchy of lists, allowing deeply nested structures to be + represented in a compact way. QTableView presents items from a model + in the form of a table, much like the layout of a spreadsheet + application. + + \img standard-views.png + + The default behavior of the standard views shown above should be + sufficient for most applications. They provide basic editing + facilities, and can be customized to suit the needs of more specialized + user interfaces. + + \section2 Using a Model + + We take the string list model that \l{Creating New Models}{we created as + an example model}, set it up with some data, and construct a view to + display the contents of the model. This can all be performed within a + single function: + + \snippet doc/src/snippets/stringlistmodel/main.cpp 0 + + Note that the \c StringListModel is declared as a \l QAbstractItemModel. + This allows us to use the abstract interface to the model, and + ensures that the code will still work even if we replace the string list + model with a different model in the future. + + The list view provided by \l QListView is sufficient for presenting + the items in the string list model. We construct the view, and set up + the model using the following lines of code: + + \snippet doc/src/snippets/stringlistmodel/main.cpp 2 + \snippet doc/src/snippets/stringlistmodel/main.cpp 4 + + The view is shown in the normal way: + + \snippet doc/src/snippets/stringlistmodel/main.cpp 5 + + The view renders the contents of a model, accessing data via the model's + interface. When the user tries to edit an item, the view uses a default + delegate to provide an editor widget. + + \img stringlistmodel.png + + The above image shows how a QListView represents the data in the string + list model. Since the model is editable, the view automatically allows + each item in the list to be edited using the default delegate. + + \section2 Using Multiple Views onto the Same Model + + Providing multiple views onto the same model is simply a matter of + setting the same model for each view. In the following code we create + two table views, each using the same simple table model which we have + created for this example: + + \snippet doc/src/snippets/sharedtablemodel/main.cpp 0 + \codeline + \snippet doc/src/snippets/sharedtablemodel/main.cpp 1 + + The use of signals and slots in the model/view architecture means that + changes to the model can be propagated to all the attached views, + ensuring that we can always access the same data regardless of the + view being used. + + \img sharedmodel-tableviews.png + + The above image shows two different views onto the same model, each + containing a number of selected items. Although the data from the model + is shown consistently across view, each view maintains its own internal + selection model. This can be useful in certain situations but, for + many applications, a shared selection model is desirable. + + \section1 Handling Selections of Items + + The mechanism for handling selections of items within views is provided + by the \l QItemSelectionModel class. All of the standard views construct + their own selection models by default, and interact with them in the + normal way. The selection model being used by a view can be obtained + through the \l{QAbstractItemView::selectionModel()}{selectionModel()} + function, and a replacement selection model can be specified with + \l{QAbstractItemView::setSelectionModel()}{setSelectionModel()}. + The ability to control the selection model used by a view is useful + when we want to provide multiple consistent views onto the same model + data. + + Generally, unless you are subclassing a model or view, you will not + need to manipulate the contents of selections directly. However, the + interface to the selection model can be accessed, if required, and + this is explored in the chapter on + \l{Handling Selections in Item Views}. + + \section2 Sharing Selections Between Views + + Although it is convenient that the view classes provide their own + selection models by default, when we use more than one view onto the + same model it is often desirable that both the model's data and the + user's selection are shown consistently in all views. + Since the view classes allow their internal selection models to be + replaced, we can achieve a unified selection between views with the + following line: + + \snippet doc/src/snippets/sharedtablemodel/main.cpp 2 + + The second view is given the selection model for the first view. + Both views now operate on the same selection model, keeping both + the data and the selected items synchronized. + + \img sharedselection-tableviews.png + + In the example shown above, two views of the same type were used to + display the same model's data. However, if two different types of view + were used, the selected items may be represented very differently in + each view; for example, a contiguous selection in a table view can be + represented as a fragmented set of highlighted items in a tree view. + +*/ + +/*! + \page model-view-delegate.html + \contentspage model-view-programming.html Contents + \previouspage Handling Selections in Item Views + \nextpage Item View Convenience Classes + + \title Delegate Classes + + \tableofcontents + + \section1 Concepts + + Unlike the Model-View-Controller pattern, the model/view design does not + include a completely separate component for managing interaction with + the user. Generally, the view is responsible for the presentation of + model data to the user, and for processing user input. To allow some + flexibility in the way this input is obtained, the interaction is + performed by delegates. These components provide input capabilities + and are also responsible for rendering individual items in some views. + The standard interface for controlling delegates is defined in the + \l QAbstractItemDelegate class. + + Delegates are expected to be able to render their contents themselves + by implementing the \l{QItemDelegate::paint()}{paint()} + and \l{QItemDelegate::sizeHint()}{sizeHint()} functions. + However, simple widget-based delegates can subclass \l QItemDelegate + instead of \l QAbstractItemDelegate, and take advantage of the default + implementations of these functions. + + Editors for delegates can be implemented either by using widgets to manage + the editing process or by handling events directly. + The first approach is covered later in this chapter, and it is also + shown in the \l{Spin Box Delegate Example}{Spin Box Delegate} example. + + The \l{Pixelator Example}{Pixelator} example shows how to create a + custom delegate that performs specialized rendering for a table view. + + \section1 Using an Existing Delegate + + The standard views provided with Qt use instances of \l QItemDelegate + to provide editing facilities. This default implementation of the + delegate interface renders items in the usual style for each of the + standard views: \l QListView, \l QTableView, and \l QTreeView. + + All the standard roles are handled by the default delegate used by + the standard views. The way these are interpreted is described in the + QItemDelegate documentation. + + The delegate used by a view is returned by the + \l{QAbstractItemView::itemDelegate()}{itemDelegate()} function. + The \l{QAbstractItemView::setItemDelegate()}{setItemDelegate()} function + allows you to install a custom delegate for a standard view, and it is + necessary to use this function when setting the delegate for a custom + view. + + \section1 A Simple Delegate + + The delegate implemented here uses a \l QSpinBox to provide editing + facilities, and is mainly intended for use with models that display + integers. Although we set up a custom integer-based table model for + this purpose, we could easily have used \l QStandardItemModel instead + since the custom delegate will control data entry. We construct a + table view to display the contents of the model, and this will use + the custom delegate for editing. + + \img spinboxdelegate-example.png + + We subclass the delegate from \l QItemDelegate because we do not want + to write custom display functions. However, we must still provide + functions to manage the editor widget: + + \snippet examples/itemviews/spinboxdelegate/delegate.h 0 + + Note that no editor widgets are set up when the delegate is + constructed. We only construct an editor widget when it is needed. + + \section2 Providing an Editor + + In this example, when the table view needs to provide an editor, it + asks the delegate to provide an editor widget that is appropriate + for the item being modified. The + \l{QAbstractItemDelegate::createEditor()}{createEditor()} function is + supplied with everything that the delegate needs to be able to set up + a suitable widget: + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 1 + + Note that we do not need to keep a pointer to the editor widget because + the view takes responsibility for destroying it when it is no longer + needed. + + We install the delegate's default event filter on the editor to ensure + that it provides the standard editing shortcuts that users expect. + Additional shortcuts can be added to the editor to allow more + sophisticated behavior; these are discussed in the section on + \l{#EditingHints}{Editing Hints}. + + The view ensures that the editor's data and geometry are set + correctly by calling functions that we define later for these purposes. + We can create different editors depending on the model index supplied + by the view. For example, if we have a column of integers and a column + of strings we could return either a \c QSpinBox or a \c QLineEdit, + depending on which column is being edited. + + The delegate must provide a function to copy model data into the + editor. In this example, we read the data stored in the + \l{Qt::ItemDataRole}{display role}, and set the value in the + spin box accordingly. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 2 + + In this example, we know that the editor widget is a spin box, but we + could have provided different editors for different types of data in + the model, in which case we would need to cast the widget to the + appropriate type before accessing its member functions. + + \section2 Submitting Data to the Model + + When the user has finished editing the value in the spin box, the view + asks the delegate to store the edited value in the model by calling the + \l{QAbstractItemDelegate::setModelData()}{setModelData()} function. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 3 + + Since the view manages the editor widgets for the delegate, we only + need to update the model with the contents of the editor supplied. + In this case, we ensure that the spin box is up-to-date, and update + the model with the value it contains using the index specified. + + The standard \l QItemDelegate class informs the view when it has + finished editing by emitting the + \l{QAbstractItemDelegate::closeEditor()}{closeEditor()} signal. + The view ensures that the editor widget is closed and destroyed. In + this example, we only provide simple editing facilities, so we need + never emit this signal. + + All the operations on data are performed through the interface + provided by \l QAbstractItemModel. This makes the delegate mostly + independent from the type of data it manipulates, but some + assumptions must be made in order to use certain types of + editor widgets. In this example, we have assumed that the model + always contains integer values, but we can still use this + delegate with different kinds of models because \l{QVariant} + provides sensible default values for unexpected data. + + \section2 Updating the Editor's Geometry + + It is the responsibility of the delegate to manage the editor's + geometry. The geometry must be set when the editor is created, and + when the item's size or position in the view is changed. Fortunately, + the view provides all the necessary geometry information inside a + \l{QStyleOptionViewItem}{view option} object. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 4 + + In this case, we just use the geometry information provided by the + view option in the item rectangle. A delegate that renders items with + several elements would not use the item rectangle directly. It would + position the editor in relation to the other elements in the item. + + \target EditingHints + \section2 Editing Hints + + After editing, delegates should provide hints to the other components + about the result of the editing process, and provide hints that will + assist any subsequent editing operations. This is achieved by + emitting the \l{QAbstractItemDelegate::closeEditor()}{closeEditor()} + signal with a suitable hint. This is taken care of by the default + QItemDelegate event filter which we installed on the spin box when + it was constructed. + + The behavior of the spin box could be adjusted to make it more user + friendly. In the default event filter supplied by QItemDelegate, if + the user hits \key Return to confirm their choice in the spin box, + the delegate commits the value to the model and closes the spin box. + We can change this behavior by installing our own event filter on the + spin box, and provide editing hints that suit our needs; for example, + we might emit \l{QAbstractItemDelegate::closeEditor()}{closeEditor()} + with the \l{QAbstractItemDelegate::EndEditHint}{EditNextItem} hint to + automatically start editing the next item in the view. + + Another approach that does not require the use of an event + filter is to provide our own editor widget, perhaps subclassing + QSpinBox for convenience. This alternative approach would give us + more control over how the editor widget behaves at the cost of + writing additional code. It is usually easier to install an event + filter in the delegate if you need to customize the behavior of + a standard Qt editor widget. + + Delegates do not have to emit these hints, but those that do not will + be less integrated into applications, and will be less usable than + those that emit hints to support common editing actions. +*/ + +/*! + \page model-view-selection.html + \contentspage model-view-programming.html Contents + \previouspage View Classes + \nextpage Delegate Classes + + \title Handling Selections in Item Views + + \tableofcontents + + \section1 Concepts + + The selection model used in the new item view classes offers many + improvements over the selection model used in Qt 3. It provides a + more general description of selections based on the facilities of + the model/view architecture. Although the standard classes for + manipulating selections are sufficient for the item views provided, + the selection model allows you to create specialized selection models + to suit the requirements for your own item models and views. + + Information about the items selected in a view is stored in an instance + of the \l QItemSelectionModel class. This maintains model indexes for + items in a single model, and is independent of any views. Since there + can be many views onto a model, it is possible to share selections + between views, allowing applications to show multiple views in a + consistent way. + + Selections are made up of \e{selection ranges}. These efficiently + maintain information about large selections of items by recording + only the starting and ending model indexes for each range of selected + items. Non-contiguous selections of items are constructed by using + more than one selection range to describe the selection. + + Selections are applied to a collection of model indexes held by + a selection model. The most recent selection of items applied is + known as the \e{current selection}. The effects of this selection can + be modified even after its application through the use of certain + types of selection commands. These are discussed later in this + section. + + When manipulating selections, it is often helpful to think of + \l QItemSelectionModel as a record of the selection state of all the + items in an item model. Once a selection model is set up, collections + of items can be selected, deselected, or their selection states can + be toggled without the need to know which items are already selected. + The indexes of all selected items can be retrieved at any time, and + other components can be informed of changes to the selection model + via the signals and slots mechanism. + + + \section1 Using a Selection Model + + The standard view classes provide default selection models that can + be used in most applications. A selection model belonging to one view + can be obtained using the view's + \l{QAbstractItemView::selectionModel()}{selectionModel()} function, + and shared between many views with + \l{QAbstractItemView::setSelectionModel()}{setSelectionModel()}, + so the construction of new selection models is generally not required. + + A selection is created by specifying a model, and a pair of model + indexes to a \l QItemSelection. This uses the indexes to refer to items + in the given model, and interprets them as the top-left and bottom-right + items in a block of selected items. + To apply the selection to items in a model requires the selection to be + submitted to a selection model; this can be achieved in a number of ways, + each having a different effect on the selections already present in the + selection model. + + + \section2 Selecting Items + + To demonstrate some of the principal features of selections, we construct + an instance of a custom table model with 32 items in total, and open a + table view onto its data: + + \snippet doc/src/snippets/itemselection/main.cpp 0 + + The table view's default selection model is retrieved for later use. + We do not modify any items in the model, but instead select a few + items that the view will display at the top-left of the table. To do + this, we need to retrieve the model indexes corresponding to the + top-left and bottom-right items in the region to be selected: + + \snippet doc/src/snippets/itemselection/main.cpp 1 + + To select these items in the model, and see the corresponding change + in the table view, we need to construct a selection object then apply + it to the selection model: + + \snippet doc/src/snippets/itemselection/main.cpp 2 + + The selection is applied to the selection model using a command + defined by a combination of + \l{QItemSelectionModel::SelectionFlag}{selection flags}. + In this case, the flags used cause the items recorded in the + selection object to be included in the selection model, regardless + of their previous state. The resulting selection is shown by the view. + + \img selected-items1.png + + The selection of items can be modified using various operations that + are defined by the selection flags. The selection that results from + these operations may have a complex structure, but will be represented + efficiently by the selection model. The use of different selection + flags to manipulate the selected items is described when we examine + how to update a selection. + + \section2 Reading the Selection State + + The model indexes stored in the selection model can be read using + the \l{QItemSelectionModel::selectedIndexes()}{selectedIndexes()} + function. This returns an unsorted list of model indexes that we can + iterate over as long as we know which model they are for: + + \snippet doc/src/snippets/reading-selections/window.cpp 0 + + The above code uses Qt's convenient \l{Generic Containers}{foreach + keyword} to iterate over, and modify, the items corresponding to the + indexes returned by the selection model. + + The selection model emits signals to indicate changes in the + selection. These notify other components about changes to both the + selection as a whole and the currently focused item in the item + model. We can connect the + \l{QItemSelectionModel::selectionChanged()}{selectionChanged()} + signal to a slot, and examine the items in the model that are selected or + deselected when the selection changes. The slot is called with two + \l{QItemSelection} objects: one contains a list of indexes that + correspond to newly selected items; the other contains indexes that + correspond to newly deselected items. + + In the following code, we provide a slot that receives the + \l{QItemSelectionModel::selectionChanged()}{selectionChanged()} + signal, fills in the selected items with + a string, and clears the contents of the deselected items. + + \snippet doc/src/snippets/updating-selections/window.cpp 0 + \snippet doc/src/snippets/updating-selections/window.cpp 1 + \codeline + \snippet doc/src/snippets/updating-selections/window.cpp 2 + + We can keep track of the currently focused item by connecting the + \l{QItemSelectionModel::currentChanged()}{currentChanged()} signal + to a slot that is called with two model indexes. These correspond to + the previously focused item, and the currently focused item. + + In the following code, we provide a slot that receives the + \l{QItemSelectionModel::currentChanged()}{currentChanged()} signal, + and uses the information provided to update the status bar of a + \l QMainWindow: + + \snippet doc/src/snippets/updating-selections/window.cpp 3 + + Monitoring selections made by the user is straightforward with these + signals, but we can also update the selection model directly. + + \section2 Updating a Selection + + Selection commands are provided by a combination of selection flags, + defined by \l{QItemSelectionModel::SelectionFlag}. + Each selection flag tells the selection model how to update its + internal record of selected items when either of the + \l{QItemSelection::select()}{select()} functions are called. + The most commonly used flag is the + \l{QItemSelectionModel::SelectionFlag}{Select} flag + which instructs the selection model to record the specified items as + being selected. The + \l{QItemSelectionModel::SelectionFlag}{Toggle} flag causes the + selection model to invert the state of the specified items, + selecting any deselected items given, and deselecting any currently + selected items. The \l{QItemSelectionModel::SelectionFlag}{Deselect} + flag deselects all the specified items. + + Individual items in the selection model are updated by creating a + selection of items, and applying them to the selection model. In the + following code, we apply a second selection of items to the table + model shown above, using the + \l{QItemSelectionModel::SelectionFlag}{Toggle} command to invert the + selection state of the items given. + + \snippet doc/src/snippets/itemselection/main.cpp 3 + + The results of this operation are displayed in the table view, + providing a convenient way of visualizing what we have achieved: + + \img selected-items2.png + + By default, the selection commands only operate on the individual + items specified by the model indexes. However, the flag used to + describe the selection command can be combined with additional flags + to change entire rows and columns. For example if you call + \l{QItemSelectionModel::select()}{select()} with only one index, but + with a command that is a combination of + \l{QItemSelectionModel::SelectionFlag}{Select} and + \l{QItemSelectionModel::SelectionFlag}{Rows}, the + entire row containing the item referred to will be selected. + The following code demonstrates the use of the + \l{QItemSelectionModel::SelectionFlag}{Rows} and + \l{QItemSelectionModel::SelectionFlag}{Columns} flags: + + \snippet doc/src/snippets/itemselection/main.cpp 4 + + Although only four indexes are supplied to the selection model, the + use of the + \l{QItemSelectionModel::SelectionFlag}{Columns} and + \l{QItemSelectionModel::SelectionFlag}{Rows} selection flags means + that two columns and two rows are selected. The following image shows + the result of these two selections: + + \img selected-items3.png + + The commands performed on the example model have all involved + accumulating a selection of items in the model. It is also possible + to clear the selection, or to replace the current selection with + a new one. + + To replace the current selection with a new selection, combine + the other selection flags with the + \l{QItemSelectionModel::SelectionFlag}{Current} flag. A command using + this flag instructs the selection model to replace its current collection + of model indexes with those specified in a call to + \l{QItemSelectionModel::select()}{select()}. + To clear all selections before you start adding new ones, + combine the other selection flags with the + \l{QItemSelectionModel::SelectionFlag}{Clear} flag. This + has the effect of resetting the selection model's collection of model + indexes. + + \section2 Selecting All Items in a Model + + To select all items in a model, it is necessary to create a + selection for each level of the model that covers all items in that + level. We do this by retrieving the indexes corresponding to the + top-left and bottom-right items with a given parent index: + + \snippet doc/src/snippets/reading-selections/window.cpp 2 + + A selection is constructed with these indexes and the model. The + corresponding items are then selected in the selection model: + + \snippet doc/src/snippets/reading-selections/window.cpp 3 + + This needs to be performed for all levels in the model. + For top-level items, we would define the parent index in the usual way: + + \snippet doc/src/snippets/reading-selections/window.cpp 1 + + For hierarchical models, the + \l{QAbstractItemModel::hasChildren()}{hasChildren()} function is used to + determine whether any given item is the parent of another level of + items. +*/ + +/*! + \page model-view-creating-models.html + \contentspage model-view-programming.html Contents + \previouspage Model Classes + \nextpage View Classes + + \title Creating New Models + + \tableofcontents + + \section1 Introduction + + The separation of functionality between the model/view components allows + models to be created that can take advantage of existing views. This + approach lets us present data from a variety of sources using standard + graphical user interface components, such as QListView, QTableView, and + QTreeView. + + The QAbstractItemModel class provides an interface that is flexible + enough to support data sources that arrange information in hierarchical + structures, allowing for the possibility that data will be inserted, + removed, modified, or sorted in some way. It also provides support for + drag and drop operations. + + The QAbstractListModel and QAbstractTableModel classes provide support + for interfaces to simpler non-hierarchical data structures, and are + easier to use as a starting point for simple list and table models. + + In this chapter, we create a simple read-only model to explore + the basic principles of the model/view architecture. Later in this + chapter, we will adapt this simple model so that items can be modified + by the user. + + For an example of a more complex model, see the + \l{itemviews/simpletreemodel}{Simple Tree Model} example. + + The requirements of QAbstractItemModel subclasses is described in more + detail in the \l{Model Subclassing Reference} document. + + \section1 Designing a Model + + When creating a new model for an existing data structure, it is important + to consider which type of model should be used to provide an interface + onto the data. If the data structure can be represented as a + list or table of items, you can subclass QAbstractListModel or + QAbstractTableModel since these classes provide suitable default + implementations for many functions. + + However, if the underlying data structure can only be represented by a + hierarchical tree structure, it is necessary to subclass + QAbstractItemModel. This approach is taken in the + \l{itemviews/simpletreemodel}{Simple Tree Model} example. + + In this chapter, we will implement a simple model based on a list of + strings, so the QAbstractListModel provides an ideal base class on + which to build. + + Whatever form the underlying data structure takes, it is + usually a good idea to supplement the standard QAbstractItemModel API + in specialized models with one that allows more natural access to the + underlying data structure. This makes it easier to populate the model + with data, yet still enables other general model/view components to + interact with it using the standard API. The model described below + provides a custom constructor for just this purpose. + + \section1 A Read-Only Example Model + + The model implemented here is a simple, non-hierarchical, read-only data + model based on the standard QStringListModel class. It has a \l QStringList + as its internal data source, and implements only what is needed to make a + functioning model. To make the implementation easier, we subclass + \l QAbstractListModel because it defines sensible default behavior for list + models, and it exposes a simpler interface than the \l QAbstractItemModel + class. + + When implementing a model it is important to remember that + \l QAbstractItemModel does not store any data itself, it merely + presents an interface that the views use to access the data. + For a minimal read-only model it is only necessary to implement a few + functions as there are default implementations for most of the + interface. The class declaration is as follows: + + + \snippet doc/src/snippets/stringlistmodel/model.h 0 + \snippet doc/src/snippets/stringlistmodel/model.h 1 + \codeline + \snippet doc/src/snippets/stringlistmodel/model.h 5 + + Apart from the model's constructor, we only need to implement two + functions: \l{QAbstractItemModel::rowCount()}{rowCount()} returns the + number of rows in the model and \l{QAbstractItemModel::data()}{data()} + returns an item of data corresponding to a specified model index. + + Well behaved models also implement + \l{QAbstractItemModel::headerData()}{headerData()} to give tree and + table views something to display in their headers. + + Note that this is a non-hierarchical model, so we don't have to worry + about the parent-child relationships. If our model was hierarchical, we + would also have to implement the + \l{QAbstractItemModel::index()}{index()} and + \l{QAbstractItemModel::parent()}{parent()} functions. + + The list of strings is stored internally in the \c stringList private + member variable. + + \section2 Dimensions of The Model + + We want the number of rows in the model to be the same as the number of + strings in the string list. We implement the + \l{QAbstractItemModel::rowCount()}{rowCount()} function with this in + mind: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 0 + + Since the model is non-hierarchical, we can safely ignore the model index + corresponding to the parent item. By default, models derived from + QAbstractListModel only contain one column, so we do not need to + reimplement the \l{QAbstractItemModel::columnCount()}{columnCount()} + function. + + \section2 Model Headers and Data + + For items in the view, we want to return the strings in the string list. + The \l{QAbstractItemModel::data()}{data()} function is responsible for + returning the item of data that corresponds to the index argument: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 1 + + We only return a valid QVariant if the model index supplied is valid, + the row number is within the range of items in the string list, and the + requested role is one that we support. + + Some views, such as QTreeView and QTableView, are able to display headers + along with the item data. If our model is displayed in a view with headers, + we want the headers to show the row and column numbers. We can provide + information about the headers by subclassing the + \l{QAbstractItemModel::headerData()}{headerData()} function: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 2 + + Again, we return a valid QVariant only if the role is one that we support. + The orientation of the header is also taken into account when deciding the + exact data to return. + + Not all views display headers with the item data, and those that do may + be configured to hide them. Nonetheless, it is recommended that you + implement the \l{QAbstractItemModel::headerData()}{headerData()} function + to provide relevant information about the data provided by the model. + + An item can have several roles, giving out different data depending on the + role specified. The items in our model only have one role, + \l{Qt::ItemDataRole}{DisplayRole}, so we return the data + for items irrespective of the role specified. + However, we could reuse the data we provide for the + \l{Qt::ItemDataRole}{DisplayRole} in + other roles, such as the + \l{Qt::ItemDataRole}{ToolTipRole} that views can use to + display information about items in a tooltip. + + \section1 An Editable Model + + The read-only model shows how simple choices could be presented to the + user but, for many applications, an editable list model is much more + useful. We can modify the read-only model to make the items editable + by implementing two extra functions: + \l{QAbstractItemModel::flags()}{flags()} and + \l{QAbstractItemModel::setData()}{setData()}. + The following function declarations are added to the class definition: + + \snippet doc/src/snippets/stringlistmodel/model.h 2 + \snippet doc/src/snippets/stringlistmodel/model.h 3 + + \section2 Making the Model Editable + + A delegate checks whether an item is editable before creating an + editor. The model must let the delegate know that its items are + editable. We do this by returning the correct flags for each item in + the model; in this case, we enable all items and make them both + selectable and editable: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 3 + + Note that we do not have to know how the delegate performs the actual + editing process. We only have to provide a way for the delegate to set the + data in the model. This is achieved through the + \l{QAbstractItemModel::setData()}{setData()} function: + + \snippet doc/src/snippets/stringlistmodel/model.cpp 4 + \snippet doc/src/snippets/stringlistmodel/model.cpp 5 + + In this model, the item in the string list that corresponds to the + model index is replaced by the value provided. However, before we + can modify the string list, we must make sure that the index is + valid, the item is of the correct type, and that the role is + supported. By convention, we insist that the role is the + \l{Qt::ItemDataRole}{EditRole} since this is the role used by the + standard item delegate. For boolean values, however, you can use + Qt::CheckStateRole and set the Qt::ItemIsUserCheckable flag; a + checkbox will then be used for editing the value. The underlying + data in this model is the same for all roles, so this detail just + makes it easier to integrate the model with standard components. + + When the data has been set, the model must let the views know that some + data has changed. This is done by emitting the + \l{QAbstractItemModel::dataChanged()}{dataChanged()} signal. Since only + one item of data has changed, the range of items specified in the signal + is limited to just one model index. + + \section2 Inserting and Removing Rows + + It is possible to change the number of rows and columns in a model. In the + string list model it only makes sense to change the number of rows, so we + only reimplement the functions for inserting and removing rows. These are + declared in the class definition: + + \snippet doc/src/snippets/stringlistmodel/model.h 4 + + Since rows in this model correspond to strings in a list, the + \c insertRows() function inserts a number of empty strings into the string + list before the specified position. The number of strings inserted is + equivalent to the number of rows specified. + + The parent index is normally used to determine where in the model the + rows should be added. In this case, we only have a single top-level list + of strings, so we just insert empty strings into that list. + + \snippet doc/src/snippets/stringlistmodel/model.cpp 6 + \snippet doc/src/snippets/stringlistmodel/model.cpp 7 + + The model first calls the + \l{QAbstractItemModel::beginInsertRows()}{beginInsertRows()} function to + inform other components that the number of rows is about to change. The + function specifies the row numbers of the first and last new rows to be + inserted, and the model index for their parent item. After changing the + string list, it calls + \l{QAbstractItemModel::endInsertRows()}{endInsertRows()} to complete the + operation and inform other components that the dimensions of the model + have changed, returning true to indicate success. + + The function to remove rows from the model is also simple to write. + The rows to be removed from the model are specified by the position and + the number of rows given. + We ignore the parent index to simplify our implementation, and just + remove the corresponding items from the string list. + + \snippet doc/src/snippets/stringlistmodel/model.cpp 8 + \snippet doc/src/snippets/stringlistmodel/model.cpp 9 + + The \l{QAbstractItemModel::beginRemoveRows()}{beginRemoveRows()} function + is always called before any underlying data is removed, and specifies the + first and last rows to be removed. This allows other components to access + the data before it becomes unavailable. + After the rows have been removed, the model emits + \l{QAbstractItemModel::endRemoveRows()}{endRemoveRows()} to finish the + operation and let other components know that the dimensions of the model + have changed. + + \section1 Next Steps + + We can display the data provided by this model, or any other model, using + the \l QListView class to present the model's items in the form of a vertical + list. + For the string list model, this view also provides a default editor so that + the items can be manipulated. We examine the possibilities made available by + the standard view classes in the chapter on \l{View Classes}. + + The \l{Model Subclassing Reference} document discusses the requirements of + QAbstractItemModel subclasses in more detail, and provides a guide to the + virtual functions that must be implemented to enable various features in + different types of models. +*/ + +/*! + \page model-view-convenience.html + \contentspage model-view-programming.html Contents + \previouspage Delegate Classes + \nextpage Using Drag and Drop with Item Views + + \title Item View Convenience Classes + + \tableofcontents + + \section1 Overview + + Alongside the model/view classes, Qt 4 also includes standard widgets to + provide classic item-based container widgets. These behave in a similar + way to the item view classes in Qt 3, but have been rewritten to use the + underlying model/view framework for performance and maintainability. The + old item view classes are still available in the compatibility library + (see the \l{porting4.html}{Porting Guide} for more information). + + The item-based widgets have been given names which reflect their uses: + \c QListWidget provides a list of items, \c QTreeWidget displays a + multi-level tree structure, and \c QTableWidget provides a table of cell + items. Each class inherits the behavior of the \c QAbstractItemView + class which implements common behavior for item selection and header + management. + + \section1 List Widgets + + Single level lists of items are typically displayed using a \c QListWidget + and a number of \c{QListWidgetItem}s. A list widget is constructed in the + same way as any other widget: + + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 0 + + List items can be added directly to the list widget when they are + constructed: + + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 3 + + They can also be constructed without a parent list widget and added to + a list at some later time: + + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 6 + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 7 + + Each item in a list can display a text label and an icon. The colors + and font used to render the text can be changed to provide a customized + appearance for items. Tooltips, status tips, and "What's + This?" help are all easily configured to ensure that the list is properly + integrated into the application. + + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 8 + + By default, items in a list are presented in the order of their creation. + Lists of items can be sorted according to the criteria given in + \l{Qt::SortOrder} to produce a list of items that is sorted in forward or + reverse alphabetical order: + + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 4 + \snippet doc/src/snippets/qlistwidget-using/mainwindow.cpp 5 + + + \section1 Tree Widgets + + Trees or hierarchical lists of items are provided by the \c QTreeWidget + and \c QTreeWidgetItem classes. Each item in the tree widget can have + child items of its own, and can display a number of columns of + information. Tree widgets are created just like any other widget: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 0 + + Before items can be added to the tree widget, the number of columns must + be set. For example, we could define two columns, and create a header + to provide labels at the top of each column: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 1 + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 2 + + The easiest way to set up the labels for each section is to supply a string + list. For more sophisticated headers, you can construct a tree item, + decorate it as you wish, and use that as the tree widget's header. + + Top-level items in the tree widget are constructed with the tree widget as + their parent widget. They can be inserted in an arbitrary order, or you + can ensure that they are listed in a particular order by specifying the + previous item when constructing each item: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 3 + \codeline + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 4 + + Tree widgets deal with top-level items slightly differently to other + items from deeper within the tree. Items can be removed from the top + level of the tree by calling the tree widget's + \l{QTreeWidget::takeTopLevelItem()}{takeTopLevelItem()} function, but + items from lower levels are removed by calling their parent item's + \l{QTreeWidgetItem::takeChild()}{takeChild()} function. + Items are inserted in the top level of the tree with the + \l{QTreeWidget::insertTopLevelItem()}{insertTopLevelItem()} function. + At lower levels in the tree, the parent item's + \l{QTreeWidgetItem::insertChild()}{insertChild()} function is used. + + It is easy to move items around between the top level and lower levels + in the tree. We just need to check whether the items are top-level items + or not, and this information is supplied by each item's \c parent() + function. For example, we can remove the current item in the tree widget + regardless of its location: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 10 + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 11 + + Inserting the item somewhere else in the tree widget follows the same + pattern: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 8 + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 9 + + + \section1 Table Widgets + + Tables of items similar to those found in spreadsheet applications + are constructed with the \c QTableWidget and \c QTableWidgetItem. These + provide a scrolling table widget with headers and items to use within it. + + Tables can be created with a set number of rows and columns, or these + can be added to an unsized table as they are needed. + + \snippet doc/src/snippets/qtablewidget-using/mainwindow.h 0 + \snippet doc/src/snippets/qtablewidget-using/mainwindow.cpp 0 + + Items are constructed outside the table before being added to the table + at the required location: + + \snippet doc/src/snippets/qtablewidget-using/mainwindow.cpp 3 + + Horizontal and vertical headers can be added to the table by constructing + items outside the table and using them as headers: + + \snippet doc/src/snippets/qtablewidget-using/mainwindow.cpp 1 + + Note that the rows and columns in the table begin at zero. + + \section1 Common Features + + There are a number of item-based features common to each of the + convenience classes that are available through the same interfaces + in each class. We present these in the following sections with some + examples for different widgets. + Look at the list of \l{Model/View Classes} for each of the widgets + for more details about the use of each function used. + + \section2 Hidden Items + + It is sometimes useful to be able to hide items in an item view widget + rather than remove them. Items for all of the above widgets can be + hidden and later shown again. You can determine whether an item is hidden + by calling the isItemHidden() function, and items can be hidden with + \c setItemHidden(). + + Since this operation is item-based, the same function is available for + all three convenience classes. + + \section2 Selections + + The way items are selected is controlled by the widget's selection mode + (\l{QAbstractItemView::SelectionMode}). + This property controls whether the user can select one or many items and, + in many-item selections, whether the selection must be a continuous range + of items. The selection mode works in the same way for all of the + above widgets. + + \table + \row + \i \img selection-single.png + \i \bold{Single item selections:} + Where the user needs to choose a single item from a widget, the + default \c SingleSelection mode is most suitable. In this mode, the + current item and the selected item are the same. + + \row + \i \img selection-multi.png + \i \bold{Multi-item selections:} + In this mode, the user can toggle the selection state of any item in the + widget without changing the existing selection, much like the way + non-exclusive checkboxes can be toggled independently. + + \row + \i \img selection-extended.png + \i \bold{Extended selections:} + Widgets that often require many adjacent items to be selected, such + as those found in spreadsheets, require the \c ExtendedSelection mode. + In this mode, continuous ranges of items in the widget can be selected + with both the mouse and the keyboard. + Complex selections, involving many items that are not adjacent to other + selected items in the widget, can also be created if modifier keys are + used. + + If the user selects an item without using a modifier key, the existing + selection is cleared. + \endtable + + The selected items in a widget are read using the \c selectedItems() + function, providing a list of relevant items that can be iterated over. + For example, we can find the sum of all the numeric values within a + list of selected items with the following code: + + \snippet doc/src/snippets/qtablewidget-using/mainwindow.cpp 4 + + Note that for the single selection mode, the current item will be in + the selection. In the multi-selection and extended selection modes, the + current item may not lie within the selection, depending on the way the + user formed the selection. + + \section2 Searching + + It is often useful to be able to find items within an item view widget, + either as a developer or as a service to present to users. All three + item view convenience classes provide a common \c findItems() function + to make this as consistent and simple as possible. + + Items are searched for by the text that they contain according to + criteria specified by a selection of values from Qt::MatchFlags. + We can obtain a list of matching items with the \c findItems() + function: + + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 6 + \snippet doc/src/snippets/qtreewidget-using/mainwindow.cpp 7 + + The above code causes items in a tree widget to be selected if they + contain the text given in the search string. This pattern can also be + used in the list and table widgets. +*/ + +/*! + \page model-view-dnd.html + \contentspage model-view-programming.html Contents + \previouspage Item View Convenience Classes + \nextpage Proxy Models + + \title Using Drag and Drop with Item Views + + \tableofcontents + + \section1 Overview + + Qt's drag and drop infrastructure is fully supported by the model/view framework. + Items in lists, tables, and trees can be dragged within the views, and data can be + imported and exported as MIME-encoded data. + + The standard views automatically support internal drag and drop, where items are + moved around to change the order in which they are displayed. By default, drag and + drop is not enabled for these views because they are configured for the simplest, + most common uses. To allow items to be dragged around, certain properties of the + view need to be enabled, and the items themselves must also allow dragging to occur. + + The requirements for a model that only allows items to be exported from a + view, and which does not allow data to be dropped into it, are fewer than + those for a fully-enabled drag and drop model. + + See also the \l{Model Subclassing Reference} for more information about + enabling drag and drop support in new models. + + \section1 Using Convenience Views + + Each of the types of item used with QListWidget, QTableWidget, and QTreeWidget + is configured to use a different set of flags by default. For example, each + QListWidgetItem or QTreeWidgetItem is initially enabled, checkable, selectable, + and can be used as the source of a drag and drop operation; each QTableWidgetItem + can also be edited and used as the target of a drag and drop operation. + + Although all of the standard items have one or both flags set for drag and drop, + you generally need to set various properties in the view itself to take advantage + of the built-in support for drag and drop: + + \list + \o To enable item dragging, set the view's + \l{QAbstractItemView::dragEnabled}{dragEnabled} property to \c true. + \o To allow the user to drop either internal or external items within the view, + set the view's \l{QAbstractScrollArea::}{viewport()}'s + \l{QWidget::acceptDrops}{acceptDrops} property to \c true. + \o To show the user where the item currently being dragged will be placed if + dropped, set the view's \l{QAbstractItemView::showDropIndicator}{showDropIndicator} + property. This provides the user with continuously updating information about + item placement within the view. + \endlist + + For example, we can enable drag and drop in a list widget with the following lines + of code: + + \snippet doc/src/snippets/qlistwidget-dnd/mainwindow.cpp 0 + + The result is a list widget which allows the items to be copied + around within the view, and even lets the user drag items between + views containing the same type of data. In both situations, the + items are copied rather than moved. + + To enable the user to move the items around within the view, we + must set the list widget's \l {QAbstractItemView::}{dragDropMode}: + + \snippet doc/src/snippets/qlistwidget-dnd/mainwindow.cpp 1 + + \section1 Using Model/View Classes + + Setting up a view for drag and drop follows the same pattern used with the + convenience views. For example, a QListView can be set up in the same way as a + QListWidget: + + \snippet doc/src/snippets/qlistview-dnd/mainwindow.cpp 0 + + Since access to the data displayed by the view is controlled by a model, the + model used also has to provide support for drag and drop operations. The + actions supported by a model can be specified by reimplementing the + QAbstractItemModel::supportedDropActions() function. For example, copy and + move operations are enabled with the following code: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 10 + + Although any combination of values from Qt::DropActions can be given, the + model needs to be written to support them. For example, to allow Qt::MoveAction + to be used properly with a list model, the model must provide an implementation + of QAbstractItemModel::removeRows(), either directly or by inheriting the + implementation from its base class. + + \section2 Enabling Drag and Drop for Items + + Models indicate to views which items can be dragged, and which will accept drops, + by reimplementing the QAbstractItemModel::flags() function to provide suitable + flags. + + For example, a model which provides a simple list based on QAbstractListModel + can enable drag and drop for each of the items by ensuring that the flags + returned contain the \l Qt::ItemIsDragEnabled and \l Qt::ItemIsDropEnabled + values: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 7 + + Note that items can be dropped into the top level of the model, but dragging is + only enabled for valid items. + + In the above code, since the model is derived from QStringListModel, we + obtain a default set of flags by calling its implementation of the flags() + function. + + \section2 Encoding Exported Data + + When items of data are exported from a model in a drag and drop operation, they + are encoded into an appropriate format corresponding to one or more MIME types. + Models declare the MIME types that they can use to supply items by reimplementing + the QAbstractItemModel::mimeTypes() function, returning a list of standard MIME + types. + + For example, a model that only provides plain text would provide the following + implementation: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 9 + + The model must also provide code to encode data in the advertised format. This + is achieved by reimplementing the QAbstractItemModel::mimeData() function to + provide a QMimeData object, just as in any other drag and drop operation. + + The following code shows how each item of data, corresponding to a given list of + indexes, is encoded as plain text and stored in a QMimeData object. + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 8 + + Since a list of model indexes is supplied to the function, this approach is general + enough to be used in both hierarchical and non-heirarchical models. + + Note that custom datatypes must be declared as \l{QMetaObject}{meta objects} + and that stream operators must be implemented for them. See the QMetaObject + class description for details. + + \section2 Inserting Dropped Data into a Model + + The way that any given model handles dropped data depends on both its type + (list, table, or tree) and the way its contents is likely to be presented to + the user. Generally, the approach taken to accommodate dropped data should + be the one that most suits the model's underlying data store. + + Different types of model tend to handle dropped data in different ways. List + and table models only provide a flat structure in which items of data are + stored. As a result, they may insert new rows (and columns) when data is + dropped on an existing item in a view, or they may overwrite the item's + contents in the model using some of the data supplied. Tree models are + often able to add child items containing new data to their underlying data + stores, and will therefore behave more predictably as far as the user + is concerned. + + Dropped data is handled by a model's reimplementation of + QAbstractItemModel::dropMimeData(). For example, a model that handles a + simple list of strings can provide an implementation that handles data + dropped onto existing items separately to data dropped into the top level + of the model (i.e., onto an invalid item). + + The model first has to make sure that the operation should be acted on, + the data supplied is in a format that can be used, and that its destination + within the model is valid: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 0 + \snippet doc/src/snippets/qlistview-dnd/model.cpp 1 + + A simple one column string list model can indicate failure if the data + supplied is not plain text, or if the column number given for the drop + is invalid. + + The data to be inserted into the model is treated differently depending on + whether it is dropped onto an existing item or not. In this simple example, + we want to allow drops between existing items, before the first item in the + list, and after the last item. + + When a drop occurs, the model index corresponding to the parent item will + either be valid, indicating that the drop occurred on an item, or it will + be invalid, indicating that the drop occurred somewhere in the view that + corresponds to top level of the model. + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 2 + + We initially examine the row number supplied to see if we can use it + to insert items into the model, regardless of whether the parent index is + valid or not. + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 3 + + If the parent model index is valid, the drop occurred on an item. In this + simple list model, we find out the row number of the item and use that + value to insert dropped items into the top level of the model. + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 4 + + When a drop occurs elsewhere in the view, and the row number is unusable, + we append items to the top level of the model. + + In hierarchical models, when a drop occurs on an item, it would be better to + insert new items into the model as children of that item. In the simple + example shown here, the model only has one level, so this approach is not + appropriate. + + \section2 Decoding Imported Data + + Each implementation of \l{QAbstractItemModel::dropMimeData()}{dropMimeData()} must + also decode the data and insert it into the model's underlying data structure. + + For a simple string list model, the encoded items can be decoded and streamed + into a QStringList: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 5 + + The strings can then be inserted into the underlying data store. For consistency, + this can be done through the model's own interface: + + \snippet doc/src/snippets/qlistview-dnd/model.cpp 6 + + Note that the model will typically need to provide implementations of the + QAbstractItemModel::insertRows() and QAbstractItemModel::setData() functions. + + \sa {Item Views Puzzle Example} +*/ + +/*! + \page model-view-proxy-models.html + \contentspage model-view-programming.html Contents + \previouspage Using Drag and Drop with Item Views + \nextpage Model Subclassing Reference + + \title Proxy Models + + \tableofcontents + + \section1 Overview + + In the model/view framework, items of data supplied by a single model can be shared + by any number of views, and each of these can possibly represent the same information + in completely different ways. + Custom views and delegates are effective ways to provide radically different + representations of the same data. However, applications often need to provide + conventional views onto processed versions of the same data, such as differently-sorted + views onto a list of items. + + Although it seems appropriate to perform sorting and filtering operations as internal + functions of views, this approach does not allow multiple views to share the results + of such potentially costly operations. The alternative approach, involving sorting + within the model itself, leads to the similar problem where each view has to display + items of data that are organized according to the most recent processing operation. + + To solve this problem, the model/view framework uses proxy models to manage the + information supplied between individual models and views. Proxy models are components + that behave like ordinary models from the perspective of a view, and access data from + source models on behalf of that view. The signals and slots used by the model/view + framework ensure that each view is updated appropriately no matter how many proxy models + are placed between itself and the source model. + + \section1 Using Proxy Models + + Proxy models can be inserted between an existing model and any number of views. + Qt is supplied with a standard proxy model, QSortFilterProxyModel, that is usually + instantiated and used directly, but can also be subclassed to provide custom filtering + and sorting behavior. The QSortFilterProxyModel class can be used in the following way: + + \snippet doc/src/snippets/qsortfilterproxymodel/main.cpp 0 + \codeline + \snippet doc/src/snippets/qsortfilterproxymodel/main.cpp 1 + + Since proxy models are inherit from QAbstractItemModel, they can be connected to + any kind of view, and can be shared between views. They can also be used to + process the information obtained from other proxy models in a pipeline arrangement. + + The QSortFilterProxyModel class is designed to be instantiated and used directly + in applications. More specialized proxy models can be created by subclassing this + classes and implementing the required comparison operations. + + \section1 Customizing Proxy Models + + Generally, the type of processing used in a proxy model involves mapping each item of + data from its original location in the source model to either a different location in + the proxy model. In some models, some items may have no corresponding location in the + proxy model; these models are \e filtering proxy models. Views access items using + model indexes provided by the proxy model, and these contain no information about the + source model or the locations of the original items in that model. + + QSortFilterProxyModel enables data from a source model to be filtered before + being supplied to views, and also allows the contents of a source model to + be supplied to views as pre-sorted data. + + \section2 Custom Filtering Models + + The QSortFilterProxyModel class provides a filtering model that is fairly versatile, + and which can be used in a variety of common situations. For advanced users, + QSortFilterProxyModel can be subclassed, providing a mechanism that enables custom + filters to be implemented. + + Subclasses of QSortFilterProxyModel can reimplement two virtual functions that are + called whenever a model index from the proxy model is requested or used: + + \list + \o \l{QSortFilterProxyModel::filterAcceptsColumn()}{filterAcceptsColumn()} is used to + filter specific columns from part of the source model. + \o \l{QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} is used to filter + specific rows from part of the source model. + \endlist + + The default implementations of the above functions in QSortFilterProxyModel + return true to ensure that all items are passed through to views; reimplementations + of these functions should return false to filter out individual rows and columns. + + \section2 Custom Sorting Models + + QSortFilterProxyModel instances use Qt's built-in qStableSort() function to set up + mappings between items in the source model and those in the proxy model, allowing a + sorted hierarchy of items to be exposed to views without modifying the structure of the + source model. To provide custom sorting behavior, reimplement the + \l{QSortFilterProxyModel::lessThan()}{lessThan()} function to perform custom + comparisons. +*/ + +/*! + \page model-view-model-subclassing.html + \contentspage model-view-programming.html Contents + \previouspage Proxy Models + + \title Model Subclassing Reference + + \tableofcontents + + \section1 Introduction + + Model subclasses need to provide implementations of many of the virtual functions + defined in the QAbstractItemModel base class. The number of these functions that need + to be implemented depends on the type of model - whether it supplies views with + a simple list, a table, or a complex hierarchy of items. Models that inherit from + QAbstractListModel and QAbstractTableModel can take advantage of the default + implementations of functions provided by those classes. Models that expose items + of data in tree-like structures must provide implementations for many of the + virtual functions in QAbstractItemModel. + + The functions that need to be implemented in a model subclass can be divided into three + groups: + + \list + \o \bold{Item data handling:} All models need to implement functions to enable views and + delegates to query the dimensions of the model, examine items, and retrieve data. + \o \bold{Navigation and index creation:} Hierarchical models need to provide functions + that views can call to navigate the tree-like structures they expose, and obtain + model indexes for items. + \o \bold{Drag and drop support and MIME type handling:} Models inherit functions that + control the way that internal and external drag and drop operations are performed. + These functions allow items of data to be described in terms of MIME types that + other components and applications can understand. + \endlist + + For more information, see the \l + {"Item View Classes" Chapter of C++ GUI Programming with Qt 4}. + + \section1 Item Data Handling + + Models can provide varying levels of access to the data they provide: They can be + simple read-only components, some models may support resizing operations, and + others may allow items to be edited. + + \section2 Read-Only Access + + To provide read-only access to data provided by a model, the following functions + \e{must} be implemented in the model's subclass: + + \table 90% + \row \o \l{QAbstractItemModel::flags()}{flags()} + \o Used by other components to obtain information about each item provided by + the model. In many models, the combination of flags should include + Qt::ItemIsEnabled and Qt::ItemIsSelectable. + \row \o \l{QAbstractItemModel::data()}{data()} + \o Used to supply item data to views and delegates. Generally, models only + need to supply data for Qt::DisplayRole and any application-specific user + roles, but it is also good practice to provide data for Qt::ToolTipRole, + Qt::AccessibleTextRole, and Qt::AccessibleDescriptionRole. + \row \o \l{QAbstractItemModel::headerData()}{headerData()} + \o Provides views with information to show in their headers. The information is + only retrieved by views that can display header information. + \row \o \l{QAbstractItemModel::rowCount()}{rowCount()} + \o Provides the number of rows of data exposed by the model. + \endtable + + These four functions must be implemented in all types of model, including list models + (QAbstractListModel subclasses) and table models (QAbstractTableModel subclasses). + + Additionally, the following functions \e{must} be implemented in direct subclasses + of QAbstractTableModel and QAbstractItemModel: + + \table 90% + \row \o \l{QAbstractItemModel::columnCount()}{columnCount()} + \o Provides the number of columns of data exposed by the model. List models do not + provide this function because it is already implemented in QAbstractListModel. + \endtable + + \section2 Editable Items + + Editable models allow items of data to be modified, and may also provide + functions to allow rows and columns to be inserted and removed. To enable + editing, the following functions must be implemented correctly: + + \table 90% + \row \o \l{QAbstractItemModel::flags()}{flags()} + \o Must return an appropriate combination of flags for each item. In particular, + the value returned by this function must include \l{Qt::ItemIsEditable} in + addition to the values applied to items in a read-only model. + \row \o \l{QAbstractItemModel::setData()}{setData()} + \o Used to modify the item of data associated with a specified model index. + To be able to accept user input, provided by user interface elements, this + function must handle data associated with Qt::EditRole. + The implementation may also accept data associated with many different kinds + of roles specified by Qt::ItemDataRole. After changing the item of data, + models must emit the \l{QAbstractItemModel::dataChanged()}{dataChanged()} + signal to inform other components of the change. + \row \o \l{QAbstractItemModel::setHeaderData()}{setHeaderData()} + \o Used to modify horizontal and vertical header information. After changing + the item of data, models must emit the + \l{QAbstractItemModel::headerDataChanged()}{headerDataChanged()} + signal to inform other components of the change. + \endtable + + \section2 Resizable Models + + All types of model can support the insertion and removal of rows. Table models + and hierarchical models can also support the insertion and removal of columns. + It is important to notify other components about changes to the model's dimensions + both \e before and \e after they occur. As a result, the following functions + can be implemented to allow the model to be resized, but implementations must + ensure that the appropriate functions are called to notify attached views and + delegates: + + \table 90% + \row \o \l{QAbstractItemModel::insertRows()}{insertRows()} + \o Used to add new rows and items of data to all types of model. + Implementations must call + \l{QAbstractItemModel::beginInsertRows()}{beginInsertRows()} \e before + inserting new rows into any underlying data structures, and call + \l{QAbstractItemModel::endInsertRows()}{endInsertRows()} + \e{immediately afterwards}. + \row \o \l{QAbstractItemModel::removeRows()}{removeRows()} + \o Used to remove rows and the items of data they contain from all types of model. + Implementations must call + \l{QAbstractItemModel::beginRemoveRows()}{beginRemoveRows()} + \e before inserting new columns into any underlying data structures, and call + \l{QAbstractItemModel::endRemoveRows()}{endRemoveRows()} + \e{immediately afterwards}. + \row \o \l{QAbstractItemModel::insertColumns()}{insertColumns()} + \o Used to add new columns and items of data to table models and hierarchical models. + Implementations must call + \l{QAbstractItemModel::beginInsertColumns()}{beginInsertColumns()} \e before + rows are removed from any underlying data structures, and call + \l{QAbstractItemModel::endInsertColumns()}{endInsertColumns()} + \e{immediately afterwards}. + \row \o \l{QAbstractItemModel::removeColumns()}{removeColumns()} + \o Used to remove columns and the items of data they contain from table models and + hierarchical models. + Implementations must call + \l{QAbstractItemModel::beginRemoveColumns()}{beginRemoveColumns()} + \e before columns are removed from any underlying data structures, and call + \l{QAbstractItemModel::endRemoveColumns()}{endRemoveColumns()} + \e{immediately afterwards}. + \endtable + + Generally, these functions should return true if the operation was successful. + However, there may be cases where the operation only partly succeeded; for example, + if less than the specified number of rows could be inserted. In such cases, the + model should return false to indicate failure to enable any attached components to + handle the situation. + + The signals emitted by the functions called in implementations of the resizing + API give attached components the chance to take action before any data becomes + unavailable. The encapsulation of insert and remove operations with begin and end + functions also enable the model to manage + \l{QPersistentModelIndex}{persistent model indexes} correctly. + + Normally, the begin and end functions are capable of informing other components + about changes to the model's underlying structure. For more complex changes to the + model's structure, perhaps involving internal reorganization or sorting of data, + it is necessary to emit the \l{QAbstractItemModel::layoutChanged()}{layoutChanged()} + signal to cause any attached views to be updated. + + \section2 Lazy Population of Model Data + + Lazy population of model data effectively allows requests for information + about the model to be deferred until it is actually needed by views. + + Some models need to obtain data from remote sources, or must perform + time-consuming operations to obtain information about the way the + data is organized. Since views generally request as much information + as possible in order to accurately display model data, it can be useful + to restrict the amount of information returned to them to reduce + unnecessary follow-up requests for data. + + In hierarchical models where finding the number of children of a given + item is an expensive operation, it is useful to ensure that the model's + \l{QAbstractItemModel::}{rowCount()} implementation is only called when + necessary. In such cases, the \l{QAbstractItemModel::}{hasChildren()} + function can be reimplemented to provide an inexpensive way for views to + check for the presence of children and, in the case of QTreeView, draw + the appropriate decoration for their parent item. + + Whether the reimplementation of \l{QAbstractItemModel::}{hasChildren()} + returns \c true or \c false, it may not be necessary for the view to call + \l{QAbstractItemModel::}{rowCount()} to find out how many children are + present. For example, QTreeView does not need to know how many children + there are if the parent item has not been expanded to show them. + + If it is known that many items will have children, reimplementing + \l{QAbstractItemModel::}{hasChildren()} to unconditionally return \c true + is sometimes a useful approach to take. This ensures that each item can + be later examined for children while making initial population of model + data as fast as possible. The only disadvantage is that items without + children may be displayed incorrectly in some views until the user + attempts to view the non-existent child items. + + + \section1 Navigation and Model Index Creation + + Hierarchical models need to provide functions that views can call to navigate the + tree-like structures they expose, and obtain model indexes for items. + + \section2 Parents and Children + + Since the structure exposed to views is determined by the underlying data + structure, it is up to each model subclass to create its own model indexes + by providing implementations of the following functions: + + \table 90% + \row \o \l{QAbstractItemModel::index()}{index()} + \o Given a model index for a parent item, this function allows views and delegates + to access children of that item. If no valid child item - corresponding to the + specified row, column, and parent model index, can be found, the function + must return QModelIndex(), which is an invalid model index. + \row \o \l{QAbstractItemModel::parent()}{parent()} + \o Provides a model index corresponding to the parent of any given child item. + If the model index specified corresponds to a top-level item in the model, or if + there is no valid parent item in the model, the function must return + an invalid model index, created with the empty QModelIndex() constructor. + \endtable + + Both functions above use the \l{QAbstractItemModel::createIndex()}{createIndex()} + factory function to generate indexes for other components to use. It is normal for + models to supply some unique identifier to this function to ensure that + the model index can be re-associated with its corresponding item later on. + + \section1 Drag and Drop Support and MIME Type Handling + + The model/view classes support drag and drop operations, providing default behavior + that is sufficient for many applications. However, it is also possible to customize + the way items are encoded during drag and drop operations, whether they are copied + or moved by default, and how they are inserted into existing models. + + Additionally, the convenience view classes implement specialized behavior that + should closely follow that expected by existing developers. + The \l{#Convenience Views}{Convenience Views} section provides an overview of this + behavior. + + \section2 MIME Data + + By default, the built-in models and views use an internal MIME type + (\c{application/x-qabstractitemmodeldatalist}) to pass around information about + model indexes. This specifies data for a list of items, containing the row and + column numbers of each item, and information about the roles that each item + supports. + + Data encoded using this MIME type can be obtained by calling + QAbstractItemModel::mimeData() with a QModelIndexList containing the items to + be serialized. + \omit + The following types are used to store information about + each item as it is streamed into a QByteArray and stored in a QMimeData object: + + \table 90% + \header \o Description \o Type + \row \o Row \o int + \row \o Column \o int + \row \o Data for each role \o QMap + \endtable + + This information can be retrieved for use in non-model classes by calling + QMimeData::data() with the \c{application/x-qabstractitemmodeldatalist} MIME + type and streaming out the items one by one. + \endomit + + When implementing drag and drop support in a custom model, it is possible to + export items of data in specialized formats by reimplementing the following + function: + + \table 90% + \row \o \l{QAbstractItemModel::mimeData()}{mimeData()} + \o This function can be reimplemented to return data in formats other + than the default \c{application/x-qabstractitemmodeldatalist} internal + MIME type. + + Subclasses can obtain the default QMimeData object from the base class + and add data to it in additional formats. + \endtable + + For many models, it is useful to provide the contents of items in common format + represented by MIME types such as \c{text/plain} and \c{image/png}. Note that + images, colors and HTML documents can easily be added to a QMimeData object with + the QMimeData::setImageData(), QMimeData::setColorData(), and + QMimeData::setHtml() functions. + + \section2 Accepting Dropped Data + + When a drag and drop operation is performed over a view, the underlying model is + queried to determine which types of operation it supports and the MIME types + it can accept. This information is provided by the + QAbstractItemModel::supportedDropActions() and QAbstractItemModel::mimeTypes() + functions. Models that do not override the implementations provided by + QAbstractItemModel support copy operations and the default internal MIME type + for items. + + When serialized item data is dropped onto a view, the data is inserted into + the current model using its implementation of QAbstractItemModel::dropMimeData(). + The default implementation of this function will never overwrite any data in the + model; instead, it tries to insert the items of data either as siblings of an + item, or as children of that item. + + To take advantage of QAbstractItemModel's default implementation for the built-in + MIME type, new models must provide reimplementations of the following functions: + + \table 90% + \row \o \l{QAbstractItemModel::insertRows()}{insertRows()} + \o {1, 2} These functions enable the model to automatically insert new data using + the existing implementation provided by QAbstractItemModel::dropMimeData(). + \row \o \l{QAbstractItemModel::insertColumns()}{insertColumns()} + \row \o \l{QAbstractItemModel::setData()}{setData()} + \o Allows the new rows and columns to be populated with items. + \row \o \l{QAbstractItemModel::setItemData()}{setItemData()} + \o This function provides more efficient support for populating new items. + \endtable + + To accept other forms of data, these functions must be reimplemented: + + \table 90% + \row \o \l{QAbstractItemModel::supportedDropActions()}{supportedDropActions()} + \o Used to return a combination of \l{Qt::DropActions}{drop actions}, + indicating the types of drag and drop operations that the model accepts. + \row \o \l{QAbstractItemModel::mimeTypes()}{mimeTypes()} + \o Used to return a list of MIME types that can be decoded and handled by + the model. Generally, the MIME types that are supported for input into + the model are the same as those that it can use when encoding data for + use by external components. + \row \o \l{QAbstractItemModel::dropMimeData()}{dropMimeData()} + \o Performs the actual decoding of the data transferred by drag and drop + operations, determines where in the model it will be set, and inserts + new rows and columns where necessary. How this function is implemented + in subclasses depends on the requirements of the data exposed by each + model. + \endtable + + If the implementation of the \l{QAbstractItemModel::dropMimeData()}{dropMimeData()} + function changes the dimensions of a model by inserting or removing rows or + columns, or if items of data are modified, care must be taken to ensure that + all relevant signals are emitted. It can be useful to simply call + reimplementations of other functions in the subclass, such as + \l{QAbstractItemModel::setData()}{setData()}, + \l{QAbstractItemModel::insertRows()}{insertRows()}, and + \l{QAbstractItemModel::insertColumns()}{insertColumns()}, to ensure that the + model behaves consistently. + + In order to ensure drag operations work properly, it is important to + reimplement the following functions that remove data from the model: + + \list + \o \l{QAbstractItemModel::}{removeRows()} + \o \l{QAbstractItemModel::}{removeRow()} + \o \l{QAbstractItemModel::}{removeColumns()} + \o \l{QAbstractItemModel::}{removeColumn()} + \endlist + + For more information about drag and drop with item views, refer to + \l{Using Drag and Drop with Item Views}. + + \section2 Convenience Views + + The convenience views (QListWidget, QTableWidget, and QTreeWidget) override + the default drag and drop functionality to provide less flexible, but more + natural behavior that is appropriate for many applications. For example, + since it is more common to drop data into cells in a QTableWidget, replacing + the existing contents with the data being transferred, the underlying model + will set the data of the target items rather than insert new rows and columns + into the model. For more information on drag and drop in convenience views, + you can see \l{Using Drag and Drop with Item Views}. + + \section1 Performance Optimization for Large Amounts of Data + + The \l{QAbstractItemModel::}{canFetchMore()} function checks if the parent + has more data available and returns true or false accordingly. The + \l{QAbstractItemModel::}{fetchMore()} function fetches data based on the + parent specified. Both these functions can be combined, for example, in a + database query involving incremental data to populate a QAbstractItemModel. + We reimplement \l{QAbstractItemModel::}{canFetchMore()} to indicate if there + is more data to be fetched and \l{QAbstractItemModel::}{fetchMore()} to + populate the model as required. + + Another example would be dynamically populated tree models, where we + reimplement \l{QAbstractItemModel::}{fetchMore()} when a branch in the tree + model is expanded. + + If your reimplementation of \l{QAbstractItemModel::}{fetchMore()} adds rows + to the model, you need to call \l{QAbstractItemModel::}{beginInsertRows()} + and \l{QAbstractItemModel::}{endInsertRows()}. Also, both + \l{QAbstractItemModel::}{canFetchMore()} and \l{QAbstractItemModel::} + {fetchMore()} must be reimplemented as their default implementation returns + false and does nothing. +*/ + diff --git a/doc/src/modules.qdoc b/doc/src/modules.qdoc new file mode 100644 index 0000000..7372994 --- /dev/null +++ b/doc/src/modules.qdoc @@ -0,0 +1,105 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group modules + \title Qt's Modules + \startpage index.html Qt Reference Documentation + \nextpage QtCore + + Qt 4 consists of several modules, each of which lives in a + separate library. + + Modules for general software development: + + \table 80% + \row \o \l{QtCore} \o Core non-graphical classes used by other modules + \row \o \l{QtGui} \o Graphical user interface (GUI) components + \row \o \l{QtNetwork} \o Classes for network programming + \row \o \l{QtOpenGL} \o OpenGL support classes + \row \o \l{QtScript} \o Classes for evaluating Qt Scripts + \row \o \l{QtScriptTools} \o Additional Qt Script components + \row \o \l{QtSql} \o Classes for database integration using SQL + \row \o \l{QtSvg} \o Classes for displaying the contents of SVG files + \row \o \l{QtWebKit} \o Classes for displaying and editing Web content + \row \o \l{QtXml} \o Classes for handling XML + \row \o \l{QtXmlPatterns} \o An XQuery & XPath engine for XML and custom data models + \row \o \l{Phonon Module}{Phonon} \o Multimedia framework classes + \row \o \l{Qt3Support} \o Qt 3 compatibility classes + \endtable + + Modules for working with Qt's tools: + + \table 80% + \row \o \l{QtDesigner} \o Classes for extending \QD + \row \o \l{QtUiTools} \o Classes for handling \QD forms in applications + \row \o \l{QtHelp} \o Classes for online help + \row \o \l{QtAssistant} \o Support for online help + \row \o \l{QtTest} \o Tool classes for unit testing + \endtable + + The following extension modules are available in the \l{Qt + Commercial Editions} on Windows: + + \table 80% + \row \o \l{QAxContainer} \o Extension for accessing ActiveX controls + \row \o \l{QAxServer} \o Extension for writing ActiveX servers + \endtable + + The following extension module is available in all \l {Qt Editions} + on Unix platforms: + + \table 80% + \row \o \l{QtDBus} \o Classes for Inter-Process Communication using the D-Bus + \endtable + + If you use \l qmake to build your projects, the QtCore and QtGui + modules are included by default. To link only against QtCore, add + the following line to your \c .pro file: + + \snippet doc/src/snippets/code/doc_src_modules.qdoc 0 + + On Windows, if you do not use \l qmake, the \l{Visual Studio Integration} + available to \l{Qt Commercial Editions}{commercial licensees}, or other + build tools such as CMake, you also need to link against the \c qtmain library. + + \sa {Qt's Classes} +*/ diff --git a/doc/src/object.qdoc b/doc/src/object.qdoc new file mode 100644 index 0000000..3bd563a --- /dev/null +++ b/doc/src/object.qdoc @@ -0,0 +1,132 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page object.html + \title Qt Object Model + \ingroup architecture + \brief A description of the powerful features made possible by Qt's dynamic object model. + + The standard C++ object model provides very efficient runtime + support for the object paradigm. But its static nature is + inflexibile in certain problem domains. Graphical user interface + programming is a domain that requires both runtime efficiency and + a high level of flexibility. Qt provides this, by combining the + speed of C++ with the flexibility of the Qt Object Model. + + Qt adds these features to C++: + + \list + \o a very powerful mechanism for seamless object + communication called \l{signals and slots} + \o queryable and designable \l{Qt's Property System}{object + properties} + \o powerful \l{events and event filters} + \o contextual \l{i18n}{string translation for internationalization} + \o sophisticated interval driven \l timers that make it possible + to elegantly integrate many tasks in an event-driven GUI + \o hierarchical and queryable \l{Object Trees and Object Ownership}{object + trees} that organize object ownership in a natural way + \o guarded pointers (QPointer) that are automatically + set to 0 when the referenced object is destroyed, unlike normal C++ + pointers which become dangling pointers when their objects are destroyed + \o a \l{metaobjects.html#qobjectcast}{dynamic cast} that works across + library boundaries. + \endlist + + Many of these Qt features are implemented with standard C++ + techniques, based on inheritance from QObject. Others, like the + object communication mechanism and the dynamic property system, + require the \l{Meta-Object System} provided + by Qt's own \l{moc}{Meta-Object Compiler (moc)}. + + The meta-object system is a C++ extension that makes the language + better suited to true component GUI programming. Although + templates can be used to extend C++, the meta-object system + provides benefits using standard C++ that cannot be achieved with + templates; see \l{Why Doesn't Qt Use Templates for Signals and + Slots?} + + \target Identity vs Value + \section1 Qt Objects: Identity vs Value + + Some of the added features listed above for the Qt Object Model, + require that we think of Qt Objects as identities, not values. + Values are copied or assigned; identities are cloned. Cloning + means to create a new identity, not an exact copy of the old + one. For example, twins have different identities. They may look + identical, but they have different names, different locations, and + may have completely different social networks. + + Then cloning an identity is a more complex operation than copying + or assigning a value. We can see what this means in the Qt Object + Model. + + \bold{A Qt Object...} + + \list + + \o might have a unique \l{QObject::objectName()}. If we copy a Qt + Object, what name should we give the copy? + + \o has a location in an \l{Object Trees and Object Ownership} + {object hierarchy}. If we copy a Qt Object, where should the copy + be located? + + \o can be connected to other Qt Objects to emit signals to them or + to receive signals emitted by them. If we copy a Qt Object, how + should we transfer these connections to the copy? + + \o can have \l{Qt's Property System} {new properties} added to it + at runtime that are not declared in the C++ class. If we copy a Qt + Object, should the copy include the properties that were added to + the original? + + \endlist + + For these reasons, Qt Objects should be treated as identities, not + as values. Identities are cloned, not copied or assigned, and + cloning an identity is a more complex operation than copying or + assigning a value. Therefore, QObject and all subclasses of + QObject (direct or indirect) have their \l{No copy constructor} + {copy constructor and assignment operator} disabled. + + */ diff --git a/doc/src/objecttrees.qdoc b/doc/src/objecttrees.qdoc new file mode 100644 index 0000000..4b868c0 --- /dev/null +++ b/doc/src/objecttrees.qdoc @@ -0,0 +1,117 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page objecttrees.html +\title Object Trees and Object Ownership +\ingroup architecture +\brief Information about the parent-child pattern used to describe +object ownership in Qt. + +\section1 Overview + +\link QObject QObjects\endlink organize themselves in object trees. +When you create a QObject with another object as parent, it's added to +the parent's \link QObject::children() children() \endlink list, and +is deleted when the parent is. It turns out that this approach fits +the needs of GUI objects very well. For example, a \l QShortcut +(keyboard shortcut) is a child of the relevant window, so when the +user closes that window, the shorcut is deleted too. + +\l QWidget, the base class of everything that appears on the screen, +extends the parent-child relationship. A child normally also becomes a +child widget, i.e. it is displayed in its parent's coordinate system +and is graphically clipped by its parent's boundaries. For example, +when the application deletes a message box after it has been +closed, the message box's buttons and label are also deleted, just as +we'd want, because the buttons and label are children of the message +box. + +You can also delete child objects yourself, and they will remove +themselves from their parents. For example, when the user removes a +toolbar it may lead to the application deleting one of its \l QToolBar +objects, in which case the tool bar's \l QMainWindow parent would +detect the change and reconfigure its screen space accordingly. + +The debugging functions \l QObject::dumpObjectTree() and \l +QObject::dumpObjectInfo() are often useful when an application looks or +acts strangely. + +\target note on the order of construction/destruction of QObjects +\section1 Construction/Destruction Order of QObjects + +When \l {QObject} {QObjects} are created on the heap (i.e., created +with \e new), a tree can be constructed from them in any order, and +later, the objects in the tree can be destroyed in any order. When any +QObject in the tree is deleted, if the object has a parent, the +destructor automatically removes the object from its parent. If the +object has children, the destructor automatically deletes each +child. No QObject is deleted twice, regardless of the order of +destruction. + +When \l {QObject} {QObjects} are created on the stack, the same +behavior applies. Normally, the order of destruction still doesn't +present a problem. Consider the following snippet: + +\snippet doc/src/snippets/code/doc_src_objecttrees.qdoc 0 + +The parent, \c window, and the child, \c quit, are both \l {QObject} +{QObjects} because QPushButton inherits QWidget, and QWidget inherits +QObject. This code is correct: the destructor of \c quit is \e not +called twice because the C++ language standard \e {(ISO/IEC 14882:2003)} +specifies that destructors of local objects are called in the reverse +order of their constructors. Therefore, the destructor of +the child, \c quit, is called first, and it removes itself from its +parent, \c window, before the destructor of \c window is called. + +But now consider what happens if we swap the order of construction, as +shown in this second snippet: + +\snippet doc/src/snippets/code/doc_src_objecttrees.qdoc 1 + +In this case, the order of destruction causes a problem. The parent's +destructor is called first because it was created last. It then calls +the destructor of its child, \c quit, which is incorrect because \c +quit is a local variable. When \c quit subsequently goes out of scope, +its destructor is called again, this time correctly, but the damage has +already been done. + +*/ diff --git a/doc/src/opensourceedition.qdoc b/doc/src/opensourceedition.qdoc new file mode 100644 index 0000000..d8253d3 --- /dev/null +++ b/doc/src/opensourceedition.qdoc @@ -0,0 +1,91 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page opensourceedition.html + + \title Open Source Versions of Qt + \ingroup licensing + \brief Information about the license and features of the Open Source Edition. + + Free (or open source) software is software that comes with a license + that gives users certain rights. In particular the right to use the + software, to modify it, to obtain its source, and to pass it on (under + the same terms). Notice that the term "free" is about rights, not + money. The Free Software Foundation (creators of the GNU GPL) speaks + of free in this context as in "free speech", not as in "no cost". + + Qt Software supports the free software concept by providing the Qt Open Source + Edition, which is licensed under the \l{GNU General Public License (GPL)} + (version 3) and the \l{GNU Lesser General Public License (LGPL)} (version 2.1). + You can use this edition of Qt to create and distribute software with licenses + that are compatible to these free software licenses. + + The support of open source with the Open Source Versions of Qt has enabled large + successful software projects like KDE to thrive, with thousands of developers + around the world using open source versions of Qt at no cost to themselves. With + the release of Qt 4, open source versions of Qt became available for Unix/X11, + Mac OS X, and Windows platforms. + + The Open Source Edition can be downloaded from the \l{Downloads}{Qt website}. + + Please refer to the online \l{License FAQ} for answers to frequently asked + questions on open source licensing and its implications. + + More information on Free and Open Source software is available online: + + \list + \o GNU GPL: \l http://www.gnu.org/. + \o Open Source licensing: \l http://www.opensource.org/. + \endlist + + See \l{Licensing Information} for a collection of documents about licenses + used in Qt. + + Information about Qt Commercial License Agreements is available + in the \l{Qt Licensing Overview} on the Qt website or by email + from \l{mailto:qt-sales@nokia.com}{qt-sales@nokia.com}. + + If you are in doubt what edition of Qt is right for your project, + please contact + \l{mailto:qt-info@nokia.com}{qt-info@nokia.com}. + +*/ diff --git a/doc/src/overviews.qdoc b/doc/src/overviews.qdoc new file mode 100644 index 0000000..8eb4e35 --- /dev/null +++ b/doc/src/overviews.qdoc @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page overviews.html + + \title All Overviews and HOWTOs + + \generatelist overviews +*/ diff --git a/doc/src/paintsystem.qdoc b/doc/src/paintsystem.qdoc new file mode 100644 index 0000000..11b9a5b --- /dev/null +++ b/doc/src/paintsystem.qdoc @@ -0,0 +1,485 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page paintsystem.html + + \title The Paint System + + Qt's paint system enables painting on screen and print devices + using the same API, and is primarily based on the QPainter, + QPaintDevice, and QPaintEngine classes. + + QPainter is used to perform drawing operations, QPaintDevice is an + abstraction of a two-dimensional space that can be painted on + using a QPainter, and QPaintEngine provides the interface that the + painter uses to draw onto different types of devices. The + QPaintEngine class is used internally by QPainter and + QPaintDevice, and is hidden from application programmers unless + they create their own device type. + + \image paintsystem-core.png + + The main benefit of this approach is that all painting follows the + same painting pipeline making it easy to add support for new + features and providing default implementations for unsupported + ones. + + Alternatively, Qt provides the QtOpenGL module, offering classes + that makes it easy to use OpenGL in Qt applications. Among others, + the module provides an OpenGL widget class that can be used just + like any other Qt widget, except that it opens an OpenGL display + buffer where the OpenGL API can be used to render the contents. + + \tableofcontents section1 + + \section1 Drawing + + QPainter provides highly optimized functions to do most of the + drawing GUI programs require. It can draw everything from simple + graphical primitives (represented by the QPoint, QLine, QRect, + QRegion and QPolygon classes) to complex shapes like vector + paths. In Qt vector paths are represented by the QPainterPath + class. QPainterPath provides a container for painting operations, + enabling graphical shapes to be constructed and reused. + + \table 100% + \row + \o \image paintsystem-painterpath.png + \o \bold QPainterPath + + A painter path is an object composed of lines and curves. For + example, a rectangle is composed by lines and an ellipse is + composed by curves. + + The main advantage of painter paths over normal drawing operations + is that complex shapes only need to be created once; then they can + be drawn many times using only calls to the QPainter::drawPath() + function. + + A QPainterPath object can be used for filling, outlining, and + clipping. To generate fillable outlines for a given painter path, + use the QPainterPathStroker class. + + \endtable + + Lines and outlines are drawn using the QPen class. A pen is + defined by its style (i.e. its line-type), width, brush, how the + endpoints are drawn (cap-style) and how joins between two + connected lines are drawn (join-style). The pen's brush is a + QBrush object used to fill strokes generated with the pen, + i.e. the QBrush class defines the fill pattern. + + QPainter can also draw aligned text and pixmaps. + + When drawing text, the font is specified using the QFont class. Qt + will use the font with the specified attributes, or if no matching + font exists, Qt will use the closest matching installed font. The + attributes of the font that is actually used can be retrieved + using the QFontInfo class. In addition, the QFontMetrics class + provides the font measurements, and the QFontDatabase class + provides information about the fonts available in the underlying + window system. + + Normally, QPainter draws in a "natural" coordinate system, but it + is able to perform view and world transformations using the + QMatrix class. For more information, see \l {The Coordinate + System} documentation which also describes the rendering process, + i.e. the relation between the logical representation and the + rendered pixels, and the benefits of anti-aliased painting. + + \table 100% + \row \o + \bold {Anti-Aliased Painting} + + When drawing, the pixel rendering is controlled by the + QPainter::Antialiasing render hint. The QPainter::RenderHint enum + is used to specify flags to QPainter that may or may not be + respected by any given engine. + + The QPainter::Antialiasing value indicates that the engine should + antialias edges of primitives if possible, i.e. smoothing the + edges by using different color intensities. + + \o \image paintsystem-antialiasing.png + + \endtable + + \section1 Filling + + Shapes are filled using the QBrush class. A brush is defined + by its color and its style (i.e. its fill pattern). + + Any color in Qt is represented by the QColor class which supports + the RGB, HSV and CMYK color models. QColor also support + alpha-blended outlining and filling (specifying the transparency + effect), and the class is platform and device independent (the + colors are mapped to hardware using the QColormap class). For more + information, see the QColor class documentation. + + When creating a new widget, it is recommend to use the colors in + the widget's palette rather than hard-coding specific colors. All + widgets in Qt contain a palette and use their palette to draw + themselves. A widget's palette is represented by the QPalette + class which contains color groups for each widget state. + + The available fill patterns are described by the Qt::BrushStyle + enum. These include basic patterns spanning from uniform color to + very sparse pattern, various line combinations, gradient fills and + textures. Qt provides the QGradient class to define custom + gradient fills, while texture patterns are specified using the + QPixmap class. + + \table 100% + \row + \o \image paintsystem-fancygradient.png + \o \bold QGradient + + The QGradient class is used in combination with QBrush to specify + gradient fills. + + \image paintsystem-gradients.png + + Qt currently supports three types of gradient fills: Linear + gradients interpolate colors between start and end points, radial + gradients interpolate colors between a focal point and end points + on a circle surrounding it, and conical gradients interpolate + colors around a center point. + + \endtable + + \section1 Creating a Paint Device + + The QPaintDevice class is the base class of objects that can be + painted, i.e. QPainter can draw on any QPaintDevice + subclass. QPaintDevice's drawing capabilities are currently + implemented by the QWidget, QImage, QPixmap, QGLWidget, + QGLPixelBuffer, QPicture and QPrinter subclasses. + + \image paintsystem-devices.png + + \table 100% + \row \o \bold {Custom Backends} + + Support for a new backend can be implemented by deriving from the + QPaintDevice class and reimplementing the virtual + QPaintDevice::paintEngine() function to tell QPainter which paint + engine should be used to draw on this particular device. To + actually be able to draw on the device, this paint engine must be + a custom paint engine created by deriving from the QPaintEngine + class. + + \endtable + + \section2 Widget + + The QWidget class is the base class of all user interface + objects. The widget is the atom of the user interface: it receives + mouse, keyboard and other events from the window system, and + paints a representation of itself on the screen. + + \section2 Image + + The QImage class provides a hardware-independent image + representation which is designed and optimized for I/O, and for + direct pixel access and manipulation. QImage supports several + image formats including monochrome, 8-bit, 32-bit and + alpha-blended images. + + One advantage of using QImage as a paint device is that it is + possible to guarantee the pixel exactness of any drawing operation + in a platform-independent way. Another benefit is that the + painting can be performed in another thread than the current GUI + thread. + + \section2 Pixmap + + The QPixmap class is an off-screen image representation which is + designed and optimized for showing images on screen. Unlike + QImage, the pixel data in a pixmap is internal and is managed by + the underlying window system, i.e. pixels can only be accessed + through QPainter functions or by converting the QPixmap to a + QImage. + + To optimize drawing with QPixmap, Qt provides the QPixmapCache + class which can be used to store temporary pixmaps that are + expensive to generate without using more storage space than the + cache limit. + + Qt also provides the QBitmap convenience class, inheriting + QPixmap. QBitmap guarantees monochrome (1-bit depth) pixmaps, and + is mainly used for creating custom QCursor and QBrush objects, + constructing QRegion objects, and for setting masks for pixmaps + and widgets. + + \section2 OpenGL Widget + + As mentioned above, Qt provides the QtOpenGL module offering + classes that makes it easy to use OpenGL in Qt applications. For + example, the QGLWidget enables the OpenGL API for + rendering. + + But QGLWidget is also a QWidget subclass, and can be used by + QPainter as any other paint device. One huge benefit from this is + that it enables Qt to utilize the high performance of OpenGL for + most drawing operations, such as transformations and pixmap + drawing. + + \section2 Pixel Buffer + + The QtOpenGL module also provides the QGLPixelBuffer class which + inherits QPaintDevice directly. + + QGLPixelBuffer encapsulates an OpenGL pbuffer. Rendering into a + pbuffer is normally done using full hardware acceleration which + can be significantly faster than rendering into a QPixmap. + + \section2 Framebuffer Object + + The QtOpenGL module also provides the QGLFramebufferObject class + which inherits QPaintDevice directly. + + QGLFramebufferObject encapsulates an OpenGL framebuffer object. + Framebuffer objects can also be used for off-screen rendering, and + offer several advantages over pixel buffers for this purpose. + These are described in the QGLFramebufferObject class documentation. + + \section2 Picture + + The QPicture class is a paint device that records and replays + QPainter commands. A picture serializes painter commands to an IO + device in a platform-independent format. QPicture is also + resolution independent, i.e. a QPicture can be displayed on + different devices (for example svg, pdf, ps, printer and screen) + looking the same. + + Qt provides the QPicture::load() and QPicture::save() functions + for loading and saving pictures. But in addition the QPictureIO + class is provided to enable the programmer to install new picture + file formats in addition to those that Qt provides. + + \section2 Printer + + The QPrinter class is a paint device that paints on a printer. On + Windows or Mac OS X, QPrinter uses the built-in printer + drivers. On X11, QPrinter generates postscript and sends that to + lpr, lp, or another print program. QPrinter can also print to any + other QPrintEngine object. + + The QPrintEngine class defines an interface for how QPrinter + interacts with a given printing subsystem. The common case when + creating your own print engine, is to derive from both + QPaintEngine and QPrintEngine. + + The output format is by default determined by the platform the + printer is running on, but by explicitly setting the output format + to QPrinter::PdfFormat, QPrinter will generate its output as a PDF + file. + + \section1 Reading and Writing Image Files + + The most common way to read images is through QImage and QPixmap's + constructors, or by calling the QImage::load() and QPixmap::load() + functions. In addition, Qt provides the QImageReader class which + gives more control over the process. Depending on the underlying + support in the image format, the functions provided by the class + can save memory and speed up loading of images. + + Likewise, Qt provides the QImageWriter class which supports + setting format specific options, such as the gamma level, + compression level and quality, prior to storing the image. If you + do not need such options, you can use QImage::save() or + QPixmap::save() instead. + + \table 100% + \row + \o \bold QMovie + + QMovie is a convenience class for displaying animations, using the + QImageReader class internally. Once created, the QMovie class + provides various functions for both running and controlling the + given animation. + + \o \image paintsystem-movie.png + \endtable + + The QImageReader and QImageWriter classes rely on the + QImageIOHandler class which is the common image I/O interface for + all image formats in Qt. QImageIOHandler objects are used + internally by QImageReader and QImageWriter to add support for + different image formats to Qt. + + A list of the supported file formats are available through the + QImageReader::supportedImageFormats() and + QImageWriter::supportedImageFormats() functions. Qt supports + several file formats by default, and in addition new formats can + be added as plugins. The currently supported formats are listed in + the QImageReader and QImageWriter class documentation. + + Qt's plugin mechanism can also be used to write a custom image + format handler. This is done by deriving from the QImageIOHandler + class, and creating a QImageIOPlugin object which is a factory for + creating QImageIOHandler objects. When the plugin is installed, + QImageReader and QImageWriter will automatically load the plugin + and start using it. + + \table 100% + \row + \o \image paintsystem-svg.png + \o \bold {SVG Rendering} + + Scalable Vector Graphics (SVG) is an language for describing both + static and animated two-dimensional vector graphics. Qt includes + support for the static features of SVG 1.2 Tiny. + + SVG drawings can be rendered onto any QPaintDevice subclass. This + approach gives developers the flexibility to experiment, in order + to find the best solution for each application. + + The easiest way to render SVG files is to construct a QSvgWidget + and load an SVG file using one of the QSvgWidget::load() + functions. The rendering is performed by the QSvgRenderer class + which also can be used directly to provide SVG support for custom + widgets. + + For more information, see the QtSvg module documentation. + + \endtable + + \section1 Styling + + Qt's built-in widgets use the QStyle class to perform nearly all + of their drawing. QStyle is an abstract base class that + encapsulates the look and feel of a GUI, and can be used to make + the widgets look exactly like the equivalent native widgets or to + give the widgets a custom look. + + Qt provides a set of QStyle subclasses that emulate the native + look of the different platforms supported by Qt (QWindowsStyle, + QMacStyle, QMotifStyle, etc.). These styles are built into the + QtGui library, other styles can be made available using Qt's + plugin mechansim. + + Most functions for drawing style elements take four arguments: + + \list + \o an enum value specifying which graphical element to draw + \o a QStyleOption object specifying how and where to render that element + \o a QPainter object that should be used to draw the element + \o a QWidget object on which the drawing is performed (optional) + \endlist + + The style gets all the information it needs to render the + graphical element from the QStyleOption class. The widget is + passed as the last argument in case the style needs it to perform + special effects (such as animated default buttons on Mac OS X), + but it isn't mandatory. In fact, QStyle can be used to draw on any + paint device (not just widgets), in which case the widget argument + is a zero pointer. + + \image paintsystem-stylepainter.png + + The paint system also provides the QStylePainter class inheriting + from QPainter. QStylePainter is a convenience class for drawing + QStyle elements inside a widget, and extends QPainter with a set + of high-level drawing functions implemented on top of QStyle's + API. The advantage of using QStylePainter is that the parameter + lists get considerably shorter. + + \table 100% + \row + \o \inlineimage paintsystem-icon.png + \o \bold QIcon + + The QIcon class provides scalable icons in different modes and states. + + QIcon can generate pixmaps reflecting an icon's state, mode and + size. These pixmaps are generated from the set of pixmaps + made available to the icon, and are used by Qt widgets to show an + icon representing a particular action. + + The rendering of a QIcon object is handled by the QIconEngine + class. Each icon has a corresponding icon engine that is + responsible for drawing the icon with a requested size, mode and + state. + + \endtable + + \section1 Selecting the Painting Backend + + Since Qt 4.5, it is possible to replace the paint engines and paint + devices used for widgets, pixmaps and the offscreen double buffer. By + default the backends are: + + \table + \row + \o Windows + \o Software Rasterizer + \row + \o X11 + \o X11 + \row + \o Mac OS X + \o CoreGraphics + \row + \o Embedded + \o Software Rasterizer + \endtable + + Passing a command line parameter to the application, such as, + \c{-graphicssystem raster}, specifies that Qt should use the software + rasterizer for this application. The Software rasterizer is fully + supported on all platforms. + + \code + > analogclock -graphicssystem raster + \endcode + + There is also a \c{-graphicssystem opengl} mode that uses OpenGL for + all drawing. Currently, this engine is experimental as it does not draw + everything correctly. + + Qt also supports being configured using \c {-graphicssystem + raster|opengl} in which case all applications will use the + specified graphics system for its graphics. + + */ + diff --git a/doc/src/phonon-api.qdoc b/doc/src/phonon-api.qdoc new file mode 100644 index 0000000..01f7c8a --- /dev/null +++ b/doc/src/phonon-api.qdoc @@ -0,0 +1,4993 @@ +/* + This file is part of the KDE project + Copyright (C) 2005-2007 Matthias Kretz + Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). + Contact: Qt Software Information (qt-info@nokia.com) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License version 2 as published by the Free Software Foundation. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + + +/*! + \enum Phonon::DiscType + Enum to identify the media discs supported by MediaObject. + + \value NoDisc + No disc was selected. This is only useful as a return value from + MediaSource::diskType(). + \value Cd Identifies Audio CDs. + \value Dvd Identifies DVDs (not arbitrary data DVDs, only movie DVDs). + \value Vcd Identifies Video CDs. + + \sa MediaSource, MediaObject +*/ + +/*! + \enum Phonon::MetaData + + Provided as keys for Phonon::MediaObject::metaData(). The enum + values matches strings defined in the Ogg Vorbis specification + + \value ArtistMetaData + \value AlbumMetaData + \value TitleMetaData + \value DateMetaData + \value GenreMetaData + \value TracknumberMetaData + \value DescriptionMetaData + \value MusicBrainzDiscIdMetaData +*/ + +/*! + \enum Phonon::State + \since 4.4 + + The state enum describes the different states a media object can + take. Several functions of \l{Phonon::}{MediaObject} are + asynchronous, so even if a you have requested a state change + through a function call, e.g., through + \l{Phonon::MediaObject::}{play()}, you cannot be sure that the + change has taken place before you receive the + \l{Phonon::MediaObject::}{stateChanged()} signal. + + A media object can at any time change into any state, regardless + of the state it previously had. \omit In the + \l{Phonon::}{MediaObject} class description explains the typical + state changes in the life of a media object. \endomit + + \value LoadingState + After construction it might take a while before the media object + is ready to \l{Phonon::MediaObject::}{play()}. This state is + commonly used by backends to initialize the \l{Phonon + Overview}{media graph} and loading the source. When + the object leaves the loading state, it will enter the + StoppedState unless an error occurred or another state is + requested through a function call, e.g., + \l{Phonon::}{MediaObject::play()}. + + \value StoppedState + In the stopped state, the media object is ready to play its + current media source. The current + \l{MediaObject::seek()}{position} in the media stream is then 0. + + \value PlayingState + The media object is playing back its media source. + + \value BufferingState + The Player is waiting for data to be able to start or continue + playing. This state is commonly used to wait for media data over a + network connection. + + \value PausedState + The media player has currently paused its playback, i.e., it + stops playing but keeps the current playback position in the + stream. + + \value ErrorState + When a media object enters the error state a problem with the + playback has occurred. The possible errors are grouped into + two categories by Phonon::ErrorType, and the type can be + queried through \l{Phonon::MediaObject::}{errorType()}. A + \l{Phonon::}{FatalError} implies that the playback + cannot continue, but one can still try with a new media + source. With a \l{Phonon::}{NormalError} it might + be possible to continue playback, and a media object may + therefore change state from the ErrorState. + + \sa MediaObject +*/ + +/*! + \enum Phonon::Category + + Sets the category your program should be listed in in the mixer. + + \value NoCategory + Will make use of the default device. + \value NotificationCategory + If the sounds produced are notifications (ping, beep and such) you + should use this category. + \value MusicCategory + If your application is a music player (like a jukebox or media player + playing an audio file). + \value VideoCategory + If the sound is the audio channel of a video. + \value CommunicationCategory + If your applications produces sounds from communication with somebody + else (VoIP, voice chat). + \value GameCategory + Sound produced by a computer game should go into this category. + \value AccessibilityCategory + Sounds produced for accessibility (e.g., Text-To-Speech) + \omitvalue LastCategory + Holds the largest value of categories. + \omitvalue AccessibilityCategory + + A Jukebox will set this to Music, a VoIP program to Communication, a + DVD player to video, and so on. + + \note These categories can also become useful for an application that + controls the volumes automatically, like turning down the music when a call + comes in, or turning down the notifications when the media player knows + it's playing classical music. +*/ + +/*! + \enum Phonon::ErrorType + + This enum describes the severity when an error has occurred during + playback. + + After a media object has entered the \l{Phonon::}{ErrorState}, one + can query the type of error from + \l{Phonon::}{MediaObject::errorType()}. Note that you should query + the error when receiving the + \l{Phonon::}{MediaObject::stateChanged()} signal, because the + error type will be lost if the media object leaves the error + state. + + \value NoError No error. MediaObject::errorType() returns this if + MediaObject::state() != Phonon::ErrorState. + + \value NormalError An error has occurred with the playback of the current + source. It might be possible to continue playback, for instance, if only the + audio stream in a video cannot be played back. The media object will then + leave the error state again. + + \value FatalError. Something important does not work. Your program cannot continue + the playback of the current source, but it might be possible to try another. + + \sa MediaObject::errorType() +*/ + +/*! + \fn QString Phonon::categoryToString(Category c) + + Returns a (translated) string to show to the user identifying the given + Category (\a c). +*/ + +/*! + \enum Phonon::ObjectDescriptionType + \relates Phonon::ObjectDescription + + This enum defines the type of information that is contained in a + \l{Phonon::}{ObjectDescription} object. + + \value AudioOutputDeviceType An audio output device (\l{Phonon::}{AudioOutputDevice}). + This can be soundcards (with different drivers), + sound servers, or other virtual outputs like playback on a different + computer on the network. + + \value EffectType An audio effect (\l{Phonon::}{EffectDescription}). + \omitvalue SubtitleType + \omitvalue AudioCaptureDeviceType + \omitvalue AudioChannelType +*/ + +/*! + \typedef Phonon::AudioOutputDevice + \relates Phonon::ObjectDescription + + This typedef of \l{Phonon::}{ObjectDescription} describes an audio output + device, such as soundcards (with different drivers), sound servers, or other + virtual outputs like playback on a different computer on the network. + + \omit + For Hardware devices the backend should use libkaudiodevicelist + (AudioDevice and AudioDeviceEnumerator) which will list removable + devices even when they are unplugged and provide a unique identifier + that can make backends use the same identifiers. + \endomit + + A list of available devices is given by the backend with + Backendcapabilities::availableAudioOutputDevices() + + \snippet doc/src/snippets/phononobjectdescription.cpp 1 + +*/ + +/*! + \fn Phonon::phononVersion() + \inmodule Phonon + \since 4.5 + + Returns the Phonon version. +*/ + +/*! + \class Phonon::ObjectDescription + \inmodule Phonon + \inheaderfile Phonon/ObjectDescription + \since 4.4 + \brief The ObjectDescription class provides information about Phonon objects. + + Phonon currently uses this class to describe audio effects and + audio output devices - using the typedefs AudioOutputDevice and + EffectDescription. The type of an ObjectDescription is also + described through the \l{Phonon::}{ObjectDescriptionType} enum. + Objects of the same \l{Phonon::ObjectDescriptionType}{type} are + uniquely identified by an index(). + + The class gives a description() and a name() of the object, both + of which are strings appropriate for end users of a Phonon + application. You can also check whether the device or effect + described is \l{isValid()}{valid}. This does not guarantee that + the device or effect functions as expected, but that the + ObjectDescription describes an existing device or effect. + + Audio output devices and effect descriptions are used to select + the audio output device to be used for playback and to create + effects; we show examples of this in the snippet below. The + available descriptions can be fetched with + \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()} + and \l{Phonon::BackendCapabilities::}{availableAudioEffects()} + static functions in the Phonon::BackendCapabilities namespace + + \snippet doc/src/snippets/phononobjectdescription.cpp 0 + + Other types of ObjectDescriptions might be possible in the future, + e.g., descriptions of audio capture devices, such as microphones. + + \omit Not implemented yet. + Need a new paragraph on that some descriptions 'belong + together', such as chained audio effects. + + Some parts give the end user choices, e.g. what source to capture + audio from. These choices are described by the name and + description methods of this class and identified with the id + method. Subclasses then define additional information like which + audio and video choices belong together. \endomit + + \sa Phonon::AudioOutputDevice, Phonon::EffectDescription, {Capabilities Example}, {Phonon Module} +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription() + \brief constructs a new object description. + \internal +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription (int index, const QHash & properties) + \internal +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription(const QExplicitlySharedDataPointer &dd) + \internal +*/ + +/*! + \fn static inline ObjectDescription Phonon::ObjectDescription::fromIndex(int index) + \internal + + \omit Currently indices are not unique for all ObjectDescription types, making + the behavior of this function undefined. \endomit + + Returns a new description object that describes the + device/effect/codec/... with the given \a index. +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::operator==(const ObjectDescription &otherDescription) const + + Returns \c true if this ObjectDescription describes the same + object as \a otherDescription; otherwise, returns \c false. +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::operator!=(const ObjectDescription &otherDescription) const + Returns \c false if this ObjectDescription describes the same + as \a otherDescription; otherwise, returns \c true. +*/ + +/*! + \fn inline QString Phonon::ObjectDescription::name() const + + Returns a string appropriate for a user to select between + object descriptions, e.g., from a QComboBox. + + \sa description() +*/ + +/*! + \fn inline QString Phonon::ObjectDescription::description() const + + Returns a more extensive description than the name() function. + + For example, in the case of \l{Phonon::}{AudioOutputDevice}s, this + text should make clear which sound source is described; this is + sometimes hard to describe or understand from just the name. + + The text is appropriate to present to an end user in for example + tool tips of items, with the name()'s as text, in a QComboBox. + +*/ + +/*! + \fn inline QVariant Phonon::ObjectDescription::property(const char *name) const + + Returns the property named \a name. A property can be used for + extended information, such as the manufacturer of a sound card. The + information will usually be given as text. + + If the property is not set an invalid QVariant is returned. + + Qt's backends do not use properties at the time of this writing. + + \sa propertyNames() +*/ + +/*! + \fn inline QList Phonon::ObjectDescription::propertyNames() const + + Properties can be used for extended information about a + ObjectDescription, e.g., a manufacturer of a sound card. The + information will usually be given text. + + This function returns all names that return valid data when + property() is called. + + Currently, Qt backends do not use properties for their object + descriptions. + + \sa property() +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::isValid() const + + Returns true if the device or effect described exists. + + An ObjectDescription that is invalid, will also have an + index() of -1. + + \sa index() +*/ + +/*! + \fn inline int Phonon::ObjectDescription::index() const + + Returns a unique identifier for this ObjectDescription. Used + internally to distinguish between the descriptions. + + Notice that the identifiers are only unique to the type of + description, e.g., \l{Phonon::}{AudioOutputDevice} or + \l{Phonon::}{EffectDescription}. +*/ + +/*! + \class Phonon::ObjectDescriptionPrivate + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::StreamInterface + \inmodule Phonon + \since 4.4 + \brief Backend interface to handle media streams (AbstractMediaStream). + \internal +*/ + +/*! + \fn virtual Phonon::StreamInterface::~StreamInterface() +*/ + +/*! + \fn virtual void Phonon::StreamInterface::writeData(const QByteArray &data) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::endOfData() = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::setStreamSize(qint64 newSize) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::setStreamSeekable(bool s) = 0 + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::connectToSource(const MediaSource &mediaSource) + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::needData() + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::enoughData() + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::seekStream(qint64) + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::reset() + \internal +*/ + +/*! + \fn Phonon::StreamInterface::StreamInterface() + \internal + \omit + For subclasses. + \endomit +*/ + +/*! + \class StreamInterfacePrivate + \inmodule Phonon + \internal +*/ + +/*! + \class Phonon::AbstractVideoOutput + \inmodule Phonon + \internal + \since 4.4 + \brief The AbstractVideoOutput class is the common base class for all video output classes. + + \sa VideoWidget +*/ + +/*! + \namespace Phonon::Experimental + \internal +*/ + +/*! + \fn Phonon::AbstractVideoOutput::AbstractVideoOutput(AbstractVideoOutputPrivate &d) + \internal + + Constructor that is called from derived classes. + + \param parent Standard QObject parent. +*/ + +/*! + \class Phonon::AbstractVideoOutputPrivate + \inmodule Phonon + \internal + \since 4.4 +*/ + +/*! + \class Phonon::VolumeFaderEffect + \inmodule Phonon + \internal + \since 4.4 + + This effect differs from gradually changing the output volume in that + a dedicated effect can change the volume in the smallest possible + steps while every other volume control will make more or less + noticeable steps. + + \sa AudioOutput::volume() +*/ + +/*! + \property Phonon::VolumeFaderEffect::volume + + This is the current volume of the output as voltage factor. + Setting this property changes the volume immediately. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% + + \sa volumeDecibel +*/ + +/*! + \property Phonon::VolumeFaderEffect::volumeDecibel + + This is the current volume of the output in decibel. + Setting this property changes the volume immediately. + + 0 dB means no change in volume, -6dB means an attenuation of the + voltage to 50% and an attenuation of the power to 25%, -inf dB means + silence. + + \sa volume +*/ + +/*! + \property Phonon::VolumeFaderEffect::fadeCurve + + This property holds the fade curve to be used for the fadeIn(), fadeOut() + and fadeTo() slots. + + Defaults to Fade3Decibel. + + \sa FadeCurve +*/ + +/*! + \enum Phonon::VolumeFaderEffect::FadeCurve + Determines the curve of the volume change. + + \value Fade3Decibel Crossfade curve/fast fade out. + This is the default fade curve. + \value Fade6Decibel Linear fade out. + \value Fade9Decibel Slow fade out. + \value Fade12Decibel A more extreme version of the -9dB fade. + + \bold{Notes:} + + \c Fade3Decibel is often the best fade for a crossfade, as after half + of the time the volume reached -3dB. This means that half the + possible power (which is proportional to the square of the + voltage) is reached. Summed, the maximum power of two audio + signals fading with a -3dB curve will always be equal. + + For fading in or out the -3dB curve is too abrupt in the end. + + With a -6dB fade curve, a volume of -6dB is reached after half of + the fading time. -6dB is equal to half of the voltage meaning + that the voltage multiplier changes linearly from the start + of the fade to the end. + + With the \c Fade9Decibel fade, a volume of -9dB is reached after + half of the fade time, so the fade is fast in the beginning and + slow at the end. This is a good fade for ending music. +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeIn(int fadeTime) + + Tells the Fader to change the volume from the current volume to 100% + in \a fadeTime milliseconds. + + Short for \c fadeTo(1.0, fadeTime). + + \param fadeTime the fade duration in milliseconds + + \sa fadeTo(), volume +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeOut(int fadeTime) + + Tells the Fader to change the volume from the current volume to 0% + in \a fadeTime milliseconds. + Short for \c fadeTo(0.0, fadeTime). + + \param fadeTime the fade duration in milliseconds + + \sa fadeTo +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeTo(float volume, int fadeTime) + + Tells the Fader to change the volume from the current value to + \a volume in \a fadeTime milliseconds. + + \sa fadeIn(), fadeOut() +*/ + +/*! + \class Phonon::VolumeFaderEffectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::VolumeFaderInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual Phonon::VolumeFaderInterface::~VolumeFaderInterface() + \internal +*/ + +/*! + \fn virtual float Phonon::VolumeFaderInterface::volume() const + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::setVolume(float) + \internal +*/ + +/*! + \fn virtual Phonon::VolumeFaderEffect::FadeCurve Phonon::VolumeFaderInterface::fadeCurve() const + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::setFadeCurve(Phonon::VolumeFaderEffect::FadeCurve) + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::fadeTo(float, int) + \internal +*/ + +/*! + \class Phonon::AbstractMediaStream + \inmodule Phonon + \internal + \since 4.4 + \brief The AbstractMediaStream class is the base class for custom media data streams. + \inheaderfile Phonon/AbstractMediaStream + + This class is subclassed to provide custom data streams for + \l{Phonon::}{MediaSource}s. + + The \l{Phonon::}{MediaSource} knows how to handle the most common + media sources, such as files and CD. If you need to fetch + multimedia from other sources, you can reimplement this class, + which can be used by a \l{Phonon::}{MediaSource}. + + When a backend needs more data from the stream, needData() will be + called. You must then use writeData() to write the data to the + backend. You can either write one time and wait for a new + needData() call, or continue to write data until you receive an + enoughData() call. When the stream is at its end, call endOfData() + instead of writeData(). + + Before the custom stream is passed to a \l{Phonon::}{MediaSource}, + setStreamSize() needs to be called, and also setStreamSeekable() + (if the stream is seekable). A good place to do this work is in + the constructor. A seekable stream must also reimplement + seekStream(). + + We show two examples. The first writes data repeatedly until it + receives the enoughData() call, while the second only writes once + and waits for a new needData() call. + + Example where data is written repeatedly. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 0 + + Example where data is written once: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 1 + + \sa Phonon::MediaSource, Phonon::MediaObject + +*/ + +/*! + \fn Phonon::AbstractMediaStream::AbstractMediaStream(QObject *parent = 0) + \internal + + Constructs an AbstractMediaStream object with the given \a parent. + +*/ + +/*! + \fn qint64 Phonon::AbstractMediaStream::streamSize() const + + Returns the stream size that was set with setStreamSize(). + + A negative value means that the length of the stream cannot be known. + + Defaults to 0. + + \sa setStreamSize() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::setStreamSize(qint64 size) + + Sets the \a size of the stream in number of bytes. + + A negative value means that the length of the stream cannot be known. + + Defaults to 0. + + This function has to be called. A backend will not call needData() + until the stream size is set. + + \sa streamSize() + +*/ + +/*! + \fn bool Phonon::AbstractMediaStream::streamSeekable() const + + Returns whether your data stream is set as seekable. + + Defaults to \c false. + + \sa setStreamSeekable() + +*/ + +/*! + \fn void Phonon::AbstractMediaStream::setStreamSeekable(bool s) + + Sets whether your data stream is seekable. \a s should be true if + the stream is seekable; otherwise false. + + Defaults to \c false. + + If you set this to \c true you have to implement the seekStream() + function. + + \sa streamSeekable() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::writeData(const QByteArray &data) + + Sends the media \a data to the backend for decoding. + + Use this function to send data to the backend after needData() has + been called. + + If your stream is a push stream, data should be written until the + enoughData() function is called. For a pull stream, write data + once before the call to needData() function returns. + + If the data is depleted, call endOfData() instead of writeData(). + + \warning Don't call this function before the first needData() is emitted. + + \sa needData(), endOfData() + +*/ + +/*! + \fn void Phonon::AbstractMediaStream::endOfData() + + Tells the backend that the media data stream is at its end. + + \warning Don't call this function before the first needData() is emitted. + + \sa writeData(), needData() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::error(Phonon::ErrorType errorType, const QString &errorString) + + If an I/O error occurs you should call this function to make + MediaObject go into ErrorState. \c errorType classifies the error, + while \a errorString is a textual description of the error suitable + for users of Phonon applications. + + \sa MediaObject::errorType(), MediaObject::errorString() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::reset() = 0 + + Reimplement this function to reset the stream. Subsequent calls to writeData should start + from the first position of the data unless a seek is requested. + + The function is necessary for the case where a non-seekable MediaStream is + played more than once. For a seekable stream the implementation can simply call + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 2 + + \sa writeData(), needData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::needData() = 0 + + Reimplement this function to be notified when the backend needs data. + + When this function is called you should write data to the backend + (See writeData()). + + \sa writeData(), endOfData(), enoughData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::enoughData() + + If your stream is a push stream, reimplement this function to be + notified when the backend has enough data and your stream object + may take a break. + + This method is important for pushing data to the backend in order + to not fill the backend buffer unnecessarily. + + \sa needData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::seekStream(qint64 offset) + + Reimplement this function if your stream is seekable. + + When this function is called the next call to writeData has to be at the + requested \a offset. + + \warning Do not call the parent implementation. + + \sa setStreamSeekable(), streamSeekable(), needData() +*/ + +/*! + \class Phonon::BackendInterface + \inmodule Phonon + \since 4.4 + \brief Main Backend class interface + \internal + + This interface defines the main factory of the backend. The createObject() function creates all the + objects needed by the frontend. + + The objectDescriptionIndexes and objectDescriptionProperties functions return information about + available devices, effects and codecs. + + An implementation could look like this: + \snippet snippets/phonon/samplebackend/main.cpp snippet + +*/ + +/*! + \fn virtual Phonon::BackendInterface::~BackendInterface() + \internal + + Silence gcc's warning. +*/ + +/*! + \enum Phonon::BackendInterface::Class + \internal + + Classes that the createObject() function has to handle. + + \value MediaObjectClass Request to return a \c MediaObject object. + \value VolumeFaderEffectClass Request to return a \c VolumeFaderEffect + object. + \value AudioOutputClass Request to return an \c AudioOutput object. + \value AudioDataOutputClass Request to return an \c AudioDataOutput object. + \value VisualizationClass Request to return a \c Visualization object. + \value VideoDataOutputClass Request to return a \c VideoDataOutput object. + \value EffectClass Request to return a \c Effect object. + Takes an additional int that specifies the effect ID. + \value VideoWidgetClass Request to return a \c VideoWidget object. +*/ + +/*! + \fn virtual QObject *Phonon::BackendInterface::createObject(Class c, QObject *parent, const QList &args = QList()) = 0 + \internal + + Returns a new instance of the requested class. + + \param c The requested class. + \param parent The parent object. + \param args Additional arguments (documented in Class). +*/ + + +/*! + \fn virtual QList Phonon::BackendInterface::objectDescriptionIndexes(ObjectDescriptionType type) const = 0 + \internal + + Returns the unique identifiers for the devices/effects/codecs of the given \a type. + + \param type see ObjectDescriptionType +*/ + +/*! + \fn virtual QHash Phonon::BackendInterface::objectDescriptionProperties(ObjectDescriptionType type, int index) const = 0 + \internal + + Given a unique identifier that was returned from objectDescriptionIndexes this function + returns a hash mapping property names to values. + + The property "name" must always be present. All other properties are optional. + + \table + \header \o Property \o Description + \row \o name \o The name of the device/effect/codec/... + \row \o description \o A text explaining what this device/effect/codec/... is/can do + \row \o icon \o An icon name (using the freedesktop naming scheme) or a QIcon for this + device/effect/codec/... + \row \o available \o A bool telling whether the device is present or unplugged. + \endtable + + \param type see ObjectDescriptionType + \param index The unique identifier that is returned from objectDescriptionIndexes +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::startConnectionChange(QSet) = 0; + \internal + + When this function is called the nodes given in the parameter list should + not lose any signal data when connections are changed. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::connectNodes(QObject *, QObject *) = 0 + \internal + + Defines a signal connection between the two given nodes. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::disconnectNodes(QObject *, QObject *) = 0 + \internal + + Cuts a signal connection between the two given nodes. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::endConnectionChange(QSet) = 0 + \internal + + When this function is called the nodes given in the parameter list may lose + signal data when a port is not connected. +*/ + +/*! + \fn virtual QStringList Phonon::BackendInterface::availableMimeTypes() const = 0 + \internal + + Returns all available MIME types. +*/ + +/*! + \class Phonon::MediaSource + \inmodule Phonon + \inheaderfile Phonon/MediaSource + \since 4.4 + \brief The MediaSource class provides multimedia data for media objects. + + The MediaSource class manages a source of multimedia content, such + as a music or video file, of which data is given to a + \l{Phonon::}{MediaObject}. + + The media source knows how fetch its data from several sources, + e.g., from files, a QIODevice, or a CD. The possible source types + are described by the \l{MediaSource::}{Type} enum. The type of the + source is set by the media source itself, and is dependent on the + constructor used to create it. Note that it is possible to provide + data from any source by implementing a QIODevice. + + The class has several functions to acquire information about the + source it manages, e.g., fileName() and url(). The return from + these functions are dependent on the type() of the media source. + + Normally, a programmer does not need to be concerned with media + sources. It's constructors are implicit, so one can, for instance, + send an URL or filename directly to the constructors of the + \l{Phonon::}{MediaObject}. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 3 + + A MediaSource object cannot be reused for another multimedia + source. It is possible to play the same source again, and also + stop and start a non-seekable media source, such as a radio + stream, with the same MediaSource object. + + \section1 Qt Backends + + Currently, Qt's backends support files in local and remote + locations. Support for other sources, such as CD/DVD, are planned + for the future. + + \sa MediaObject, {Phonon Module} +*/ + +/*! + \enum Phonon::MediaSource::Type + + Identifies the type of media described by the MediaSource object. + + \value Invalid The MediaSource object does not describe any valid source. + \value LocalFile The MediaSource object describes a local file. + \value Url The MediaSource object describes an URL, which can be either a + local file or a file on the network. + \value Disc The MediaSource object describes a disc, e.g., a CD. + \value Stream The MediaSource object describes a data stream. + This is the type used for \l{QIODevice}s. Note + that a stream opened with a QUrl, will still be of the Url type. + + \sa MediaSource::type() +*/ + +/*! + \fn Phonon::MediaSource::MediaSource() + \internal + + Creates an invalid MediaSource object. + + \sa Invalid +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const QString &fileName) + + Creates a MediaSource object for the file specified by \a + fileName. You can also use this constructor with \l{The Qt + Resource System}{Qt resources} + + \omit + \param fileName file name of a local media file or a Qt resource that was compiled in. + \endomit +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const QUrl &url) + + Creates a MediaSource object for a the URL specified by \a url. + + If the multimedia content you would like to play back is on a + remote network location, you should use this constructor; though, + it also possible to specify an URL to a local file. + + \sa QUrl +*/ + + +/*! + \fn Phonon::MediaSource::MediaSource(Phonon::DiscType discType, const QString &deviceName = QString()) + + Creates a MediaSource object for the type of disc specified by \a discType in the named + device referred to by \a deviceName. + + \note \a deviceName is a platform dependent device name. It can be useful to specify this + if the computer has more than one CD drive. On KDE, it is recommended to use the Solid + hardware discovery framework to retrieve the device name in a portable way. +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(AbstractMediaStream *stream) + \internal + Creates a MediaSource object for a data stream. + + Your application can provide the media data by subclassing AbstractMediaStream and + passing a pointer to that object. Phonon will never delete the \a stream. + + \param stream The AbstractMediaStream subclass to provide the media data. + + \sa setAutoDelete +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(QIODevice *ioDevice) + + Creates a MediaSource object for the QIODevice specified by \a ioDevice. + + This constructor can be very handy in the combination of + QByteArray and QBuffer. + + If you need to fetch multimedia data from a source that is not + supported by MediaSource, you should subclass QIODevice and use + this MediaSource constructor. It is important that you reimplement + QIODevice::isSequential(), as it is used by MediaSource to + determine if the media source is seekable. + + \a ioDevice is an arbitrary readable QIODevice subclass. If the device is not opened + MediaSource will open it as QIODevice::ReadOnly. + + \note Sequential devices can also be used, but MediaObject::isSeekable() will + return false as a result. + + \sa setAutoDelete() +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(MediaSourcePrivate &) + \internal +*/ + +/*! + \fn Phonon::MediaSource::~MediaSource() + + Destroys the MediaSource object. You should never delete a + MediaSource yourself, the MediaObject will handle this. + +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const MediaSource &other) + + Constructs a copy of the \a other media source. + + This constructor is fast thanks to explicit sharing. +*/ + +/*! + \fn MediaSource &Phonon::MediaSource::operator=(const MediaSource &other) + + Assigns the \a other media source to this media source and returns a + reference to it. + + This operation is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::MediaSource::operator==(const MediaSource &other) const + + Returns true if this media source is equal to the \a other media source; + otherwise returns false. +*/ + +/*! + \fn void Phonon::MediaSource::setAutoDelete(bool enable) + + If \a enable is true, the media source will take ownership of the + object passed in the \l{Phonon::}{MediaSource}'s constructor + object that was passed in the constructor; otherwise, the + programmer is responsible for deletion of this object. + + This setting is false by default. If you enable it, you should + only access the stream or device as long as you keep the media + source object around. As long as you keep the media source + wrapping the stream or device, the object will not get deleted. + + \sa autoDelete() +*/ + +/*! + \fn bool Phonon::MediaSource::autoDelete() const + + Returns the setting of the auto-delete option. The default is + false. + + \sa setAutoDelete() +*/ + +/*! + \fn Type Phonon::MediaSource::type() const + + Returns the type of the MediaSource (depends on the constructor + that was used). + + \sa Type +*/ + +/*! + \fn QString Phonon::MediaSource::fileName() const + + Returns the file name of the MediaSource if type() == + LocalFile; otherwise, returns QString(). + + \sa type() +*/ + +/*! + \fn QUrl Phonon::MediaSource::url() const + Returns the URL of the MediaSource if type() == URL or type() == LocalFile; + otherwise returns QUrl(). + + \sa type() +*/ + +/*! + \fn Phonon::DiscType Phonon::MediaSource::discType() const + Returns the disc type of the MediaSource if type() == Disc; otherwise + returns NoDisc. + + \sa type() +*/ + +/*! + \fn QString Phonon::MediaSource::deviceName() const + + Returns the device name of the MediaSource if type() == Disc; otherwise + returns QString(). + + \sa type() +*/ + +/*! + \fn AbstractMediaStream *Phonon::MediaSource::stream() const + \internal + Returns the media stream of the MediaSource if type() == Stream; otherwise + returns 0. + QIODevices are handled as streams, too. +*/ + +/*! + \class Phonon::MediaSourcePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::SeekSlider + \inmodule Phonon + \inheaderfile Phonon/SeekSlider + \since 4.4 + \brief The SeekSlider class provides a slider for seeking to positions in media streams. + + The SeekSlider connects to a \l{Phonon::}{MediaObject}, and + controls the seek position in the object's media stream. + + The slider will connect to the necessary signals to keep track of + the sliders maximum, minimum, and current values. It will also + disable itself for non-seekable streams, and update the media + object when the current value of the slider changes. + + Here follows a typical example of SeekSlider usage: + + \snippet doc/src/snippets/seekslider.cpp 0 + + \sa Phonon::VolumeSlider, Phonon::VideoWidget, {Music Player Example}, {Phonon Module} + +*/ + +/*! + \property Phonon::SeekSlider::iconVisible + \brief whether the icon next to the slider is visible + + By default the icon is visible if the platform provides an icon; else + it's hidden. + +*/ + +/*! + \property Phonon::SeekSlider::tracking + \brief whether slider tracking is enabled + + If tracking is enabled (the default), the media seeks + while the slider is being dragged. If tracking is + disabled, the media seeks only when the user + releases the slider. +*/ + +/*! + \property Phonon::SeekSlider::pageStep + \brief the page step interval + + The larger of two natural steps that a slider provides and + typically corresponds to the user pressing PageUp or PageDown. + + Defaults to 5 seconds. +*/ + +/*! + \property Phonon::SeekSlider::singleStep + \brief the single step interval + + The smaller of two natural steps that a slider provides and + typically corresponds to the user pressing an arrow key. + + Defaults to 0.5 seconds. +*/ + +/*! + \property Phonon::SeekSlider::orientation + \brief the orientation of the slider + + The orientation must be Qt::Vertical or Qt::Horizontal (the default). +*/ + +/*! + \property Phonon::SeekSlider::iconSize + \brief the icon size used for the mute button/icon. + + The default size is defined by the GUI style. +*/ + +/*! + \fn explicit Phonon::SeekSlider::SeekSlider(QWidget *parent = 0) + + Constructs a seek slider widget with the given \a parent. +*/ + +/*! + \fn explicit Phonon::SeekSlider::SeekSlider(MediaObject *media, QWidget *parent = 0) + + Constructs a seek slider widget for the specified \a media with the + given \a parent. +*/ + +/*! + \fn Phonon::SeekSlider::~SeekSlider() + Destroys the seek slider. +*/ + +/*! + \fn Phonon::MediaObject *Phonon::SeekSlider::mediaObject() const + + Return the media object this SeekSlider controls. +*/ + +/*! + \class Phonon::SeekSliderPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn void Phonon::SeekSlider::setMediaObject(MediaObject *media) + + Sets the media object to be controlled by this slider to the \a media specified. +*/ + +/*! + \class Phonon::VideoPlayer + \inmodule Phonon + \inheaderfile Phonon/VideoPlayer + \since 4.4 + \brief The VideoPlayer widget is used to perform playback of video. + + With VideoPlayer you can get results quickly and easily. You can + do the standard playback tasks like play(), pause(), and stop(), + but also set a playback volume and seek - if the media and backend + supports seeking. + + VideoPlayer is provided for convenience and removes the need to + create a media graph with a \l{Phonon::}{MediaObject}, + \l{Phonon::}{AudioOutput}, and \l{Phonon::}{VideoWidget}. If + you need functionality not supported by the player, you can build + this \l{Building Graphs}{graph} yourself. + + Keep in mind that when the VideoPlayer instance is deleted the + playback will stop. + + Note also that most of the functions in this class are + asynchronous. For instance, a media source may not play + immediately after you call the play() function. + + A play and forget code example: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 4 + + \sa {Phonon Module}, MediaObject +*/ + +/*! + \fn Phonon::VideoPlayer::VideoPlayer(QWidget *parent = 0) + + Constructs a new video widget with a \a parent using + Phonon::VideoCategory as its category. + + \param parent The QObject parent. +*/ + +/*! + \fn Phonon::VideoPlayer::VideoPlayer(Phonon::Category category, QWidget *parent = 0) + + Constructs a new VideoPlayer instance with the specified \a + parent. + + \a category is the category used for the audio output device. +*/ + +/*! + \fn Phonon::VideoPlayer::~VideoPlayer() + + On destruction the playback is stopped, also the audio output is + removed so that the desktop mixer will not show the application + anymore. If you need a persistent audio output don't use + VideoPlayer but MediaObject, VideoPath and VideoOutput. +*/ + +/*! + \fn qint64 Phonon::VideoPlayer::totalTime() const + + Get the total time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn qint64 Phonon::VideoPlayer::currentTime() const + + Get the current time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn float Phonon::VideoPlayer::volume() const + + This is the current volume of the output as voltage factor. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% +*/ + +/*! + \fn bool Phonon::VideoPlayer::isPlaying() const + + Returns true if it is currently playing; otherwise returns false if it + is currently stopped or paused +*/ + +/*! + \fn bool Phonon::VideoPlayer::isPaused() const + + Returns true if it is currently paused; otherwise returns false if it + is currently playing or stopped. +*/ + +/*! + \fn void Phonon::VideoPlayer::load(const Phonon::MediaSource &source) + + Starts pre-loading the media data from the specified \a source and + filling audio buffers in the backend. + + When there's already a media playing (or paused) it will be stopped + (the finished signal will not be emitted). + + \sa MediaObject::setCurrentSource() +*/ + +/*! + \fn void Phonon::VideoPlayer::play(const Phonon::MediaSource &source) + + Plays the media from the given \a source. Starts playback as fast as + possible. + This can take a considerable time depending on the URL and the + backend. + + If you need low latency between calling play() and the sound actually + starting to play on your output device you need to use MediaObject + and be able to set the URL before calling play(). Note that + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 5 + doesn't make a difference: the application should be idle between the + load and play calls so that the backend can start preloading the + media and fill audio buffers. +*/ + +/*! + \fn void Phonon::VideoPlayer::play() + + Continues playback of paused media. Restarts playback of a stopped + (or newly loaded) media. + + \sa MediaObject::play(), play() +*/ + +/*! + \fn void Phonon::VideoPlayer::pause() + + Pauses the playback. + + \sa MediaObject::pause() +*/ + +/*! + \fn void Phonon::VideoPlayer::stop() + + Stops the playback. + + \sa MediaObject::stop() +*/ + +/*! + \fn void Phonon::VideoPlayer::seek(qint64 ms) + + Seeks to the requested time. Note that the backend is free to + ignore the seek request if the media source isn't seekable; you + can check this by asking the media object of the VideoPlayer. + + \snippet doc/src/snippets/videomedia.cpp 0 + + The \a ms parameter is the time in milliseconds from the start of + the media. + + The call is asynchronous, so currentTime() can still be the old + value right after this method was called. If all you need is a + slider that shows the current position and allows the user to + seek, use the class SeekSlider. + + \sa MediaObject::seek(), MediaObject::isSeekable(), mediaObject() +*/ + +/*! + \fn void Phonon::VideoPlayer::setVolume(float volume) + + Sets the \a volume of the output as voltage factor. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% +*/ + +/*! + \fn MediaObject *Phonon::VideoPlayer::mediaObject() const + + Returns the media object being used by the player. + + The media object can be accessed directly instead of using the + \l{VideoPlayer}s convenience functions, e.g., play() and stop(). + It is also possible to give the object to other Phonon widgets, + e.g., a \l{Phonon::}{SeekSlider} or a \l{Phonon::}{VolumeSlider}. + + \sa Phonon::SeekSlider, Phonon::MediaObject +*/ + +/*! + \fn AudioOutput *Phonon::VideoPlayer::audioOutput() const + + Returns the audio output object being used by the player. + +*/ + +/*! + \fn VideoWidget *Phonon::VideoPlayer::videoWidget() const + + Returns the video widget being used by the player. +*/ + +/*! + \fn void Phonon::VideoPlayer::finished() + + This signal is emitted when the playback finished. + +*/ + +/*! + \class Phonon::VideoWidgetPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaObject + \inmodule Phonon + \inheaderfile Phonon/MediaObject + \since 4.4 + \brief The MediaObject class provides an interface for media playback. + + + The media object manages a \l{Phonon::}{MediaSource}, which + supplies the media object with multimedia content, e.g., from a + file. A playback in Phonon is always started by calling the + \l{Phonon::MediaObject::}{play()} function. + + The state of play (play, pause, stop, seek) is controlled by the + media object, and you can also query the current + \l{Phonon::MediaObject::}{state()}. It keeps track of the playback + position in the media stream, and emits the + \l{Phonon::MediaObject::}{tick()} signal when the current position + in the stream changes. + + Notice that most functions of this class are asynchronous, so you + cannot rely on that a state is entered after a function call + before you receive the \l{Phonon::MediaObject::}{stateChanged()} + signal. The description of the \l{Phonon::}{State} enum gives a + description of the different states. + + Before play() is called, the media object should be connected to + \l{Sinks}{output nodes}, which outputs the media to the + underlying hardware. The output nodes required are dependent on + the contents of the multimedia file that is played back. Phonon + has currently two output nodes: the \l{Phonon::}{AudioOutput} for + audio content and \l{Phonon::}{VideoWidget} for video content. If + a \l{Phonon::}{MediaSource} contains both audio and video, both + nodes need to be connected to the media object. + + \snippet snippets/phonon.cpp 4 + \snippet snippets/phonon.cpp 5 + + The media object can queue sources for playback. When it has + finished to play one source, it will start playing the next in the + queue; the new source is then removed from the queue. The + queue can be altered at any time. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 7 + + You can also make use of the + \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is + guaranteed to be emitted in time for altering the queue. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 8 + + When playback is finishing, i.e., when a media source has been + played to the end and the queue is empty, several signals are + emitted. First, the media object will emit aboutToFinish() - + shortly before the playback has finished - and then finished(). + The stateChanged() signal will also be emitted with + \l{Phonon::}{PausedState}, which is the state the media object + takes when the playback is finished. If you wish to enter another + state, you can connect a slot to finished() and set a new state + there. + + The media object resolves the meta information, such as title, + artist, and album. The meta data is not resolved immediately after + a new source is provided, but will be resolved before the object + leaves the \l{Phonon::}{LoadingState}. The data is queried by + string keys - which should follow the Ogg Vorbis specification + \l http://xiph.org/vorbis/doc/v-comment.html - or by using the + \l{Phonon::}{MetaData} enum. The data available will depend on the + type and content of the individual media files. metaDataChanged() + will be emitted when the media object has resolved new meta data. + + Errors encountered during playback and loading of media sources + are reported by emitting a state changed signal with + \l{Phonon::}{ErrorState}. The severity of the error can be queried + by the \l{Phonon::}{ErrorType}. With a \l{Phonon::}{NormalError}, + it might be possible to continue the playback, for instance, if + only audio playback fails for a media source which also has video. + A \l{Phonon::}{FatalError} indicates that Phonon cannot continue + playback of the current source, but it is possible to try with a + different one. A user readable error message is given by + errorString(). + + \sa Phonon::MediaSource, Phonon::AudioOutput, VideoWidget, + {Music Player Example}, {Phonon Overview}, Phonon::VideoPlayer, + Phonon::createPlayer(), {Phonon Module} + +*/ + +/*! + \property Phonon::MediaObject::transitionTime + \brief Defines the time between playback of two media sources + in the media queue. + + A positive transition time defines a gap of silence between queued + media sources. + + A transition time of 0 ms requests gapless playback (i.e., the + next source in the media queue starts immediately after the + playback of the current source finishes). + + A negative transition time defines a crossfade between the queued + media sources. + + Defaults to 0 (gapless playback). + + \warning This feature might not work reliably with every + backend. +*/ + +/*! + \property Phonon::MediaObject::prefinishMark + \brief the time when the prefinishMarkReached signal is emitted before playback ends. + + This property specifies the time in milliseconds the + prefinishMarkReached() signal is emitted before the playback + finishes. A value of \c 0 disables the signal. The signal is only + emitted for the last source in the \l{queue()}{media queue}. + + Defaults to \c 0 (disabled). + + \warning For some media data the total time cannot be determined + accurately, therefore the accuracy of the prefinishMarkReached signal + can be bad sometimes. Still, it is better to use this method than to + look at totalTime() and currentTime() to emulate the behavior + because the backend might have more information available than your + application does through totalTime() and currentTime(). + + \sa prefinishMarkReached() +*/ + +/*! + \property Phonon::MediaObject::tickInterval + \brief The time interval in milliseconds between two ticks. + + The tick() signal is emitted continuously during playback. + The tick interval is the time that elapses between the emission of two tick signals. + If you set the interval to \c 0 the tick signal gets disabled. + + The tick() signal can, for instance, be used to update widgets + that show the current position in the playback of a media source. + + Defaults to \c 0 (disabled). + + \warning The back-end is free to choose a different tick interval close + to what you asked for. This means that the following code \c may fail: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 9 + On the other hand the following is guaranteed: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 10 + + \sa tick() +*/ + +/*! + \fn Phonon::MediaObject::~MediaObject() + + Destroys the MediaObject. +*/ + +/*! + \fn State Phonon::MediaObject::state() const + + Returns the current Phonon::State of the object. + + \sa Phonon::State, stateChanged() +*/ + +/*! + \fn bool Phonon::MediaObject::hasVideo() const + + Check whether the current media source includes a video stream. + + \warning This information is not resolved immediately after a + media object gets a new source. Listen to the hasVideoChanged() + signal instead. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 11 + + Returns \c true if the media contains video data; otherwise, + returns \c false. + + \sa hasVideoChanged() +*/ + +/*! + \fn bool Phonon::MediaObject::isSeekable() const + + Check whether it is possible to seek, i.e., change the + playback position in the media stream. + + \warning This information is not solved immediately after the + media object gets a new media source. The hasVideoChanged() signal + is emitted after this information is available. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 12 + + Returns \c true if the current media may be seeked; otherwise, + returns \c false. + + \sa seekableChanged() +*/ + +/*! + \fn QStringList Phonon::MediaObject::metaData(const QString &key) const + + Returns the strings associated with the given \a key. + + Backends should use the keys specified in the Ogg Vorbis + documentation: \l http://xiph.org/vorbis/doc/v-comment.html + + Therefore the following should work with every backend: + + Note that meta data is not resolved before the \c + metaDataChanged() signal is emitted. + + A typical usage looks like this: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 13 +*/ + +/*! + \fn QStringList Phonon::MediaObject::metaData(Phonon::MetaData key) const + + Returns the strings associated with the given \a key. + + Same as above except that the keys are defined in the + Phonon::MetaData enum. + + \sa metaDataChanged() +*/ + +/*! + \fn QMultiMap Phonon::MediaObject::metaData() const + + Returns all meta data in a multi map. + + \sa metaDataChanged() +*/ + +/*! + \fn QString Phonon::MediaObject::errorString() const + + Returns a human-readable description of the last error that occurred. + The strings given may vary between backends. + + The error description can be used to give a message to the user - + and the developer - when the stateChanged() signal is emitted with + \l{Phonon::}{ErrorState}. + + \section1 Qt Backends + + On Windows, Qt fetches its error messages from the DirectShow + backend. This usually includes an error number, which can be + looked up in the DirectShow documentation: + \l{http://msdn.microsoft.com/archive/default.asp?url=/archive/en-us/dx81_c/directx_cpp/htm/errorandsuccesscodes.asp}. + + On Linux and Mac, the error strings are not fetched directly from + the backend, but are created in the backend. + + \sa Phonon::ErrorState, stateChanged() +*/ + +/*! + \fn ErrorType Phonon::MediaObject::errorType() const + + Tells your program what to do about the last error that occurred. + Use this function after receiving a stateChanged() signal with + \l{Phonon::}{ErrorState}. + + \sa Phonon::ErrorType, Phonon::ErrorState, stateChanged() +*/ + +/*! + \fn MediaSource Phonon::MediaObject::currentSource() const + + Returns the current media source, i.e., the media source that is + being played back. The current source is either set with + setCurrentSource() or taken from the media queue() when a media + source has finished playing. + + \sa setCurrentSource() +*/ + +/*! + \fn void Phonon::MediaObject::setCurrentSource(const MediaSource &source) + + Set the media source the MediaObject should use. + + After the media object receives a new source, it will enter the + \l{Phonon::}{LoadingState}. When it is ready to play, it + enters the \l{Phonon::}{StoppedState} unless another state + has been requested, e.g., by calling play(). + + \a source is the MediaSource object to the media data. You can + just as well use a QUrl or QString (for a local file) here. + + We show an example: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 14 + + \sa currentSource() +*/ + +/*! + \fn QList Phonon::MediaObject::queue() const + + Returns the queued media sources. + + This does list does not include the current source, + returned by currentSource(). + + \sa enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::setQueue(const QList &sources) + + Set the \a sources to play when the current source has finished. + + This function will overwrite the current queue. + + \sa clearQueue(), enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::setQueue(const QList &urls) + + Set the \a urls to play when the current media has finished. + + This function overwrites the current queue. + + \sa clearQueue(), enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const MediaSource &source) + + Appends \a source to the queue. + + You can use this function to provide the next source after the + aboutToFinish() signal has been emitted. + + \sa aboutToFinish(), setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const QList &sources) + + Appends multiple \a sources to the queue. + + \sa setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const QList &urls) + + Appends the URLs in \a urls to the media source queue. + + The function will create \l{MediaSource}s from the \l{QUrl}s, and + append these to the queue. + + \sa setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::clearQueue() + + Clears the queue of media sources. + + \sa queue(), enqueue() +*/ + +/*! + \fn qint64 Phonon::MediaObject::currentTime() const + + Returns the current time (in milliseconds), i.e., position in the + media stream, of the file currently being played. + + \sa tick(), totalTime(), remainingTime() +*/ + +/*! + \fn qint64 Phonon::MediaObject::totalTime() const + + Get the total time (in milliseconds) of the file currently being played. + + Returns the total time in milliseconds. + + \warning The total time is not defined before the media object + enters the \l{Phonon::}{LoadingState}. + + \sa totalTimeChanged() +*/ + +/*! + \fn qint64 Phonon::MediaObject::remainingTime() const + + Get the remaining time (in milliseconds) of the file currently being played. + + Returns the remaining time in milliseconds. + + \sa totalTime(), currentTime(), totalTimeChanged() +*/ + +/*! + \fn void Phonon::MediaObject::play() + + Requests playback of the media data to start. + + Playback starts when the stateChanged() signal is emitted with + \l{Phonon::}{PlayingState}. + + If the media object is already in a + \l{Phonon::}{PlayingState}, nothing happens. + + \sa stop(), pause(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::pause() + + Requests playback to pause, and the media object to enter the + \l{Phonon::}{PausedState}. If it was paused already, nothing + changes. + + This function is asynchronous and the media might not be paused + immediately. + + \sa play(), stop(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::stop() + + Requests playback to stop, and the media object to enter the + \l{Phonon::}{StoppedState}. If it was stopped before + nothing changes. + + This function is asynchronous and the media might not be + stopped immediately. + + \sa play(), pause(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::seek(qint64 time) + + Requests a seek to the \a time indicated, specified in milliseconds. + + You can only seek if state() is PlayingState, BufferingState or PausedState. + + The call is asynchronous, so currentTime can still be the old + value right after this method was called. If all you need is a + slider that shows the current position and allows the user to + seek, use the class SeekSlider. + + If the current source of the media object is not seekable, calls + to this functions do nothing. + + \sa SeekSlider, tick() +*/ + +/*! + \fn void Phonon::MediaObject::stateChanged(Phonon::State newstate, Phonon::State oldstate) + + This signal is emitted when the state of the MediaObject has changed. + The \a oldstate and \a newstate parameters indicate the previous + state and current state of the media object. + + If you are only interested in the new state of the media object, you can + connect this signal to a slot that accepts only one State argument. +*/ + +/*! + \fn void Phonon::MediaObject::tick(qint64 time) + + This signal is emitted in intervals defined by the + \l{tickInterval} property. The current position of the media + object in the stream is given by the \a time parameter. The \a + time is specified in milliseconds. + + \sa tickInterval +*/ + +/*! + \fn void Phonon::MediaObject::metaDataChanged() + + This signal is emitted when the media object has resolved new meta + data. This will happen before the media object leaves the + \l{Phonon::}{LoadingState} after a new source has been set. + + This signal is not emitted when the media object removes the + current data, i.e., when a new source is set or an error has + occurred. If you need to know this, you can listen for the + \l{Phonon::}{ErrorState}, and connect to the + \l{Phonon::MediaObject::}{currentSourceChanged()} signal. + + You can get the new meta data with the metaData methods. + + \sa metaData(), currentSourceChanged(), stateChanged(), Phonon::State +*/ + +/*! + \fn void Phonon::MediaObject::seekableChanged(bool isSeekable) + + This signal is emitted when the media object's ability to seek in + the media stream changes. \a isSeekable is true if it is possible + to seek(); otherwise, it is false. + + Change in the ability to seek in the stream usually happens when + the current source changes or when an error occurs. + + \omit Emitted whenever the return value of isSeekable() + changes. \endomit + + Normally you'll check isSeekable() after setting a new media + source, and then let this signal tell you when seeking is + possible. That way you don't have to poll isSeekable(). +*/ + +/*! + \fn void Phonon::MediaObject::hasVideoChanged(bool hasVideo) + + Emitted whenever the return value of hasVideo() changes, i.e., + the media source being played back contains video. + + Normally you'll check hasVideo() first and then let this signal + tell you whether video is available now or not. That way you + don't have to poll hasVideo(). + + \a hasVideo is true when the stream contains video and adding a + VideoWidget will show a video, and false if there is no video data + in the stream and adding a VideoWidget will show an empty (black) + VideoWidget. +*/ + +/*! + \fn void Phonon::MediaObject::bufferStatus(int percentFilled) + + Provides information about the status of the buffer. + + When a MediaObject is in the \l{Phonon::}{BufferingState}, it will + send this signal regularly. \a percentFilled is a number between 0 + and 100 telling you how much the buffer is filled. + + You can use this signal to show a progress bar to the user when + in BufferingState: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 15 + + Note that the \l{Phonon::}{BufferingState} is commonly used when + waiting for data over a network connection, but this might not be + true for all backends. +*/ + +/*! + \fn void Phonon::MediaObject::finished() + + Emitted when the object has finished playback. It is not emitted + if you call stop(), pause() or load(). It is emitted only when the + current media source has finished playing and the media queue() is + empty, or when a \l{Phonon::FatalError}{fatal error} occurs. + + \warning This signal is not emitted when the current source has + finished and there's another source in the queue. It is only + emitted when the queue is empty. + + \sa currentSourceChanged(), aboutToFinish(), prefinishMarkReached() +*/ + +/*! + \fn void Phonon::MediaObject::currentSourceChanged(const Phonon::MediaSource &newSource) + + Emitted when the MediaObject fetches a new MediaSource from the + queue() and before it enters the \l{Phonon::}{LoadingState} for + the new source. The media object will take a new source from the + queue() when it has finished the playback of the + \l{currentSource()}{current source}. + + \a newSource is the source that starts to play at the time the + signal is emitted. +*/ + +/*! + \fn void Phonon::MediaObject::aboutToFinish() + + Emitted before the playback of the whole queue ends. When this + signal is emitted you still have time to enqueue() a new + MediaSource, so that playback continues. + + If you need a signal to be emitted at a specific time before + playback is finished, you should use the prefinishMarkReached() + signal instead. + + \sa enqueue(), prefinishMark, prefinishMarkReached() +*/ + +/*! + \fn void Phonon::MediaObject::prefinishMarkReached(qint32 msecToEnd) + + Emitted when there are only \a msecToEnd milliseconds left + of playback. + + \warning This signal is not emitted when there is another source + in the queue. It is only emitted when the queue is empty. + + \sa setPrefinishMark(), prefinishMark(), aboutToFinish(), finished() +*/ + +/*! + \fn void Phonon::MediaObject::totalTimeChanged(qint64 newTotalTime) + + This signal is emitted as soon as the total time of the media file is + known or has changed. For most non-local media data the total + time of the media can only be known after some time. At that time the + totalTime function can not return useful information. You have + to wait for this signal to know the real total time. + + \a newTotalTime is the length of the media file in milliseconds. + + \sa totalTime() +*/ + +/*! + \fn MediaObject *Phonon::createPlayer(Phonon::Category category, const MediaSource &source = MediaSource()) + + Convenience function to create a MediaObject and AudioOutput + connected by a path. The \l{Phonon::}{MediaObject} return will + have \a source set as its current source and the specified \a + category. + +*/ + +/*! + \class Phonon::MediaObjectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \namespace Phonon::BackendCapabilities + \inmodule Phonon + \since 4.4 + \brief The BackendCapabilities namespace contains functions to describe the capabilities of the multimedia backend. + +*/ + +/*! + \class Phonon::BackendCapabilitiesPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::BackendCapabilities::Notifier + \since 4.4 + \inmodule Phonon + \inheaderfile Phonon/BackendCapabilities + + Notifications about backend capabilities. +*/ + +/*! + \fn void Phonon::BackendCapabilities::Notifier::capabilitiesChanged() + + This signal is emitted if the capabilities have changed. This can + happen if the user has requested a backend change. +*/ + +/*! + \fn void Phonon::BackendCapabilities::Notifier::availableAudioOutputDevicesChanged() + + This signal is emitted when audio output devices were plugged or + unplugged. + + Check BackendCapabilities::availableAudioOutputDevices to get the + current list of available devices. +*/ + +/*! + \fn Notifier *Phonon::BackendCapabilities::notifier() + + Use this function to get a QObject pointer to connect to the capabilitiesChanged signal. + + \return a pointer to a QObject. + + The capabilitiesChanged signal is emitted if the capabilities have changed. This can + happen if the user has requested a backend change. + + To connect to this signal do the following: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 16 + + \sa Notifier::capabilitiesChanged() +*/ + +/*! + \fn QStringList Phonon::BackendCapabilities::availableMimeTypes() + + Returns a list of mime types that the Backend can decode. + + \sa isMimeTypeAvailable() +*/ + +/*! + \fn bool Phonon::BackendCapabilities::isMimeTypeAvailable(const QString &mimeType) + + Often all you want to know is whether one given MIME type can be + decoded by the backend. Use this method in favor of + availableMimeTypes() as it can give you a negative answer without + having a backend loaded. + + Returns true if the given \a mimeType is supported by the backend; + otherwise, returns false. + + \sa availableMimeTypes() +*/ + +/*! + \fn QList Phonon::BackendCapabilities::availableAudioOutputDevices() + + Returns the audio output devices the backend supports. + + \return A list of AudioOutputDevice objects that give a name and + description for every supported audio output device. +*/ + +/*! + \fn QList Phonon::BackendCapabilities::availableAudioEffects() + + Returns descriptions for the audio effects the backend supports. + + \return A list of AudioEffectDescription objects that give a name and + description for every supported audio effect. +*/ + +/*! + \internal + \class ObjectDescriptionModelData + \internal + \inmodule Phonon + \brief Data class for models for ObjectDescription objects. +*/ + +/*! + \typedef Phonon::EffectDescription + \relates Phonon::ObjectDescription + + EffectDescription gives a description of an \l{Processors}{audio + effect}. It is a typedef of the \l{Phonon::}{ObjectDescription} + class. Please see its class description for details. + + EffectDescription is used to create audio \l{Phonon::}{Effect}s, + which can be inserted into a media graph, altering an audio + stream. + + \sa Phonon::ObjectDescription, {Capabilities Example}, {Media + Player} + +*/ + +/*! + \class Phonon::ObjectDescriptionModel + \inmodule Phonon + \internal + \since 4.4 + \brief The ObjectDescriptionModel class provides a model from + a list of ObjectDescription objects. + + ObjectDescriptionModel is a read only model that supplies a list + using ObjectDescription::name() for the text and + ObjectDescription::description() for the tooltip. If set the properties + "icon" and "available" are used to set the decoration and disable the + item (disabled only visually, you can still select and drag it). + + It also provides the methods moveUp() and moveDown() to order the list. + Additionally drag and drop is possible so that + QAbstractItemView::InternalMove can be used. + The resulting order of the ObjectDescription::index() values can then be + retrieved using tupleIndexOrder(). + + An example use case would be to give the user a QComboBox to select + the output device: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 17 + + And to retrieve the selected AudioOutputDevice: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 18 + +*/ + +/*! + \fn inline int Phonon::ObjectDescriptionModel::rowCount(const QModelIndex &parent = QModelIndex()) const + + Returns the number of rows in the model. This value corresponds + to the size of the list passed through setModelData. + + \param parent The optional \a parent argument is used in most models to specify + the parent of the rows to be counted. Because this is a list if a + valid parent is specified the result will always be 0. + + Reimplemented from QAbstractItemModel. + + \sa QAbstractItemModel::rowCount() +*/ + +/*! + \fn inline QVariant Phonon::ObjectDescriptionModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const + + Returns data from the item with the given \a index for the specified + \a role. + If the view requests an invalid index, an invalid variant is + returned. + + Reimplemented from QAbstractItemModel. + + \sa QAbstractItemModel::data(), Qt::ItemDataRole +*/ + +/*! + \fn inline Qt::ItemFlags Phonon::ObjectDescriptionModel::flags(const QModelIndex &index) const + \internal + + Reimplemented to show unavailable devices as disabled (but still + selectable). The \a index of the model index for which to return + flags. + +*/ + +/*! + \fn inline QList Phonon::ObjectDescriptionModel::tupleIndexOrder() const + + Returns a list of indexes in the same order as they are in the + model. The indexes come from the ObjectDescription::index + method. + + This is useful to let the user define a list of preference. +*/ + +/*! + \fn inline int Phonon::ObjectDescriptionModel::tupleIndexAtPositionIndex(int positionIndex) const + + Returns the ObjectDescription::index for the tuple + at the given position \a positionIndex. For example a + QComboBox will give you the currentIndex as the + position in the list. But to select the according + AudioOutputDevice using AudioOutputDevice::fromIndex + you can use this method. + + \param positionIndex The position in the list. +*/ + +/*! + \class Phonon::ObjectDescriptionModelDataPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn inline QMimeData *Phonon::ObjectDescriptionModel::mimeData(const QModelIndexList &indexes) const + \internal + + Returns the MIME data that dropMimeData() can use to create new + items. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::moveUp(const QModelIndex &index) + + Moves the item at the given \a index up. In the resulting list + the items at index.row() and index.row() - 1 are swapped. + + Connected views are updated automatically. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::moveDown(const QModelIndex &index) + + Moves the item at the given \a index down. In the resulting list + the items at index.row() and index.row() + 1 are swapped. + + Connected views are updated automatically. +*/ + +/*! + \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(QObject *parent = 0) + + Constructs a ObjectDescription model with the + given \a parent. +*/ + +/*! + \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(const QList > &data, QObject *parent = 0) + + Constructs a ObjectDescription model with the + given \a parent and the given \a data. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::setModelData(const QList > &data) + + Sets the model data using the list provided by \a data. + + All previous model data is cleared. +*/ + +/*! + \fn inline QList > Phonon::ObjectDescriptionModel::modelData() const + + Returns the model data. + + As the order of the list might have changed this can be different + to what was set using setModelData(). +*/ + +/*! + \fn inline ObjectDescription Phonon::ObjectDescriptionModel::modelData(const QModelIndex &index) const + + Returns one ObjectDescription of the model data for the given \a index. +*/ + +/*! + \fn inline Qt::DropActions Phonon::ObjectDescriptionModel::supportedDropActions() const + + This model supports drag and drop to copy or move + items. +*/ + +/*! + \fn inline bool Phonon::ObjectDescriptionModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) + + Accept drops from other models of the same ObjectDescriptionType. + + The \a data is dropped at the given \a row and \a column; you + also receive the \a parent model index. + + If a valid \a parent is given the dropped items will be inserted + above that item. +*/ + +/*! + \fn inline bool Phonon::ObjectDescriptionModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex()) + + Removes count rows starting with the given row. + + If a valid \a parent is given no rows are removed since this is a + list model. + + Returns true if the rows were successfully removed; otherwise returns false. +*/ + +/*! + \fn inline QStringList Phonon::ObjectDescriptionModel::mimeTypes() const + + Returns a list of supported drag and drop MIME types. Currently + it only supports one type used internally. +*/ + +/*! + \class Phonon::EffectInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::Effect + \inmodule Phonon + \inheaderfile Phonon/Effect + \since 4.4 + \brief The Effect class is used to transform audio streams. + + An effect is a media node which is inserted into a path between a + \l{Phonon::}{MediaObject} and an audio output node, for instance, + an \l{Phonon::}{AudioOutput}. The Effect transforms the media + stream on that path. + + Examples may include simple modifiers, such as fading or pitch + shifting, and more complex mathematical transformations. You can + query the backend for available effects with + BackendCapabilities::availableAudioEffects(). Note that the + effects available is dependent on the underlying system + (DirectDraw, GStreamer, or QuickTime). + + In order to use an effect, insert it into the path as follows: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 19 + + The effect will immediately begin applying it's transformations on + the path. To stop it, remove the Effect from the path. + + To create an effect, you use the \l{Phonon::}{EffectDescription} + class, which you get from + \l{BackendCapabilities::}{availableAudioEffects()}. We give a code + example below. + + \snippet doc/src/snippets/audioeffects.cpp 0 + + An effect can have one or more parameters, which let you alter how + the effect works, for instance, by specifying the depth of a + reverb effect. See the EffectParameter class description for + details. + + Phonon also provides EffectWidget, which lets the user modify the + parameters of an effect an the fly, e.g., with comboboxes. + + \sa {Phonon Module}, EffectWidget +*/ + +/*! + \fn explicit Phonon::Effect::Effect(const EffectDescription &description, QObject *parent = 0) + + Constructs a new effect object with the given \a description and \a parent object. + + The EffectDescription object determines the type of the effect. + + \sa {Phonon::BackendCapabilities::availableAudioEffects()} +*/ + +/*! + \fn Phonon::Effect::Effect(EffectPrivate &dd, QObject *parent) + \internal +*/ + +/*! + \fn Phonon::Effect::~Effect() + \internal +*/ + +/*! + \fn QVariant Phonon::Effect::parameterValue(const EffectParameter ¶meter) const + + Returns the value of the given effect \a parameter. You can fetch + the available parameters for an effect with parameters(). + + \sa setParameterValue(), EffectParameter +*/ + +/*! + \fn void Phonon::Effect::setParameterValue(const EffectParameter ¶meter, const QVariant &value) + + Sets the given effect \a parameter to the specified \a value. + + Parameters for an effect are returned by parameters(). You can + check which QVariant::Type an EffectParameter takes with the + EffectParameter::type() function. + + \sa parameterValue(), EffectParameter +*/ + +/*! + \fn EffectDescription Phonon::Effect::description() const; + + Returns the description of this effect. This is the same + description that was passed to the constructor. +*/ + +/*! + \fn QList Phonon::Effect::parameters() const; + + Returns a list of parameters that this effect provides to control + its behavior. + + \sa EffectParameter, EffectWidget +*/ + +/*! + \class Phonon::EffectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::AudioOutput + \inmodule Phonon + \inheaderfile Phonon/AudioOutput + \since 4.4 + \brief The AudioOutput class is used to send data to audio output devices. + + The AudioOutput class plays sound over a sound device. The audio + output needs to be connected to a \l{Phonon::}{MediaObject} using + \l{Phonon::}{createPath()}. To start playback, you call + \l{Phonon::MediaObject::}{play()} on the media object. + + \snippet snippets/phonon.cpp 2 + + The class supports changing the volume(). It is also possible to + mute the sound. + + To find out what \l{Phonon::}{AudioOutputDevice}s are available + for AudioOutput, you can call + BackendCapabilities::availableAudioDevices(). A default device is + selected by the backend, but it is possible to set the device to + be used with setOutputDevice(). The outputDeviceChanged() signal + will be emitted if the device changes. + + If an error occurs with the playback, for instance, if no valid + output device is found, the media object will receive a + stateChanged() signal with the \l{Phonon::}{ErrorState}. + + Note that the default values of properties are dependent on the + backend. + + \sa Phonon::VolumeSlider, {Music Player Example}, BackendCapabilities, {Phonon Module} +*/ + +/*! + \property Phonon::AudioOutput::name + + This is the name that appears in Mixer applications that control + the volume of this output. + +*/ + +/*! + \property Phonon::AudioOutput::volume + + This is the current loudness of the output. \omit The volume is a + real value between 0.0 (minimum) and 1.0 (maximum). The volume + follows the sound device used, with 1.0 being the maximum volume + the device can produce. \endomit + + (it is using Stevens' law + to calculate the change in voltage internally). + + \sa volumeDecibel +*/ + +/*! + \property Phonon::AudioOutput::volumeDecibel + + This is the current volume of the output in decibel. + + 0 dB means no change in volume, -6dB means an attenuation of the + voltage to 50% and an attenuation of the power to 25%, -inf dB means + silence. + + \sa volume +*/ + +/*! + \property Phonon::AudioOutput::outputDevice + This property holds the (hardware) destination for the output. + + The default device is determined by the \l{Phonon::}{Category} and the global + configuration for that category. Normally you don't need + to override this setting - letting the user change the global + configuration is the right choice. You can still override the + device though, if you have good reasons to do so. + + \sa outputDeviceChanged() +*/ + +/*! + \property Phonon::AudioOutput::muted + This property tells whether the output is muted. + + Muting the output has the same effect as calling setVolume(0.0). +*/ + +/*! + \fn explicit Phonon::AudioOutput::AudioOutput(Phonon::Category category, QObject *parent = 0) + + Creates a new AudioOutput with the given \a parent that defines + output to a physical device. + + The \a category can be used by mixer applications to group volume + controls of applications into categories. That makes it easier for + the user to identify the programs. + The category is also used for the default output device that is + configured centrally. As an example: often users want to have the + audio signal of a VoIP application go to their USB headset while + all other sounds should go to the internal soundcard. + + \sa Phonon::categoryToString(), outputDevice +*/ + +/*! + \fn explicit Phonon::AudioOutput::AudioOutput(QObject *parent = 0) + + Creates a new AudioOutput that defines output to the system + default device with the \{Phonon::Category::}{NoCategory} category + + \sa Phonon::categoryToString(), outputDevice +*/ + +/*! + \fn Phonon::Category Phonon::AudioOutput::category() const + + Returns the category of this output. + + \sa Phonon::AudioOutput::AudioOutput() +*/ + +/*! + \fn void Phonon::AudioOutput::volumeChanged(qreal newVolume) + + This signal is emitted whenever the volume has changed. As the + volume can change without a call to setVolume (calls over dbus) + this is important to keep a widget showing the current volume up + to date. + + \a newVolume is the new volume level. + + \sa setVolume(), volume() +*/ + +/*! + \fn void Phonon::AudioOutput::mutedChanged(bool muted) + + This signal is emitted when the muted property has changed. The \a muted + value passed by the signal indicates the state of the muted property. + As this property can change by IPC (DBus) calls a UI element showing + the muted property should listen to this signal. +*/ + +/*! + \fn void Phonon::AudioOutput::outputDeviceChanged(const Phonon::AudioOutputDevice &newAudioOutputDevice) + + This signal is emitted when the (hardware) device for the output + has changed. \a newAudioOutputDevice is the new device. + + The change can happen either through setOutputDevice or if the + global configuration for the used category has changed. + + \sa outputDevice +*/ + +/*! + \class Phonon::AudioOutputPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectParameter + \inmodule Phonon + \inheaderfile Phonon/EffectParameter + \since 4.4 + \brief The EffectParameter class describes one parameter of an effect. + + You fetch the parameters of an \l{Phonon::}{Effect} with + \l{Phonon::}{Effect::parameters()}. + + \snippet doc/src/snippets/phononeffectparameter.cpp 0 + + To describe itself, an effect parameter gives a name() and + possibly description() (depending on the backend used). These are + suited to present the effect parameter to the user of a Phonon + application. + + Note that effects are created by the backend, and that + their name and descriptions may vary. + + The value of an effect parameter is stored in a \l{QVariant}, + of which type() is usually \c int or \c double. + + The value is retrieved with \l{Phonon::}{Effect::parameterValue()} + and set with \l{Phonon::Effect::}{setParameterValue()} - both of + which takes the EffectParameter as argument. Note that not all + effect parameters support setting of their value. + + You get the values a parameter can take with possibleValues(); an + empty list is returned if the values are continuous. + + A parameter may also specify default(), minimum(), and maximum() + values. Values are returned as \l{QVariant}s. If the parameter + does not have the requested value, an \l{QVariant::Invalid} + invalid QVariant is returned from these functions. + + The \l{Phonon::}{EffectWidget} provides a widget with which one + can control the parameters of an \l{Phonon::}{Effect}. + + \snippet doc/src/snippets/phononeffectparameter.cpp 1 + + \sa Effect, EffectWidget, {Capabilities Example}, {Phonon Module} +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter() + \internal + + Creates an invalid effect parameter. +*/ + +/*! + \fn Phonon::EffectParameter::~EffectParameter() + + Destroys the effect parameter. +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter(const EffectParameter &other) + + Constructs a copy of the \a other effect parameter. +*/ + +/*! + \fn const QString &Phonon::EffectParameter::name() const + + The name of the parameter. Can be used as the label. + + \return A label for the parameter. +*/ + +/*! + \fn const QString &Phonon::EffectParameter::description() const + + The parameter may come with a description (LADSPA doesn't have a + field for this, so don't expect many effects to provide a + description). + + The description can be used for a tooltip or WhatsThis help. + + \return A text describing the parameter. +*/ + +/*! + \fn QVariant::Type Phonon::EffectParameter::type() const + + Returns the parameter type. + + Common types are QVariant::Int, QVariant::Double, QVariant::Bool and QVariant::String. When + QVariant::String is returned you get the possible values from possibleValues. +*/ + +/*! + \fn bool Phonon::EffectParameter::isLogarithmicControl() const + + Returns whether the parameter should be + displayed using a logarithmic scale. This is particularly useful for + frequencies and gains. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::minimumValue() const + + The minimum value to be used for the control to edit the parameter. + + If the returned QVariant is invalid the value is not bounded from + below. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::maximumValue() const + + The maximum value to be used for the control to edit the parameter. + + If the returned QVariant is invalid the value is not bounded from + above. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::defaultValue() const + + The default value. +*/ + +/*! + \fn QVariantList Phonon::EffectParameter::possibleValues() const + + The possible values to be used for the control to edit the parameter. + + if the value of this parameter is to be picked from predefined values + this returns the list (otherwise it returns an empty QVariantList). +*/ + +/*! + \fn bool Phonon::EffectParameter::operator<(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn bool Phonon::EffectParameter::operator>(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn bool Phonon::EffectParameter::operator==(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn Phonon::EffectParameter &Phonon::EffectParameter::operator=(const EffectParameter &other) + + Assigns the \a other effect parameter to this parameter and returns + a reference to this parameter. +*/ + +/*! + \enum Phonon::EffectParameter::Hint + + Only for backend developers: + + Flags to set the return values of isToggleControl(), + isLogarithmicControl(), isIntegerControl(), isBoundedBelow() and + isBoundedAbove(). The values of the flags correspond to the values + used for LADSPA effects. + + \value ToggledHint + If this hint is set it means that + the the control has only two states: zero and non-zero + (see isToggleControl()). + + \value LogarithmicHint + LADSPA's SAMPLE_RATE hint needs to be translated by the backend + to normal bounds, as the backend knows the sample rate - and the + frontend doesn't (see isLogarithmicControl()). + + \value IntegerHint See isIntegerControl(). +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter(int parameterId, + const QString &name, EffectParameter::Hints hints, + const QVariant &defaultValue, const QVariant &min = QVariant(), + const QVariant &max = QVariant(), const QVariantList &values = QVariantList(), + const QString &description = QString()) + + Only to be used by backend implementations: + + Creates a new effect parameter. + + \a parameterId This is a number to uniquely identify the + parameter. The id is used for value() and setValue(). + + \a name is the name/label for this parameter. + + \a hints sets the hints for the type of parameter. + + \a defaultValue The value that should be used as a default. + + \a min is the minimum value allowed for this parameter. You only + need to set this if the BoundedBelowHint is set. + + \a max is the maximum value allowed for this parameter. You only + need to set this if the BoundedAboveHint is set. + + The \a values parameter is the values that the effect parameter + can take (only applies if non-continuous) + + \a description is a descriptive text for the parameter + (explaining what it controls) to be used as a tooltip or + WhatsThis help. +*/ + +/*! + \fn int Phonon::EffectParameter::id() const + + \internal + + Returns the parameter's identifier. +*/ + +/*! + \class Phonon::AudioOutputInterface40 + \inmodule Phonon + \since 4.4 + \internal + \brief Interface for AudioOutput objects + +*/ + +/*! + \fn virtual Phonon::AudioOutputInterface40::~AudioOutputInterface40() + \internal +*/ + +/*! + \fn virtual qreal Phonon::AudioOutputInterface40::volume() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::AudioOutputInterface40::setVolume(qreal) = 0 + \internal +*/ + +/*! + \fn virtual int Phonon::AudioOutputInterface40::outputDevice() const = 0 + \internal +*/ + +/*! + \fn virtual bool Phonon::AudioOutputInterface40::setOutputDevice(int) = 0 + \internal +*/ + +/*! + \class Phonon::Path + \inmodule Phonon + \inheaderfile Phonon/Path + \since 4.4 + \brief The Path class describes connections between media nodes. + + In a \l{Building Graphs}{media graph}, \l{Phonon::}{MediaNode}s + are connected by Paths. The multimedia travels in streams over + these paths. + + You create a path between two media nodes using the static + Phonon::createPath() function, which takes two nodes as arguments. + The first argument will send the media stream to the second. + Please refer to the class description of the individual media + nodes and the Phonon \l{Phonon Overview}{overview} to see which + nodes can be connected to each other. + + Paths are also used to insert audio \l{Phonon::}{Effect}s between + two media nodes. The effect will then alter the stream on the + path. Notice that \l{Phonon::}{Effect}s also are media nodes, but + that insertEffect() - instead of Phonon::createPath() - is used to + insert them into the media graph. + + The following code example shows how to create a path between two + media nodes and insert an effect on that path. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 20 + + \sa Phonon::MediaNode, Phonon::MediaObject, Phonon::AudioOutput, + Phonon::VideoWidget, {Phonon Module} +*/ + +/*! + \fn Phonon::Path::~Path(); + + Destroys this reference to the Path. If the path was valid the connection is not broken + as both the source and the sink MediaNodes still keep a reference to the Path. + + \sa disconnect() +*/ + +/*! + \fn Phonon::Path::Path(); + + Creates an invalid path. + + You can still make it a valid path by calling reconnect. It is + recommended to use the Phonon::createPath() function to create + paths. + + \sa Phonon::createPath(), isValid() +*/ + +/*! + \fn Phonon::Path::Path(const Path &path); + + Constructs a copy of the other \a path specified. + + This constructor is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::Path::isValid() const; + + A path is considered valid if it is connected to two media nodes, + in which case this function returns true. If it is connected to + one or no media nodes, it is consider invalid, and this function + will then return false. +*/ + +/*! + \fn Effect *Phonon::Path::insertEffect(const EffectDescription &desc, Effect *insertBefore = 0); + + Creates and inserts an effect into the path. + + You may insert effects of the same class as often as you like, + but if you insert the same object, the call will fail. + + \a desc is the EffectDescription object for the effect to be inserted. + + If you already inserted an effect you can + tell with \a insertBefore in which order the data gets + processed. If this is \c 0 the effect is appended at the end of + the processing list. If the effect has not been inserted before + the method will do nothing and return \c false. + + Returns a pointer to the effect object if it could be inserted + at the specified position. If \c 0 is returned, the effect was not + inserted. + + Below is a code example for inserting an effect into a path: + + \snippet doc/src/snippets/audioeffects.cpp 0 + + \sa removeEffect(), effects() +*/ + +/*! + \fn bool Phonon::Path::insertEffect(Effect *effect, Effect *insertBefore = 0); + + Inserts the given \a effect into the path before the effect specified by \a insertBefore + and returns true if successful; otherwise returns false. + + If \a insertBefore is zero, the effect is appended to the processing list. + + You may insert effects of the same class as often as you like, but if you insert + the same object, the call will fail. + + \a effect will be inserted right before \a insertBefore. If + \a insertBefore is \c 0, the effect is appended at the end of the + processing list. If the effect has not been inserted before the + method will do nothing and return \c false. + + Returns whether the effect could be inserted at the specified + position. If \c false is returned the effect was not inserted. + + \sa removeEffect(), effects() +*/ + +/*! + \fn bool Phonon::Path::removeEffect(Effect *effect); + + Removes the given \a effect from the path and returns true; otherwise returns false. + + Removes an \a effect from the path. + + If the effect is deleted while it is still connected, the effect will be removed + automatically. + + \omit + \param effect The effect to be removed. + + \return Returns whether the call was successful. If it returns + \c false the effect could not be found in the path, meaning it + has not been inserted before. + \endomit + + \sa insertEffect(), effects() +*/ + +/*! + \fn QList Phonon::Path::effects() const; + + Returns a list of Effect objects that are currently + used as effects. The order in the list determines the order the + signal is sent through the effects. + + \return A list with all current effects. + + \sa insertEffect(), removeEffect() +*/ + +/*! + \fn bool Phonon::Path::reconnect(MediaNode *source, MediaNode *sink); + + Changes the media nodes the path is connected to by connecting the path + to the \a source and \a sink nodes specified. Returns true if successful; + otherwise returns false. + + If unsuccessful, the path remains connected to the same nodes as before. + + \sa Phonon::createPath(), {Phonon Overview} +*/ + +/*! + \fn bool Phonon::Path::disconnect(); + + Tries to disconnect the path from the MediaNodes it is connected to, returning + true if successful or false if unsuccessful. + + If successful, the path is invalidated: isValid() will returns false. +*/ + +/*! + \fn Path &Phonon::Path::operator=(const Path &p); + + Assigns \a p to this Path and returns a reference to this Path. + + This operation is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::Path::operator==(const Path &p) const; + + Returns true if this Path is equal to \a p; otherwise returns false; +*/ + +/*! + \fn bool Phonon::Path::operator!=(const Path &p) const; + + Returns true if this Path is not equal to \a p; otherwise returns false; +*/ + +/*! + \fn Path Phonon::createPath(MediaNode *source, MediaNode *sink); + + \relates Phonon::Path + Creates a new Path connecting the two MediaNodes \a source and \a sink. + + The implementation will automatically select the right format and media type. E.g. connecting a + MediaObject and AudioOutput will create a Path object connecting the audio. This might be + represented as PCM or perhaps even AC3 depending on the AudioOutput object. + + \param source The MediaNode to connect an output from + \param sink The MediaNode to connect to. +*/ + +/*! + \class Phonon::PathPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaObjectInterface + \inmodule Phonon + \since 4.4 + \internal + \brief Backend interface for media sources. + + The backend implementation has to provide two signals, that are not defined + in this interface: + \list + \o \target phonon_MediaObjectInterface_stateChanged + void stateChanged(Phonon::State newstate, Phonon::State oldstate) + + Emitted when the state of the MediaObject has changed. + In case you're not interested in the old state you can also + connect to a slot that only has one State argument. + + \param newstate The state the Player is in now. + \param oldstate The state the Player was in before. + + \o \target phonon_MediaObjectInterface_tick + void tick(qint64 time) + + This signal gets emitted every tickInterval milliseconds. + + \param time The position of the media file in milliseconds. + + \sa setTickInterval() + \sa tickInterval() + \endlist + + \sa MediaObject +*/ + +/*! + \fn virtual Phonon::MediaObjectInterface::~MediaObjectInterface() + \internal +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::remainingTime() const + \internal +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::prefinishMark() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setPrefinishMark(qint32) = 0 + \internal +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::transitionTime() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setTransitionTime(qint32) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::play() = 0 + \internal + + Requests the playback to start. + + This method is only called if the state transition to PlayingState is possible. + + The backend should react immediately + by either going into PlayingState or BufferingState if the + former is not possible. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::pause() = 0 + \internal + + Requests the playback to pause. + + This method is only called if the state transition to PausedState is possible. + + The backend should react as fast as possible. Go to PausedState + as soon as playback is paused. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::stop() = 0 + \internal + + Requests the playback to be stopped. + + This method is only called if the state transition to StoppedState is possible. + + The backend should react as fast as possible. Go to StoppedState + as soon as playback is stopped. + + A subsequent call to play() will start playback at the beginning of + the media. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::seek(qint64 milliseconds) = 0 + \internal + + Requests the playback to be seeked to the given time. + + The backend does not have to finish seeking while in this function + (i.e. the backend does not need to block the thread until the seek is + finished; even worse it might lead to deadlocks when using a + ByteStream which gets its data from the thread this function would + block). + + As soon as the seek is done the currentTime() function and + the tick() signal will report it. + + \param milliseconds The time where playback should seek to in + milliseconds. +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::tickInterval() const = 0 + \internal + + Return the time interval in milliseconds between two ticks. + + Returns the tick interval that it was set to (might not + be the same as you asked for). +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setTickInterval(qint32 interval) = 0 + \internal + + Change the interval the tick signal is emitted. Set \a interval to 0 to + disable the signal. + + \a interval tick interval in milliseconds + + Returns the tick interval that it was set to (might not be the same as you + asked for). + +*/ + +/*! + \fn virtual bool Phonon::MediaObjectInterface::hasVideo() const = 0 + \internal + + Check whether the media data includes a video stream. + + Returns true if the media contains video data. +*/ + +/*! + \fn virtual bool Phonon::MediaObjectInterface::isSeekable() const = 0 + \internal + + If the current media may be seeked this function returns true; + otherwise, false. + + Returns whether the current media may be seeked. +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::currentTime() const = 0 + \internal + + Get the current time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn virtual Phonon::State Phonon::MediaObjectInterface::state() const = 0 + \internal + + Get the current state. +*/ + +/*! + \fn virtual QString Phonon::MediaObjectInterface::errorString() const = 0 + \internal + + A translated string describing the error. +*/ + +/*! + \fn virtual Phonon::ErrorType Phonon::MediaObjectInterface::errorType() const = 0 + \internal + + Tells your program what to do about the error. + + \sa Phonon::ErrorType +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::totalTime() const = 0 + \internal + + Returns the total time of the media in milliseconds. + + If the total time is not know return -1. Do not block until it is + known, instead emit the totalTimeChanged signal as soon as the total + time is known or changes. +*/ + +/*! + \fn virtual MediaSource Phonon::MediaObjectInterface::source() const = 0 + \internal + + Returns the current source. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setSource(const MediaSource &) = 0 + \internal + + Sets the current source. When this function is called the MediaObject is + expected to stop all current activity and start loading the new + source (i.e. go into LoadingState). + + It is expected that the + backend now starts preloading the media data, filling the audio + and video buffers and making all media meta data available. It + will also trigger the totalTimeChanged signal. + + If the backend does not know how to handle the source it needs to + change state to Phonon::ErrorState. Don't bother about handling KIO + URLs. It is enough to handle AbstractMediaStream sources correctly. + + \warning Keep the MediaSource object around as long as the backend + uses the AbstractMediaStream returned by the MediaSource. In case + that no other reference to the MediaSource exists and it is set to + MediaSource::autoDelete, the AbstractMediaStream is deleted when the + last MediaSource ref is deleted. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setNextSource(const MediaSource &source) = 0 + \internal + + Sets the next source to be used for transitions. When a next source + is set playback should continue with the new source. In that case + finished and prefinishMarkReached are not emitted. + + \param source The source to transition to (crossfade/gapless/gap). If + \a source is an invalid MediaSource object then the queue is empty + and the playback should stop normally. + + \warning Keep the MediaSource object around as long as the backend + uses the AbstractMediaStream returned by the MediaSource. In case + that no other reference to the MediaSource exists and it is set to + MediaSource::autoDelete, the AbstractMediaStream is deleted when the + last MediaSource ref is deleted. +*/ + +/*! + \class Phonon::EffectWidget effectwidget.h Phonon/EffectWidget + \inmodule Phonon + \inheaderfile Phonon/EffectWidget + \since 4.4 + \brief The EffectWidget class provides a widget to control the parameters of an Effect. + + The EffectWidget class provides a widget, with which an effects + parameters can be controlled. The widget does not have an API, + and is constructed with the \l{Phonon::}{Effect}, of which + parameters should be controlled. + + \snippet doc/src/snippets/audioeffects.cpp 1 + + The following image shows an example of an effect widget. + + \image effectwidget.png + + Note that some audio effects do not have parameters, and the + widget will then not \l{QWidget::}{show()} at all. + + \sa Effect, BackendCapabilities, EffectDescription, {Phonon Module} +*/ + +/*! + \class Phonon::AbstractAudioOutput + \inmodule Phonon + \internal + \brief Provides a common base class for all audio outputs. + + \sa AudioOutput +*/ + +/*! + \fn Phonon::AbstractAudioOutput::~AbstractAudioOutput() + \internal +*/ + +/*! + \class Phonon::AbstractAudioOutputPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class AudioOutputAdaptor + \inmodule Phonon + \brief Provides an adaptor class for interface org.kde.Phonon.AudioOutput + \internal +*/ + +/*! + \class Phonon::VolumeSlider + \inmodule Phonon + \inheaderfile Phonon/VolumeSlider + \since 4.4 + \brief The VolumeSlider widget provides a slider that is used to control the volume of an audio output device. + + The slider also displays an icon indicating if the volume of the + \l{Phonon::}{AudioOutput} it is connected to is muted. The icon + can be removed with setMuteVisible(). + + It is possible to set the \l{maximumVolume}{maximum} value of the + slider. By default, the minimum and maximum values of the slider + are 0.0 (no sound) to 1.0 (the maximum volume the audio output can + produce). + + Here follows a code example: + + \snippet doc/src/snippets/volumeslider.cpp 0 + + \omit mention how to change the style of the slider. \endomit + + \sa {Phonon Module} +*/ + +/*! + \property Phonon::VolumeSlider::maximumVolume + + This property holds the maximum volume that can be set with this slider. + + By default the maximum value is 1.0 (100%). +*/ + +/*! + \property Phonon::VolumeSlider::orientation + This property holds the orientation of the slider. + + The orientation must be Qt::Vertical (the default) or Qt::Horizontal. +*/ + +/*! + \property Phonon::VolumeSlider::tracking + This property holds whether slider tracking is enabled. + + If tracking is enabled (the default), the volume changes + while the slider is being dragged. If tracking is + disabled, the volume changes only when the user + releases the slider. +*/ + +/*! + \property Phonon::VolumeSlider::pageStep + This property holds the page step. + + The larger of two natural steps that a slider provides and + typically corresponds to the user pressing PageUp or PageDown. + + Defaults to 5 (5% of the voltage). +*/ + +/*! + \property Phonon::VolumeSlider::singleStep + This property holds the single step. + + The smaller of two natural steps that a slider provides and + typically corresponds to the user pressing an arrow key. + + Defaults to 1 (1% of the voltage). +*/ + +/*! + \property Phonon::VolumeSlider::muteVisible + This property holds whether the mute button/icon next to the slider is visible. + + By default the mute button/icon is visible. +*/ + +/*! + \property Phonon::VolumeSlider::iconSize + \brief the icon size used for the mute button/icon. + + The default size is defined by the GUI style. +*/ + +/*! + \fn explicit Phonon::VolumeSlider::VolumeSlider(QWidget *parent = 0) + Constructs a new volume slider with the given \a parent. +*/ + +/*! + \fn explicit Phonon::VolumeSlider::VolumeSlider(AudioOutput *output, QWidget *parent = 0) + Constructs a new volume slider with the given \a output object and \a parent. +*/ + +/*! + \fn Phonon::VolumeSlider::~VolumeSlider() +*/ + +/*! + \fn AudioOutput *Phonon::VolumeSlider::audioOutput() const +*/ + +/*! + \fn void Phonon::VolumeSlider::setAudioOutput(Phonon::AudioOutput *output) + + Sets the audio output object to be controlled by this slider to the specified + \a output object. +*/ + +/*! + \class Phonon::VolumeSliderPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaController + \inmodule Phonon + \inheaderfile Phonon/MediaController + \since 4.4 + \brief The MediaController class controls optional features of a media file/device. + + Some media sources have content that the \l{Phonon::}{MediaObject} + does not provide control over, for instance, chapters in a DVD + file. The functionality the media controller offers is + dependent on the type of media source that is played back. + Commonly, the media controller allows you to: + + \list + \o Navigate between \bold chapters. + \o Navigate between \bold titles. + \o Select between \bold angles. + \endlist + + The \l{Phonon::MediaController::}{Feature} enum explains these + terms in more detail, and their context in playback of CD and DVD. + + The media controller keeps a \l{Phonon::}{MediaObject}, of which + \l{Phonon::MediaObject::currentSource()}{media source} is played + back. You can still call the media object's functions, e.g., + \l{Phonon::MediaObject::}{stop()}; this is all handled correctly + by the media controller. You have the option of letting the media + controller play all titles of a source in sequence by setting the + \l{autoplayTitles()}{autoplay titles} option. + + To start a playback using a media object, you call + \l{Phonon::MediaObject::}{play()} on the media object. To play a + specific title, use setCurrentTitle() and then call + \l{Phonon::MediaObject::}{play()}. + + \warning The Phonon::MediaController class is not yet supported by + Qt backends. + + \sa {Phonon Module} +*/ + +/*! + \fn int Phonon::MediaController::availableAudioChannels() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::availableAudioChannelsChanged() + \internal +*/ + +/*! + \fn QList Phonon::MediaController::availableSubtitles() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::availableSubtitlesChanged() + \internal +*/ + +/*! + \fn AudioChannelDescription Phonon::MediaController::currentAudioChannel() const + \internal +*/ + +/*! + \fn SubtitleDescription Phonon::MediaController::currentSubtitle() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::setCurrentAudioChannel(const Phonon::AudioChannelDescription &stream) + \internal +*/ + +/*! + \fn void Phonon::MediaController::setCurrentSubtitle(const Phonon::SubtitleDescription &stream) + \internal +*/ + +/*! + \fn Phonon::BackendCapabilities::availableAudioCaptureDevices() + \internal +*/ + +/*! + \fn Phonon::BackendCapabilities::Notifier::availableAudioCaptureDevicesChanged() + \internal +*/ + +/*! + \enum Phonon::MediaController::Feature + + The values of this enum are interpreted differently depending on + the type of media source, e.g., DVD or CD. We give examples for + these sources. + + \value Angles In the VOB (DVD) format, it is possible to to give + several video streams of the same scene, each of which displays + the scene from a different angle. The DVD viewer can then change + between these angles. + + \value Chapters In the VOB format, chapters are points in a + single video stream that can be played and seeked to + separately. + + \value Titles On a CD, a title is a separate sound track. On DVD, + a title is a separate VOB file. + +*/ + +/*! + \fn Phonon::MediaController::MediaController(MediaObject *parent) + + Constructs a new MediaController with the media object (\a parent) + to be used by the media controller. + + \sa MediaObject, Feature +*/ + +/*! + \fn Phonon::MediaController::~MediaController() +*/ + +/*! + \fn Features Phonon::MediaController::supportedFeatures() const +*/ + +/*! + \fn int Phonon::MediaController::availableAngles() const + + Returns the available angles that is available for the current + media source. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentAngle() const + + Returns the angle that is currently used. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::availableChapters() const + + Returns the number of chapters the current media source + contains. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentChapter() const + + Returns the chapter that is currently being played back. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::availableTitles() const + + Returns the number of titles that the current media source + contains. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentTitle() const + + Returns the title that is currently played back. + + The current title is 0 (the first) by default. + + \sa Feature +*/ + +/*! + \fn bool Phonon::MediaController::autoplayTitles() const + + Returns true if titles will automatically be played when the media + is played; otherwise returns false. + + The media controller will play the titles of the media source in + sequence when the media object's \l{Phonon::MediaObject::}{play()} + function is called. If the autoplay option is disabled, the media + object will play the + \l{Phonon::}{MediaController::currentTitle()}{current title} and then + finish the playback. + + \sa setAutoplayTitles(), currentTitle() +*/ + +/*! + \fn void Phonon::MediaController::setAutoplayTitles(bool enable) + + Sets the titles to play automatically when the media is played if + \a enable is true; otherwise disables this option. + + The media controller will play the titles of the media source in + sequence when the media object's \l{Phonon::MediaObject::}{play()} + function is called. If the autoplay option is disabled, the media + object will play the + \l{Phonon::}{MediaController::currentTitle()}{current title} and then + finish the playback. + + \sa autoplayTitles(), currentTitle() +*/ + +/*! + \fn void Phonon::MediaController::setCurrentAngle(int angleNumber) + + Sets the current angle to the given \a angleNumber if the media + file or device supports navigation by angle number. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::setCurrentChapter(int chapterNumber) + + Sets the current chapter to the given \a chapterNumber if the media + file or device supports navigation by chapter number. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::setCurrentTitle(int titleNumber) + + Skips to the given title \a titleNumber. + + If it was playing before the title change it will start playback on the new title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::nextTitle() + + Skips to the next title. + + If it was playing before the title change it will start playback on the next title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::previousTitle() + + Skips to the previous title. + + If it was playing before the title change it will start playback on the previous title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableAnglesChanged(int availableAngles) + + This signal is emitted whenever the number of available angles changes. + The new number of available angles is given by \a availableAngles. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::angleChanged(int angleNumber) + + This signal is emitted whenever the current angle changes. + The new angle number is given by \a angleNumber. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableChaptersChanged(int availableChapters) + + This signal is emitted whenever the number of available chapters changes. + The new number of available chapters is given by \a availableChapters. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::chapterChanged(int chapterNumber) + + This signal is emitted whenever the current chapter changes. + The new chapter number is given by \a chapterNumber. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableTitlesChanged(int availableTitles) + + This signal is emitted whenever the number of available titles changes. + The new number of available titles is given by \a availableTitles. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::titleChanged(int titleNumber) + + This signal is emitted whenever the current title changes. + The new title number is given by \a titleNumber. + + \sa Feature +*/ + +/*! + \class Phonon::VideoWidget + \inmodule Phonon + \inheaderfile Phonon/VideoWidget + \since 4.4 + \ingroup advanced + \ingroup multimedia + \brief The VideoWidget class provides a widget that is used to display video. + + The VideoWidget class renders the video of a media stream on a + QWidget. It is connected to the \l{Phonon::}{MediaObject}, of + which video stream it should render. You connect the two objects + using the Phonon::createPath() function. + + The widget has some possibilities to manipulate the video + stream. You can change the brightness(), hue(), saturation(), + and contrast(). + + Resizing of the video is handled automatically, but you can affect + the way the video is resized with the aspectRatio and scaleMode + properties. By default, the widget will use the aspect ratio of + the video stream itself. + + The video widget takes the size of the video when it receives a new video + stream (i.e., when a new MediaSource is set on the MediaObject to which it is + connected). If you need to know the size of the video, you can call + \l{QWidget::}{sizeHint()} after the video has been loaded (i.e., after the + MediaObject leaves the \l{Phonon::}{LoadingState}). + + It is also possible to go to \l{fullScreen}{full screen} mode. + + A typical example of usage follows below: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 21 + + \sa {Phonon Module} +*/ + +/*! + \fn Phonon::VideoWidget::VideoWidget(QWidget *parent = 0) + + Constructs a new video widget with the specified \a parent. +*/ + +/*! + \fn Phonon::VideoWidget::VideoWidget(VideoWidgetPrivate &d, QWidget *parent) + \internal + + Constructs a new video widget with the specified \a parent. +*/ + +/*! + \fn bool Phonon::VideoWidget::event(QEvent *) + \reimp +*/ + +/*! + \fn void Phonon::VideoWidget::mouseMoveEvent(QMouseEvent *) + \reimp +*/ + +/*! + \enum Phonon::VideoWidget::ScaleMode + + The ScaleMode enum describes how to treat aspect ratio during + resizing of video. + + \value FitInView The video will be fitted to fill the view + keeping aspect ratio. + \value ScaleAndCrop The video is scaled + + +*/ + +/*! + \property Phonon::VideoWidget::fullScreen + This property holds whether the video is shown using the complete + screen. + + The property differs from QWidget::fullScreen in that it is + writeable. + + By default the widget is not shown in fullScreen. + + \warning When switching to full screen mode using setFullScreen(), + the widget onto which the video is rendered is shown as a + top-level window. Key event forwarding is handled by VideoWidget, + but if you need to handle other events, e.g., mouse events, you + should handle fullscreen mode yourself. + +*/ + +/*! + \property Phonon::VideoWidget::aspectRatio + Defaults to AspectRatioAuto. + + \sa AspectRatio +*/ + +/*! + \property Phonon::VideoWidget::scaleMode + + If the size of the widget and the size of the video are not equal. + The video will be zoomed to fit the widget. The smaller zoom + (AddBarsScaleMode) adds black bars at the left/right or top/bottom to + make all of the image visible (default). The bigger zoom (ExpandMode) + fills the widget completely, keeping all information in one direction + and leaving parts of the image outside of the widget in the other + direction. +*/ + +/*! + \property Phonon::VideoWidget::brightness + + This property holds brightness of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::contrast + + This property holds the contrast of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::hue + + This property holds the hue of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::saturation + + This property holds saturation of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \enum Phonon::VideoWidget::AspectRatio + + Defines the width:height to be used for the video. + + \value AspectRatioAuto + Let the decoder find the aspect ratio automatically from the + media file (this is the default). + + \value AspectRatioWidget + Fits the video into the widget making the aspect ratio depend + solely on the size of the widget. This way the aspect ratio + is freely resizeable by the user. + + \value AspectRatio4_3 + Make width/height == 4/3, which is the old TV size and + monitor size (1024/768 == 4/3). (4:3) + + \value AspectRatio16_9 + Make width/height == 16/9, which is the size of most current + media. (16:9) +*/ + +/*! + \fn void Phonon::VideoWidget::exitFullScreen() + + Convenience slot, calling setFullScreen(false) +*/ + + +/*! + \fn void Phonon::VideoWidget::enterFullScreen() + + Convenience slot, calling setFullScreen(true) +*/ + +/*! + \class Phonon::VideoWidgetInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual Phonon::VideoWidgetInterface::~VideoWidgetInterface() +*/ + +/*! + \fn virtual Phonon::VideoWidget::AspectRatio Phonon::VideoWidgetInterface::aspectRatio() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setAspectRatio(Phonon::VideoWidget::AspectRatio ratio) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::brightness() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setBrightness(qreal) = 0 + \internal +*/ + +/*! + \fn virtual Phonon::VideoWidget::ScaleMode Phonon::VideoWidgetInterface::scaleMode() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setScaleMode(Phonon::VideoWidget::ScaleMode mode) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::contrast() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setContrast(qreal) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::hue() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setHue(qreal) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::saturation() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setSaturation(qreal) = 0 + \internal +*/ + +/*! + \fn virtual QWidget *Phonon::VideoWidgetInterface::widget() = 0 + \internal +*/ + +/*! + \class Phonon::PlatformPlugin + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual AbstractMediaStream *Phonon::PlatformPlugin::createMediaStream(const QUrl &url, QObject *parent) = 0 + + Creates a AbstractMediaStream object with the given \a parent that provides the data + for the given URL specified by \a url. + \omit + On KDE this uses KIO. + \endomit +*/ + +/*! + \fn virtual QIcon Phonon::PlatformPlugin::icon(const QString &name) const = 0 + + Returns the icon for the given icon name. +*/ + +/*! + \fn virtual void Phonon::PlatformPlugin::notification(const char *notificationName, const QString &text, + const QStringList &actions, QObject *receiver, const char *actionSlot) const = 0 + + Shows a notification pop-up with the given \a notificationName and \a text. + Each action in the associated list of \a actions is connected to the \a actionSlot + of the specified \a receiver object, which is expected to act on the actions as + they are triggered by the user. +*/ + +/*! + \fn virtual QString Phonon::PlatformPlugin::applicationName() const = 0 + + Returns the name of the application. For most Qt application this is + QCoreApplication::applicationName(), but for KDE this is overridden by KAboutData. +*/ + + +/*! + \fn virtual QObject *Phonon::PlatformPlugin::createBackend() = 0 + + Creates a backend object. This way the platform can decide the backend preference. +*/ + +/*! + \fn virtual QObject *Phonon::PlatformPlugin::createBackend(const QString &library, const QString &version) = 0 + + Using the library loader of the platform, loads a given backend provided the + specified \a library and \a version. +*/ + +/*! + \fn virtual bool Phonon::PlatformPlugin::isMimeTypeAvailable(const QString &mimeType) const = 0 + + Tries to check whether the default backend supports the MIME type specified by \a mimeType + without loading the actual backend library. + \omit + On KDE this reads the MIME type list from the .desktop file of + the backend. + \endomit +*/ + +/*! + \fn virtual void Phonon::PlatformPlugin::saveVolume(const QString &outputName, qreal volume) = 0 + + Saves the volume for the given output. +*/ + +/*! + \fn virtual qreal Phonon::PlatformPlugin::loadVolume(const QString &outputName) const = 0 + + Loads the volume for the given output. +*/ + +/*! + \class Phonon::MediaNode + \inmodule Phonon + \inheaderfile Phonon/MediaNode + \since 4.4 + \brief The MediaNode class is the base class for all nodes in a media graph. + + In all phonon applications, one builds a media graph consisting of + MediaNodes. The graph will take multimedia content, e.g., from a + file, as input. After its nodes have processed the multimedia, the + graph will output the media again, e.g., to a sound card. + + The multimedia content is streamed over \l{Phonon::}{Path}s + between the nodes in the graph. You can query the paths that are + connected to a media node with inputPaths() and outputPaths(). + + You can check whether the node is implemented by the current + backend by calling isValid(). This does not guarantee that an + instance of the class works as expected, but that the backend has + implemented functionality for the class. + + Currently, Phonon has four media nodes: \l{Phonon::}{MediaObject}, + \l{Phonon::}{AudioOutput}, \l{Phonon::}{VideoWidget}, and \l{Phonon::}{Effect}. + Please refer to their class descriptions for details about their usage, and to + find out which nodes can be connected to each other. See also \l{Building + Graphs} in Phonon's \l{Phonon Overview}{overview} document. + + Two nodes are connected to each other using the + Phonon::createPath() or \l{Phonon::}{Path::insertEffect()} + functions (only \l{Phonon::Effect}s use + \l{Phonon::Path::}{insertEffect()}). We show a code example below, + in which we build a media graph for video playback and then query + its media nodes for their \l{Phonon::}{Path}s: + + \snippet doc/src/snippets/medianodesnippet.cpp 0 + + When you create a Phonon application, you will likely build the + graph yourself. This makes isValid() the most useful function of + this class. The other two functions help navigate the graph, which + you do not need to do as you created the nodes yourself. + + \sa {Phonon Overview}, Phonon::MediaObject, + Phonon::AudioOutput, Phonon::VideoWidget, {Phonon Module} +*/ + +/*! + \fn virtual Phonon::MediaNode::~MediaNode() + + Destroys the media node and any paths connecting it to other + nodes. Any \l{Phonon::}{Effect}s connected to these paths will + also be deleted. +*/ + +/*! + \fn bool Phonon::MediaNode::isValid() const + + Returns true if the backend provides an implementation of this + class; otherwise returns false. + + This does not guarantee that instances of the class works as + expected, but that the backend has implemented the functionality + for this class. For instance, Qt's GStreamer backend will return + true for instances of the \l{Phonon::}{AudioOutput} class, even if + there is a problem with GStreamer and it could not play sound. + +*/ + +/*! + \fn QList Phonon::MediaNode::inputPaths() const + + Returns the paths that inputs multimedia to this media node. + + \sa outputPaths() +*/ + +/*! + \fn QList Phonon::MediaNode::outputPaths() const + + Returns the paths to which this media node outputs media. + + \sa inputPaths() +*/ + +/*! + \fn Phonon::MediaNode::MediaNode(MediaNodePrivate &dd) + \internal +*/ + +/*! + \class Phonon::GlobalConfig + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn Phonon::GlobalConfig::GlobalConfig() + \internal +*/ + +/*! + \fn Phonon::GlobalConfig::~GlobalConfig() + \internal +*/ + +/*! + \fn QList Phonon::GlobalConfig::audioOutputDeviceListFor(Phonon::Category category, HideAdvancedDevicesOverride override = FromSettings) const + \internal +*/ + +/*! + \fn int Phonon::GlobalConfig::audioOutputDeviceFor(Phonon::Category category) const + \internal +*/ + +/*! + \class Phonon::ObjectDescriptionData + \inmodule Phonon + \since 4.4 + \internal + \brief Data class for objects describing devices or features of the backend. + + \sa Phonon::BackendCapabilities +*/ + +/*! + \fn bool Phonon::ObjectDescriptionData::operator==(const ObjectDescriptionData &otherDescription) const + + Returns \c true if this ObjectDescription describes the same + as \a otherDescription; otherwise returns \c false. +*/ + +/*! + \fn QString Phonon::ObjectDescriptionData::name() const + + Returns the name of the capture source. + + \return A string that should be presented to the user to + choose the capture source. +*/ + +/*! + \fn QString Phonon::ObjectDescriptionData::description() const + + Returns a description of the capture source. This text should + make clear what sound source this is, which is sometimes hard + to describe or understand from just the name. + + \return A string describing the capture source. +*/ + +/*! + \fn QVariant Phonon::ObjectDescriptionData::property(const char *name) const + + Returns a named property. + + If the property is not set an invalid value is returned. + + \sa propertyNames() +*/ + +/*! + \fn QList Phonon::ObjectDescriptionData::propertyNames() const + + Returns all names that return valid data when property() is called. + + \sa property() +*/ + +/*! + \fn bool Phonon::ObjectDescriptionData::isValid() const + + Returns true if the Tuple is valid (index != -1); otherwise returns + false. +*/ + +/*! + \fn int Phonon::ObjectDescriptionData::index() const + + A unique identifier for this device/. Used internally + to distinguish between the devices/. + + \return An integer that uniquely identifies every device. +*/ + +/*! + \fn static ObjectDescriptionData *Phonon::ObjectDescriptionData::fromIndex(ObjectDescriptionType type, int index) + \internal +*/ + +/*! + \fn Phonon::ObjectDescriptionData::~ObjectDescriptionData() + \internal +*/ + +/*! + \fn Phonon::ObjectDescriptionData::ObjectDescriptionData(ObjectDescriptionPrivate * = 0) + \internal +*/ + +/*! + \class Phonon::AddonInterface + \inmodule Phonon + \since 4.4 + \internal + \brief Interface for Menu, Chapter, Angle and Title/Track control. +*/ + +/*! + \fn virtual Phonon::AddonInterface::~AddonInterface() + \internal +*/ + +/*! + \enum Phonon::AddonInterface::Interface + + This enum describes the type of interface represented by an AddonInterface object. + + \value NavigationInterface + \value ChapterInterface + \value AngleInterface + \value TitleInterface +*/ + +/*! + \enum Phonon::AddonInterface::NavigationCommand + \internal + \value Menu1Button +*/ + +/*! + \enum Phonon::AddonInterface::ChapterCommand + \internal + \value availableChapters + \value chapter + \value setChapter +*/ + +/*! + \enum Phonon::AddonInterface::AngleCommand + \internal + \value availableAngles + \value angle + \value setAngle +*/ + +/*! + \enum Phonon::AddonInterface::TitleCommand + \internal + \value availableTitles + \value title + \value setTitle + \value autoplayTitles + \value setAutoplayTitles +*/ + +/*! + \fn virtual bool Phonon::AddonInterface::hasInterface(Interface iface) const = 0 + \internal +*/ + +/*! + \fn virtual QVariant Phonon::AddonInterface::interfaceCall(Interface iface, int command, + const QList &arguments) = 0 + \internal +*/ + +/*! + \class Phonon::MediaNodePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \namespace Phonon::Factory + \inmodule Phonon + \internal +*/ + +/*! + \fn Sender *Phonon::Factory::sender() + + Returns a pointer to the object emitting the signals. + + \sa Sender::backendChanged() +*/ + +/*! + \fn QObject *Phonon::Factory::createMediaObject(QObject *parent = 0) + + Create a new backend object for a MediaObject. + + \return a pointer to the MediaObject the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createEffect(int effectId, QObject *parent = 0) + + Create a new backend object for a Effect. + + \return a pointer to the Effect the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createVolumeFaderEffect(QObject *parent = 0) + + Create a new backend object for a VolumeFaderEffect. + + \return a pointer to the VolumeFaderEffect the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createAudioOutput(QObject *parent = 0) + + Create a new backend object for a AudioOutput. + + \return a pointer to the AudioOutput the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createVideoWidget(QObject *parent = 0) + + Create a new backend object for a VideoWidget. + + \return a pointer to the VideoWidget the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::backend(bool createWhenNull = true) + + \return a pointer to the backend interface. +*/ + +/*! + \fn QString Phonon::Factory::identifier() + + Unique identifier for the Backend. Can be used in configuration files + for example. +*/ + + +/*! + \fn QString Phonon::Factory::backendName() + + Get the name of the Backend. + \omit + It's the name from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendComment() + + Get the comment of the Backend. + \omit + It's the comment from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendVersion() + + Get the version of the Backend. + \omit + It's the version from the .desktop file. + \endomit + + The version is especially interesting if there are several versions + available for binary incompatible versions of the backend's media + framework. +*/ + +/*! + \fn QString Phonon::Factory::backendIcon() + + Get the icon (name) of the Backend. + \omit + It's the icon from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendWebsite() + + Get the website of the Backend. + \omit + It's the website from the .desktop file. + \endomit +*/ + +/*! + \fn QObject *Phonon::Factory::registerQObject(QObject *object) + + Registers the given backend \a object with the factory. +*/ + +/*! + \fn bool Phonon::Factory::isMimeTypeAvailable(const QString &mimeType) +*/ + +/*! + \fn void Phonon::Factory::registerFrontendObject(MediaNodePrivate *) + \internal +*/ + +/*! + \fn void Phonon::Factory::deregisterFrontendObject(MediaNodePrivate *) + \internal +*/ + +/*! + \fn void Phonon::Factory::setBackend(QObject *) +*/ + +/*! + \fn PlatformPlugin *Phonon::Factory::platformPlugin() +*/ + +/*! +/*! + \class Phonon::AbstractMediaStreamPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::FrontendInterfacePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectWidgetPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::IODeviceStream + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn explicit Phonon::IODeviceStream::IODeviceStream(QIODevice *ioDevice, QObject *parent = 0) + \internal + + Creates a new IODeviceStream with the given \a ioDevice and \a + parent. + +*/ + +/*! + \fn Phonon::IODeviceStream::~IODeviceStream() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::reset() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::needData() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::seekStream(qint64) + \internal +*/ + +/*! + \namespace Phonon::Platform + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::EffectDescriptionModel + \inmodule Phonon + \brief provides a item view model containing available audio effects. + +*/ + +/*! + \typedef Phonon::SubtitleDescription + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::SubtitleDescriptionModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioChannelDescription + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioChannelDescriptionModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioCaptureDevice + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioCaptureDeviceModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef typedef void (*CleanUpFunction)() + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::QObjectPair + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \typedef Phonon::AudioOutputDeviceModel + \inmodule Phonon + \brief provides an item view model containing available audio output devices. + +*/ + +/*! + \fn uint Phonon::qHash(const Phonon::EffectParameter ¶m) + \internal + +*/ + +/*! + \fn Phonon::CleanUpGlobalStatic::~CleanUpGlobalStatic() + \internal +*/ + +/*! + \class Phonon::ConstIface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::CleanUpGlobalStatic + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectParameterPrivate + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::QSettingsGroup + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::MediaNodeDestructionHandler + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \fn Phonon::MediaNodeDestructionHandler::~MediaNodeDestructionHandler() + \internal + Called from Base::~Base if this object was registered + using BasePrivate::addDestructionHandler(). +*/ + +/*! + \fn Phonon::MediaNodeDestructionHandler::phononObjectDestroyed(MediaNodePrivate *) + \internal +*/ + +/*! + \fn explicit Phonon::EffectWidget::EffectWidget(Effect *effect, QWidget *parent = 0) + \internal + + Constructs a new EffectWidget for the specified \a effect and with + the specified \a parent. +*/ + +/*! + \fn Phonon::EffectWidget::~EffectWidget() + \internal +*/ + +/*! + \fn QDebug Phonon::operator<<(QDebug s, const ObjectDescription &o) + \internal +*/ + +/*! + \class Phonon::ListModelHelper + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class AudioOutputInterface42 + \inmodule Phonon + \since 4.4 + \internal +*/ + diff --git a/doc/src/phonon.qdoc b/doc/src/phonon.qdoc new file mode 100644 index 0000000..e86ccf6 --- /dev/null +++ b/doc/src/phonon.qdoc @@ -0,0 +1,642 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page phonon-overview.html + \title Phonon Overview + \ingroup multimedia + + \tableofcontents + + \section1 Introduction + + Qt uses the Phonon multimedia framework to provide functionality + for playback of the most common multimedia formats.The media can + be read from files or streamed over a network, using a QURL to a + file. + + In this overview, we take a look at the main concepts of Phonon. + We also explain the architecture, examine the + core API classes, and show examples on how to use the classes + provided. + + \section1 Architecture + + Phonon has three basic concepts: media objects, sinks, and paths. + A media object manages a media source, for instance, a music file; + it provides simple playback control, such as starting, stopping, + and pausing the playback. A sink outputs the media from Phonon, + e.g., by rendering video on a widget, or by sending audio to a + sound card. Paths are used to connect Phonon objects, i.e., a + media object and a sink, in a graph - called a media graph in + Phonon. + + As an example, we show a media graph for an audio stream: + + \image conceptaudio.png + + The playback is started and managed by the media object, which + send the media stream to any sinks connected to it by a path. The + sink then plays the stream back, usually though a sound card. + + \omit Not sure if this goes here, or anywhere... + All nodes in the graph are synchronized by the framework, + meaning that if more than one sink is connected to the same + media object, the framework will handle the synchronization + between the sinks; this happens for instance when a media + source containing video with sound is played back. More on + this later. + \endomit + + \section2 Media Objects + + The media object, an instance of the \l{Phonon::}{MediaObject} + class, lets you start, pause, and stop the playback of a media + stream, i.e., it provided basic control over the playback. You may + think of the object as a simple media player. + + The media data is provided by a media source, which is + kept by the media object. The media source is a separate + object - an instance of \l{Phonon::}{MediaSource} - in Phonon, and + not part of the graph itself. The source will supply the media + object with raw data. The data can be read from files and streamed + over a network. The contents of the source will be interpreted by + the media object. + + A media object is always instantiated with the default constructor + and then supplied with a media source. Concrete code examples are + given later in this overview. + + As a complement to the media object, Phonon also provides + \l{Phonon::}{MediaController}, which provides control over + features that are optional for a given media. For instance, for + chapters, menus, and titles of a VOB (DVD) file will be features + managed by a \l{Phonon::}{MediaController}. + + \section2 Sinks + + A sink is a node that can output media from the graph, i.e., it + does not send its output to other nodes. A sink is usually a + rendering device. + + The input of sinks in a Phonon media graph comes from a + \l{Phonon::}{MediaObject}, though it might have been processed + through other nodes on the way. + + While the \l{Phonon::}{MediaObject} controls the playback, the + sink has basic controls for manipulation of the media. With an + audio sink, for instance, you can control the volume and mute the + sound, i.e., it represents a virtual audio device. Another example + is the \l{Phonon::}{VideoWidget}, which can render video on a + QWidget and alter the brightness, hue, and scaling of the video. + + As an example we give an image of a graph used for playing back a + video file with sound. + + \image conceptvideo.png + + \section2 Processors + + Phonon does not allow manipulation of media streams directly, + i.e., one cannot alter a media stream's bytes programmatically + after they have been given to a media object. We have other nodes + to help with this: processors, which are placed in the graph on + the path somewhere between the media object and its sinks. In + Phonon, processors are of the \l{Phonon::}{Effect} class. + + When inserted into the rendering process, the processor will + alter the media stream, and will be active as long as it is part + of the graph. To stop, it needs to be removed. + + \omit \image conceptprocessor.png \endomit + + The \c {Effect}s may also have controls that affect how the media + stream is manipulated. A processor applying a depth effect to + audio, for instance, can have a value controlling the amount of + depth. An \c Effect can be configured at any point in time. + + \section1 Playback + + In some common cases, it is not necessary to build a graph + yourself. + + Phonon has convenience functions for building common graphs. For + playing an audio file, you can use the + \l{Phonon::}{createPlayer()} function. This will set up the + necessary graph and return the media object node; the sound can + then be started by calling its \l{Phonon::MediaObject::}{play()} + function. + + \snippet snippets/phonon.cpp 0 + + We have a similar solution for playing video files, the + \l{Phonon::}{VideoPlayer}. + + \snippet snippets/phonon.cpp 1 + + The VideoPlayer is a widget onto which the video will be drawn. + + The \c .pro file for a project needs the following line to be added: + + \snippet doc/src/snippets/code/doc_src_phonon.qdoc 0 + + Phonon comes with several widgets that provide functionality + commonly associated with multimedia players - notably SeekSlider + for controlling the position of the stream, VolumeSlider for + controlling sound volume, and EffectWidget for controlling the + parameters of an effect. You can learn about them in the API + documentation. + + \section1 Building Graphs + + If you need more freedom than the convenience functions described + in the previous section offers you, you can build the graphs + yourself. We will now take a look at how some common graphs are + built. Starting a graph up is a matter of calling the + \l{Phonon::MediaObject::}{play()} function of the media object. + + If the media source contains several types of media, for instance, a + stream with both video and audio, the graph will contain two + output nodes: one for the video and one for the audio. + + We will now look at the code required to build the graphs discussed + previously in the \l{Architecture} section. + + \section2 Audio + + When playing back audio, you create the media object and connect + it to an audio output node - a node that inherits from + AbstractAudioOutput. Currently, AudioOutput, which outputs audio + to the sound card, is provided. + + The code to create the graph is straight forward: + + \snippet snippets/phonon.cpp 2 + + Notice that the type of media an input source has is resolved by + Phonon, so you need not be concerned with this. If a source + contains multiple media formats, this is also handled + automatically. + + The media object is always created using the default constructor + since it handles all multimedia formats. + + The setting of a Category, Phonon::MusicCategory in this case, + does not affect the actual playback; the category can be used by + KDE to control the playback through, for instance, the control + panel. + + \omit Not sure about this + Users of KDE can often also choose to send sound with the + CommunicationCategory, e.g., given to VoIP, to their headset, + while sound with MusicCategory is sent to the sound card. + \endomit + + The AudioOutput class outputs the audio media to a sound card, + that is, one of the audio devices of the operating system. An + audio device can be a sound card or a intermediate technology, + such as \c DirectShow on windows. A default device will be chosen + if one is not set with \l{Phonon::AudioOutput::}{setOutputDevice()}. + + The AudioOutput node will work with all audio formats supported by + the back end, so you don't need to know what format a specific + media source has. + + For a an extensive example of audio playback, see the \l{Music + Player Example}{Phonon Music Player}. + + \section3 Audio Effects + + Since a media stream cannot be manipulated directly, the backend + can produce nodes that can process the media streams. These nodes + are inserted into the graph between a media object and an output + node. + + Nodes that process media streams inherit from the Effect class. + The effects available depends on the underlying system. Most of + these effects will be supported by Phonon. See the \l{Querying + Backends for Support} section for information on how to resolve + the available effects on a particular system. + + We will now continue the example from above using the Path + variable \c path to add an effect. The code is again trivial: + + \snippet snippets/phonon.cpp 3 + + Here we simply take the first available effect on the system. + + The effect will start immediately after being inserted into the + graph if the media object is playing. To stop it, you have to + detach it again using \l{Phonon::Path::}{removeEffect()} of the Path. + + \section2 Video + + For playing video, VideoWidget is provided. This class functions + both as a node in the graph and as a widget upon which it draws + the video stream. The widget will automatically choose an available + device for playing the video, which is usually a technology + between the Qt application and the graphics card, such as \c + DirectShow on Windows. + + The video widget does not play the audio (if any) in the media + stream. If you want to play the audio as well, you will need + an AudioOutput node. You create and connect it to the graph as + shown in the previous section. + + The code for creating this graph is given below, after which + one can play the video with \l{Phonon::MediaObject::}{play()}. + + \snippet snippets/phonon.cpp 4 + + The VideoWidget does not need to be set to a Category, it is + automatically classified to \l{Phonon::}{VideoCategory}, we only + need to assure that the audio is also classified in the same + category. + + The media object will split files with different media content + into separate streams before sending them off to other nodes in + the graph. It is the media object that determines the type of + content appropriate for nodes that connect to it. + + \omit This section is from the future + + \section2 Multiple Audio Sources and Graph Outputs + + In this section, we take a look at a graph that contains multiple + audio sources in addition to video. We have a video camera with + some embarrassing home footage from last weekend's party, a + microphone with which we intend to add commentary, and an audio + music file to set the correct mood. It would be an advantage to + write the graph output to a file for later viewing, but since this + is not yet supported by Qt backends, we will play it back + directly. + + + + + + + + \endomit + + \section1 Backends + + The multimedia functionality is not implemented by Phonon itself, + but by a back end - often also referred to as an engine. This + includes connecting to, managing, and driving the underlying + hardware or intermediate technology. For the programmer, this + implies that the media nodes, e.g., media objects, processors, and + sinks, are produced by the back end. Also, it is responsible for + building the graph, i.e., connecting the nodes. + + The backends of Qt use the media systems DirectShow (which + requires DirectX) on Windows, QuickTime on Mac, and GStreamer on + Linux. The functionality provided on the different platforms are + dependent on these underlying systems and may vary somewhat, e.g., + in the media formats supported. + + Backends expose information about the underlying system. It can + tell which media formats are supported, e.g., \c AVI, \c mp3, or + \c OGG. + + A user can often add support for new formats and filters to the + underlying system, by, for instance, installing the DivX codex. We + can therefore not give an exact overview of which formats are + available with the Qt backends. + + \omit Not sure I want a separate section for this + \section2 Communication with the Backends + + We cooperate with backends through static functions in the + Phonon namespace. We have already seen some of these functions + in code examples. Their two main responsibilities are creating + graph nodes and supplying information about the capabilities + of the various nodes. The nodes uses the backend internally + when created, so it is only connecting them in the graph that + you need to use the backend directly. + + The main functions for graph building are: + + \list + \o createPath(): This function creates a path between to + nodes, which it takes as arguments. + \o + \endlist + + For more detailed information, please consult the API + documentation. + + \endomit + + \section2 Querying Backends for Support + + As mentioned, Phonon depends on the backend to provide its + functionality. Depending on the individual backend, full support + of the API may not be in place. Applications therefore need to + check with the backend if functionality they require is + implemented. In this section, we take look at how this is done. + + The backend provides the + \l{Phonon::BackendCapabilities::}{availableMimeTypes()} and + \l{Phonon::BackendCapabilities::}{isMimeTypeAvailable()} functions + to query which MIME types the backend can produce nodes for. The + types are listed as strings, which for any type is equal for any + backend or platform. + + The backend will emit a signal - + \l{Phonon::BackendCapabilities::}{Notifier::capabilitiesChanged()} + - if its abilities have changed. If the available audio devices + have changed, the + \l{Phonon::BackendCapabilities::}{Notifier::availableAudioOutputDevicesChanged()} + signal is emitted instead. + + To query the actual audio devices possible, we have the + \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()} as + mentioned in the \l{#Sinks}{Sinks} section. To query information + about the individual devices, you can examine its \c name(); this + string is dependent on the operating system, and the Qt backends + does not analyze the devices further. + + The sink for playback of video does not have a selection of + devices. For convenience, the \l{Phonon::}{VideoWidget} is both a + node in the graph and a widget on which the video output is + rendered. To query the various video formats available, use + \l{Phonon::BackendCapabilities::}{isMimeTypeAvailable()}. To add + it to a path, you can use the Phonon::createPath() as usual. After + creating a media object, it is also possible to call its + \l{Phonon::MediaObject::}{hasVideo()} function. + + See also the \l{Capabilities Example}. + + \section1 Installing Phonon + + When running the Qt configure script, you will be notified whether + Phonon support is available on your system. As mentioned + previously, to use develop and run Phonon applications, you also + need to link to a backend, which provides the multimedia + functionality. + + Note that Phonon applications will compile and run without a + working backend, but will, of course, not work as expected. + + The following sections explains requirements for each backend. + + \section2 Windows + + On Windows, building Phonon requires DirectX and DirectShow + version 9 or higher. You'll need additional SDKs you can download + from Microsoft. + + \section3 Windows XP and later Windows versions + + If you develop for Windows XP and up, you should download the Windows SDK + \l{http://www.microsoft.com/downloads/details.aspx?FamilyID=e6e1c3df-a74f-4207-8586-711ebe331cdc&DisplayLang=en}{here}. + Before building Qt, just call the script: \c {C:\Program Files\Microsoft SDKs\Windows\v6.1\Bin\setenv.cmd} + + \note Visual C++ 2008 already contains the Windows SDK and doesn't + need that package and has already the environment set up for a + smooth compilation of phonon. + + \section3 Earlier Windows versions than Windows XP + + If you want to support previous Windows versions, you should download and install the Platform SDK. You find it + \l{http://www.microsoft.com/downloads/details.aspx?FamilyId=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en}{here}. + + \note The platform SDK provided with Visual C++ is not + complete and + you'll need this one to have DirectShow 9.0 support. You can download the DirectX SDK + \l{http://www.microsoft.com/downloads/details.aspx?familyid=09F7578C-24AA-4E0A-BF91-5FEC24C8C7BF&displaylang=en}{here}. + + \section3 Setting up the environment + + Once the SDKs are installed, please make sure to set your + environment variables LIB and INCLUDE correctly. The paths to the + include and lib directory of the SDKs should appear first. + Typically, to setup your environment, you would execute the + following script: + + \code + Set DXSDK_DIR=C:\Program Files\Microsoft DirectX SDK (February 2007) + %DXSDK_DIR%\utilities\bin\dx_setenv.cmd + C:\program files\Microsoft Platform SDK\setenv.cmd + \endcode + + If your environment is setup correctly, executing configure.exe on + your Qt installation should automatically activate Phonon. + + \warning The MinGW version of Qt does not support building the + Qt backend. + + \section2 Linux + + The Qt backend on Linux uses GStreamer (minimum version is 0.10), + which must be installed on the system. At a minimum, you need the + GStreamer library and base plugins, which provides support for \c + .ogg files. The package names may vary between Linux + distributions; on Mandriva, they have the following names: + + \table + \header + \o Package + \o Description + \row + \o libgstreamer0.10_0.10 + \o The GStreamer base library. + \row + \o libgstreamer0.10_0.10-devel + \o Contains files for developing applications with + GStreamer. + \row + \o libgstreamer-plugins-base0.10 + \o Contains the basic plugins for audio and video + playback, and will enable support for \c ogg files. + \row + \o libgstreamer-plugins-base0.10-devel + \o Makes it possible to develop applications using the + base plugins. + \endtable + + \omit Should go in troubleshooting (in for example README) + alsasink backend for GStreamer + \table + \header + \o Variable + \o Description + \row + \o PHONON_GST_AUDIOSINK + \o Sets the audio sink to be used. Possible values are + ... alsasink. + \row + \o PHONON_GSTREAMER_DRIVER + \o Sets the driver for GStreamer. This driver will + usually be configured automatically when + installing. + \row + \o PHONON_GST_VIDEOWIDGET + \o This variable can be set to the name of a widget to + use as the video widget?? + \row + \o PHONON_GST_DEBUG + \o Phonon will give debug information while running if + this variable is set to a number between 1 and 3. + \row + \o PHONON_TESTURL + \o ... + \endtable + \endomit + + \section2 Mac OS X + + On Mac OS X, Qt uses QuickTime for its backend. The minimum + supported version is 7.0. + + \section1 Deploying Phonon Applications on Windows and Mac OS X + + On Windows and Mac OS X, the Qt backend makes use of the + \l{QtOpenGL Module}{QtOpenGL} module. You therefore need to deploy + the QtOpenGL shared library. If this is not what you want, it is + possible to configure Qt without OpenGL support. In that case, you + need to run \c configure with the \c -no-opengl option. + + \section1 Work in Progress + + Phonon and its Qt backends, though fully functional for + multimedia playback, are still under development. Functionality to + come is the possibility to capture media and more processors for + both music and video files. + + Another important consideration is to implement support for + storing media to files; i.e., not playing back media directly. + + We also hope in the future to be able to support direct + manipulation of media streams. This will give the programmer more + freedom to manipulate streams than just through processors. + + Currently, the multimedia framework supports one input source. It will be + possible to include several sources. This is useful in, for example, audio + mixer applications where several audio sources can be sent, processed and + output as a single audio stream. +*/ + +/*! + \namespace Phonon + \brief The Phonon namespace contains classes and functions for multimedia applications. + \since 4.4 + + This namespace contains classes to access multimedia functions for + audio and video playback. Those classes are not dependent on any specific + framework, but rather use exchangeable backends to do the work. + + See the \l{Phonon Module} page for general information about the + framework. +*/ + +/*! + \page phonon-module.html + \module Phonon + \title Phonon Module + \contentspage Qt's Modules + \previouspage QtXmlPatterns + \nextpage Qt3Support + \ingroup modules + + \brief The Phonon module contains namespaces and classes for multimedia functionality. + + \generatelist{classesbymodule Phonon} + + Phonon is a cross-platform multimedia framework that enables the use of + audio and video content in Qt applications. The \l{Phonon Overview} + document provides an introduction to the architecture and features included + in Phonon. The \l{Phonon} namespace contains a list of all classes, functions + and namespaces provided by the module. + + Applications that use Phonon's classes need to + be configured to be built against the Phonon module. + The following declaration in a \c qmake project file ensures that + an application is compiled and linked appropriately: + + \snippet doc/src/snippets/code/doc_src_phonon.qdoc 1 + + The Phonon module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. + + \section1 Qt Backends + + Qt Backends are currently developed for Phonon version 4.1. The Phonon + project has moved on and introduced new features that the Qt Backends do not + implement. We have chosen not to document the part of Phonon that we do not + support. Any class or function not appearing in our documentation can be + considered unsupported. + + \section1 License Information + + Qt Commercial Edition licensees that wish to distribute applications that + use the Phonon module need to be aware of their obligations under the + GNU Lesser General Public License (LGPL). + + Developers using the Open Source Edition can choose to redistribute + the module under the appropriate version of the GNU LGPL; version 2.1 + for applications and libraries licensed under the GNU GPL version 2, + or version 3 for applications and libraries licensed under the GNU + GPL version 2. + + \legalese + This file is part of the KDE project + + Copyright (C) 2005-2007 Matthias Kretz \BR + Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). + Contact: Qt Software Information (qt-info@nokia.com) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License version 2 as published by the Free Software Foundation. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. + \endlegalese +*/ diff --git a/doc/src/platform-notes.qdoc b/doc/src/platform-notes.qdoc new file mode 100644 index 0000000..d5eee27 --- /dev/null +++ b/doc/src/platform-notes.qdoc @@ -0,0 +1,740 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page platform-notes-platforms.html + \ingroup platform-notes + \title Platform Notes + \brief Information about the platforms on which Qt can be used. + + This page contains information about the platforms Qt is currently known + to run on, with links to platform-specific notes, including any known bugs + or incompatibilities. + + \list + \o \l{Platform Notes - X11} + \tableofcontents{1 Platform Notes - X11} + \o \l{Platform Notes - Windows} + \tableofcontents{1 Platform Notes - Windows} + \o \l{Platform Notes - Mac OS X} + \tableofcontents{1 Platform Notes - Mac OS X} + \o \l{Platform Notes - Embedded Linux} + \tableofcontents{1 Platform Notes - Embedded Linux} + \o \l{Platform Notes - Windows CE} + \tableofcontents{1 Platform Notes - Windows CE} + \endlist + + See also the \l{Compiler Notes} for information about compiler-specific + build issues. Information about the combinations of platforms and compilers + supported by Qt can be found on the \l{Supported Platforms} page. + + If you have anything to add to this list or any of the platform or + compiler-specific pages, please submit it via the \l{Bug Report Form}. +*/ + +/*! + \page platform-notes-x11.html + \title Platform Notes - X11 + \contentspage Platform Notes + + This page contains information about the X11 platforms Qt is currently + known to run on, with links to platform-specific notes. More information + about the combinations of platforms and compilers supported by Qt can be + found on the \l{Supported Platforms} page. + + \tableofcontents + + \target AIX + \section1 AIX - 5.2 + + Qt has been tested on AIX 5.2, using the + \l{Compiler Notes#IBM xlC (AIX)}{xlC} compiler. + + \table + \header \o Compiler \o Notes + \row \o xlC + \o If Qt is built correctly but all symbols are reported to be missing + when you link an application, your makeC++SharedLib script might be out + of date. Make sure you have the latest version from the + \l{http://www-306.ibm.com/software/awdtools/vacpp/support/}{IBM website}. + \row \o GCC + \o We have tested earlier versions of Qt 4 successfully with GCC version + 3.3 and above. Some versions of GCC may fail to link Qt with a "TOC overflow" + message. + Fix this by upgrading to the latest maintenance release of the dynamic + linker. On AIX this is bos.rte.bind_cmds.4.1.5.3 or later. + Some versions of GCC may fail to build Qt with STL and large-file support + enabled, due to + \l{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=9551}{a bug in GCC}. + Fix this by upgrading to the latest maintenance release of the compiler. + It is also possible to work around this problem by running configure with + either \c{-no-stl} or \c{-no-largefile}. + \endtable + + \target FreeBSD + \section1 FreeBSD - 6.0-RELEASE + + \note FreeBSD is a community supported platform. See the + \l{Supported Platforms} page for more information. + + The system compiler on FreeBSD 4.x is gcc 2.95.4, which is not + officially supported by Qt 4. We develop using and recommend + ports/lang/gcc34. You will need to run configure with the + \c{-platform freebsd-g++34} arguments. Optionally, you may use + ports/lang/icc. + + The system compiler on FreeBSD 5.x and 6.x is GCC 3.4.4, which should be + sufficient to build Qt. You do not need to add any special arguments when + running configure. Optionally, you may use ports/lang/icc. + + Note that we do not actively test FreeBSD 4.x and 5.x. Our developers + migrated to 6.x after the Qt 4 launch. FreeBSD-CURRENT is not supported. + + \target HP-UX + \section1 HP-UX + + Qt supports HP-UX on both PA-RISC and the Itanium (IA64) architectures. + + \section2 PA-RISC - B.11.11 or later + + You can configure Qt for aCC in 32 and 64 bit mode (hpux-acc-64 or + hpux-acc-32), or gcc in 32 bit mode (hpux-g++). The default platform is + hpux-acc-32. The minimum required version for aCC (HP ANSI C++) on PA-RISC + is A.03.57. The supported gcc compiler is gcc 3.4.3. + + \section2 Itanium - B.11.23 or later + + You can configure Qt for aCC in 32 and 64 bit mode (hpuxi-acc-64 or + hpuxi-acc-32). gcc is currently unsupported. The default platform is + hpuxi-acc-64. The minimum required version for aCC (HP ANSI C++) on + Itanium is A.06.12. + + \section2 OpenGL Support + + Qt's \l{QtOpenGL}{OpenGL} module requires GLX 1.3 or later to be installed. + This is available for HP-UX 11i - see the + \l{http://docs.hp.com/en/5992-2331/ch04s02.html}{Graphics and Technical Computing Software} + section of the release notes for more information. + + \target IRIX + \section1 IRIX - 6.5.x + + \bold{IRIX is an unsupported platform - please see Qt Software's online + \l{Platform Support Policy} for details.} + + Unpackaging and IRIX tar: + Because of long filenames some files will be cut off incorrectly with IRIX + tar. Please use GNU tar to unpack Qt packages. + + \section1 Linux + + There are no known problems with using Qt on production versions of + Linux/x86, Linux/ppc, Linux/amd64 and Linux/ia64 (including Altix(R)). + + For the gcc/g++ compiler, please also see the relevant + \l{Compiler Notes#GCC}{compiler page}. + + \section2 Installation problems + + See also the \l{Installation FAQ}. + + If you experience problems when installing new open source versions of Qt + versions, try to use the open source Qt archives (e.g., RPM) + provided by your Linux distribution. If you need to install the source (.tgz) + archive, be aware that you will probably end up with two different + versions of the Qt library installed on your system, which will probably + lead to link errors, like this: + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 0 + Fix this by removing the old version of the library. + + If you have problems installing open source versions of Qt + provided by your Linux distribution (e.g., RPM), please consult the + maintainers of the distribution, not us. + + Some RPM versions have problems installing some of the Qt RPM archives + where installation stops with an error message warning about a + "Failed Dependency". Use the \c{--nodeps} option to \c rpm to workaround + this problem. + + \target Solaris + \section1 Solaris - 9 or later + + \section2 Unpackaging and Solaris tar + + On some Solaris systems, both Solaris tar and GNU tar have been reported + to truncate long filenames. We recommend using star instead + (http://star.berlios.de). + + \section2 CC on Solaris + + Be sure to check our \l{Compiler Notes#Sun Studio}{Forte Developer / Sun Studio} + notes. + + \section2 GCC on Solaris + + Be sure to check the installation notes for \l{GCC on Solaris}. + Do not use GCC with Sun's assembler/linker, this will result in link-time + errors in shared libraries. Use GNU binutils instead. + + GCC 3.2.* is known to miscompile Qt due to an optimizer bug that will + cause the resulting binaries to hang. Please use GCC 3.4.2 or later. +*/ + +/*! + \page platform-notes-windows.html + \title Platform Notes - Windows + \contentspage Platform Notes + + This page contains information about the Windows platforms Qt is currently + known to run on, with links to platform-specific notes. More information + about the combinations of platforms and compilers supported by Qt can be + found on the \l{Supported Platforms} page. + + \tableofcontents + + \section1 Windows Vista + + Known issues for Qt on Vista will be listed here. + + As of Qt 4.2.0 no Vista-specific issues are known. + + \target Windows NT + \section1 Windows XP, Windows 2000 and Windows NT + + \section2 Installation location + + Installing Qt into a directory with spaces, e.g. C:\\Program Files, may + cause linker errors like the following: + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 2 + + Install Qt into a subdirectory without spaces to avoid this problem. + + \section2 AccelGALAXY graphic card + + When you use a NT 4.0 machine with the driver number + 4,00,1381,1000,021,4.0.0 there is a problem with drag an drop and icons. + The computer freezes, and you have to reset. The problem disappears with + the newest version of the driver, available at + \l{http://www.es.com/}{www.es.com}. + + \section2 Possible GL conflict + + There is a known issue with running Microsoft NetMeeting, Lotus SameTime + and other applications that require screen grabbing while direct + rendering is enabled. Other GL-applications may not work as expected, + unless direct rendering is disabled. +*/ + +/*! + \page platform-notes-mac.html + \title Platform Notes - Mac OS X + \contentspage Platform Notes + + This page contains information about the Mac OS X versions Qt is currently + known to run on, with links to platform-specific notes. More information + about the combinations of platforms and compilers supported by Qt can be + found on the \l{Supported Platforms} page. + + \tableofcontents + + \section1 General Information + + Qt 4.4 and Qt 4.5 development is only supported on Mac OS X 10.4 and up. + Applications built against these version of Qt can be deployed on Mac OS X + 10.3, but cannot be developed on that version of the operating system due + to compiler issues. + + Qt 4.3 has been tested to run on Mac OS X 10.3.9 and up. See notes on + the binary package for more information. + + Qt 4.1 has been tested to run on Mac OS X 10.2.8 and up. Qt 4.1.4 is the + last release to work with Mac OS X 10.2. + + \section2 Required GCC version + + Apple's gcc 4 that is shipped with the Xcode Tools for both Mac OS X 10.4 + and 10.5 will compile Qt. There is preliminary support for gcc 4.2 which + is included with Xcode Tools 3.1+ (configurable with + \c{-platform macx-g++42}). + + \section2 Binary Package + + The binary package requires that you have your .qt-license file in your + home directory. Installer.app cannot complete without a valid .qt-license + file. Evaluation users of Qt will have information about how to create + this file in the email they receive. + + The binary package was built on Mac OS X 10.4 with Xcode Tools 2.1 + (gcc 4.0.0) for Qt 4.1.0, Xcode Tools 2.2 (gcc 4.0.1) for Qt 4.1.1-4.1.4 + and Xcode Tools 2.3 for 4.2.0. It will only link executables built + against 10.4 (or a 10.4 SDK). You should be able to run applications + linked against these frameworks on Mac OS X 10.3.9 and Mac OS X 10.4+. + If you require a different configuration, you will have to use the + source package and build with GCC 3.3. + + \section2 Mac OS X on Intel hardware + + Qt 4 fully supports both the Intel and PowerPC architectures on the Mac. + As of Qt 4.1 it is possible to support the Intel architecture by + creating Universal Binaries with qmake. As of Qt 4.1 it is possible to + build Qt as a set of universal binaries and frameworks from configure by + adding these extra flags: + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 3 + + If you are building on Intel hardware you can omit the sdk parameter, but + PowerPC hardware requires it. + + You can also generate universal binaries using qmake. Simply add these + lines to your .pro file: + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 4 + + \section2 Build Issues + + If Qt does not build upon executing make, and fails with an error message + such as + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 5 + + this could be an indication you have upgraded your version of Mac OS X + (e.g. 10.3 to 10.4), without upgrading your Developer Tools (Xcode Tools). + These must match in order to successfully compile files. + + Please be sure to upgrade both simultaneously. If problems still occur, + contact support. + + \section2 Fink + + If you have installed the Qt for X11 package from \l{Fink}, + it will set the QMAKESPEC environment variable to darwin-g++. This will + cause problems when you build the Qt for Mac OS X package. To fix this, simply + unset your QMAKESPEC or set it to macx-g++ before you run configure. + You need to have a fresh Qt distribution (make confclean). + + \section2 MySQL and Mac OS X + + There seems to be a issue when both -prebind and -multi_module are + defined when linking static C libraries into dynamic library. If you + get the following error message when linking Qt: + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 6 + + re-link Qt using -single_module. This is only a problem when building the + MySQL driver into Qt. It does not affect plugins or static builds. + + \section2 Qt and Precompiled Headers (PCH) + + Starting with Qt 3.3.0 it is possible to use precompiled headers. They + are not enabled by default as it appears that some versions of Apple's + GCC and make have problems with this feature. If you want to use + precompiled headers when building the Qt source package, specify the + -pch option to configure. If, while using precompiled headers, you + encounter an internal compile error, try removing the -include header + statement from the compile line and trying again. If this solves the + problem, it probably is a good idea to turn off precompiled headers. + Also, consider filing a bug report with Apple so that they can + improve support for this feature. +*/ + +/*! + \page supported-platforms.html + \title Supported Platforms + \brief The platforms supported by Nokia for Qt. + \ingroup platform-notes + + Qt is supported on a variety of 32-bit and 64-bit platforms, and can + usually be built on each platform with GCC, a vendor-supplied compiler, or + a third party compiler. Although Qt may be built on a range of platform-compiler + combinations, only a subset of these are actively supported by Qt Software. + + A more general overview of the platforms Qt runs on can be found on the + \l{Platform Notes} page. Information about the compilers used on each platform + can be found on the \l{Compiler Notes} page. + + \tableofcontents + + \section1 Most Common Actively Supported Platforms + + \table + \header \o Platform \o Compilers + \row \o Apple Mac OS X (32-bit) \o gcc 4.0.1 + \row \o Linux (32 and 64-bit) \o gcc 4.1, 4.2, 4.3 + \row \o Microsoft Windows \o gcc 3.4.2 (MinGW) (32-bit), MSVC 2003, 2005 (32 and 64-bit), 2008, + \l{Known Issues in %VERSION%}{Intel icc (see note)} + \endtable + + Any platform-compiler combinations not listed here should be considered unsupported. + + \section1 Actively Supported Platforms + + \table + \header \o OS \o Architecture \o Makespec \o Compiler version(s) + \row \o AIX \o PowerPC \o aix-xlc \o xlC 6 + \row \o AIX \o PowerPC \o aix-xlc-64 \o xlC 6 + \row \o HPUX \o PA/RISC \o hpux-acc* \o A.03.57 (aCC 3.57) + \row \o HPUX \o PA/RISC \o hpux-g++ \o GCC 3.4.4 + \row \o HPUX \o PA/RISC \o hpux-g++-64 \o GCC 3.4.4 + \row \o HPUX \o Itanium \o hpuxi-acc* \o A.06.10 (aCC 6.10) + \row \o Embedded Linux \o ARM \o qws/linux-arm-g++ \o GCC 3.4, 4.1, 4.2, 4.3 + \row \o Embedded Linux \o Intel 32-bit \o qws/linux-x86-g++ \o GCC 3.4, 4.1, 4.2, 4.3 + \row \o Linux \o Intel 32/64-bit \o linux-g++ \o GCC 4.1, 4.2, 4.3 + \row \o Linux \o Intel 32/64-bit \o linux-icc \o icc 10.1 + \row \o Linux \o Intel 32-bit \o linux-icc-32 \o icc 10.1 + \row \o Linux \o Intel 64-bit \o linux-icc-64 \o icc 10.1 + \row \o Mac OS X \o Intel 32/64-bit, PowerPC \o macx-g++ \o GCC 4.0.1 + \row \o Mac OS X \o Intel 32/64-bit, PowerPC \o macx-g++42 \o GCC 4.2 + \row \o Solaris \o SPARC, Intel 32-bit \o solaris-cc* \o Sun CC 5.5 + \row \o Solaris \o SPARC, Intel 32-bit \o solaris-g++* \o GCC 3.4.2 + \row \o Windows XP/Vista \o Intel 32/64-bit \o win32-g++ \o GCC 3.4.2 (MinGW 5.1.4) + \row \o Windows XP/Vista \o Intel 32/64-bit \o win32-icc \o icc 9.1 + \row \o Windows XP/Vista \o Intel 32/64-bit \o win32-msvc2003 \o Visual Studio 2003 + \row \o Windows XP/Vista \o Intel 32/64-bit \o win32-msvc2005 \o Visual Studio 2005 + \row \o Windows XP/Vista \o Intel 32/64-bit \o win32-msvc2008 \o Visual Studio 2008 + \row \o Windows CE \o Intel 32-bit, ARMv4i, MIPS + \o wince*-msvc2005 \o Visual Studio 2005 + \row \o Windows CE \o Intel 32-bit, ARMv4i, MIPS + \o wince*-msvc2008 \o Visual Studio 2008 + \endtable + + \section1 Community Supported Platforms + + \table + \header \o OS \o Architecture \o Makespec \o Compiler version(s) + \row \o Mac OS X \o Intel 32-bit, PowerPC \o darwin-g++ \o - + \row \o FreeBSD \o - \o freebsd-g++ \o - + \row \o FreeBSD \o - \o freebsd-g++34 \o - + \row \o FreeBSD \o - \o freebsd-g++40 \o - + \row \o FreeBSD \o - \o freebsd-icc \o - + \row \o HPUX \o Itanium \o hpuxi-g++* \o GCC 4.1 + \row \o Linux \o - \o linux-cxx \o - + \row \o Linux \o - \o linux-ecc-64 \o - + \row \o Linux \o Itanium \o linux-g++ \o GCC 3.4 + \row \o Linux \o Intel 32/64-bit \o linux-g++ \o GCC 3.3, 3.4 + \row \o Linux \o Intel 32/64-bit \o linux-g++ \o GCC 4.0 + \row \o Linux \o - \o linux-kcc \o - + \row \o Linux \o - \o linux-llvm \o - + \row \o Linux \o - \o linux-lsb-g++ \o - + \row \o LynxOS \o - \o lynxos-g++ \o - + \row \o Mac OS X \o - \o macx-llvm \o - + \row \o NetBSD \o - \o netbsd-g++ \o - + \row \o OpenBSD \o - \o openbsd-g++ \o - + \row \o Embedded Linux \o MIPS, PowerPC \o qws/linux-g++ \o GCC 3.4, 4.1, 4.2, 4.3 + \endtable + + \section1 Unsupported Platforms + + The following platforms were supported in previous releases, either as actively supported + or community supported platforms, but are now unsupported. + + \table + \header \o OS \o Architecture \o Makespec \o Compiler version(s) + \row \o IRIX \o MIPS \o irix-cc* \o MIPS Pro + \row \o IRIX \o MIPS \o irix-g++* \o GCC 3.3 + \row \o Windows XP/Vista \o Intel 32/64-bit \o win32-msvc \o Visual C++ 6.0 + \row \o Windows XP/Vista \o Intel 32/64-bit \o win32-msvc2002 \o Visual Studio 2002 + \row \o Windows XP/Vista \o Intel 32/64-bit \o win32-msvc.net \o Visual Studio 2002 + \endtable + + Qt Software's online \l{Platform Support Policy} for Qt describes the level of + support you should expect for these platforms. + + \section1 Supported Features + + Not all compilers used to build Qt are able to compile all modules. The following table + shows the compiler support for five modules that are not uniformly available for all + platforms and compilers. + + \table + \header \o Compiler \o{5,1} Features + \header \o \o Concurrent \o XmlPatterns \o WebKit \o CLucene \o Phonon + \row \o g++ 3.3 \o \o \bold{X} \o \o \bold{X} \o \bold{X} + \row \o g++ 3.4 and up \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} + \row + \row \o SunCC 5.5 \o \o \o \o \bold{X} \o \bold{X} + \row + \row \o aCC series 3 \o \o \o \o \bold{X} \o \bold{X} + \row \o aCC series 6 \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} + \row \o MIPSpro 7.4.2m \o{5,1} \e{Unsupported - see the Unsupported Platforms table} + \row \o xlC 6 \o \o \o \o \bold{X} \o \bold{X} + \row \o \l{Known Issues in %VERSION%}{Intel CC 10 (see note)} + \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} + \row + \row \o MSVC 2003 \o \bold{X} \o \bold{X} \o \o \bold{X} \o \bold{X} + \row \o MSVC 2005 and up \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} + \endtable +*/ + +/*! + \page platform-notes-windows-ce.html + \title Platform Notes - Windows CE + \contentspage Platform Notes + + This page contains information about the Windows CE and Windows Mobile + platforms Qt is currently known to run on, with links to platform-specific + notes. More information about the combinations of platforms and compilers + supported by Qt can be found on the \l{Supported Platforms} page. +*/ + +/*! + \page platform-notes-embedded-linux.html + \title Platform Notes - Embedded Linux + \contentspage Platform Notes + + This page contains information about the Embedded Linux platforms Qt is + currently known to run on, with links to platform-specific notes. More + information about the combinations of platforms and compilers supported + by Qt can be found on the \l{Supported Platforms} page. +*/ + +/*! + \page compiler-notes.html + \ingroup platform-notes + \title Compiler Notes + \brief Information about the C++ compilers and tools used to build Qt. + + This page contains information about the C++ compilers and tools used + to build Qt on various platforms. + + \tableofcontents + + Please refer to the \l{Platform Notes} for information on the platforms + Qt is currently known to run on, and see the \l{Supported Platforms} + page for information about the status of each platform. + + If you have anything to add to this list or any of the platform or + compiler-specific pages, please submit it via the + \l{Bug Report Form}. + + \target GCC + \section1 GCC + + \section2 GCC on Windows (MinGW) + + We have tested Qt with this compiler on Windows XP. + The minimal version of MinGW supported is: + + \list + \o GCC 3.4.2 + \o MinGW runtime 3.7 + \o win32api 3.2 + \o binutils 2.15.91 + \o mingw32-make 3.80.0-3 + \endlist + + \section2 GCC 4.0.0 + + The released package of the compiler has some bugs that lead to miscompilations. + We recommend using GCC 4.0.1 or later, or to use a recent CVS snapshot of the + GCC 4.0 branch. The version of GCC 4.0.0 that is shipped with Mac OS X 10.4 + "Tiger" is known to work with Qt for Mac OS X. + + \section2 HP-UX + + The hpux-g++ platform is tested with GCC 3.4.4. + + \section2 Solaris + + Please use GCC 3.4.2 or later. + + \section2 Mac OS X + + Please use the latest GCC 3.3 from Apple or a later version of GCC 3. + The gcc 3.3 that is provided with Xcode 1.5 is known to generate bad code. + Use the November 2004 GCC 3.3 updater \l{http://connect.apple.com}{available from Apple}. + + \section2 GCC 3.4.6 (Debian 3.4.6-5) on AMD64 (x86_64) + + This compiler is known to miscompile some parts of Qt when doing a + release build. There are several workarounds: + + \list 1 + \o Use a debug build instead. + \o For each miscompilation encountered, recompile the file, removing the -O2 option. + \o Add -fno-gcse to the QMAKE_CXXFLAGS_RELEASE. + \endlist + + \section1 HP ANSI C++ (aCC) + + The hpux-acc-32 and hpux-acc-64 platforms are tested with aCC A.03.57. The + hpuxi-acc-32 and hpuxi-acc-64 platforms are tested with aCC A.06.10. + + \section1 Intel C++ Compiler + + \warning Please see the \l{Known Issues in %VERSION%} page for information + about an issue with this compiler. + + \section2 Intel C++ Compiler for Linux + + Qt Software currently tests the following compilers: + + \list + + \o Intel(R) C++ Compiler for applications running on IA-32, + Version 10.1 Build 20080602 Package ID: l_cc_p_10.1.017 + + \o Intel(R) C++ Compiler for applications running on Intel(R) 64, + Version 10.1 Build 20080602 Package ID: l_cc_p_10.1.017 + + \endlist + + We do not currently test the IA-64 (Itanium) compiler. + + \section2 Known Issues with Intel C++ Compiler for Linux + + \list + + \o Precompiled header support does not work in version 10.0.025 + and older. For these compilers, you should configure Qt with + -no-pch. Precompiled header support works properly in version + 10.0.026 and later. + \o Version 10.0.026 for Intel 64 is known to miscompile qmake when + building in release mode. For now, configure Qt with + -debug. Version 10.1.008 and later can compile qmake in release + mode. + \o Versions 10.1.008 to 10.1.015 for both IA-32 and Intel 64 are + known crash with "(0): internal error: 0_47021" when compiling + QtXmlPatterns, QtWebKit, and Designer in release mode. Version + 10.1.017 compiles these modules correctly in release mode. + \endlist + + \section2 Intel C++ Compiler (Windows, Altix) + + Qt 4 has been tested successfully with: + + \list + \o Windows - Intel(R) C++ Compiler for 32-bit applications, + Version 8.1 Build 20050309Z Package ID: W_CC_PC_8.1.026 + \o Altix - Intel(R) C++ Itanium(R) Compiler for Itanium(R)-based + applications Version 8.1 Build 20050406 Package ID: l_cc_pc_8.1.030 + \endlist + + We currently only test the Intel compiler on 32-bit Windows versions. + + \section1 MIPSpro (IRIX) + + \bold{IRIX is an unsupported platform. See the \l{Supported Platforms} page + and Qt's Software's online \l{Platform Support Policy} page for details.} + + Qt 4.4.x requires MIPSpro version 7.4.2m. + + Note that MIPSpro version 7.4.4m is currently not supported, since it has + introduced a number of problems that have not yet been resolved. + We recommend using 7.4.2m for Qt development. However, please note the + unsupported status of this platform. + + \target Sun Studio + \section1 Forte Developer / Sun Studio (Solaris) + + \section2 Sun Studio + + Qt is tested using Sun Studio 8 (Sun CC 5.5). Go to + \l{Sun Studio Patches} page on Sun's Web site to download + the latest patches for your Sun compiler. + + \section2 Sun WorkShop 5.0 + + Sun WorkShop 5.0 is not supported with Qt 4. + + \section1 Visual Studio (Windows) + + We do most of our Windows development on Windows XP, using Microsoft + Visual Studio .NET 2005 and Visual Studio 2008 (both the 32- and 64-bit + versions). + + Qt works with the Standard Edition, the Professional Edition and Team + System Edition of Visual Studio 2005. + + We also test Qt 4 on Windows XP with Visual Studio .NET and Visual Studio 2003. + + In order to use Qt with the Visual Studio 2005/2008 Express Edition you need + to download and install the platform SDK. Due to limitations in the + Express Edition it is not possible for us to install the Qt Visual + Studio Integration. You will need to use our command line tools to + build Qt applications with this edition. + + The Visual C++ Linker doesn't understand filenames with spaces (as in + \c{C:\Program files\Qt\}) so you will have to move it to another place, + or explicitly set the path yourself; for example: + + \snippet doc/src/snippets/code/doc_src_compiler-notes.qdoc 0 + + If you are experiencing strange problems with using special flags that + modify the alignment of structure and union members (such as \c{/Zp2}) + then you will need to recompile Qt with the flags set for the + application as well. + + If you're using Visual Studio .NET (2002) Standard Edition, you should be + using the Qt binary package provided, and not the source package. + As the Standard Edition does not optimize compiled code, your compiled + version of Qt would perform suboptimally with respect to speed. + + With Visual Studio 2005 Service Pack 1 a bug was introduced which + causes Qt not to compile, this has been fixed with a hotfix available + from Microsoft. See this + \l{http://www.qtsoftware.com/developer/faqs/faq.2006-12-18.3281869860}{Knowledge Base entry} + for more information. + + \section1 IBM xlC (AIX) + + The makeC++SharedLib utility must be in your PATH and be up to date to + build shared libraries. From IBM's + \l{http://www.redbooks.ibm.com/abstracts/sg245674.html}{C and C++ Application Development on AIX} + Redbook: + + \list + \o "The second step is to use the makeC++SharedLib command to create the + shared object. The command has many optional arguments, but in its + simplest form, can be used as follows:" + \snippet doc/src/snippets/code/doc_src_compiler-notes.qdoc 1 + \o "The full path name to the command is not required; however, to avoid + this, you will have to add the directory in which it is located to + your PATH environment variable. The command is located in the + /usr/vacpp/bin directory with the VisualAge C++ Professional for AIX, + Version 5 compiler." + \endlist + + \section2 VisualAge C++ for AIX, Version 6.0 + + Make sure you have the + \l{http://www-1.ibm.com/support/search.wss?rs=32&tc=SSEP5D&dc=D400}{latest upgrades} + installed. +*/ diff --git a/doc/src/plugins-howto.qdoc b/doc/src/plugins-howto.qdoc new file mode 100644 index 0000000..95710f6 --- /dev/null +++ b/doc/src/plugins-howto.qdoc @@ -0,0 +1,485 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page plugins-howto.html + \title How to Create Qt Plugins + \brief A guide to creating plugins to extend Qt applications and functionality provided by Qt. + \ingroup howto + + \keyword QT_DEBUG_PLUGINS + \keyword QT_NO_PLUGIN_CHECK + + Qt provides two APIs for creating plugins: + + \list + \o A higher-level API for writing extensions to Qt itself: custom database + drivers, image formats, text codecs, custom styles, etc. + \o A lower-level API for extending Qt applications. + \endlist + + For example, if you want to write a custom QStyle subclass and + have Qt applications load it dynamically, you would use the + higher-level API. + + Since the higher-level API is built on top of the lower-level API, + some issues are common to both. + + If you want to provide plugins for use with \QD, see the QtDesigner + module documentation. + + Topics: + + \tableofcontents + + \section1 The Higher-Level API: Writing Qt Extensions + + Writing a plugin that extends Qt itself is achieved by + subclassing the appropriate plugin base class, implementing a few + functions, and adding a macro. + + There are several plugin base classes. Derived plugins are stored + by default in sub-directories of the standard plugin directory. Qt + will not find plugins if they are not stored in the right + directory. + + \table + \header \o Base Class \o Directory Name \o Key Case Sensitivity + \row \o QAccessibleBridgePlugin \o \c accessiblebridge \o Case Sensitive + \row \o QAccessiblePlugin \o \c accessible \o Case Sensitive + \row \o QDecorationPlugin \o \c decorations \o Case Insensitive + \row \o QFontEnginePlugin \o \c fontengines \o Case Insensitive + \row \o QIconEnginePlugin \o \c iconengines \o Case Insensitive + \row \o QImageIOPlugin \o \c imageformats \o Case Sensitive + \row \o QInputContextPlugin \o \c inputmethods \o Case Sensitive + \row \o QKbdDriverPlugin \o \c kbddrivers \o Case Insensitive + \row \o QMouseDriverPlugin \o \c mousedrivers \o Case Insensitive + \row \o QPictureFormatPlugin \o \c pictureformats \o Case Sensitive + \row \o QScreenDriverPlugin \o \c gfxdrivers \o Case Insensitive + \row \o QScriptExtensionPlugin \o \c script \o Case Sensitive + \row \o QSqlDriverPlugin \o \c sqldrivers \o Case Sensitive + \row \o QStylePlugin \o \c styles \o Case Insensitive + \row \o QTextCodecPlugin \o \c codecs \o Case Sensitive + \endtable + + But where is the \c{plugins} directory? When the application + is run, Qt will first treat the application's executable directory + as the \c{pluginsbase}. For example if the application is in + \c{C:\Program Files\MyApp} and has a style plugin, Qt will look in + \c{C:\Program Files\MyApp\styles}. (See + QCoreApplication::applicationDirPath() for how to find out where + the application's executable is.) Qt will also look in the + directory specified by + QLibraryInfo::location(QLibraryInfo::PluginsPath), which typically + is located in \c QTDIR/plugins (where \c QTDIR is the directory + where Qt is installed). If you want Qt to look in additional + places you can add as many paths as you need with calls to + QCoreApplication::addLibraryPath(). And if you want to set your + own path or paths you can use QCoreApplication::setLibraryPaths(). + You can also use a \c qt.conf file to override the hard-coded + paths that are compiled into the Qt library. For more information, + see the \l {Using qt.conf} documentation. Yet another possibility + is to set the \c QT_PLUGIN_PATH environment variable before running + the application. If set, Qt will look for plugins in the + paths (separated by the system path separator) specified in the variable. + + Suppose that you have a new style class called \c MyStyle that you + want to make available as a plugin. The required code is + straightforward, here is the class definition (\c + mystyleplugin.h): + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 0 + + Ensure that the class implementation is located in a \c .cpp file + (including the class definition): + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 1 + + (Note that QStylePlugin is case insensitive, and the lower-case + version of the key is used in our + \l{QStylePlugin::create()}{create()} implementation; most other + plugins are case sensitive.) + + For database drivers, image formats, text codecs, and most other + plugin types, no explicit object creation is required. Qt will + find and create them as required. Styles are an exception, since + you might want to set a style explicitly in code. To apply a + style, use code like this: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 2 + + Some plugin classes require additional functions to be + implemented. See the class documentation for details of the + virtual functions that must be reimplemented for each type of + plugin. + + Qt applications automatically know which plugins are available, + because plugins are stored in the standard plugin subdirectories. + Because of this applications don't require any code to find and load + plugins, since Qt handles them automatically. + + The default directory for plugins is \c{QTDIR/plugins} (where \c + QTDIR is the directory where Qt is installed), with each type of + plugin in a subdirectory for that type, e.g. \c styles. If you + want your applications to use plugins and you don't want to use + the standard plugins path, have your installation process + determine the path you want to use for the plugins, and save the + path, e.g. using QSettings, for the application to read when it + runs. The application can then call + QCoreApplication::addLibraryPath() with this path and your + plugins will be available to the application. Note that the final + part of the path (e.g., \c styles) cannot be changed. + + The normal way to include a plugin with an application is either + to \l{Static Plugins}{compile it in with the application} or to + compile it into a dynamic library and use it like any other + library. + + If you want the plugin to be loadable then one approach is to + create a subdirectory under the application and place the plugin + in that directory. If you distribute any of the plugins that come + with Qt (the ones located in the \c plugins directory), you must + copy the sub-directory under \c plugins where the plugin is + located to your applications root folder (i.e., do not include the + \c plugins directory). + + For more information about deployment, + see the \l {Deploying Qt Applications} documentation. + + The \l{Style Plugin Example} shows how to implement a plugin + that extends the QStylePlugin base class. + + \note In Symbian all binaries must be located in the directory \\sys\\bin, + so each Qt plugin has a stub with the same basename as the plugin dll + and suffix ".qtplugin" to make Qt extension plugins work similarly to + other platforms. + When trying to locate the plugin, Qt actually looks for the stub + instead of the plugin binary. While plugin stub files have the + suffix ".qtplugin", they can still be loaded also by specifying a filename + with the normal library suffix ".dll" for QPluginLoader, so normally application + developer doesn't need to care about the different suffix of the stub. + In Symbian the default plugin stubs path is \\resource\\qt\\plugins. + Because of the way applications can be installed + on ROM or various other drives in Symbian, all available drives are + searched for that path when looking for plugins. + + \section1 The Lower-Level API: Extending Qt Applications + + Not only Qt itself but also Qt application can be extended + through plugins. This requires the application to detect and load + plugins using QPluginLoader. In that context, plugins may provide + arbitrary functionality and are not limited to database drivers, + image formats, text codecs, styles, and the other types of plugin + that extend Qt's functionality. + + Making an application extensible through plugins involves the + following steps: + + \list 1 + \o Define a set of interfaces (classes with only pure virtual + functions) used to talk to the plugins. + \o Use the Q_DECLARE_INTERFACE() macro to tell Qt's + \l{meta-object system} about the interface. + \o Use QPluginLoader in the application to load the plugins. + \o Use qobject_cast() to test whether a plugin implements a given + interface. + \endlist + + Writing a plugin involves these steps: + + \list 1 + \o Declare a plugin class that inherits from QObject and from the + interfaces that the plugin wants to provide. + \o Use the Q_INTERFACES() macro to tell Qt's \l{meta-object + system} about the interfaces. + \o Export the plugin using the Q_EXPORT_PLUGIN2() macro. + \o Build the plugin using a suitable \c .pro file. + \endlist + + For example, here's the definition of an interface class: + + \snippet examples/tools/plugandpaint/interfaces.h 2 + + Here's the definition of a plugin class that implements that + interface: + + \snippet examples/tools/plugandpaintplugins/extrafilters/extrafiltersplugin.h 0 + + The \l{tools/plugandpaint}{Plug & Paint} example documentation + explains this process in detail. See also \l{Creating Custom + Widgets for Qt Designer} for information about issues that are + specific to \QD. You can also take a look at the \l{Echo Plugin + Example} is a more trivial example on how to implement a plugin + that extends Qt applications. Please note that a QCoreApplication + must have been initialized before plugins can be loaded. + + \section1 Loading and Verifying Plugins Dynamically + + When loading plugins, the Qt library does some sanity checking to + determine whether or not the plugin can be loaded and used. This + provides the ability to have multiple versions and configurations of + the Qt library installed side by side. + + \list + \o Plugins linked with a Qt library that has a higher version number + will not be loaded by a library with a lower version number. + + \br + \bold{Example:} Qt 4.3.0 will \e{not} load a plugin built with Qt 4.3.1. + + \o Plugins linked with a Qt library that has a lower major version + number will not be loaded by a library with a higher major version + number. + + \br + \bold{Example:} Qt 4.3.1 will \e{not} load a plugin built with Qt 3.3.1. + \br + \bold{Example:} Qt 4.3.1 will load plugins built with Qt 4.3.0 and Qt 4.2.3. + + \o The Qt library and all plugins are built using a \e {build + key}. The build key in the Qt library is examined against the build + key in the plugin, and if they match, the plugin is loaded. If the + build keys do not match, then the Qt library refuses to load the + plugin. + + \br \bold{Rationale:} See the \l{#The Build Key}{The Build Key} section below. + \endlist + + When building plugins to extend an application, it is important to ensure + that the plugin is configured in the same way as the application. This means + that if the application was built in release mode, plugins should be built + in release mode, too. + + If you configure Qt to be built in both debug and release modes, + but only build applications in release mode, you need to ensure that your + plugins are also built in release mode. By default, if a debug build of Qt is + available, plugins will \e only be built in debug mode. To force the + plugins to be built in release mode, add the following line to the plugin's + project file: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 3 + + This will ensure that the plugin is compatible with the version of the library + used in the application. + + \section2 The Build Key + + When loading plugins, Qt checks the build key of each plugin against its + own configuration to ensure that only compatible plugins are loaded; any + plugins that are configured differently are not loaded. + + The build key contains the following information: + \list + \o Architecture, operating system and compiler. + + \e {Rationale:} + In cases where different versions of the same compiler do not + produce binary compatible code, the version of the compiler is + also present in the build key. + + \o Configuration of the Qt library. The configuration is a list + of the missing features that affect the available API in the + library. + + \e {Rationale:} + Two different configurations of the same version of + the Qt library are not binary compatible. The Qt library that + loads the plugin uses the list of (missing) features to + determine if the plugin is binary compatible. + + \e {Note:} There are cases where a plugin can use features that are + available in two different configurations. However, the + developer writing plugins would need to know which features are + in use, both in their plugin and internally by the utility + classes in Qt. The Qt library would require complex feature + and dependency queries and verification when loading plugins. + Requiring this would place an unnecessary burden on the developer, and + increase the overhead of loading a plugin. To reduce both + development time and application runtime costs, a simple string + comparision of the build keys is used. + + \o Optionally, an extra string may be specified on the configure + script command line. + + \e {Rationale:} + When distributing binaries of the Qt library with an + application, this provides a way for developers to write + plugins that can only be loaded by the library with which the + plugins were linked. + \endlist + + For debugging purposes, it is possible to override the run-time build key + checks by configuring Qt with the \c QT_NO_PLUGIN_CHECK preprocessor macro + defined. + + \section1 Static Plugins + + Plugins can be linked statically against your application. If you + build the static version of Qt, this is the only option for + including Qt's predefined plugins. + + When compiled as a static library, Qt provides the following + static plugins: + + \table + \header \o Plugin name \o Type \o Description + \row \o \c qtaccessiblecompatwidgets \o Accessibility \o Accessibility for Qt 3 support widgets + \row \o \c qtaccessiblewidgets \o Accessibility \o Accessibility for Qt widgets + \row \o \c qdecorationdefault \o Decorations (Qt Extended) \o Default style + \row \o \c qdecorationwindows \o Decorations (Qt Extended) \o Windows style + \row \o \c qgif \o Image formats \o GIF + \row \o \c qjpeg \o Image formats \o JPEG + \row \o \c qmng \o Image formats \o MNG + \row \o \c qico \o Image formats \o ICO + \row \o \c qsvg \o Image formats \o SVG + \row \o \c qtiff \o Image formats \o TIFF + \row \o \c qimsw_multi \o Input methods (Qt Extended) \o Input Method Switcher + \row \o \c qwstslibmousehandler \o Mouse drivers (Qt Extended) \o \c tslib mouse + \row \o \c qgfxtransformed \o Graphic drivers (Qt Extended) \o Transformed screen + \row \o \c qgfxvnc \o Graphic drivers (Qt Extended) \o VNC + \row \o \c qscreenvfb \o Graphic drivers (Qt Extended) \o Virtual frame buffer + \row \o \c qsqldb2 \o SQL driver \o IBM DB2 \row \o \c qsqlibase \o SQL driver \o Borland InterBase + \row \o \c qsqlite \o SQL driver \o SQLite version 3 + \row \o \c qsqlite2 \o SQL driver \o SQLite version 2 + \row \o \c qsqlmysql \o SQL driver \o MySQL + \row \o \c qsqloci \o SQL driver \o Oracle (OCI) + \row \o \c qsqlodbc \o SQL driver \o Open Database Connectivity (ODBC) + \row \o \c qsqlpsql \o SQL driver \o PostgreSQL + \row \o \c qsqltds \o SQL driver \o Sybase Adaptive Server (TDS) + \row \o \c qcncodecs \o Text codecs \o Simplified Chinese (People's Republic of China) + \row \o \c qjpcodecs \o Text codecs \o Japanese + \row \o \c qkrcodecs \o Text codecs \o Korean + \row \o \c qtwcodecs \o Text codecs \o Traditional Chinese (Taiwan) + \endtable + + To link statically against those plugins, you need to use the + Q_IMPORT_PLUGIN() macro in your application and you need to add + the required plugins to your build using \c QTPLUGIN. + For example, in your \c main.cpp: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 4 + + In the \c .pro file for your application, you need the following + entry: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 5 + + It is also possible to create your own static plugins, by + following these steps: + + \list 1 + \o Add \c{CONFIG += static} to your plugin's \c .pro file. + \o Use the Q_IMPORT_PLUGIN() macro in your application. + \o Link your application with your plugin library using \c LIBS + in the \c .pro file. + \endlist + + See the \l{tools/plugandpaint}{Plug & Paint} example and the + associated \l{tools/plugandpaintplugins/basictools}{Basic Tools} + plugin for details on how to do this. + + \note If you are not using qmake to build your application you need + to make sure that the \c{QT_STATICPLUGIN} preprocessor macro is + defined. + + \sa QPluginLoader, QLibrary, {Plug & Paint Example} + + \section1 The Plugin Cache + + In order to speed up loading and validation of plugins, some of + the information that is collected when plugins are loaded is cached + through QSettings. This includes information about whether or not + a plugin was successfully loaded, so that subsequent load operations + don't try to load an invalid plugin. However, if the "last modified" + timestamp of a plugin has changed, the plugin's cache entry is + invalidated and the plugin is reloaded regardless of the values in + the cache entry, and the cache entry itself is updated with the new + result. + + This also means that the timestamp must be updated each time the + plugin or any dependent resources (such as a shared library) is + updated, since the dependent resources might influence the result + of loading a plugin. + + Sometimes, when developing plugins, it is necessary to remove entries + from the plugin cache. Since Qt uses QSettings to manage the plugin + cache, the locations of plugins are platform-dependent; see + \l{QSettings#Platform-Specific Notes}{the QSettings documentation} + for more information about each platform. + + For example, on Windows the entries are stored in the registry, and the + paths for each plugin will typically begin with either of these two strings: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 6 + + \section1 Debugging Plugins + + There are a number of issues that may prevent correctly-written plugins from + working with the applications that are designed to use them. Many of these + are related to differences in the way that plugins and applications have been + built, often arising from separate build systems and processes. + + The following table contains descriptions of the common causes of problems + developers experience when creating plugins: + + \table + \header \o Problem \o Cause \o Solution + \row \o Plugins sliently fail to load even when opened directly by the + application. \QD shows the plugin libraries in its + \gui{Help|About Plugins} dialog, but no plugins are listed under each + of them. + \o The application and its plugins are built in different modes. + \o Either share the same build information or build the plugins in both + debug and release modes by appending the \c debug_and_release to + the \l{qmake Variable Reference#CONFIG}{CONFIG} variable in each of + their project files. + \row \o A valid plugin that replaces an invalid (or broken) plugin fails to load. + \o The entry for the plugin in the plugin cache indicates that the original + plugin could not be loaded, causing Qt to ignore the replacement. + \o Either ensure that the plugin's timestamp is updated, or delete the + entry in the \l{#The Plugin Cache}{plugin cache}. + \endtable + + You can also use the \c QT_DEBUG_PLUGINS environment variable to obtain + diagnostic information from Qt about each plugin it tries to load. Set this + variable to a non-zero value in the environment from which your application is + launched. +*/ diff --git a/doc/src/porting-qsa.qdoc b/doc/src/porting-qsa.qdoc new file mode 100644 index 0000000..0560060 --- /dev/null +++ b/doc/src/porting-qsa.qdoc @@ -0,0 +1,475 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Moving from QSA to Qt Script + \page porting-qsa.html + \ingroup porting + + The purpose of this document is to map the differences between Qt + Script for Applications (QSA) and Qt Script, the ECMAScript compatible + engine supplied with Qt 4.3. This document is not supposed to be a + complete function by function porting guide, but will cover the most + obvious aspects. + + First of all it is important to realize that Qt Script is only an + interpreter, it does not provide an editor, completion or script project + management, like QSA does. Qt Script however does provides almost full + compliance with the ECMAScript standard and performs significantly + better than the script engine provided by QSA. + + \tableofcontents + + \section1 The Scripting Language + + The scripting language used in QSA, from here on referred to as QSA, + was derived from ECMAScript 3.0 and 4.0 and is a hybrid of these + standards. Most of the run-time logic, such as classes and scoping + rules, is based on the ECMAScript 4.0 proposal, while the library + implementation is based on the ECMAScript 3.0 standard. + Qt Script on the other hand is solely based on the ECMAScript 3.0 + standard. Though the languages look identical at first glance, + there are a few differences that we'll cover in the sections below. + + + \section2 Classes vs. Objects and Properties + + QSA implements classes and inheritance much in a familiar way to users + of other object oriented languages, like C++ and Java. However, the + ECMAScript 3.0 standard defines that everything is an object, and objects + can have named properties. For instance to create an point object with + the properties x and y one would write the following Qt Script code: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 0 + + The object \c point in this case is constructed as a plain object and + we assign two properties, \c x and \c y, to it with the values 12 and + 35. The \c point object is assigned to the "Global Object" as the + named property \c{point}. The global object can be considered the + global namespace of the script engine. Similarly, global functions are + named properties of the global object; for example: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 1 + + An equivalent construction that illustrates that the function is a + property of the global object is the following assignment: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 2 + + Since functions are objects, they can be assigned to objects as + properties, becoming member functions: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 3 + + In the code above, we see the first subtle difference between + QSA and Qt Script. In QSA one would write the point class like this: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 4 + + where in the \c manhattanLength() function we access \c x and \c y + directly because, when the function is called, the \c this object is + implicitly part of the current scope, as in C++. In Qt Script, + however, this is not the case, and we need to explicitly access + the \c x and \c y values via \c{this}. + + All the code above runs with QSA except the assignment of a function + to \c{point.manhattanLength}, which we repeat here for clarity: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 5 + + This is because, in QSA, the value of \c this is decided based on + the location of the declaration of the function it is used in. In the + code above, the function is assigned to an object, but it is declared + in the global scope, hence there will be no valid \c this value. + In Qt Script, the value of \c this is decided at run-time, + hence you could have assigned the \c manhattanLength() function to any + object that had \c x and \c y values. + + + \section2 Constructors + + In the code above, we use a rather awkward method for constructing + the objects, by first instantiating them, then manually + assigning properties to them. In QSA, the proper way to solve this + is to implement a constructor in the class: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 6 + + The equivalent in Qt Script is to create a constructor function: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 7 + + As we can see, the constructor is just a normal function. What is + special with is how we call it, namely prefixed with the \c new + keyword. This will create a new object and call the \c Car() + function with the newly created object as the \c this pointer. + So, in a sense, it is equivalent to: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 8 + + This is similar to the manhattenLength() example above. Again, the + main difference between QSA and Qt Script is that one has to + explicitly use the keyword \c this to access the members and that + instead of declaring the variable, \c regNumber, we just extend the + \c this object with the property. + + + \section2 Member Functions and Prototypes + + As we saw above, one way of creating member functions of a Qt Script + object is to assign the member function to the object as a property + and use the \c this object inside the functions. So, if we add a + \c toString function to the \c Car class + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 9 + + one could write this in Qt Script as: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 10 + + In QSA, the member functions were part of the class declaration, + and were therefore shared between all instances of a given class. + In Qt Script, each instance has a instance member for each function. + This means that more memory is used when multiple instances are used. + Qt Script uses prototypes to remedy this. + + The basic prototype-based inheritance mechanism works as follows. + Each Qt Script object has an internal link to another object, its + prototype. When a property is looked up in an object, and the object + itself does not have the property, the interpreter searches for the + property in the prototype object instead; if the prototype has the + property then that property is returned. If the prototype object does + not have the property, the interpreter searches for the property in + the prototype of the prototype object, and so on. + + This chain of objects constitutes a prototype chain. The chain of + prototype objects is followed until the property is found or the end + of the chain is reached. + + To make the \c toString() function part of the prototype, we write + code like this: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 11 + + Here, we made the \c toString() function part of the prototype so + that, when we call \c{car.toString()} it will be resolved via the + internal prototype object of the car object. Note, however, that the + \c this object is still the original object that the function was + called on, namely \c{car}. + + + \section2 Inheritance + + Now that we've seen how to use prototypes to create a "class" members + in Qt Script, let's see how we can use prototypes to create + polymorphism. In QSA you would write + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 12 + + With Qt Script, we acheive the same effect by creating a prototype + chain. The default prototype of an object is a plain \c Object + without any special members, but it is possible to replace this + object with another prototype object. + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 13 + + In the code above, we have a constructor, \c{GasolineCar}, which + calls the "base class" implementation of the constructor to + initialize the \c this object with the property \c{regNumber}, + based on the values passed in the constructor. The interesting line + in this case is the line after the constructor where we change the + default prototype for \c GasolineCar to be an instance of type + \c{Car}. This means that all members available in a \c Car object + are now available in all \c GasolineCar objects. In the last line, + we replace the \c toString() function in the prototype with our own, + thus overriding the \c toString() for all instances of + \c{GasolineCar}. + + + \section2 Static Members + + QSA allowed users to declare static members in classes, and these + could be accessed both through instances of the class and through + the class itself. For example, the following variable is accessed + through the \c Car class: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 14 + + The equivalent in Qt Script is to assign variables that should appear + as static members as properties of the constructor function. For + example: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 15 + + Note that in QSA, static member variables were also accessible in + instances of the given class. In Qt Script, with the approach + illustrated above, the variable is a member of the constructor + object only, and thus only accessible through \c{Car.globalCount}. + + + \section1 The Built-in Functions and Library + + The built-in functions in QSA are based on those defined in the + ECMAScript 3.0 standard, the same standard used for Qt Script, but + QSA adds some extensions to this, specifically for the \c String + and \c RegExp types. QSA also lacked some functions from the + standard, most notably the \c Date type. Below we list all the + differences. All changes made to Qt Script are to increase + compliance with ECMAScript 3.0. + + \table + \header \o QSA Function \o Notes about Equivalent Qt Script Functions + \row \o eval() + \o The eval function in QSA opened a new scope for code being + executed in the eval function, so locally declared variables were not + accessible outside. In Qt Script, the eval() function shares the + current scope, making locally declared variables accessible outside + the eval() call. + + \row \o debug() + \o This function is not available in Qt Script. Use print() instead. + + \row \o connect() + \o QSA had closures, meaning that a member function + reference implicitly contained its \c this object. Qt Script does not + support this. See the Qt Script documentation for details on using the + connect function. + + \row \o String.arg() + \o This function is not available in Qt Script. Use replace() or concat() instead. + + \row \o String.argDec() + \o This function is not available in Qt Script. Use replace() or concat() instead. + + \row \o String.argInt() + \o This function is not available in Qt Script. Use replace() or concat() instead. + + \row \o String.argStr() + \o This function is not available in Qt Script. Use replace() or concat() instead. + + \row \o String.endsWith() + \o This function is not available in Qt Script. Use lastIndexOf() instead. + + \row \o String.find() + \o This function is not available in Qt Script. Use indexOf() instead. + + \row \o String.findRev() + \o This function is not available in Qt Script. Use lastIndexOf() and length instead. + + \row \o String.isEmpty() + \o This function is not available in Qt Script. Use length == 0 instead. + + \row \o String.left() + \o This function is not available in Qt Script. Use substring() instead. + + \row \o String.lower() + \o This function is not available in Qt Script. Use toLowerCase() instead. + + \row \o String.mid() + \o This function is not available in Qt Script. Use substring() instead. + + \row \o String.right() + \o This function is not available in Qt Script. Use substring() instead. + + \row \o String.searchRev() + \o This function is not available in Qt Script. Use search() / match() instead. + + \row \o String.startsWith() + \o This function is not available in Qt Script. Use indexOf() == 0 instead. + + \row \o String.upper() + \o This function is not available in Qt Script. Use toUpperCase() instead. + + \row \o RegExp.valid + \o This property is not available in Qt Script because it is not + required; a \c SyntaxError exception is thrown for bad \c RegExp objects. + + \row \o RegExp.empty + \o This property is not available in Qt Script. Use \c{toString().length == 0} instead. + + \row \o RegExp.matchedLength + \o This property is not available in Qt Script. RegExp.exec() returns an + array whose size is the matched length. + + \row \o RegExp.capturedTexts + \o This property is not available in Qt Script. RegExp.exec() returns an + array of captured texts. + + \row \o RegExp.search() + \o This function is not available in Qt Script. Use RegExp.exec() instead. + + \row \o RegExp.searchRev() + \o This function is not available in Qt Script. Use RegExp.exec() or + String.search()/match() instead. + + \row \o RegExp.exactMatch() + \o This function is not available in Qt Script. Use RegExp.exec() instead. + + \row \o RegExp.pos() + \o This function is not available in Qt Script. Use String.match() instead. + + \row \o RegExp.cap() + \o This function is not available in Qt Script. RegExp.exec() returns an + array of captured texts. + \endtable + + QSA also defined some internal Qt API which is not present in Qt + Script. The types provided by QSA which are not provided by Qt Script are: + + \list + \o Rect + \o Point + \o Size + \o Color + \o Palette + \o ColorGroup + \o Font + \o Pixmap + \o ByteArray + \endlist + + + \section1 The C++ API of QSA vs Qt Script + + QSA is more than just a scripting engine. It provides project + management, an editor with completion and a minimalistic IDE to edit + scriptable projects. Qt Script on the other hand is just a scripting + engine. This means that equivalents to the classes \c QSEditor, + \c QSScript, \c QSProject and \c QSWorkbench do not exist in Qt Script. + QSA also provides some extension APIs through the \c QSUtilFactory and + \c QSInputDialogFactory. There is also no equivalent to these classes + in the Qt Script API. + + + \section2 Making QObjects Accessible from Scripts + + There are two different ways of making \l{QObject}s accessible from + scripts in QSA. The first method is via the + \c QSInterpreter::addTransientObject() and \c QSProject::addObject() + functions. In this case objects are added to the global namespace of + the interpreter using their object names as the names of the + variables. + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 16 + + The code above adds the button to the global namespace under the name + "button". One obvious limitation here is that there is potential for + either unnamed \l{QObject}s or objects whose names conflict. Qt Script + provides a more flexible way of adding QObjects to the scripting + environment. + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 17 + + In the code above we create a QPushButton and wrap it in a script + value using the function, QScriptEngine::newQObject(). This gives us + a script value that we put into the global object using the name + "button". The concept of objects and properties discussed above is + quite visible here in the public C++ API as well. We have no + dependency on the object's name and we can also resolve name conflicts + more gracefully. Here, we operate directly on QScriptValue objects. + This is the actual object that is being passed around inside + the script engine, so we actually have low-level access to the + internal script data structures, far beyond that which is possible + in QSA. Properties, signals and slots of the QObject are accessible + to the scripter in Qt Script, just like in QSA. + + The other way to expose \l{QObject}s in QSA was to create a + \c QSObjectFactory that made it possible to instantiate QObjects from + scripts. + + Below is listed some code from the filter example in the QSA + package. + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 18 + + The equivalent in Qt Script is written in much the same way as + constructors are written in scripts. We register a callback C++ + function under the name "ImageSource" in the global namespace and + return the QObject from this function: + + \snippet doc/src/snippets/code/doc_src_porting-qsa.qdoc 19 + + In the Qt Script case we use the same approach that we use to expose + a QObject, namely via QScriptEngine::newQObject(). This function also + has the benefit that it is possible to specify if the QObject should + expose properties and slots of its base class. It is also possible to + specify custom ownership rules. + + The reader might question why we don't add the constructor function + directly into the namespace, but create a meta-object script value for + it in addition. The plain function would certainly be good enough, + but by creating a QMetaObject based constructor we get the enums on + QPushButton for free in the QPushButton function object. Exposing + enums in QSA is rather painful in comparison. + + If we want to add more "static" data to the QPushButton type in Qt + Script, we're free to add properties, similar to how we did for + the script. It is also possible to add custom functions to a Qt Script + QPushButton instance by setting more properties on it, such as making + the \l{QPushButton::}{setText()} C++ function available. It is also + possible to acheive this by installing a custom prototype, and be + memory efficient, as discussed in the script example above. + + + \section2 Accessing Non-QObjects + + In QSA, it was possible to expose non-QObjects to QSA by wrapping them + in a QObject and using either \c QSWrapperFactory or \c QSObjectFactory + to expose them. Deciding when to use each of these classes could be + confusing, as one was used for script based construction and the other + for wrapping function parameters and return values, but in essence they + did exactly the same thing. + + In Qt Script, providing access to QObjects and non-QObjects is done in + the same way as shown above, by creating a constructor function, and + by adding properties or a custom prototype to the constructed object. + + + \section2 Data Mapping + + QSA supported a hardcoded set of type mappings which covered most + of the QVariant types, QObjects and primitives. For more complex type + signatures, such as the template-based tool classes, it had rather + limited support. Qt Script is significantly better at type mapping + and will convert lists of template types into arrays of the + appropriate types, given that all the types are declared to the + meta-type system. +*/ diff --git a/doc/src/porting4-canvas.qdoc b/doc/src/porting4-canvas.qdoc new file mode 100644 index 0000000..dcd1a1e --- /dev/null +++ b/doc/src/porting4-canvas.qdoc @@ -0,0 +1,703 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page graphicsview-porting.html + \title Porting to Graphics View + \contentspage {Porting Guides}{Contents} + \previouspage Porting .ui Files to Qt 4 + \nextpage qt3to4 - The Qt 3 to 4 Porting Tool + \ingroup porting + \ingroup multimedia + \brief Hints and tips to assist with porting canvas applications to the + Graphics View framework. + + \keyword QGraphicsView GraphicsView Porting Graphics Canvas + \since 4.2 + + Graphics View provides a surface for managing and interacting with a large + number of custom-made 2D graphical items, and a view widget for + visualizing the items, with support for zooming and rotation. Graphics + View was introduced in Qt 4.2, replacing its predecessor, QCanvas. For + more on Graphics View, see \l{The Graphics View Framework}. + + This document walks through the steps needed, class by class and function + by function, to port a QCanvas application to Graphics View. + + \tableofcontents + + Qt 4.2 provides two complete examples of Q3Canvas applications ported to + Graphics View: + + \list + \o \l{Ported Canvas Example}, the canvas example from Qt 3. + \o \l{Ported Asteroids Example}, the Asteroids game from the Qt 3 demo. + \endlist + + \section1 Introduction + + Conceptually, the Graphics View classes from Qt 4 and the Canvas + classes from Qt 3 provide similar functionality using a similar + design. Instead of "canvas", we use the term "scene". Otherwise, the + class names and functions are almost the same as in Qt 3. The easiest + classes to port will be QCanvas and QCanvasView. Experience shows that + most time is spent porting the item classes, depending on the + complexity of the QCanvasItem classes you have been using before. + + This porting guide will assume you have already ported your + application to Qt 4, by making use of Q3Canvas. If you have not done + so already, as a first step, run the \l qt3to4 tool on your + project. This tool will automate the most tedious part of the porting + effort. + + Some additional steps are usually required before your application + will compile and run. You can read more about the porting process in + \l{Porting to Qt 4}. + + \section1 Porting from Q3Canvas + + QGraphicsScene is the closest equivalent to Q3Canvas. There + are some noticable differences in this new API: Whereas the + Q3Canvas classes use integer precision, QGraphicsScene is + entirely based on double coordinates, with graphical + primitives such as QPointF instead of QPoint, QRectF instead + of QRect, and QPolygonF and QPainterPath. The canvas area is + defined by a scene rectangle, allowing negative coordinates, + as opposed to Q3Canvas, which only defines a size (QSize), and + whose top-left corner is always (0, 0). + + In addition, there is no explicit support for canvas tiles + anymore; see \l{Porting scenes with tiles} for more + information. The chunks-based indexing system has been + replaced with an implicitly maintained internal BSP tree. + + \section2 Porting table + + \table + \header \o Q3Canvas \o QGraphicsScene + + \row \o Q3Canvas::Q3Canvas() \o There is no QPixmap based + constructor, and the concept of tiles is gone. You can use + QGraphicsScene::backgroundBrush to set a brush pattern for + the background, or reimplement + QGraphicsScene::drawBackground() in a QGraphicsScene + subclass (see \l{Porting scenes with tiles}). In addition, + the QGraphicsScene geometry is provided as a full + QRectF. Instead of Q3Canvas(int width, int height), you can + use QGraphicsScene(int top, int left, int width, int + height). + + \row \o Q3Canvas::allItems() \o QGraphicsScene::items() + returns a list of all items on the scene. + + \row \o Q3Canvas::backgroundColor() \o You can assign a color for the + background through the QGraphicsScene::backgroundBrush + or QGraphicsView::backgroundBrush properties. + + \row \o Q3Canvas::backgroundPixmap() \o You can set a tiled + pixmap for the background through + QGraphicsScene::backgroundBrush or + QGraphicsView::backgroundBrush. For more control on the pixmap + positioning, you can reimplement + QGraphicsScene::drawBackground() or + QGraphicsView::drawBackground(). + + \row \o Q3Canvas::chunkSize() \o The closest equivalent to the + chunks size in Q3Canvas is the depth of QGraphicsScene's BSP + tree. QGraphicsScene assigns a depth automatically, and the + size of each scene segment depends on this depth, and + QGraphicsScene::sceneRect(). See + QGraphicsScene::itemIndexMethod. + + \row \o Q3Canvas::collisions() \o QGraphicsScene provides + several means to detect item collisions. The + QGraphicsScene::items() overloads return items that collide + with a point, a rectangle, a polygon, or an arbitrary vector + path (QPainterPath). You can also call + QGraphicsScene::collidingItems() to determine collision with + an item. + + \row \o Q3Canvas::drawArea() \o The QGraphicsScene::render() + function provides the original behavior + Q3Canvas::drawArea(). In addition, you can pass a source + rectangle for rendering only parts of the scene, and a + destination rectangle for rendering onto designated area of + the destination device. QGraphicsScene::render() can + optionally transform the source rectangle to fit into the + destination rectangle. See \l{Printing} + + \row \o Q3Canvas::onCanvas() \o The is no equivalent to this + function in Graphics View. However, you can combine + QGraphicsScene::sceneRect() and QRectF::intersects(): + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 0 + + \row \o Q3Canvas::rect() \o The equivalent, + QGraphicsScene::sceneRect(), returns a QRectF (double + precision coordinates). Its top-left corner can be an + arbitrary coordinate (Q3Canvas::rect().topLeft() is always (0, + 0)). + + \row \o Q3Canvas::resize() \o You can call + QGraphicsScene::setSceneRect(0, 0, width, height) instead. + + \row \o Q3Canvas::retune() \o See + QGraphicsScene::itemIndexMethod. You can tune the indexing by + setting a suitable sceneRect(). The optimal depth of + QGraphicsScene's BSP tree is determined automatically. + + \row \o Q3Canvas::setAdvancePeriod() \o There is no concept of + an advance period in the new API; instead, you can connect + QTimer::timeout() to the QGraphicsScene::advance() slot to + obtain similar functionality. This will cause all items' + QGraphicsItem::advance() function to be called. See also + QGraphicsItemAnimation. + + \row \o Q3Canvas::setAllChanged() \o You can call + QGraphicsScene::update() with no arguments. + + \row \o Q3Canvas::setChanged() \o QGraphicsScene::update() + will trigger a repaint of the whole scene, or parts of the + scene. + + \row \o Q3Canvas::setDoubleBuffering() \o Q3Canvas' double + buffering enabled cacheing of the scene contents in device + (i.e., viewport) coordinates. This cache layer has been moved + to the view instead; you can cache QGraphicsScene's background + through + QGraphicsView::setCacheMode(). QGraphicsView::resetCachedContent() + will reset the areas of the cache that has changed. + + \row \o Q3Canvas::tile() \o See \l{Porting scenes with tiles}. + + \row \o Q3Canvas::setTiles() \o See \l{Porting scenes with tiles}. + + \row \o Q3Canvas::setUnchanged() \o There is no equivalent in + Graphics View. This call can usually be removed with no side + effects. + + \row \o Q3Canvas::setUpdatePeriod() \o There is no concept of an + update period in the new API; instead, you can connect + QTimer::timeout() to the QGraphicsScene::update() slot to obtain + similar functionality. See also QGraphicsItemAnimation. + + \row \o Q3Canvas::size() \o + \tt{QGraphicsScene::sceneRect().size()} returns a QSizeF, with + double precision coordinates. + + \row \o Q3Canvas::validChunk() \o To determine if an area is + inside the scene area or not, you can combine + QRectF::intersects() with QGraphicsScene::sceneRect(). + + \row \o Q3Canvas::resized() \o QGraphicsScene emits + \l{QGraphicsScene::sceneRectChanged()}{sceneRectChanged()} + whenever the scene rect changes. + + \row \o Q3Canvas::drawBackground() \o You can reimplement + QGraphicsScene::drawBackground() to render the scene + background. You can also reimplement + QGraphicsView::drawBackground() to override this background if + you need different backgrounds for different views. + + \row \o Q3Canvas::drawForeground() \o You can reimplement + QGraphicsScene::drawForeground() to render the scene + foreground. You can also reimplement + QGraphicsView::drawForeground() to override this foreground if + you need different foregrounds for different views. + + \endtable + + \section2 Porting scenes with tiles + + QGraphicsScene does not provide an API for tiles. However, you + can achieve similar behavior by drawing pixmaps in a reimplementation of + QGraphicsScene::drawBackground(). + + Q3Canvas' tile support is based on providing one pixmap + containing tiles of a fixed width and height, and then + accessing them (reading and replacing tiles) by index. The + tiles in the pixmap are arranged from the left to right, top + to bottom. + + \table + \row \i 0 \i 1 \i 2 \i 3 + \row \i 4 \i 5 \i 6 \i 7 + \endtable + + With Graphics View, this pixmap can be stored as a member of a + subclass of QGraphicsScene. The three main functions that make + out the public tile API can then be declared as new members of + this class. Here is one example of how to implement tile support: + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 1 + + Depending on how your scene uses tiles, you may be able to + simplify this approach. In this example, we will try to mimic the behavior + of the Q3Canvas functions. + + We start by creating a subclass of QGraphicsScene ("TileScene"). + In this class, we declare two of the tile + functions from Q3Canvas, and we then add two helper function that returns the + rectangle for a certain tile in our tile pixmap. We will use a + two-dimensional vector of ints to keep track of what tiles should + be used at what parts of the scene. + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 2 + + In setTiles(), we store the pixmap and tile properties as + members of the class. Then we resize the tiles vector + to match the width and height of our tile grid. + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 3 + + The setTile() function updates the tiles index, and then + updates the corresponding rect in the scene by calling + tileRect(). + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 4 + + The first tileRect() function returns a QRect for the tile at + position (x, y). + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 5 + + The second tileRect() function returns a QRect for a tile number. + With these functions in place, we can implement the drawBackground() + function. + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 6 + + In drawBackground(), we redraw all tiles that have been + exposed by intersecting each tile rect with the exposed background + area. + + \section1 Porting from Q3CanvasView + + The closest equivalent to Q3CanvasView in Graphics View is + called QGraphicsView. In most cases, this is the easiest + class to port. In addition to providing all of Q3CanvasView's + functionality, QGraphicsView includes some useful new features. You + can read more about this in QGraphicsView's documentation. + + \section2 Porting table + + \table + \header \o Q3CanvasView \o QGraphicsView + + \row \o Q3CanvasView::Q3CanvasView() \o QGraphicsView provides + the same constructors as Q3CanvasView, but without the name + and flags arguments. You can set the name by calling + \l{QWidget::setObjectName()}{setObjectName()}, and the flags by + calling \l{QWidget::setWindowFlags()}{setWindowFlags()}. + + \row \o Q3CanvasView::canvas() \o QGraphicsView::scene() + returns the scene that is currently associated with the + view. QGraphicsScene also provides the opposite function, + QGraphicsScene::views(), which returns a list of views + observing the scene. + + \row \o Q3CanvasView::inverseWorldMatrix() \o You can call + QGraphicsView::matrix() and QMatrix::inverted(). + QGraphicsView::mapToScene() and QGraphicsView::mapFromScene() + allow transforming of viewport shapes to scene shapes, and + vice versa. + + \row \o Q3CanvasView::setCanvas() \o QGraphicsView::setScene(). + + \row \o Q3CanvasView::setWorldMatrix() \o + QGraphicsView::setMatrix(), QGraphicsView::rotate(), + QGraphicsView::scale(), QGraphicsView::shear() and + QGraphicsView::translate(). + + \row \o Q3CanvasView::worldMatrix() \o QGraphicsView::matrix() + + \row \o Q3CanvasView::drawContents() \o The + QGraphicsView::drawBackground() function draws the background, + QGraphicsView::drawItems() draws the items, and + QGraphicsView::drawForeground() draws the foreground of the + scene in scene coordinates. You can also reimplement these + functions in QGraphicsScene. + + \endtable + + \section2 Other differences + + QGraphicsView can cache the visible contents of the scene, + similar to how Q3Canvas::setDoubleBuffering() could cache the + entire scene contents. You can call + QGraphicsView::setCacheMode() to configure cacheing, and + QGraphicsView::resetCachedContent() invalidates the cache. + + For improved navigation support, you can set a resize or + transformation anchor through QGraphicsView::resizeAnchor and + QGraphicsView::transformationAnchor. This allows you to easily + rotate and zoom the view while keeping the center fixed, or + zooming towards the position under the mouse cursor. In + addition, if you set the QGraphicsView::dragMode of the view, + QGraphicsView will provide rubber band selection or + click-and-pull navigation using the + \l{Qt::OpenHandCursor}{OpenHandCursor} and + \l{Qt::ClosedHandCursor}{ClosedHandCursor} cursors. + + \section1 Porting from Q3CanvasItem + + The closest equivalent to Q3CanvasItem in Graphics View is + called QGraphicsItem. Deriving from this class is very common, + and because of that, porting from Q3CanvasItem often involves + more work than Q3Canvas and Q3CanvasView. + + Q3CanvasItem has become easier to use, easier to subclass, and more + powerful with QGraphicsItem. The key difference from Q3CanvasItem lies + in event propagation and item groups, but you will also find several + convenient new features, such as support for tooltips, cursors, item + transformation and drag and drop. You can read all about QGraphicsItem + in its own class documentation. + + This section starts with a table that shows how to port each function + from Q3CanvasItem to QGraphicsItem. Immediately after that, each of + Q3CanvasItem's standard subclasses have a section of their own. + + \table + \header \o Q3CanvasItem \o QGraphicsItem + + \row \o Q3CanvasItem::advance() \o QGraphicsItem::advance() is + provided for compatibility. QGraphicsScene::advance() calls + QGraphicsItem::advance() for all items. See also QTimeLine and + QGraphicsItemAnimation. + + \row \o Q3CanvasItem::animated() \o No equivalent; all items + are advanced by QGraphicsScene::advance(). + + \row \o Q3CanvasItem::boundingRectAdvanced() \o No + equivalent. You can translate QGraphicsItem::boundingRect() + instead (see QRectF::translate()). + + \row \o Q3CanvasItem::canvas() \o QGraphicsItem::scene() + + \row \o Q3CanvasItem::collidesWith() \o + QGraphicsItem::collidesWithItem() and + QGraphicsItem::collidesWithPath(). + + \row \o Q3CanvasItem::collisions() \o + QGraphicsItem::collidingItems() returns a list of all items + that collide with an item. You can specify whether you want + fast, rough estimate collision between bounding rectangles, or + the slower, more accurate shapes. + + \row \o Q3CanvasItem::draw() \o QGraphicsItem::paint(). See + also QStyleOptionGraphicsItem, QGraphicsScene::drawItems() and + QGraphicsView::drawItems(). + + \row \o Q3CanvasItem::hide() \o QGraphicsItem::hide() or + QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by + default; \l{Q3CanvasItem}s, however, are not. + + \row \o Q3CanvasItem::isActive() \o No equivalent. To achieve + similar behavior, you can add this property in a custom + subclass of QGraphicsItem. + + \row \o Q3CanvasItem::isVisible() \o + QGraphicsItem::isVisible(). \l{QGraphicsItem}s are \e visible by + default; \l{Q3CanvasItem}s, however, are not. + + \row \o Q3CanvasItem::move() \o You can call + QGraphicsItem::setPos() to change the position of the item. + + \row \o Q3CanvasItem::rtti() \o QGraphicsItem::type() and qgraphicsitem_cast(). + + \row \o Q3CanvasItem::setActive() \o No equivalent. + + \row \o Q3CanvasItem::setAnimated() \o No equivalent; all + items are by default "animated" (i.e., + QGraphicsScene::advance() advances all items on the scene). + + \row \o Q3CanvasItem::setCanvas() \o You can call + QGraphicsScene::addItem(), or pass a pointer to the canvas to + QGraphicsItem's constructor. + + \row \o Q3CanvasItem::setVelocity() \o No equivalent. You can + add x and y velocity as member data of your class, and call + QGraphicsItem::moveBy(x, y) from inside + QGraphicsItem::advance(). See also QTimeLine and + QGraphicsItemAnimation. + + \row \o Q3CanvasItem::setVisible() \o + QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by + default; \l{Q3CanvasItem}s, however, are not. + + \row \o Q3CanvasItem::setX() \o QGraphicsItem::setPos() + \row \o Q3CanvasItem::setY() \o QGraphicsItem::setPos() + + \row \o Q3CanvasItem::setXVelocity() \o No equivalent. + \row \o Q3CanvasItem::setYVelocity() \o No equivalent. + + \row \o Q3CanvasItem::setZ() \o QGraphicsItem::setZValue() + + \row \o Q3CanvasItem::show() \o QGraphicsItem::show() or + QGraphicsItem::setVisible(). \l{QGraphicsItem}s are \e visible by + default; \l{Q3CanvasItem}s, however, are not. + + \row \o Q3CanvasItem::xVelocity() \o No equivalent. + \row \o Q3CanvasItem::yVelocity() \o No equivalent. + + \endtable + + Note that some virtual functions that have passed on to + QGraphicsItem have lost their virtuality. An example is + Q3CanvasItem::moveBy(), which was often used to track movement of + items. In this case, the virtual QGraphicsItem::itemChange() has + taken over as a substitute. + + \section2 Q3CanvasPolygonalItem + + The closest equivalent to Q3CanvasPolygonalItem in + Graphics View is called QAbstractGraphicsShapeItem. Unlike + Q3CanvasPolygonalItem, it does not define area points + (Q3CanvasPolygonalItem::areaPoints()); instead, each + item's geometry is stored as a member of the subclasses. + + The Q3CanvasPolygonalItem::drawShape() function is no longer + available; instead, you can set the brush and pen from inside + QGraphicsItem::paint(). + + \table + \header \o Q3CanvasPolygonalItem \o QAbstractGraphicsShapeItem + + \row \o Q3CanvasPolygonalItem::areaPoints() \o No equivalent; each + item's geometry is stored in the respective subclass. + + \row \o Q3CanvasPolygonalItem::areaPointsAdvanced() \o No + equivalent; you can use QPolygonF::translate() or + QPainterPath::translate() instead. + + \row \o Q3CanvasPolygonalItem::drawShape() \o + QGraphicsItem::paint(). You can set the pen and brush from inside + this function. + + \row \o Q3CanvasPolygonalItem::invalidate() \o Call + QGraphicsItem::prepareGeometryChange() before changing the + item's geometry. + + \row \o Q3CanvasPolygonalItem::isValid() \o No equivalent; + items' geometry is always in a valid state. + + \row \o Q3CanvasPolygonalItem::winding() \o This function is only + useful for polygon items and path items; see + QGraphicsPolygonItem::fillRule(), and QPainterPath::fillRule() for + QGraphicsPathItem. + + \endtable + + \section2 Q3CanvasEllipse + + The closest equivalent to Q3CanvasEllipse in Graphics View + is called QGraphicsEllipseItem. The most noticable + difference to QGraphicsEllipseItem is that the ellipse is + not longer drawn centered around its position; rather, it + is drawn using a bounding QRectF, just like + QPainter::drawEllipse(). + + For compatibility, you may want to shift the ellipse up and to the + left to keep the ellipse centered. Example: + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 7 + + Note: QGraphicsEllipseItem uses QAbstractGraphicsShapeItem::pen() + for outlines, whereas Q3CanvasEllipse did not use + Q3CanvasPolygonalItem::pen(). + + \table + \header \o Q3CanvasEllipse \o QGraphicsEllipseItem + + \row \o Q3CanvasEllipse::angleLength() \o QGraphicsEllipseItem::spanAngle() + + \row \o Q3CanvasEllipse::angleStart() \o QGraphicsEllipseItem::startAngle() + + \row \o Q3CanvasEllipse::setAngles() \o + QGraphicsEllipseItem::setStartAngle() and + QGraphicsEllipseItem::setSpanAngle() + + \row \o Q3CanvasEllipse::setSize() \o QGraphicsEllipseItem::setRect() + + \endtable + + \section2 Q3CanvasLine + + The closest equivalent to Q3CanvasLine in Graphics View is + called QGraphicsLineItem. + + \table + \header \o Q3CanvasLine \o QGraphicsLineItem + + \row \o Q3CanvasLine::endPoint() \o QGraphicsLineItem::line() and QLineF::p2() + + \row \o Q3CanvasLine::setPoints() \o QGraphicsLineItem::setLine() + + \row \o Q3CanvasLine::startPoint() \o QGraphicsLineItem::line() + and QLineF::p1() + + \endtable + + \section2 Q3CanvasPolygon + + The closest equivalent to Q3CanvasPolygon in Graphics View + is called QGraphicsPolygonItem. + + \table + \header \o Q3CanvasPolygon \o QGraphicsPolygonItem + + \row \o Q3CanvasPolygon::areaPoints() \o + QGraphicsPolygonItem::polygon() and QGraphicsItem::mapToParent() + + \row \o Q3CanvasPolygon::points() \o QGraphicsPolygonItem::polygon() + + \row \o Q3CanvasPolygon::setPoints() \o QGraphicsPolygonItem::setPolygon() + + \endtable + + \section2 Q3CanvasSpline + + The closest equivalent to Q3CanvasSpline in Graphics View + is called QGraphicsPathItem. This item can be used to + describe any type of path supported by QPainter. + + Q3CanvasSpline takes its control points as a Q3PointArray, but + QPainterPath operates on a sequence of calls to + QPainterPath::moveTo() and QPainterPath::cubicTo(). Here is how + you can convert a bezier curve Q3PointArray to a QPainterPath: + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 8 + + Note: QGraphicsPathItem uses QAbstractGraphicsShapeItem::pen() for + outlines, whereas Q3CanvasSpline did not use + Q3CanvasPolygonalItem::pen(). + + \table + \header \o Q3CanvasSpline \o QGraphicsPathItem + + \row \o Q3CanvasSpline::closed() \o No equivalent. You can call + QPainterPath::closeSubPath() to close a subpath explicitly. + + \endtable + + \section2 Q3CanvasRectangle + + The closest equivalent to Q3CanvasRectangle in Graphics + View is called QGraphicsRectItem. + + \table + \header \o Q3CanvasRectangle \o QGraphicsRectItem + + \row \o Q3CanvasRectangle::height() \o QGraphicsRectItem::rect() + and QRectF::height() + + \row \o Q3CanvasRectangle::setSize() \o QGraphicsRectItem::setRect() + + \row \o Q3CanvasRectangle::size() \o QGraphicsRectItem::rect() and QRectF::size() + + \row \o Q3CanvasRectangle::width() \o QGraphicsRectItem::rect() and QRectF::width() + + \row \o Q3CanvasRectangle::chunks() \o No equivalent. + + \endtable + + \section2 Q3CanvasSprite + + Q3CanvasSprite is the item class that differs the most from its + Q3Canvas predecessor. The closest resemblance of Q3CanvasSprite in + Graphics View is QGraphicsPixmapItem. + + Q3CanvasSprite supports animated pixmaps; QGraphicsPixmapItem, + however, is a simple single-frame pixmap item. If all you need is + a pixmap item, porting is straight-forward. If you do need the + animation support, extra work is required; there is no direct + porting approach. + + For the \l{Ported Asteroids Example}, a subclass of + QGraphicsPixmapItem is used to replace Q3CanvasSprite, storing a + list of pixmaps and a frame counter. The animation is advanced in + QGraphicsItem::advance(). + + \section3 Q3CanvasPixmap, Q3CanvasPixmapArray + + These classes have been removed from the API. You can use + QPixmap instead of Q3CanvasPixmap, and QList instead of + Q3CanvasPixmapArray. + + Q3CanvasPixmapArray included convenience for loading a + sequence of pixmaps or masks using a path with a wildcard (see + Q3CanvasPixmapArray::readPixmaps() and + Q3CanvasPixmapArray::readCollisionMasks()). To achieve similar + functionality using Graphics View, you can load the images by + using QDir: + + \snippet doc/src/snippets/code/doc_src_porting4-canvas.qdoc 9 + + \section2 Q3CanvasText + + Q3CanvasText has been split into two classes in Graphics View: + QGraphicsSimpleTextItem and QGraphicsTextItem. For porting, + QGraphicsSimpleTextItem should be adequate. QGraphicsTextItem + provides advanced document structuring features similar to that of + QTextEdit, and it also allows interaction (e.g., editing and + selection). + + \table + \header \o Q3CanvasText \o QGraphicsSimpleTextItem + + \row \o Q3CanvasText::color() \o QGraphicsSimpleTextItem::pen(). + + \row \o Q3CanvasText::setColor() \o QGraphicsSimpleTextItem::setPen(). + + \row \o Q3CanvasText::textFlags() \o Use QGraphicsTextItem instead. + + \endtable + + + \section2 Q3CanvasItemList + + Use QList instead. + + \section1 Other Resources + + The \l{Porting to Qt 4.2's Graphics View} article in Qt Quarterly 21 covered the + process of porting the Qt 3 canvas example to Qt 4. + The result of this is the \l{Ported Canvas Example}{Ported Canvas} example. +*/ diff --git a/doc/src/porting4-designer.qdoc b/doc/src/porting4-designer.qdoc new file mode 100644 index 0000000..9ae3c52 --- /dev/null +++ b/doc/src/porting4-designer.qdoc @@ -0,0 +1,349 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page porting4-designer.html + \title Porting .ui Files to Qt 4 + \contentspage {Porting Guides}{Contents} + \previouspage Porting to Qt 4 - Drag and Drop + \nextpage Porting to Graphics View + \ingroup porting + \brief Information about changes to the .ui file format in Qt 4. + + Qt Designer has changed significantly in the Qt 4 release. We + have moved away from viewing Qt Designer as an IDE and + concentrated on creating a robust form builder which can be + extended and embedded in existing IDEs. Our efforts are ongoing + and include the \l{Visual Studio Integration}, + as well as integrating Designer with KDevelop and possibly other + IDEs. + + The most important changes in Qt Designer 4 which affect porting + for \c .ui files are summarized below: + + \list + \o \bold{Removed project manager.} + Qt Designer now only reads and edits \c .ui + files. It has no notion of a project (\c .pro file). + + \o \bold{Removed code editor.} + Qt Designer can no longer be used to edit source files. + + \o \bold{Changed format of \c .ui files.} + Qt Designer 4 cannot read files created by Qt Designer 3 and + vice versa. However, we provide the tool \c uic3 to generate Qt + 4 code out of Qt 3 \c .ui files, and to convert old \c .ui files + into a format readable by Qt Designer 4. + + \o \bold{Changed structure of the code generated by \c uic.} + The \c myform.ui file containing the form \c MyForm is now + converted into a single header file \c ui_myform.h, which + contains the declaration and inline definition of a POD class + \c Ui::MyForm. + + \o \bold{New resource file system.} Icon data is no longer + stored in the \c .ui file. Instead, icons are put into resource + files (\c .qrc). + \endlist + + The rest of this document explains how to deal with the main + differences between Qt Designer 3 and Qt Designer 4: + + \tableofcontents + + See \l{Porting to Qt 4} and \l{qt3to4 - The Qt 3 to 4 Porting + Tool} for more information about porting from Qt 3 to Qt 4. See + also the \l{Qt Designer Manual}. + + \section1 uic Output + + In Qt 3, \c uic generated a header file and an implementation for + a class, which inherited from one of Qt's widgets. To use the + form, the programmer included the generated sources into the + application and created an instance of the class. + + In Qt 4, \c uic creates a header file containing a POD class. The + name of this class is the object name of the main container, + qualified with the \c Ui namespace (e.g., \c Ui::MyForm). The + class is implemented using inline functions, removing the need of + a separate \c .cpp file. Just as in Qt 3, this class contains + pointers to all the widgets inside the form as public members. In + addition, the generated class provides the public method \c + setupUi(). + + The class generated by \c uic is not a QWidget; in fact, it's not + even a QObject. Instead, it is a class which knows how to + populate an instance of a main container with the contents of the + form. The programmer creates the main container himself, then + passes it to \c setupUi(). + + For example, here's the \c uic output for a simple \c + helloworld.ui form (some details were removed for simplicity): + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 0 + + In this case, the main container was specified to be a QWidget + (or any subclass of QWidget). Had we started with a QMainWindow + template in Qt Designer, \c setupUi()'s parameter would be of + type QMainWindow. + + There are two ways to create an instance of our form. One + approach is to create an instance of the \c Ui::HelloWorld class, + an instance of the main container (a plain QWidget), and call \c + setupUi(): + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 1 + + The second approach is to inherit from both the \c Ui::HelloWorld + class and the main container, and to call \c setupUi() in the + constructor of the subclass. In that case, QWidget (or one of + its subclasses, e.g. QDialog) must appear first in the base class + list so that \l{moc} picks it up correctly. For example: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 2 + + This second method is useful when porting Qt 3 forms to Qt 4. \c + HelloWorldWidget is a class whose instance is the actual form + and which contains public pointers to all the widgets in it. It + therefore has an interface identical to that of a class generated + by \c uic in Qt 3. + + Creating POD classes from \c .ui files is more flexible and + generic than the old approach of creating widgets. Qt Designer + doesn't need to know anything about the main container apart from + the base widget class it inherits. Indeed, \c Ui::HelloWorld can + be used to populate any container that inherits QWidget. + Conversely, all non-GUI aspects of the main container may be + implemented by the programmer in the application's sources + without reference to the form. + + \section1 Working with uic3 + + Qt 4 comes with the tool \c uic3 for working with old \c .ui + files. It can be used in two ways: + + \list 1 + \o To generate headers and source code for a widget to implement any + custom signals and slots added using Qt Designer 3. + \o To generate a new \c .ui file that can be used with Qt Designer 4. + \endlist + + You can use both these methods in combination to obtain \c{.ui}, header + and source files that you can use as a starting point when porting + your user interface to Qt 4. + + The first method generates a Qt 3 style header and implementation + which uses Qt 4 widgets (this includes the Qt 3 compatibility classes + present in the Qt3Support library). This process should be familiar to + anyone used to working with Qt Designer 3: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 3 + + The resulting files \c myform.h and \c myform.cpp implement the + form in Qt 4 using a QWidget that will include custom signals, + slots and connections specified in the \c .ui file. However, + see below for the \l{#Limitations of uic3}{limitations} of this + method. + + The second method is to use \c uic3 to convert a Qt Designer 3 \c .ui + file to the Qt Designer 4 format: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 4 + + The resulting file \c myform4.ui can be edited in Qt Designer 4. The + header file for the form is generated by Qt 4's \c uic. See the + \l{Using a Designer .ui File in Your Application} chapter of the + \l{Qt Designer Manual} for information about the preferred ways to + use forms created with Qt Designer 4. + + \c uic3 tries very hard to map Qt 3 classes and their properties to + Qt 4. However, the behavior of some classes changed significantly + in Qt 4. To keep the form working, some Qt 3 classes are mapped + to classes in the Qt3Support library. Table 1 shows a list of + classes this applies to. + + \table + \header \o Qt 3 class \o Qt 4 class + \row \o \c QButtonGroup \o Q3ButtonGroup + \row \o \c QDateEdit \o Q3DateEdit + \row \o \c QDateTimeEdit \o Q3DateTimeEdit + \row \o \c QGroupBox \o Q3GroupBox + \row \o \c QListBox \o Q3ListBox + \row \o \c QListView \o Q3ListView + \row \o \c QMainWindow \o Q3MainWindow + \row \o \c QTextEdit \o Q3TextEdit + \row \o \c QTextView \o Q3TextView + \row \o \c QTimeEdit \o Q3TimeEdit + \row \o \c QWidgetStack \o Q3WidgetStack + \row \o \c QWizard \o Q3Wizard + \endtable + + \section1 Limitations of uic3 + + Converting Qt 3 \c .ui files to Qt 4 has some limitations. The + most noticeable limitation is the fact that since \c uic no + longer generates a QObject, it's not possible to define custom + signals or slots for the form. Instead, the programmer must + define these signals and slots in the main container and connect + them to the widgets in the form after calling \c setupUi(). For + example: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 5 + + A quick and dirty way to port forms containing custom signals and + slots is to generate the code using \c uic3, rather than \c uic. Since + \c uic3 does generate a QWidget, it will populate it with custom + signals, slots and connections specified in the \c .ui file. + However, \c uic3 can only generate code from Qt 3 \c .ui files, which + implies that the \c .ui files never get translated and need to be + edited using Qt Designer 3. + + Note also that it is possible to create implicit connections + between the widgets in a form and the main container. After \c + setupUi() populates the main container with child widgets it + scans the main container's list of slots for names with the form + \tt{on_\e{objectName}_\e{signalName}().} + + If the form contains a widget whose object name is + \tt{\e{objectName}}, and if that widget has a signal called + \tt{\e{signalName}}, then this signal will be connected to the + main container's slot. For example: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 6 + + Because of the naming convention, \c setupUi() automatically + connects \c pushButton's \c clicked() signal to \c + HelloWorldWidget's \c on_pushButton_clicked() slot. + + \section1 Icons + + In Qt 3, the binary data for the icons used by a form was stored + in the \c .ui file. In Qt 4 icons and any other external files + can be compiled into the application by listing them in a \l{The + Qt Resource System}{resource file} (\c .qrc). This file is + translated into a C++ source file using Qt's resource compiler + (\c rcc). The data in the files is then available to any Qt class + which takes a file name argument. + + Imagine that we have two icons, \c yes.png and \c no.png. We + create a resource file called \c icons.qrc with the following + contents: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 7 + + Next, we add the resource file to our \c .pro file: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 8 + + When \c qmake is run, it will create the appropriate Makefile + rules to call \c rcc on the resource file, and compile and link + the result into the application. The icons may be accessed as + follows: + + \snippet doc/src/snippets/code/doc_src_porting4-designer.qdoc 9 + + In each case, the leading colon tells Qt to look for the file in + the virtual file tree defined by the set of resource files + compiled into the application instead of the file system. + + In the \c .qrc file, the \c qresource tag's \c prefix attribute + is used to arrange the files into categories and set a virtual + path where the files will be accessed. + + Caveat: If the resource file was not linked directly into the + application, but instead into a dynamic or static library that + was later linked with the application, its virtual file tree will + not be available to QFile and friends until the Q_INIT_RESOURCE() + macro is called. This macro takes one argument, which is the name + of the \c .qrc file, without the path or the file extension. A + convenient place to initialize resources is at the top of the + application's \c main() function. + + In Qt Designer 4, we can associate any number of resource files + with a form using the resource editor tool. The widgets in the + form can access all icons specified in its associated resource + files. + + In short, porting of icons from a Qt 3 to a Qt 4 form involves + the following steps: + + \list 1 + \o Use \c{uic3 -convert} to obtain a \c .ui file understood by + Qt Designer 4. + + \o Create a \c .qrc file with a list of all the icon files. + + \o Add the resource file to the \c .pro file. + + \o Open the form in Qt Designer 4 and add the resource file to the + form's resource editor. + + \o Set the icon properties for the appropriate widgets. + \endlist + + \section1 Custom Widgets + + Qt Designer 3 supported defining custom widgets by specifying + their name, header file and methods. In Qt Designer 4, a custom + widget is always created by "promoting" an existing Qt widget to + a custom class. Qt Designer 4 assumes that the custom widget will + inherit from the widget that has been promoted. In the form + editor, the custom widget will retain the looks, behavior, + properties, signals and slots of the base widget. It is not + currently possible to tell Qt Designer 4 that the custom widget + will have additional signals or slots. + + \c{uic3 -convert} handles the conversion of custom widgets to the + new \c .ui format, however all custom signals and slots are lost. + Furthermore, since Qt Designer 3 never knew the base widget class + of a custom widget, it is taken to be QWidget. This is often + sufficient. If not, the custom widgets have to be inserted + manually into the form. + + Custom widget plugins, which contain custom widgets to be used in + Qt Designer, must themselves be ported before they can be used in + forms ported with \c{uic3}. + The \l{Porting to Qt 4} document contains information about general + porting issues that may apply to the custom widget code itself, and + the \l{Creating Custom Widgets for Qt Designer} chapter of the + \l{Qt Designer Manual} describes how the ported widget should be + built in order to work in Qt Designer 4. +*/ diff --git a/doc/src/porting4-modifiedvirtual.qdocinc b/doc/src/porting4-modifiedvirtual.qdocinc new file mode 100644 index 0000000..1164238 --- /dev/null +++ b/doc/src/porting4-modifiedvirtual.qdocinc @@ -0,0 +1,63 @@ +\row \o int QAccessibleInterface::navigate(NavDirection, int) const \o int QAccessibleInterface::navigate(RelationFlag, int, QAccessibleInterface **) const +\row \o bool QApplication::winEventFilter(MSG *) \o bool QApplication::winEventFilter(MSG *, long *) +\row \o Function: Offset QIODevice::at() const \o Function: Q_LONGLONG QIODevice::pos() const +\row \o bool QIODevice::at(Offset) \o bool QIODevice::seek(Q_LONGLONG) +\row \o bool QIODevice::open(int) \o bool QIODevice::open(OpenMode) +\row \o Q_LONG QIODevice::readBlock(char *, Q_ULONG) \o Q_LONGLONG QIODevice::readData(char *, Q_LONGLONG) +\row \o Q_LONG QIODevice::writeBlock(const char *, Q_ULONG) \o Q_LONGLONG QIODevice::writeData(const char *, Q_LONGLONG) +\row \o const char * QImageFormatType::formatName() const \o QByteArray QImageFormatType::formatName() const +\row \o QPopupMenu * QLineEdit::createPopupMenu() \o QMenu * QLineEdit::createPopupMenu() +\row \o bool QMacMime::canConvert(const char *, int) \o bool QMacMime::canConvert(const QString &, int) +\row \o QValueList QMacMime::convertFromMime(QByteArray, const char *, int) \o QList QMacMime::convertFromMime(QByteArray, const QString &, int) +\row \o QByteArray QMacMime::convertToMime(QValueList data, const char *, int) \o QByteArray QMacMime::convertToMime(QList data, const QString &, int) +\row \o const char * QMacMime::convertorName() \o QString QMacMime::convertorName() +\row \o int QMacMime::flavorFor(const char *) \o int QMacMime::flavorFor(const QString &) +\row \o const char * QMacMime::mimeFor(int) \o QString QMacMime::mimeFor(int) +\row \o QMetaObject * QObject::metaObject() const \o const QMetaObject * QObject::metaObject() const +\row \o bool QScreen::onCard(unsigned char *) const \o bool QScreen::onCard(const unsigned char *) const +\row \o bool QScreen::onCard(unsigned char *, ulong &) const \o bool QScreen::onCard(const unsigned char *, ulong &) const +\row \o int QSpinBox::mapTextToValue(bool *) \o int QSpinBox::mapTextToValue(QString *, QValidator::State *) const +\row \o QString QSpinBox::mapValueToText(int) \o QString QSpinBox::mapValueToText(int) const +\row \o bool QSqlDriver::open(const QString &, const QString &, const QString &, const QString &, int) \o bool QSqlDriver::open(const QString &, const QString &, const QString &, const QString &, int, const QString &) +\row \o QStringList QSqlDriver::tables(const QString &) const \o QStringList QSqlDriver::tables(QSql::TableType) const +\row \o bool QSqlQuery::prev() \o bool QSqlQuery::previous() +\row \o bool QSqlResult::fetchPrev() \o bool QSqlResult::fetchPrevious() +\row \o void QStyle::drawComplexControl(ComplexControl, QPainter *, const QWidget *, const QRect &, const QColorGroup &, SFlags, SCFlags, SCFlags, const QStyleOption &) const \o void QStyle::drawComplexControl(ComplexControl, const QStyleOptionComplex *, QPainter *, const QWidget *) const +\row \o void QStyle::drawComplexControlMask(ComplexControl, QPainter *, const QWidget *, const QRect &, const QStyleOption &) const \o void QStyle::drawComplexControlMask(ComplexControl, const QStyleOptionComplex *, QPainter *, const QWidget *) const +\row \o void QStyle::drawControl(ControlElement, QPainter *, const QWidget *, const QRect &, const QColorGroup &, SFlags, const QStyleOption &) const \o void QStyle::drawControl(ControlElement, const QStyleOption *, QPainter *, const QWidget *) const +\row \o void QStyle::drawControlMask(ControlElement, QPainter *, const QWidget *, const QRect &, const QStyleOption &) const \o void QStyle::drawControlMask(ControlElement, const QStyleOption *, QPainter *, const QWidget *) const +\row \o void QStyle::drawItem(QPainter *, const QRect &, int, const QColorGroup &, bool, const QPixmap *, const QString &, int, const QColor *) const \o void QStyle::drawItem(QPainter *, const QRect &, int, const QPalette &, bool, const QString &, int, const QColor *) const +\row \o void QStyle::drawPrimitive(PrimitiveElement, QPainter *, const QRect &, const QColorGroup &, SFlags, const QStyleOption &) const \o void QStyle::drawPrimitive(PrimitiveElement, const QStyleOption *, QPainter *, const QWidget *) const +\row \o QRect QStyle::itemRect(QPainter *, const QRect &, int, bool, const QPixmap *, const QString &, int) const \o QRect QStyle::itemTextRect(const QFontMetrics &, const QRect &, int, bool, const QString &, int) const +\row \o int QStyle::pixelMetric(PixelMetric, const QWidget *) const \o int QStyle::pixelMetric(PixelMetric, const QStyleOption *, const QWidget *) const +\row \o SubControl QStyle::querySubControl(ComplexControl, const QWidget *, const QPoint &, const QStyleOption &) const \o SubControl QStyle::hitTestComplexControl(ComplexControl, const QStyleOptionComplex *, const QPoint &, const QWidget *) const +\row \o QRect QStyle::querySubControlMetrics(ComplexControl, const QWidget *, SubControl, const QStyleOption &) const \o QRect QStyle::subControlRect(ComplexControl, const QStyleOptionComplex *, SubControl, const QWidget *) const +\row \o QSize QStyle::sizeFromContents(ContentsType, const QWidget *, const QSize &, const QStyleOption &) const \o QSize QStyle::sizeFromContents(ContentsType, const QStyleOption *, const QSize &, const QFontMetrics &, const QWidget *) const +\row \o int QStyle::styleHint(StyleHint, const QWidget *, const QStyleOption &, QStyleHintReturn *) const \o int QStyle::styleHint(StyleHint, const QStyleOption *, const QWidget *, QStyleHintReturn *) const +\row \o QPixmap QStyle::stylePixmap(StylePixmap, const QWidget *, const QStyleOption &) const \o QPixmap QStyle::standardPixmap(StandardPixmap, const QStyleOption *, const QWidget *) const +\row \o QRect QStyle::subRect(SubRect, const QWidget *) const \o QRect QStyle::subRect(SubRect, const QStyleOption *, const QFontMetrics &, const QWidget *) const +\row \o void QStyle::unPolish(QApplication *) \o void QStyle::unpolish(QApplication *) +\row \o void QStyle::unPolish(QWidget *) \o void QStyle::unpolish(QWidget *) +\row \o QCString QTextCodec::fromUnicode(const QString &, int &) const \o QByteArray QTextCodec::fromUnicode(const QString &, int &) const +\row \o QValueList QTextCodecPlugin::mibEnums() const \o QList QTextCodecPlugin::mibEnums() const +\row \o void QTextDrag::setSubtype(const QCString &) \o void QTextDrag::setSubtype(const QString &) +\row \o QCString QTextEncoder::fromUnicode(const QString &, int &) \o QByteArray QTextEncoder::fromUnicode(const QString &, int &) +\row \o void QUriDrag::setUris(QStrList) \o void QUriDrag::setUris(const QList & list) +\row \o void QUrlInfo::setSize(uint) \o void QUrlInfo::setSize(Q_LONGLONG) +\row \o bool QWindowsMime::canConvert(const char *, int) \o bool QWindowsMime::canConvert(const QString &, int) +\row \o int QWindowsMime::cfFor(const char *) \o int QWindowsMime::cfFor(const QString &) +\row \o QByteArray QWindowsMime::convertFromMime(QByteArray, const char *, int) \o QByteArray QWindowsMime::convertFromMime(const QByteArray &, const QString &, int) +\row \o QByteArray QWindowsMime::convertToMime(QByteArray, const char *, int) \o QByteArray QWindowsMime::convertToMime(const QByteArray &, const QString &, int) +\row \o const char * QWindowsMime::convertorName() \o QString QWindowsMime::convertorName() +\row \o void QWSMouseHandler::calibrate(QWSPointerCalibrationData *) \o void QWSMouseHandler::calibrate(const QWSPointerCalibrationData *) +\row \o bool QWidget::macEvent(MSG *) \o bool QWidget::macEvent(EventHandlerCallRef, EventRef) +\row \o bool QWidget::winEvent(MSG *) \o bool QWidget::winEvent(MSG *, long *) +\row \o QString QXmlContentHandler::errorString() \o QString QXmlContentHandler::errorString() const +\row \o QString QXmlDTDHandler::errorString() \o QString QXmlDTDHandler::errorString() const +\row \o QString QXmlDeclHandler::errorString() \o QString QXmlDeclHandler::errorString() const +\row \o QString QXmlEntityResolver::errorString() \o QString QXmlEntityResolver::errorString() const +\row \o QString QXmlErrorHandler::errorString() \o QString QXmlErrorHandler::errorString() const +\row \o QString QXmlInputSource::data() \o QString QXmlInputSource::data() const +\row \o QString QXmlLexicalHandler::errorString() \o QString QXmlLexicalHandler::errorString() const +\row \o int QXmlLocator::columnNumber() \o int QXmlLocator::columnNumber() const +\row \o int QXmlLocator::lineNumber() \o int QXmlLocator::lineNumber() const diff --git a/doc/src/porting4-obsoletedmechanism.qdocinc b/doc/src/porting4-obsoletedmechanism.qdocinc new file mode 100644 index 0000000..1594570 --- /dev/null +++ b/doc/src/porting4-obsoletedmechanism.qdocinc @@ -0,0 +1,3 @@ +If you use this mechanism in your application, please submit a +report to the \l{Task Tracker} on the Trolltech +website and we will try to find a satisfactory substitute. diff --git a/doc/src/porting4-overview.qdoc b/doc/src/porting4-overview.qdoc new file mode 100644 index 0000000..b0146a6 --- /dev/null +++ b/doc/src/porting4-overview.qdoc @@ -0,0 +1,367 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page porting4-overview.html + \title Moving from Qt 3 to Qt 4 + \ingroup porting + \brief Porting advice for authors of new and existing Qt 3 applications. + + This document describes which parts of Qt should be used when + writing an application with Qt 3, so that it can be upgraded to + use Qt 4 later with a minimum of effort. However, the advice may + also be useful to developers who are porting existing applications + from Qt 3 to Qt 4. + + For a detailed overview + of the porting process for existing Qt 3 applications, see the + \l{Porting to Qt 4} document. + + \tableofcontents + + Since Qt 4 provides important new functionality at the cost of + some compatibility with Qt 3, it is useful for developers of + Qt 3-based applications to learn how to take advantage of + Qt 3's API now while preparing for future changes that will be + needed when upgrading to Qt 4. + + Certain advanced Qt 3 features were moved to the Qt 3 support + library (\l{Qt3Support}) in Qt 4.0, and have been gradually + replaced in subsequent releases of Qt 4. + + Making Qt 3 applications as portable to Qt 4 as possible + enables a smooth transition between versions of Qt in the + long term, and allows for a stable development process + throughout. + + \section1 Qt 3 Features to Avoid + + Although we are proud of the level of stability we have achieved + with Qt, it is important to realise that, for Qt 4 to be a + substantial improvement over Qt 3, certain features have + been revised to make the framework more maintainable for us + and more usable for developers. It is therefore useful to + know which features of Qt 3 should be avoided to help save + time during a later porting effort to Qt 4. Note that it is + still possible to use many of the following classes and + features through the use of the \l{Qt3Support} module. + + \section2 Painting Outside Paint Events + + In Qt 3, under certain circumstances, it was possible to use + QPainter to draw on a given custom widget outside its + \l{QWidget::}{paintEvent()} reimplementation. In Qt 4, in most + situations, painting must occur within a widget's paint event + handler. + + On X11, it is possible to set the \l{Qt::WA_PaintOutsidePaintEvent} + attribute on widgets to keep existing code, but we recommend + restricting the use of painting code to within paint event handlers + where possible. + + More information about this change can be found in the + \l{Porting to Qt 4#Painting and Redrawing Widgets}{Painting and Redrawing Widgets} + section of the \l{Porting to Qt 4} document. + + \section2 Qt Designer + + The version of Qt Designer supplied with Qt 3 provided + extensive code editing and project management features + (control over \c{.ui.h} and \c{.pro} files), and encouraged + users to design main window applications from within the + Qt Designer environment. + + The version of Qt Designer supplied with Qt 4 is intended + to be integrated with other software development tools (such + as integrated development environments), and does not + support these project-level features. + + We recommend using one of the + \l{Using a Designer .ui File in Your Application}{form subclassing approaches} + with forms created using Qt Designer. This avoids the need + to use \c{.ui.h} files and special purpose code editors. + + Existing Qt 3 forms created using Qt Designer can be gradually + ported to Qt 4 by following the advice in the + \l{Porting .ui Files to Qt 4} guide. However, some extra effort + will be required to move application logic from \c{.ui.h} files + into the main body of a Qt 4 application. + + \section2 Menu Items (QMenuItem) + + The old-style construction of menus by creating individual + menu items has been superseded in Qt 4 by the use of + generic actions which can be used in menus, toolbars, and + as keyboard shortcuts. + + Qt 3 also supports this action-based approach, so, by using + QAction throughout your application, less work will be + required to adapt your application to Qt 4. + + \section2 Pointer-Based Classes (QPtr*) + + Qt 3 provides a group of pointer-based classes (\c QPtrList, + \c QPtrDict, \c QPtrVector, etc.) that help manage collections + of pointers to objects (usually QObject subclasses) in an + application. In addition, the value-based collection classes + (\c QValueList, \c QValueDict, \c QValueVector, etc.) provide + a way to store standard value types which cannot be easily stored + in pointer-based collections. + + Qt 4 introduces a single set of collection classes which + does not require developers to pay as much attention to + memory allocation and object ownership issues. As a result, + Qt 3's pointer-based classes have no direct equivalent + classes in Qt 4. + + To ease migration, use Qt 3's value-based classes to store + most objects, including pointers; for example, use + \c QValueVector rather than + \c QPtrVector. These can be replaced by + Qt 4's QVector, QLinkedList, and QList later. + + \section2 Other Collection Classes (QStrList, Q*Dict) + + Some collection classes in Qt 3 have been deprecated in + favor of easier to use, higher level alternatives. These + include the dictionary classes (\c QAsciiDict, \c QDict, + \c QIntDict, \c QPtrDict) and \c QStrList. + + \c QStrList can usually replaced by the higher level QStringList + class in Qt 3; this is also available in Qt 4. It is + recommended that you use the QMap class instead of the \c QDict + classes. In Qt 4, QMap is also complemented by the QHash + class. + + \section2 Memory Arrays (QMemArray) + + In Qt 3, the \c QMemArray class is used as a simple array + container for simple data types. This class is deprecated in + Qt 4 in favor of the QVector and QVarLengthVector classes + which provide more powerful and consistent array objects. + + Qt 3's closest equivalent class to Qt 4's QVector is the + \c QValueVector class. For many purposes, this can be used + instead of \c QMemArray. + + \section2 URL Operations (QUrlOperator) + + The URL operator in Qt 3 provides an abstract way to + handle files via HTTP, FTP, and on the local file system. + However, Qt 4 only provides this functionality through the + use of the Q3UrlOperator. + + From Qt 4.4, the Network Access API provides a subset of the features + provided by \c QUrlOperator that are mostly intended for use with + applications that use the HTTP and FTP protocols. See the + QNetworkRequest, QNetworkReply, and QNetworkAccessManager documentation + for further details. + + It is also possible to perform operations on remote files + through the QHttp and QFtp classes, and on local files with + the QFile class. + + \section2 SQL Cursors (QSqlCursor) + + In Qt 3, one of the preferred methods of working with SQL + is to use a cursor to manipulate the contents of a database. + In Qt 4, the preferred method of working with SQL is to use + the model/view architecture (QSqlQueryModel and QSqlTableModel) + and, as a result, the cursor interface is only supplied in the + Q3SqlCursor class. + + The easiest way to ensure continuity between Qt 3 and Qt 4 + is to use QSqlQuery rather than \c QSqlCursor, + and migrate to QSqlQueryModel later. + + \section2 Domain Name Service (QDns) + + The QDns class in Qt 4 provides a much simpler interface + than the QDns class in Qt 3, and is mainly used for host + name resolution. + As a result, many of the more complex features of Qt 3's + QDns class are only available through Qt 4's Q3Dns + compatibility class. + + To resolve host names with Qt 3, it is recommended that you + use the higher level interface of QSocket rather than QDns. + The equivalent functionality is available in Qt 4 in the + QAbstractSocket and QHostInfo classes. + + \section2 Wizard Dialogs (QWizard) + + Qt 3 provides support for "wizard" dialogs in the form of + the \c QWizard class. Prior to Qt 4.3, this class was made + available as Q3Wizard, and provides the same interface for + creating relatively complex wizards. + + In Qt 4.3 and later, a revised QWizard class can be used to + create this kind of dialog, but existing Qt 3 wizard + implementations may need to be redesigned to work with the + new QWizard API. + + \section2 Abstract Grid Views (QGridView) + + Before the introduction of the Qt 3 \c QTable class, + \c QGridView was the recommended way to create tables of + custom items. + With the introduction of \c QTable, the \c QGridView class was + effectively obsoleted, and the \c QTable class should now be + used to display tabular information in your Qt 3 application. + This approach allows you to use QTableWidget as a replacement + when later porting your application to Qt 4. + + \section2 Specialized Scrolling Views + + In Qt 3, the \c QScrollView class provides a viewport that can + be used to display part of a larger widget, and will + optionally provide scroll bars for navigation purposes. + In Qt 4, this functionality is superseded by classes such as + QScrollArea, which provides a more intuitive interface for + developers to use. + \c QScrollView is available in Qt 4 as the Q3ScrollView class. + + In Qt 3, it is recommended that \c QScrollView should be + used with child widgets rather than subclassed. However, it + should be noted that this approach may not be appropriate if + you need to use extremely large scrolling areas in your + application, since Qt 3 widgets cannot be wider or taller + than 32767 pixels. + + \section1 Significantly Changed Features + + Some Qt 3 features have changed significantly for Qt 4. + and the recommended way of using them has therefore changed + significantly, too. This is most notably true for the drag + and drop API. + + Additionally, some of the more specialized features in Qt 3 are + often used to help customize widgets and add extra polish to an + application. + Although these improvements make applications more presentable to + users, many of them are unnecessary with Qt 4, and may create + additional porting work. + + \section2 Drag and Drop + + Qt 4 introduces a simpler and more intuitive implementation + of drag and drop between widgets, and with other applications. + As a result, there is no simple approach that can be used to + make drag and drop in a Qt 3 application easier to port to + Qt 4. + + \section2 Extensive Customization of Item Views + + Each of the classes that are used to display list, tree, + and table items in Qt 3 can be subclassed for the purposes + of customizing their appearance. The item view framework + in Qt 4 is implemented according to a different paradigm + (model/view) which does not allow items to be customized + using this method. + + Although Qt 4 provides compatibility classes (Q3ListBoxItem, + Q3ListViewItem, and Q3TableItem) that can be used in the same + way as their Qt 3 counterparts, these cannot be used within + the standard model/view framework. It is recommended that, + to minimize porting effort, extensive customization of item + classes should be avoided in Qt 3, if at all possible. + + \section2 Double Buffering + + Qt 3 applications often use double buffering for reducing + flicker when painting custom widgets. This approach is + unnecessary with Qt 4 because double buffering is + automatically performed by the paint engine. + + It still makes sense to use double buffering in + Qt 4 in certain contexts. For example, in + Chapter 5 of \l{GUI Programming with Qt 3}, double buffering + was presented as a speed optimization and not just as a means + of reducing flicker. + + \section2 Data-Aware Forms + + The \c QDataTable, \c QDataBrowser, and \c QDataView classes + in Qt 3 allow integration between widgets and SQL-based + databases. + + In Qt 4.1 and earlier, the preferred way to create a data-aware + widget is to connect an generic item view (such as a table view) + to a SQL model. In Qt 4.2 and later, the QDataWidgetMapper class + can be used to map data to widgets in a form-based user interface. + + New applications written with Qt 3 should use QSqlQuery in + preference to an approach based on the old-style data-aware + widgets. + This offers a choice of porting strategies when later migrating + the application to Qt 4: You can either continue to use + QSqlQuery or take the opportunity to use the model/view + classes to handle database integration. + + \section2 Dock Windows and Areas + + In Qt 4, the way that dock windows are constructed and used + in main window applications differs significantly to the + pattern of use provided by Qt 3. As a result, the introduction + of a simpler and cleaner API means that Qt 3 applications that + make extensive use of dock window areas will require careful + examination when they are ported to Qt 4. + + We recommend that the QMainWindow class be used in preference + to the Q3MainWindow compatibility class when an existing Qt 3 + main window application is ported to Qt 4. Therefore, we + recommend that specialized use of dock window areas should + be avoided when writing a Qt 3 application with Qt 4 in mind. + + \section2 Custom Styles + + The style system used to provide consistent themes for Qt's + standard widgets has been revised for Qt 4. As a result, + custom styles for Qt 3 require some porting work to be done + before they can be used with Qt 4. To ease the porting process, + we recommend that you avoid implementing custom widget styles + for Qt 3 applications unless it is absolutely necessary for + your users. + + In Qt 4.2 and later, \l{Qt Style Sheets} can be used to + implement many common modifications to existing styles, and + this may be sufficient for Qt 3 applications. +*/ diff --git a/doc/src/porting4-removedenumvalues.qdocinc b/doc/src/porting4-removedenumvalues.qdocinc new file mode 100644 index 0000000..fe38d0e --- /dev/null +++ b/doc/src/porting4-removedenumvalues.qdocinc @@ -0,0 +1,6 @@ +\row \o QButton::SingleShot +\row \o QButton::Toggle +\row \o QButton::Tristate +\row \o QEvent::AccelAvailable +\row \o QEvent::ParentFontChange +\row \o QEvent::ParentPaletteChange diff --git a/doc/src/porting4-removedtypes.qdocinc b/doc/src/porting4-removedtypes.qdocinc new file mode 100644 index 0000000..9d7c519 --- /dev/null +++ b/doc/src/porting4-removedtypes.qdocinc @@ -0,0 +1 @@ +\row \o QAbstractButton::ToggleType diff --git a/doc/src/porting4-removedvariantfunctions.qdocinc b/doc/src/porting4-removedvariantfunctions.qdocinc new file mode 100644 index 0000000..dfaa8f3 --- /dev/null +++ b/doc/src/porting4-removedvariantfunctions.qdocinc @@ -0,0 +1,16 @@ +\row \o toBitmap () \o QVariant::value() +\row \o toBrush () \o QVariant::value() +\row \o toColorGroup () \o Use QVariant::value() with QPalette instead. +\row \o toColor () \o QVariant::value() +\row \o toCString () \o QVariant::toByteArray() +\row \o toCursor () \o QVariant::value() +\row \o toFont () \o QVariant::value() +\row \o toIconSet () \o Use QVariant::value() with QIcon instead. +\row \o toImage () \o QVariant::value() +\row \o toKeySequence () \o QVariant::value() +\row \o toPalette () \o QVariant::value() +\row \o toPen () \o QVariant::value() +\row \o toPixmap () \o QVariant::value() +\row \o toPointArray () \o QVariant::value() +\row \o toRegion () \o QVariant::value() +\row \o toSizePolicy () \o QVariant::value() diff --git a/doc/src/porting4-removedvirtual.qdocinc b/doc/src/porting4-removedvirtual.qdocinc new file mode 100644 index 0000000..3eedad2 --- /dev/null +++ b/doc/src/porting4-removedvirtual.qdocinc @@ -0,0 +1,605 @@ +\row \o void QAccessibleInterface::clearSelection() \o Port to the new QAccessibleInterface API. +\row \o int QAccessibleInterface::controlAt(int, int) const \o Port to the new QAccessibleInterface API. +\row \o bool QAccessibleInterface::doDefaultAction(int) \o Port to the new QAccessibleInterface API. +\row \o QMemArray QAccessibleInterface::selection() const \o Port to the new QAccessibleInterface API. +\row \o bool QAccessibleInterface::setFocus(int) \o Port to the new QAccessibleInterface API. +\row \o bool QAccessibleInterface::setSelected(int, bool, bool) \o Port to the new QAccessibleInterface API. +\row \o bool QAction::addTo(QWidget *) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::addedTo(QWidget *, QWidget *) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::addedTo(int, QPopupMenu *) \o Use Q3Action instead or port to the new QAction API. +\row \o bool QAction::removeFrom(QWidget *) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setAccel(const QKeySequence &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setEnabled(bool) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setIconSet(const QIcon &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setMenuText(const QString &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setOn(bool) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setStatusTip(const QString &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setText(const QString &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setToggleAction(bool) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setToolTip(const QString &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QAction::setWhatsThis(const QString &) \o Use Q3Action instead or port to the new QAction API. +\row \o void QButton::drawButton(QPainter *) \o Use Q3Button instead or reimplement QButton::paintEvent(). +\row \o void QButton::drawButtonLabel(QPainter *) \o Use Q3Button instead or reimplement QButton::paintEvent(). +\row \o void QButton::setAccel(const QKeySequence &) \o Setter. +\row \o void QButton::setAutoRepeat(bool) \o Setter. +\row \o void QButton::setDown(bool) \o Setter. +\row \o void QButton::setPixmap(const QPixmap &) \o Setter. +\row \o void QButton::setState(ToggleState) \o Setter. +\row \o void QButton::setText(const QString &) \o Use the QAbstractButton::setText() setter function. +\row \o void QButton::setToggleType(ToggleType) \o Setter. +\row \o void QButtonGroup::moveFocus(int) \o Use the QWidget::setFocus() setter function. +\row \o void QButtonGroup::setButton(int) \o Setter. +\row \o void QButtonGroup::setExclusive(bool) \o Setter. +\row \o void QButtonGroup::setRadioButtonExclusive(bool) \o Setter. +\row \o void QComboBox::setAutoCompletion(bool) \o Setter. +\row \o void QComboBox::setAutoResize(bool) \o Setter. +\row \o void QComboBox::setCurrentItem(int) \o Setter. +\row \o void QComboBox::setCurrentText(const QString &) \o Setter. +\row \o void QComboBox::setFont(const QFont &) \o Setter. +\row \o void QComboBox::setInsertionPolicy(Policy) \o Setter. +\row \o void QComboBox::setLineEdit(QLineEdit *) \o Setter. +\row \o void QComboBox::setListBox(QListBox *) \o Setter. +\row \o void QComboBox::setMaxCount(int) \o Setter. +\row \o void QComboBox::setPalette(const QPalette &) \o Setter. +\row \o void QComboBox::setSizeLimit(int) \o Setter. +\row \o void QComboBox::setValidator(const QValidator *) \o Setter. +\row \o void QDateEdit::fix() \o Port to the new QDateTimeEdit API. +\row \o QString QDateEdit::sectionFormattedText(int) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setAutoAdvance(bool) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setDate(const QDate &) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setDay(int) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setMaxValue(const QDate &) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setMinValue(const QDate &) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setMonth(int) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setOrder(Order) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setRange(const QDate &, const QDate &) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setSeparator(const QString &) \o Port to the new QDateTimeEdit API. +\row \o void QDateEdit::setYear(int) \o Port to the new QDateTimeEdit API. +\row \o void QDateTimeEdit::setAutoAdvance(bool) \o Port to the new QDateTimeEdit API. +\row \o void QDateTimeEdit::setDateTime(const QDateTime &) \o Port to the new QDateTimeEdit API. +\row \o void QDial::rangeChange() \o Reimplement QDial::sliderChange() instead. +\row \o void QDial::repaintScreen(const QRect *) \o Reimplement QDial::paintEvent() instead. +\row \o void QDial::setNotchTarget(double) \o Setter. +\row \o void QDial::setNotchesVisible(bool) \o Setter. +\row \o void QDial::setTracking(bool) \o Setter. +\row \o void QDial::setValue(int) \o Use QDial::sliderChange() instead. +\row \o void QDial::setWrapping(bool) \o Setter. +\row \o void QDial::valueChange() \o Use QDial::sliderChange() instead. +\row \o QString QDir::absFilePath(const QString &, bool) const \o Value type. +\row \o QString QDir::absPath() const \o Value type. +\row \o QString QDir::canonicalPath() const \o Value type. +\row \o bool QDir::cd(const QString &, bool) \o Value type. +\row \o bool QDir::cdUp() \o Value type. +\row \o void QDir::convertToAbs() \o Value type. +\row \o QString QDir::dirName() const \o Value type. +\row \o QStrList QDir::encodedEntryList(int, int) const \o Value type. +\row \o QStrList QDir::encodedEntryList(const QString &, int, int) const \o Value type. +\row \o const QFileInfoList * QDir::entryInfoList(int, int) const \o Value type. +\row \o const QFileInfoList * QDir::entryInfoList(const QString &, int, int) const \o Value type. +\row \o QStringList QDir::entryList(const QString &, int, int) const \o Value type. +\row \o QStringList QDir::entryList(int, int) const \o Value type. +\row \o bool QDir::exists() const \o Value type. +\row \o bool QDir::exists(const QString &, bool) \o Value type. +\row \o QString QDir::filePath(const QString &, bool) const \o Value type. +\row \o bool QDir::isReadable() const \o Value type. +\row \o bool QDir::isRelative() const \o Value type. +\row \o bool QDir::isRoot() const \o Value type. +\row \o bool QDir::mkdir(const QString &, bool) const \o Value type. +\row \o bool QDir::operator!=() const \o Value type. +\row \o bool QDir::operator==() const \o Value type. +\row \o QString QDir::path() const \o Value type. +\row \o bool QDir::remove(const QString &, bool) \o Value type. +\row \o bool QDir::rename(const QString &, const QString &, bool) \o Value type. +\row \o bool QDir::rmdir(const QString &, bool) const \o Value type. +\row \o void QDir::setFilter(int) \o Value type. +\row \o void QDir::setMatchAllDirs(bool) \o Value type. +\row \o void QDir::setNameFilter(const QString &) \o Value type. +\row \o void QDir::setPath(const QString &) \o Value type. +\row \o void QDir::setSorting(int) \o Value type. +\row \o void QDns::setLabel(const QString &) \o Use Q3Dns instead. +\row \o void QDns::setLabel(const QHostAddress &) \o Use Q3Dns instead. +\row \o void QDns::setRecordType(RecordType) \o Use Q3Dns instead. +\row \o void QDockWindow::dock() \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setCloseMode(int) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setFixedExtentHeight(int) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setFixedExtentWidth(int) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setHorizontallyStretchable(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setMovingEnabled(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setNewLine(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setOffset(int) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setOpaqueMoving(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setOrientation(Orientation) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setResizeEnabled(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setVerticallyStretchable(bool) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::setWidget(QWidget *) \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o void QDockWindow::undock() \o Use Q3DockWindow instead or port to the new QDockWidget API. +\row \o QString QDomAttr::name() const \o Value type. +\row \o QDomElement QDomAttr::ownerElement() const \o Value type. +\row \o void QDomAttr::setValue(const QString &) \o Value type. +\row \o bool QDomAttr::specified() const \o Value type. +\row \o QString QDomAttr::value() const \o Value type. +\row \o void QDomCharacterData::appendData(const QString &) \o Value type. +\row \o QString QDomCharacterData::data() const \o Value type. +\row \o void QDomCharacterData::deleteData(unsigned, unsigned) \o Value type. +\row \o void QDomCharacterData::insertData(unsigned, const QString &) \o Value type. +\row \o uint QDomCharacterData::length() const \o Value type. +\row \o void QDomCharacterData::replaceData(unsigned, unsigned, const QString &) \o Value type. +\row \o void QDomCharacterData::setData(const QString &) \o Value type. +\row \o QString QDomCharacterData::substringData(unsigned, unsigned) \o Value type. +\row \o QDomNamedNodeMap QDomDocumentType::entities() const \o Value type. +\row \o QString QDomDocumentType::internalSubset() const \o Value type. +\row \o QString QDomDocumentType::name() const \o Value type. +\row \o QDomNamedNodeMap QDomDocumentType::notations() const \o Value type. +\row \o QString QDomDocumentType::publicId() const \o Value type. +\row \o QString QDomDocumentType::systemId() const \o Value type. +\row \o QDomNamedNodeMap QDomElement::attributes() const \o Value type. +\row \o QDomNodeList QDomElement::elementsByTagName(const QString &) const \o Value type. +\row \o QDomNodeList QDomElement::elementsByTagNameNS(const QString &, const QString &) const \o Value type. +\row \o QString QDomEntity::notationName() const \o Value type. +\row \o QString QDomEntity::publicId() const \o Value type. +\row \o QString QDomEntity::systemId() const \o Value type. +\row \o QDomDocument QDomImplementation::createDocument(const QString &, const QString &, const QDomDocumentType &) \o Value type. +\row \o QDomDocumentType QDomImplementation::createDocumentType(const QString &, const QString &, const QString &) \o Value type. +\row \o bool QDomImplementation::hasFeature(const QString &, const QString &) \o Value type. +\row \o QDomImplementation::~QDomImplementation() \o Value type. +\row \o QDomNode QDomNode::appendChild(const QDomNode &) \o Value type. +\row \o QDomNamedNodeMap QDomNode::attributes() const \o Value type. +\row \o QDomNodeList QDomNode::childNodes() const \o Value type. +\row \o QDomNode QDomNode::cloneNode(bool) const \o Value type. +\row \o QDomNode QDomNode::firstChild() const \o Value type. +\row \o bool QDomNode::hasAttributes() const \o Value type. +\row \o bool QDomNode::hasChildNodes() const \o Value type. +\row \o QDomNode QDomNode::insertAfter(const QDomNode &, const QDomNode &) \o Value type. +\row \o QDomNode QDomNode::insertBefore(const QDomNode &, const QDomNode &) \o Value type. +\row \o bool QDomNode::isAttr() const \o Value type. +\row \o bool QDomNode::isCDATASection() const \o Value type. +\row \o bool QDomNode::isCharacterData() const \o Value type. +\row \o bool QDomNode::isComment() const \o Value type. +\row \o bool QDomNode::isDocument() const \o Value type. +\row \o bool QDomNode::isDocumentFragment() const \o Value type. +\row \o bool QDomNode::isDocumentType() const \o Value type. +\row \o bool QDomNode::isElement() const \o Value type. +\row \o bool QDomNode::isEntity() const \o Value type. +\row \o bool QDomNode::isEntityReference() const \o Value type. +\row \o bool QDomNode::isNotation() const \o Value type. +\row \o bool QDomNode::isProcessingInstruction() const \o Value type. +\row \o bool QDomNode::isSupported(const QString &, const QString &) const \o Value type. +\row \o bool QDomNode::isText() const \o Value type. +\row \o QDomNode QDomNode::lastChild() const \o Value type. +\row \o QString QDomNode::localName() const \o Value type. +\row \o QString QDomNode::namespaceURI() const \o Value type. +\row \o QDomNode QDomNode::nextSibling() const \o Value type. +\row \o QString QDomNode::nodeName() const \o Value type. +\row \o QDomNode::NodeType QDomNode::nodeType() const \o Value type. +\row \o QString QDomNode::nodeValue() const \o Value type. +\row \o void QDomNode::normalize() \o Value type. +\row \o QDomDocument QDomNode::ownerDocument() const \o Value type. +\row \o QDomNode QDomNode::parentNode() const \o Value type. +\row \o QString QDomNode::prefix() const \o Value type. +\row \o QDomNode QDomNode::previousSibling() const \o Value type. +\row \o QDomNode QDomNode::removeChild(const QDomNode &) \o Value type. +\row \o QDomNode QDomNode::replaceChild(const QDomNode &, const QDomNode &) \o Value type. +\row \o void QDomNode::setNodeValue(const QString &) \o Value type. +\row \o void QDomNode::setPrefix(const QString &) \o Value type. +\row \o QDomNode::~QDomNode() \o Value type. +\row \o QDomNode QDomNodeList::item(int) const \o Value type. +\row \o uint QDomNodeList::length() const \o Value type. +\row \o QDomNodeList::~QDomNodeList() \o Value type. +\row \o QString QDomProcessingInstruction::data() const \o Value type. +\row \o void QDomProcessingInstruction::setData(const QString &) \o Value type. +\row \o QString QDomProcessingInstruction::target() const \o Value type. +\row \o int QEventLoop::enterLoop() \o Port to the new QAbstractEventDispatcher API. +\row \o int QEventLoop::exec() \o Port to the new QAbstractEventDispatcher API. +\row \o void QEventLoop::exit(int) \o Port to the new QAbstractEventDispatcher API. +\row \o void QEventLoop::exitLoop() \o Port to the new QAbstractEventDispatcher API. +\row \o bool QEventLoop::hasPendingEvents() const \o Port to the new QAbstractEventDispatcher API. +\row \o int QEventLoop::loopLevel() const \o Port to the new QAbstractEventDispatcher API. +\row \o bool QEventLoop::processEvents(ProcessEventsFlags) \o Port to the new QAbstractEventDispatcher API. +\row \o void QEventLoop::registerSocketNotifier(QSocketNotifier *) \o Port to the new QAbstractEventDispatcher API. +\row \o void QEventLoop::unregisterSocketNotifier(QSocketNotifier *) \o Port to the new QAbstractEventDispatcher API. +\row \o void QEventLoop::wakeUp() \o Port to the new QAbstractEventDispatcher API. +\row \o void QFrame::drawContents(QPainter *) \o Use Q3Frame or reimplement QFrame::paintEvent() instead. +\row \o void QFrame::drawFrame(QPainter *) \o Use Q3Frame or reimplement QFrame::paintEvent() instead. +\row \o void QFrame::frameChanged() \o Use Q3Frame or reimplement QFrame::resizeEvent() instead. +\row \o void QFrame::setFrameRect(const QRect &) \o Setter. +\row \o void QFrame::setFrameStyle(int) \o Setter. +\row \o void QFrame::setLineWidth(int) \o Setter. +\row \o void QFrame::setMargin(int) \o Setter. +\row \o void QFrame::setMidLineWidth(int) \o Setter. +\row \o void QGridLayout::setColStretch(int, int) \o Setter. +\row \o void QGridLayout::setRowStretch(int, int) \o Setter. +\row \o void QGroupBox::setAlignment(int) \o Setter. +\row \o void QGroupBox::setColumnLayout(int, Orientation) \o Setter. +\row \o void QGroupBox::setTitle(const QString &) \o Setter. +\row \o QHostAddress::~QHostAddress() \o Value type. +\row \o int QIODevice::getch() \o Port to the new QIODevice API. +\row \o int QIODevice::putch(int) \o Port to the new QIODevice API. +\row \o QByteArray QIODevice::readAll() \o Port to the new QIODevice API. +\row \o Q_LONG QIODevice::readLine(char *, Q_ULONG) \o Port to the new QIODevice API. +\row \o int QIODevice::ungetch(int) \o Port to the new QIODevice API. +\row \o void QIcon::setPixmap(const QString &, Size, Mode, State) \o Value type. +\row \o void QIcon::setPixmap(const QPixmap &, Size, Mode, State) \o Value type. +\row \o QIcon::~QIcon() \o Value type. +\row \o void QLabel::setAlignment(int) \o Setter. +\row \o void QLabel::setAutoResize(bool) \o Setter. +\row \o void QLabel::setBuddy(QWidget *) \o Setter. +\row \o void QLabel::setMovie(const QMovie &) \o Setter. +\row \o void QLabel::setNum(int) \o Setter. +\row \o void QLabel::setNum(double) \o Setter. +\row \o void QLabel::setPicture(const QPicture &) \o Setter. +\row \o void QLabel::setPixmap(const QPixmap &) \o Setter. +\row \o void QLabel::setText(const QString &) \o Setter. +\row \o QLayoutIterator QLayout::iterator() \o Port to the new QLayout API. +\row \o void QLayout::setAutoAdd(bool) \o Setter. +\row \o void QLayout::setMargin(int) \o Setter. +\row \o void QLayout::setMenuBar(QMenuBar *) \o Setter. +\row \o void QLayout::setSpacing(int) \o Setter. +\row \o QLayoutIterator QLayoutItem::iterator() \o Port to the new QLayoutItem API. +\row \o void QLayoutItem::setAlignment(int) \o Setter. +\row \o bool QLibrary::unload() \o Never used polymorphically in Qt. +\row \o void QLineEdit::clear() \o Connect to QLineEdit::textChanged() instead. +\row \o void QLineEdit::clearValidator() \o Never used polymorphically in Qt. +\row \o void QLineEdit::copy() const \o Never used polymorphically in Qt. +\row \o void QLineEdit::cut() \o Never used polymorphically in Qt. +\row \o void QLineEdit::deselect() \o Connect to QLineEdit::selectionChanged() instead. +\row \o void QLineEdit::insert(const QString &) \o Connect to QLineEdit::textChanged() instead. +\row \o void QLineEdit::paste() \o Connect to QLineEdit::textChanged() instead. +\row \o void QLineEdit::redo() \o Never used polymorphically in Qt. +\row \o void QLineEdit::selectAll() \o Connect to QLineEdit::selectionChanged() instead. +\row \o void QLineEdit::setAlignment(int) \o Setter. +\row \o void QLineEdit::setCursorPosition(int) \o Connect to QLineEdit::cursorPositionChanged() instead. +\row \o void QLineEdit::setDragEnabled(bool) \o Setter. +\row \o void QLineEdit::setEchoMode(EchoMode) \o Setter. +\row \o void QLineEdit::setFrame(bool) \o Setter. +\row \o void QLineEdit::setMaxLength(int) \o Setter. +\row \o void QLineEdit::setReadOnly(bool) \o Setter. +\row \o void QLineEdit::setSelection(int, int) \o Connect to QLineEdit::selectionChanged() instead. +\row \o void QLineEdit::setText(const QString &) \o Connect to QLineEdit::textChanged() instead. +\row \o void QLineEdit::setValidator(const QValidator *) \o Setter. +\row \o void QLineEdit::undo() \o Never used in a polymorphic way by Qt. +\row \o void QMainWindow::addDockWindow(QDockWindow *, Dock, bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::addDockWindow(QDockWindow *, const QString &, Dock, bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::customize() \o Port to the new QMainWindow API. +\row \o bool QMainWindow::isCustomizable() const \o Port to the new QMainWindow API. +\row \o void QMainWindow::moveDockWindow(QDockWindow *, Dock) \o Port to the new QMainWindow API. +\row \o void QMainWindow::moveDockWindow(QDockWindow *, Dock, bool, int, int) \o Port to the new QMainWindow API. +\row \o void QMainWindow::removeDockWindow(QDockWindow *) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setAppropriate(QDockWindow *, bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setCentralWidget(QWidget *) \o Setter. +\row \o void QMainWindow::setDockEnabled(QDockWindow *, Dock, bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setDockEnabled(Dock, bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setDockMenuEnabled(bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setDockWindowsMovable(bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setOpaqueMoving(bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setRightJustification(bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setUpLayout() \o Port to the new QMainWindow API. +\row \o void QMainWindow::setUsesBigPixmaps(bool) \o Port to the new QMainWindow API. +\row \o void QMainWindow::setUsesTextLabel(bool) \o Port to the new QMainWindow API. +\row \o bool QMainWindow::showDockMenu(const QPoint &) \o Port to the new QMainWindow API. +\row \o void QMenuBar::activateItemAt(int) \o Port to the new QMenuBar API. +\row \o void QMenuBar::menuContentsChanged() \o Port to the new QMenuBar API. +\row \o void QMenuBar::menuDelPopup(QPopupMenu *) \o Port to the new QMenuBar API. +\row \o void QMenuBar::menuInsPopup(QPopupMenu *) \o Port to the new QMenuBar API. +\row \o void QMenuBar::menuStateChanged() \o Port to the new QMenuBar API. +\row \o void QMenuBar::setId(int, int) \o Port to the new QMenuBar API. +\row \o void QMenuBar::setSeparator(Separator) \o Port to the new QMenuBar API. +\row \o void QMenuBar::updateItem(int) \o Port to the new QMenuBar API. +\row \o QMutex::~QMutex() \o Value type. +\row \o bool QObject::checkConnectArgs(const char *, const QObject *, const char *) \o Reimplementing this function is no longer possible. +\row \o const char * QObject::className() const \o Reimplementing this function is no longer supported. +\row \o void QObject::insertChild(QObject *) \o Reimplement QObject::childEvent() instead and handle QEvent::ChildAdded events. +\row \o QVariant QObject::property(const char *) const \o Reimplementing this function is no longer supported. +\row \o void QObject::removeChild(QObject *) \o Reimplement QObject::childEvent() instead and handle QEvent::ChildRemoved events. +\row \o void QObject::setName(const char *) \o Setter. +\row \o bool QObject::setProperty(const char *, const QVariant &) \o Setter. +\row \o bool QPaintDevice::cmd(int , QPainter * , QPDevCmdParam *) \o Port to the new QPaintEngine API. +\row \o Qt::HANDLE QPaintDevice::handle() const \o Port to the new QPaintDevice API. +\row \o HDC QPaintDevice::handle() const \o Port to the new QPaintDevice API. +\row \o void QPopupMenu::activateItemAt(int) \o Port to the new QMenu API. +\row \o void QPopupMenu::menuContentsChanged() \o Port to the new QMenu API. +\row \o void QPopupMenu::menuDelPopup(QPopupMenu *) \o Port to the new QMenu API. +\row \o void QPopupMenu::menuInsPopup(QPopupMenu *) \o Port to the new QMenu API. +\row \o void QPopupMenu::menuStateChanged() \o Port to the new QMenu API. +\row \o void QPopupMenu::setActiveItem(int) \o Port to the new QMenu API. +\row \o void QPopupMenu::setCheckable(bool) \o Port to the new QMenu API. +\row \o void QPopupMenu::setId(int, int) \o Port to the new QMenu API. +\row \o void QPopupMenu::updateItem(int) \o Port to the new QMenu API. +\row \o int QPrinter::resolution() const \o Call QPrinter::setResolution() to change the resolution. +\row \o void QPrinter::setColorMode(ColorMode) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setCreator(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setDocName(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setFromTo(int, int) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setFullPage(bool) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setMinMax(int, int) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setNumCopies(int) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setOrientation(Orientation) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setOutputFileName(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setOutputToFile(bool) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPageOrder(PageOrder) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPageSize(PageSize) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPaperSource(PaperSource) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPrintProgram(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPrinterName(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setPrinterSelectionOption(const QString &) \o Subclass QPrintEngine instead. +\row \o void QPrinter::setResolution(int) \o Subclass QPrintEngine instead. +\row \o void QProcess::addArgument(const QString &) \o Not used polymorphically in Qt. +\row \o void QProcess::closeStdin() \o Not used polymorphically in Qt. +\row \o bool QProcess::launch(const QByteArray & buf, QStringList *) \o Not used polymorphically in Qt. +\row \o bool QProcess::launch(const QString & buf, QStringList *) \o Not used polymorphically in Qt. +\row \o QString QProcess::readLineStderr() \o Not used polymorphically in Qt. +\row \o QString QProcess::readLineStdout() \o Not used polymorphically in Qt. +\row \o QByteArray QProcess::readStderr() \o Not used polymorphically in Qt. +\row \o QByteArray QProcess::readStdout() \o Not used polymorphically in Qt. +\row \o void QProcess::setArguments(const QStringList &) \o Not used polymorphically in Qt. +\row \o void QProcess::setWorkingDirectory(const QDir &) \o Not used polymorphically in Qt. +\row \o bool QProcess::start(QStringList *) \o Not used polymorphically in Qt. +\row \o void QProcess::writeToStdin(const QByteArray &) \o Not used polymorphically in Qt. +\row \o bool QProgressBar::setIndicator(QString &, int, int) \o Not used polymorphically in Qt. +\row \o void QProgressBar::setProgress(int) \o Not used polymorphically in Qt. +\row \o void QProgressBar::setTotalSteps(int) \o Not used polymorphically in Qt. +\row \o void QPushButton::setAutoDefault(bool) \o Not used polymorphically in Qt. +\row \o void QPushButton::setDefault(bool) \o Not used polymorphically in Qt. +\row \o void QPushButton::setIsMenuButton(bool) \o Not used polymorphically in Qt. +\row \o void QPushButton::setOn(bool) \o Connect to QPushButton::toggled(bool) instead. +\row \o void QRadioButton::setChecked(bool) \o Connect to QRadioButton::toggled(bool) instead. +\row \o uchar * QScreen::cache(int , int) \o Port to the new QScreen API. +\row \o void QScreen::set(unsigned int , unsigned int , unsigned int , unsigned) \o Port to the new QScreen API. +\row \o void QScreen::uncache(uchar *) \o Port to the new QScreen API. +\row \o void QScrollBar::setOrientation(Orientation) \o Setter. +\row \o void QScrollBar::setTracking(bool) \o Setter. +\row \o void QSignalMapper::setMapping(const QObject *, const QString &) \o Setter. +\row \o void QSignalMapper::setMapping(const QObject *, int) \o Setter. +\row \o void QSlider::rangeChange() \o Reimplement QSlider::sliderChange() instead. +\row \o void QSlider::setOrientation(Orientation) \o Setter. +\row \o void QSlider::setPalette(const QPalette &) \o Setter. +\row \o void QSlider::setTickInterval(int) \o Setter. +\row \o void QSlider::setTickmarks(TickSetting) \o Setter. +\row \o void QSlider::setTracking(bool) \o Setter. +\row \o void QSlider::setValue(int) \o Reimplement QSlider::sliderChange() instead. +\row \o void QSlider::valueChange() \o Reimplement QSlider::sliderChange() instead. +\row \o QString QSpinBox::cleanText() const \o Port to the new QSpinBox API. +\row \o void QSpinBox::interpretText() \o Port to the new QSpinBox API. +\row \o QString QSpinBox::prefix() const \o Port to the new QSpinBox API. +\row \o void QSpinBox::rangeChange() \o Reimplement QSpinBox::sliderChange() instead. +\row \o void QSpinBox::selectAll() \o Port to the new QSpinBox API. +\row \o void QSpinBox::setButtonSymbols(ButtonSymbols) \o Setter. +\row \o void QSpinBox::setPrefix(const QString &) \o Setter. +\row \o void QSpinBox::setSpecialValueText(const QString &) \o Setter. +\row \o void QSpinBox::setSuffix(const QString &) \o Setter. +\row \o void QSpinBox::setValidator(const QValidator *) \o Setter. +\row \o void QSpinBox::setValue(int) \o Connect to QSpinBox::valueChanged(). +\row \o void QSpinBox::setWrapping(bool) \o Setter. +\row \o void QSpinBox::stepDown() \o Reimplement QSpinBox::stepBy() instead. +\row \o void QSpinBox::stepUp() \o Reimplement QSpinBox::stepBy() instead. +\row \o QString QSpinBox::suffix() const \o Port to the new QSpinBox API. +\row \o void QSpinBox::updateDisplay() \o Port to the new QSpinBox API. +\row \o void QSpinBox::valueChange() \o Reimplement QSpinBox::sliderChange() instead. +\row \o void QSplitter::drawSplitter(QPainter *, QCOORD, QCOORD, QCOORD, QCOORD) \o Reimplement QStyle::drawPrimitive() instead and handle QStyle::PE_Splitter. +\row \o void QSplitter::setOpaqueResize(bool) \o Setter. +\row \o void QSplitter::setOrientation(Orientation) \o Setter. +\row \o void QSplitter::setResizeMode(QWidget *, ResizeMode) \o Setter. +\row \o void QSqlDatabase::setDatabaseName(const QString &) \o Setter. +\row \o void QSqlDatabase::setHostName(const QString &) \o Setter. +\row \o void QSqlDatabase::setPassword(const QString &) \o Setter. +\row \o void QSqlDatabase::setPort(int) \o Setter. +\row \o void QSqlDatabase::setUserName(const QString &) \o Setter. +\row \o QSqlQuery QSqlDriver::createQuery() const \o Port to the new QSqlDriver API. +\row \o QString QSqlDriver::nullText() const \o Port to the new QSqlDriver API. +\row \o QSqlRecord QSqlDriver::record(const QSqlQuery &) const \o Port to the new QSqlDriver API. +\row \o QSqlRecordInfo QSqlDriver::recordInfo(const QSqlQuery &) const \o Port to the new QSqlDriver API. +\row \o QSqlRecordInfo QSqlDriver::recordInfo(const QString &) const \o Port to the new QSqlDriver API. +\row \o void QSqlError::setDatabaseText(const QString &) \o Value type. +\row \o void QSqlError::setDriverText(const QString &) \o Value type. +\row \o void QSqlError::setNumber(int) \o Value type. +\row \o void QSqlError::setType(int) \o Value type. +\row \o QSqlError::~QSqlError() \o Value type. +\row \o void QSqlField::setName(const QString &) \o Value type. +\row \o void QSqlField::setNull() \o Value type. +\row \o void QSqlField::setReadOnly(bool) \o Value type. +\row \o void QSqlField::setValue(const QVariant &) \o Value type. +\row \o QVariant QSqlField::value() const \o Value type. +\row \o QSqlField::~QSqlField() \o Value type. +\row \o void QSqlFieldInfo::setCalculated(bool) \o Value type. +\row \o void QSqlFieldInfo::setGenerated(bool) \o Value type. +\row \o void QSqlFieldInfo::setTrim(bool) \o Value type. +\row \o QSqlFieldInfo::~QSqlFieldInfo() \o Value type. +\row \o void QSqlIndex::append(const QSqlField &) \o Value type. +\row \o void QSqlIndex::append(const QSqlField &, bool) \o Value type. +\row \o void QSqlIndex::setCursorName(const QString &) \o Value type. +\row \o void QSqlIndex::setDescending(int, bool) \o Value type. +\row \o void QSqlIndex::setName(const QString &) \o Value type. +\row \o QVariant QSqlQuery::value(int) const \o Exists as a non-virtual function. +\row \o void QSqlRecord::append(const QSqlField &) \o Value type. +\row \o void QSqlRecord::clear() \o Value type. +\row \o void QSqlRecord::clearValues(bool) \o Value type. +\row \o void QSqlRecord::insert(int, const QSqlField &) \o Value type. +\row \o void QSqlRecord::remove(int) \o Value type. +\row \o void QSqlRecord::setGenerated(const QString &, bool) \o Value type. +\row \o void QSqlRecord::setGenerated(int, bool) \o Value type. +\row \o void QSqlRecord::setNull(int) \o Value type. +\row \o void QSqlRecord::setNull(const QString &) \o Value type. +\row \o void QSqlRecord::setValue(const QString &, const QVariant &) \o Value type. +\row \o void QSqlRecord::setValue(int, const QVariant &) \o Value type. +\row \o QString QSqlRecord::toString(const QString &, const QString &) const \o Value type. +\row \o QStringList QSqlRecord::toStringList(const QString &) const \o Value type. +\row \o QVariant QSqlRecord::value(int) const \o Value type. +\row \o QVariant QSqlRecord::value(const QString &) const \o Value type. +\row \o QSqlRecord::~QSqlRecord() \o Value type. +\row \o void QStyle::polishPopupMenu(QPopupMenu *) \o Reimplement QStyle::polish(QWidget *) instead. +\row \o int QTabBar::addTab(QTab *) \o Reimplement QTabBar::tabInserted() instead. +\row \o int QTabBar::insertTab(QTab *, int) \o Reimplement QTabBar::tabInserted() instead. +\row \o void QTabBar::layoutTabs() \o Reimplement QTabBar::tabLayoutChange() instead. +\row \o void QTabBar::paint(QPainter *, QTab *, bool) const \o Reimplement QTabBar::paintEvent() instead. +\row \o void QTabBar::paintLabel(QPainter *, const QRect &, QTab *, bool) const \o Reimplement QTabBar::paintEvent() instead. +\row \o void QTabBar::removeTab(QTab *) \o Reimplement QTabBar::tabRemoved() instead. +\row \o QTab * QTabBar::selectTab(const QPoint &) const \o Reimplement QTabBar::mousePressEvent() instead. +\row \o void QTabBar::setCurrentTab(int) \o Connect to the QTabBar::currentChanged() signal. +\row \o void QTabBar::setCurrentTab(QTab *) \o Connect to the QTabBar::currentChanged() signal. +\row \o void QTabBar::setShape(Shape) \o Setter. +\row \o void QTabBar::setTabEnabled(int, bool) \o Setter. +\row \o void QTabWidget::addTab(QWidget *, const QString &) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::addTab(QWidget *, const QIcon &, const QString &) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::addTab(QWidget *, QTab *) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::insertTab(QWidget *, const QIcon &, const QString &, int) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::insertTab(QWidget *, const QString &, int) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::insertTab(QWidget *, QTab *, int) \o Reimplement QTabWidget::tabInserted() instead. +\row \o void QTabWidget::removePage(QWidget *) \o Reimplement QTabWidget::tabRemoved() instead. +\row \o void QTabWidget::showPage(QWidget *) \o Connect to QTabWidget::currentChanged() instead. +\row \o void QTextEdit::append(const QString &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::clear() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::clearParagraphBackground(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::copy() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o QPopupMenu * QTextEdit::createPopupMenu(const QPoint &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o QPopupMenu * QTextEdit::createPopupMenu() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::cut() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::del() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::doKeyboardAction(KeyboardAction) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::ensureCursorVisible() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o bool QTextEdit::find(const QString &, bool, bool, bool, int *, int *) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o bool QTextEdit::focusNextPrevChild(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o int QTextEdit::heightForWidth(int) const \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::insert(const QString &, bool, bool, bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::insertAt(const QString &, int, int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::insertParagraph(const QString &, int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::moveCursor(CursorAction, bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::paste() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::pasteSubType(const QCString &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::placeCursor(const QPoint &, QTextCursor *) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::redo() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::removeParagraph(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::removeSelectedText(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::removeSelection(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::scrollToAnchor(const QString &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::scrollToBottom() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::selectAll(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setAlignment(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setBold(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setColor(const QColor &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setCurrentFont(const QFont &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setCursorPosition(int, int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setFamily(const QString &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setItalic(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setLinkUnderline(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setMimeSourceFactory(QMimeSourceFactory *) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setModified(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setOverwriteMode(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setPaper(const QBrush &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setParagraphBackgroundColor(int, const QColor &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setPointSize(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setReadOnly(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setSelection(int, int, int, int, int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setSelectionAttributes(int, const QColor &, bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setStyleSheet(QStyleSheet *) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setTabStopWidth(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setText(const QString &, const QString &) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setTextFormat(TextFormat) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setUnderline(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setUndoDepth(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setUndoRedoEnabled(bool) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setVerticalAlignment(VerticalAlignment) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setWordWrap(WordWrap) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setWrapColumnOrWidth(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::setWrapPolicy(WrapPolicy) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::sync() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::undo() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::zoomIn() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::zoomIn(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::zoomOut(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::zoomOut() \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o void QTextEdit::zoomTo(int) \o Use Q3TextEdit or port to the new QTextEdit API. +\row \o QString QTimeEdit::sectionFormattedText(int) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setAutoAdvance(bool) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setHour(int) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setMaxValue(const QTime &) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setMinValue(const QTime &) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setMinute(int) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setRange(const QTime &, const QTime &) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setSecond(int) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setSeparator(const QString &) \o Port to the new QDateTimeEdit API. +\row \o void QTimeEdit::setTime(const QTime &) \o Port to the new QDateTimeEdit API. +\row \o void QToolBar::clear() \o Setter. +\row \o void QToolBar::setLabel(const QString &) \o Setter. +\row \o void QToolBar::setStretchableWidget(QWidget *) \o Setter. +\row \o void QToolButton::setIconSet(const QIcon &) \o Setter. +\row \o void QToolButton::setOn(bool) \o Connect to QToolButton::toggled(bool) instead. +\row \o void QToolButton::setTextLabel(const QString &, bool) \o Setter. +\row \o void QToolButton::setToggleButton(bool) \o Setter. +\row \o void QToolButton::setUsesBigPixmap(bool) \o Setter. +\row \o void QToolButton::setUsesTextLabel(bool) \o Setter. +\row \o void QToolTip::maybeTip(const QPoint &) \o Port to the new QToolTip API. +\row \o void QUrl::addPath(const QString &) \o Value type. +\row \o bool QUrl::cdUp() \o Value type. +\row \o bool QUrl::parse(const QString &) \o Value type. +\row \o void QUrl::reset() \o Value type. +\row \o void QUrl::setEncodedPathAndQuery(const QString &) \o Value type. +\row \o void QUrl::setFileName(const QString &) \o Value type. +\row \o void QUrl::setHost(const QString &) \o Value type. +\row \o void QUrl::setPassword(const QString &) \o Value type. +\row \o void QUrl::setPath(const QString &) \o Value type. +\row \o void QUrl::setPort(int) \o Value type. +\row \o void QUrl::setProtocol(const QString &) \o Value type. +\row \o void QUrl::setQuery(const QString &) \o Value type. +\row \o void QUrl::setRef(const QString &) \o Value type. +\row \o void QUrl::setUser(const QString &) \o Value type. +\row \o QString QUrl::toString(bool, bool) const \o Value type. +\row \o QUrl::~QUrl() \o Value type. +\row \o QWaitCondition::~QWaitCondition() \o Value type. +\row \o bool QWhatsThis::clicked(const QString &) \o Port to the new QWhatsThis API. +\row \o QString QWhatsThis::text(const QPoint &) \o Port to the new QWhatsThis API. +\row \o QWhatsThis::~QWhatsThis() \o Port to the new QWhatsThis API. +\row \o void QWidget::adjustSize() \o Reimplement QWidget::sizeHint() instead. +\row \o bool QWidget::close(bool) \o Reimplement QWidget::closeEvent(). +\row \o void QWidget::create(WId, bool, bool) \o Not supported in Qt 4. +\row \o bool QWidget::customWhatsThis() const \o Not supported in Qt 4. +\row \o void QWidget::destroy(bool, bool) \o Not supported in Qt 4. +\row \o void QWidget::enabledChange(bool) \o Reimplement QWidget::changeEvent() and handle QEvent::EnabledChange. +\row \o void QWidget::fontChange(const QFont &) \o Reimplement QWidget::changeEvent() and handle QEvent::FontChange. +\row \o void QWidget::imComposeEvent(QIMEvent *) \o Reimplement QWidget::inputMethodEvent() instead. +\row \o void QWidget::imEndEvent(QIMEvent *) \o Reimplement QWidget::inputMethodEvent() instead. +\row \o void QWidget::imStartEvent(QIMEvent *) \o Reimplement QWidget::inputMethodEvent() instead. +\row \o void QWidget::move(int, int) \o Setter. +\row \o void QWidget::paletteChange(const QPalette &) \o Reimplement QWidget::changeEvent() and handle QEvent::PaletteChange and/or QEvent::ApplicationPaletteChange. +\row \o void QWidget::polish() \o Reimplement event() and handle the QEvent::Polish event type. +\row \o void QWidget::reparent(QWidget *, WFlags, const QPoint &, bool) \o Reimplement QWidget::event() and handle QEvent::Reparent. +\row \o void QWidget::resize(int, int) \o Reimplement QWidget::resizeEvent() instead. +\row \o void QWidget::setAcceptDrops(bool) \o Setter. +\row \o void QWidget::setActiveWindow() \o Reimplement QWidget::changeEvent() and handle QEvent::ActivationChange. +\row \o void QWidget::setAutoMask(bool) \o Setter. +\row \o void QWidget::setBackgroundColor(const QColor &) \o Setter. +\row \o void QWidget::setBackgroundMode(BackgroundMode) \o Setter. +\row \o void QWidget::setBackgroundOrigin(BackgroundOrigin) \o Setter. +\row \o void QWidget::setBackgroundPixmap(const QPixmap &) \o Setter. +\row \o void QWidget::setCaption(const QString &) \o Reimplement QWidget::changeEvent() and handle QEvent::WindowTitleChange. +\row \o void QWidget::setCursor(const QCursor &) \o Setter. +\row \o void QWidget::setEnabled(bool) \o Reimplement QWidget::changeEvent() and handle QEvent::EnabledChange. +\row \o void QWidget::setEraseColor(const QColor &) \o Setter. +\row \o void QWidget::setErasePixmap(const QPixmap &) \o Setter. +\row \o void QWidget::setFocus() \o Reimplement QWidget::focusInEvent() or QWidget::focusOutEvent(). +\row \o void QWidget::setFocusPolicy(FocusPolicy) \o Setter. +\row \o void QWidget::setFocusProxy(QWidget *) \o Setter. +\row \o void QWidget::setFont(const QFont &) \o Reimplement QWidget::changeEvent() and handle QEvent::FontChange and/or QEvent::ApplicationFontChange. +\row \o void QWidget::setGeometry(int, int, int, int) \o Setter. +\row \o void QWidget::setGeometry(const QRect &) \o Setter. +\row \o void QWidget::setIcon(const QPixmap &) \o Reimplement QWidget::changeEvent() and handle QEvent::WindowIconChange. +\row \o void QWidget::setIconText(const QString &) \o Reimplement QWidget::changeEvent() and handle QEvent::IconTextChange. +\row \o void QWidget::setKeyCompression(bool) \o Setter. +\row \o void QWidget::setMask(const QRegion &) \o Setter. +\row \o void QWidget::setMask(const QBitmap &) \o Setter. +\row \o void QWidget::setMaximumSize(int, int) \o Setter. +\row \o void QWidget::setMicroFocusHint(int, int, int, int, bool, QFont *) \o Setter. +\row \o void QWidget::setMinimumSize(int, int) \o Setter. +\row \o void QWidget::setMouseTracking(bool) \o Reimplement QWidget::changeEvent() and handle QEvent::MouseTrackingChange. +\row \o void QWidget::setPalette(const QPalette &) \o Reimplement QWidget::changeEvent() and handle QEvent::PaletteChange and/or QEvent::ApplicationPaletteChange. +\row \o void QWidget::setPaletteBackgroundColor(const QColor &) \o Setter. +\row \o void QWidget::setPaletteBackgroundPixmap(const QPixmap &) \o Setter. +\row \o void QWidget::setSizeIncrement(int, int) \o Setter. +\row \o void QWidget::setSizePolicy(QSizePolicy) \o Setter. +\row \o void QWidget::setUpdatesEnabled(bool) \o Setter. +\row \o void QWidget::setWFlags(WFlags) \o Setter. +\row \o void QWidget::show() \o Reimplement QWidget::showEvent(). +\row \o void QWidget::showMaximized() \o Reimplement QWidget::changeEvent() and handle QEvent::WindowStateChange. +\row \o void QWidget::showMinimized() \o Reimplement QWidget::changeEvent() and handle QEvent::WindowStateChange. +\row \o void QWidget::showNormal() \o Reimplement QWidget::changeEvent() and handle QEvent::WindowStateChange. +\row \o void QWidget::styleChange(QStyle &) \o Reimplement QWidget::changeEvent() and handle QEvent::StyleChange. +\row \o void QWidget::unsetCursor() \o Setter. +\row \o void QWidget::windowActivationChange(bool) \o Reimplement QWidget::changeEvent() and handle QEvent::ActivationChange. diff --git a/doc/src/porting4-renamedclasses.qdocinc b/doc/src/porting4-renamedclasses.qdocinc new file mode 100644 index 0000000..ef315a1 --- /dev/null +++ b/doc/src/porting4-renamedclasses.qdocinc @@ -0,0 +1,3 @@ +\row \o QIconSet \o QIcon +\row \o QWMatrix \o QMatrix +\row \o QGuardedPtr \o QPointer diff --git a/doc/src/porting4-renamedenumvalues.qdocinc b/doc/src/porting4-renamedenumvalues.qdocinc new file mode 100644 index 0000000..9519da1 --- /dev/null +++ b/doc/src/porting4-renamedenumvalues.qdocinc @@ -0,0 +1,234 @@ +\row \o IO_Append \o QIODevice::Append +\row \o IO_ReadOnly \o QIODevice::ReadOnly +\row \o IO_ReadWrite \o QIODevice::ReadWrite +\row \o IO_Translate \o QIODevice::Text +\row \o IO_Truncate \o QIODevice::Truncate +\row \o IO_WriteOnly \o QIODevice::WriteOnly +\row \o IO_Raw \o QIODevice::Unbuffered +\row \o QAccessible::Moveable \o QAccessible::Movable +\row \o QApplication::CustomColors \o QApplication::CustomColor +\row \o QApplication::NormalColors \o QApplication::NormalColor +\row \o QButton::NoChange \o QCheckBox::NoChange +\row \o QButton::Off \o QCheckBox::Off +\row \o QButton::On \o QCheckBox::On +\row \o QChar::Single \o QChar::NoDecomposition +\row \o QChar::byteOrderMark \o QChar::ByteOrderMark +\row \o QChar::byteOrderSwapped \o QChar::ByteOrderSwapped +\row \o QChar::nbsp \o QChar::Nbsp +\row \o QChar::null \o QChar::Null +\row \o QChar::replacement \o QChar::ReplacementCharacter +\row \o QComboBox::AfterCurrent \o QComboBox::InsertAfterCurrent +\row \o QComboBox::AtBottom \o QComboBox::InsertAtBottom +\row \o QComboBox::AtCurrent \o QComboBox::InsertAtCurrent +\row \o QComboBox::AtTop \o QComboBox::InsertAtTop +\row \o QComboBox::BeforeCurrent \o QComboBox::InsertBeforeCurrent +\row \o QComboBox::NoInsertion \o QComboBox::NoInsert +\row \o QDir::DefaultFilter \o QDir::NoFilter +\row \o QDir::DefaultSort \o QDir::NoSort +\row \o QEvent::Accel \o QEvent::Shortcut +\row \o QEvent::AccelOverride \o QEvent::ShortcutOverride +\row \o QEvent::CaptionChange \o QEvent::WindowTitleChange +\row \o QEvent::ChildInserted \o QEvent::ChildAdded +\row \o QEvent::IMCompose \o QEvent::InputMethodCompose +\row \o QEvent::IMEnd \o QEvent::InputMethodEnd +\row \o QEvent::IMStart \o QEvent::InputMethodStart +\row \o QEvent::IconChange \o QEvent::WindowIconChange +\row \o QEvent::LayoutHint \o QEvent::LayoutRequest +\row \o QEvent::Reparent \o QEvent::ParentChange +\row \o QFileInfo::ExeGroup \o QFile::ExeGroup +\row \o QFileInfo::ExeOther \o QFile::ExeOther +\row \o QFileInfo::ExeOwner \o QFile::ExeOwner +\row \o QFileInfo::ExeUser \o QFile::ExeUser +\row \o QFileInfo::ReadGroup \o QFile::ReadGroup +\row \o QFileInfo::ReadOther \o QFile::ReadOther +\row \o QFileInfo::ReadOwner \o QFile::ReadOwner +\row \o QFileInfo::ReadUser \o QFile::ReadUser +\row \o QFileInfo::WriteGroup \o QFile::WriteGroup +\row \o QFileInfo::WriteOther \o QFile::WriteOther +\row \o QFileInfo::WriteOwner \o QFile::WriteOwner +\row \o QFileInfo::WriteUser \o QFile::WriteUser +\row \o QFrame::GroupBoxPanel \o QFrame::StyledPanel +\row \o QFrame::LineEditPanel \o QFrame::StyledPanel +\row \o QFrame::MenuBarPanel \o QFrame::StyledPanel +\row \o QFrame::PopupPanel \o QFrame::StyledPanel +\row \o QFrame::TabWidgetPanel \o QFrame::StyledPanel +\row \o QFrame::ToolBarPanel \o QFrame::StyledPanel +\row \o QImage::ScaleFree \o Qt::IgnoreAspectRatio +\row \o QImage::ScaleMax \o Qt::KeepAspectRatioByExpanding +\row \o QImage::ScaleMin \o Qt::KeepAspectRatio +\row \o Qt::Identical \o QKeySequence::ExactMatch +\row \o Qt::NoMatch \o QKeySequence::NoMatch +\row \o Qt::PartialMatch \o QKeySequence::PartialMatch +\row \o QLayout::Auto \o QLayout::SetDefaultConstraint +\row \o QLayout::Fixed \o QLayout::SetFixedSize +\row \o QLayout::FreeResize \o QLayout::SetNoConstraint +\row \o QLayout::Minimum \o QLayout::SetMinimumSize +\row \o QMacStyle::SizeNone \o QMacStyle::SizeDefault +\row \o QSettings::Global \o QSettings::SystemScope +\row \o QSettings::User \o QSettings::UserScope +\row \o QSize::ScaleFree \o Qt::IgnoreAspectRatio +\row \o QSize::ScaleMax \o Qt::KeepAspectRatioByExpanding +\row \o QSize::ScaleMin \o Qt::KeepAspectRatio +\row \o QSizePolicy::Horizontal \o QSizePolicy::Horizontally +\row \o QSizePolicy::Vertical \o QSizePolicy::Vertically +\row \o QSlider::Above \o QSlider::TicksAbove +\row \o QSlider::Below \o QSlider::TicksBelow +\row \o QSlider::Both \o QSlider::TicksBothSides +\row \o QSlider::Left \o QSlider::TicksLeft +\row \o QSlider::NoMarks \o QSlider::NoTicks +\row \o QSlider::Right \o QSlider::TicksRight +\row \o QSocket::Closing \o Q3Socket::Closing +\row \o QSocket::Connected \o Q3Socket::Connected +\row \o QSocket::Connecting \o Q3Socket::Connecting +\row \o QSocket::Connection \o Q3Socket::Connection +\row \o QSocket::ErrConnectionRefused \o Q3Socket::ErrConnectionRefused +\row \o QSocket::ErrHostNotFound \o Q3Socket::ErrHostNotFound +\row \o QSocket::ErrSocketRead \o Q3Socket::ErrSocketRead +\row \o QSocket::HostLookup \o QAbstractSocket::HostLookupState +\row \o QSocket::Idle \o QAbstractSocket::UnconnectedState +\row \o QSqlError::Connection \o QSqlError::ConnectionError +\row \o QSqlError::None \o QSqlError::NoError +\row \o QSqlError::Statement \o QSqlError::StatementError +\row \o QSqlError::Transaction \o QSqlError::TransactionError +\row \o QSqlError::Unknown \o QSqlError::UnknownError +\row \o QStyle::CC_ListView \o QStyle::CC_Q3ListView +\row \o QStyle::SH_UnderlineAccelerator \o QStyle::SH_UnderlineShortcut +\row \o QStyle::Style_Active \o QStyle::State_Active +\row \o QStyle::Style_AutoRaise \o QStyle::State_AutoRaise +\row \o QStyle::Style_Bottom \o QStyle::State_Bottom +\row \o QStyle::Style_Children \o QStyle::State_Children +\row \o QStyle::Style_Default \o QStyle::State_None +\row \o QStyle::Style_Down \o QStyle::State_DownArrow +\row \o QStyle::Style_Editing \o QStyle::State_Editing +\row \o QStyle::Style_Enabled \o QStyle::State_Enabled +\row \o QStyle::Style_FocusAtBorder \o QStyle::State_FocusAtBorder +\row \o QStyle::Style_HasFocus \o QStyle::State_HasFocus +\row \o QStyle::Style_Horizontal \o QStyle::State_Horizontal +\row \o QStyle::Style_Item \o QStyle::State_Item +\row \o QStyle::Style_MouseOver \o QStyle::State_MouseOver +\row \o QStyle::Style_NoChange \o QStyle::State_NoChange +\row \o QStyle::Style_None \o QStyle::State_None +\row \o QStyle::Style_Off \o QStyle::State_Off +\row \o QStyle::Style_On \o QStyle::State_On +\row \o QStyle::Style_Open \o QStyle::State_Open +\row \o QStyle::Style_Raised \o QStyle::State_Raised +\row \o QStyle::Style_Rectangle \o QStyle::State_Rectangle +\row \o QStyle::Style_Selected \o QStyle::State_Selected +\row \o QStyle::Style_Sibling \o QStyle::State_Sibling +\row \o QStyle::Style_Sunken \o QStyle::State_Sunken +\row \o QStyle::Style_Top \o QStyle::State_Top +\row \o QStyle::Style_Up \o QStyle::State_Up +\row \o QTabBar::RoundedAbove \o QTabBar::RoundedNorth +\row \o QTabBar::RoundedBelow \o QTabBar:: RoundedSouth +\row \o QTabBar::TriangularAbove \o QTabBar:: TriangularNorth +\row \o QTabBar::TriangularBelow \o QTabBar:: TriangularSouth +\row \o QTextEdit::MovePgDown \o QTextEdit::MovePageDown +\row \o QTextEdit::MovePgUp \o QTextEdit::MovePageUp +\row \o QToolButton::Right \o QToolButton::BesideIcon +\row \o QToolButton::Under \o QToolButton::BelowIcon +\row \o QValidator::Valid \o QValidator::Intermediate +\row \o QVariant::IconSet \o QCoreVariant::Icon +\row \o QWidget::ClickFocus \o Qt::ClickFocus +\row \o QWidget::NoFocus \o Qt::NoFocus +\row \o QWidget::StrongFocus \o Qt::StrongFocus +\row \o QWidget::TabFocus \o Qt::TabFocus +\row \o QWidget::WheelFocus \o Qt::WheelFocus +\row \o Qt::AlignAuto \o Qt::AlignLeft +\row \o Qt::AltButton \o Qt::AltModifier +\row \o Qt::Ascending \o Qt::AscendingOrder +\row \o Qt::Bottom \o Qt::DockBottom +\row \o Qt::BottomLeft \o Qt::BottomLeftCorner +\row \o Qt::BottomRight \o Qt::BottomRightCorner +\row \o Qt::BreakAnywhere \o Qt::TextWrapAnywhere +\row \o Qt::ControlButton \o Qt::ControlModifier +\row \o Qt::CustomPattern \o Qt::TexturePattern +\row \o Qt::Descending \o Qt::DescendingOrder +\row \o Qt::DontClip \o Qt::TextDontClip +\row \o Qt::DontPrint \o Qt::TextDontPrint +\row \o Qt::ExpandTabs \o Qt::TextExpandTabs +\row \o Qt::IncludeTrailingSpaces \o Qt::TextIncludeTrailingSpaces +\row \o Qt::KeyButtonMask \o Qt::KeyboardModifierMask +\row \o Qt::Key_BackSpace \o Qt::Key_Backspace +\row \o Qt::Key_BackTab \o Qt::Key_Backtab +\row \o Qt::Key_MediaPrev \o Qt::Key_MediaPrevious +\row \o Qt::Key_Next \o Qt::Key_PageDown +\row \o Qt::Key_Prior \o Qt::Key_PageUp +\row \o Qt::Key_aacute \o Qt::Key_Aacute +\row \o Qt::Key_acircumflex \o Qt::Key_Acircumflex +\row \o Qt::Key_adiaeresis \o Qt::Key_Adiaeresis +\row \o Qt::Key_ae \o Qt::Key_AE +\row \o Qt::Key_agrave \o Qt::Key_Agrave +\row \o Qt::Key_aring \o Qt::Key_Aring +\row \o Qt::Key_atilde \o Qt::Key_Atilde +\row \o Qt::Key_ccedilla \o Qt::Key_Ccedilla +\row \o Qt::Key_eacute \o Qt::Key_Eacute +\row \o Qt::Key_ecircumflex \o Qt::Key_Ecircumflex +\row \o Qt::Key_ediaeresis \o Qt::Key_Ediaeresis +\row \o Qt::Key_egrave \o Qt::Key_Egrave +\row \o Qt::Key_eth \o Qt::Key_ETH +\row \o Qt::Key_iacute \o Qt::Key_Iacute +\row \o Qt::Key_icircumflex \o Qt::Key_Icircumflex +\row \o Qt::Key_idiaeresis \o Qt::Key_Idiaeresis +\row \o Qt::Key_igrave \o Qt::Key_Igrave +\row \o Qt::Key_ntilde \o Qt::Key_Ntilde +\row \o Qt::Key_oacute \o Qt::Key_Oacute +\row \o Qt::Key_ocircumflex \o Qt::Key_Ocircumflex +\row \o Qt::Key_odiaeresis \o Qt::Key_Odiaeresis +\row \o Qt::Key_ograve \o Qt::Key_Ograve +\row \o Qt::Key_oslash \o Qt::Key_Ooblique +\row \o Qt::Key_otilde \o Qt::Key_Otilde +\row \o Qt::Key_thorn \o Qt::Key_THORN +\row \o Qt::Key_uacute \o Qt::Key_Uacute +\row \o Qt::Key_ucircumflex \o Qt::Key_Ucircumflex +\row \o Qt::Key_udiaeresis \o Qt::Key_Udiaeresis +\row \o Qt::Key_ugrave \o Qt::Key_Ugrave +\row \o Qt::Key_yacute \o Qt::Key_Yacute +\row \o Qt::Keypad \o Qt::KeypadModifier +\row \o Qt::Left \o Qt::DockLeft +\row \o Qt::MV_10_DOT_0 \o QSysInfo::MV_10_0 +\row \o Qt::MV_10_DOT_1 \o QSysInfo::MV_10_1 +\row \o Qt::MV_10_DOT_2 \o QSysInfo::MV_10_2 +\row \o Qt::MV_10_DOT_3 \o QSysInfo::MV_10_3 +\row \o Qt::MV_10_DOT_4 \o QSysInfo::MV_10_4 +\row \o Qt::MV_9 \o QSysInfo::MV_9 +\row \o Qt::MV_CHEETAH \o QSysInfo::MV_10_0 +\row \o Qt::MV_JAGUAR \o QSysInfo::MV_10_2 +\row \o Qt::MV_PANTHER \o QSysInfo::MV_10_3 +\row \o Qt::MV_PUMA \o QSysInfo::MV_10_1 +\row \o Qt::MV_TIGER \o QSysInfo::MV_10_4 +\row \o Qt::MV_Unknown \o QSysInfo::MV_Unknown +\row \o Qt::MetaButton \o Qt::MetaModifier +\row \o Qt::Minimized \o Qt::DockMinimized +\row \o Qt::NoAccel \o Qt::TextHideMnemonic +\row \o Qt::Overline \o Qt::TextOverline +\row \o Qt::Right \o Qt::DockRight +\row \o Qt::ShiftButton \o Qt::ShiftModifier +\row \o Qt::ShowPrefix \o Qt::TextShowMnemonic +\row \o Qt::SingleLine \o Qt::TextSingleLine +\row \o Qt::StrikeOut \o Qt::TextStrikeOut +\row \o Qt::Top \o Qt::DockTop +\row \o Qt::TopLeft \o Qt::TopLeftCorner +\row \o Qt::TopRight \o Qt::TopRightCorner +\row \o Qt::TornOff \o Qt::DockTornOff +\row \o Qt::Underline \o Qt::TextUnderline +\row \o Qt::Unmanaged \o Qt::DockUnmanaged +\row \o Qt::WNorthWestGravity \o Qt::WStaticContents +\row \o Qt::WRepaintNoErase \o Qt::WNoAutoErase +\row \o Qt::WStyle_Dialog \o Qt::WType_Dialog +\row \o Qt::WStyle_NoBorderEx \o Qt::WStyle_NoBorder +\row \o Qt::WType_Modal \o (Qt::WType_Dialog | Qt::WShowModal) +\row \o Qt::WV_2000 \o QSysInfo::WV_2000 +\row \o Qt::WV_2003 \o QSysInfo::WV_2003 +\row \o Qt::WV_32s \o QSysInfo::WV_32s +\row \o Qt::WV_95 \o QSysInfo::WV_95 +\row \o Qt::WV_98 \o QSysInfo::WV_98 +\row \o Qt::WV_CE \o QSysInfo::WV_CE +\row \o Qt::WV_CENET \o QSysInfo::WV_CENET +\row \o Qt::WV_CE_based \o QSysInfo::WV_CE_based +\row \o Qt::WV_DOS_based \o QSysInfo::WV_DOS_based +\row \o Qt::WV_Me \o QSysInfo::WV_Me +\row \o Qt::WV_NT \o QSysInfo::WV_NT +\row \o Qt::WV_NT_based \o QSysInfo::WV_NT_based +\row \o Qt::WV_XP \o QSysInfo::WV_XP +\row \o Qt::WordBreak \o Qt::TextWordWrap +\row \o Qt::IbeamCursor \o Qt::IBeamCursor diff --git a/doc/src/porting4-renamedfunctions.qdocinc b/doc/src/porting4-renamedfunctions.qdocinc new file mode 100644 index 0000000..3e59a82 --- /dev/null +++ b/doc/src/porting4-renamedfunctions.qdocinc @@ -0,0 +1,6 @@ +\row \o QRegExp::search() \o QRegExp::indexIn() +\row \o QPixmap::convertFromImage \o QPixmap::fromImage() (static function) +\row \o QStyle::querySubControl() \o QStyle::hitTestComplexControl() +\row \o QStyle::querySubControlMetrics() \o QStyle::subControlRect() +\row \o QStyle::unPolish() \o QStyle::unpolish() +\row \o QThread::currentThread() \o QThread::currentThreadId() diff --git a/doc/src/porting4-renamedstatic.qdocinc b/doc/src/porting4-renamedstatic.qdocinc new file mode 100644 index 0000000..156ab73 --- /dev/null +++ b/doc/src/porting4-renamedstatic.qdocinc @@ -0,0 +1,3 @@ +\row \o QPixmap::fromMimeSource \o qPixmapFromMimeSource +\row \o QImage::inputFormats \o QImageReader::supportedImageFormats +\row \o QImage::outputFormats \o QImageWriter::supportedImageFormats diff --git a/doc/src/porting4-renamedtypes.qdocinc b/doc/src/porting4-renamedtypes.qdocinc new file mode 100644 index 0000000..fc8f604 --- /dev/null +++ b/doc/src/porting4-renamedtypes.qdocinc @@ -0,0 +1,26 @@ +\row \o QApplication::ColorMode \o QApplication::ColorSpec +\row \o QButton::ToggleState \o QCheckBox::ToggleState +\row \o QCursorShape \o Qt::CursorShape +\row \o QFile::FilterSpec \o QFile::Filters +\row \o QFile::PermissionSpec \o QFile::Permission +\row \o QFile::SortSpec \o QFile::SortFlags +\row \o QFile::Status \o QFile::Error +\row \o QFileInfo::PermissionSpec \o QFile::Permission +\row \o QGrid::Direction \o Qt::Orientation +\row \o QGridWidget::Direction \o Qt::Orientation +\row \o QIODevice::Offset \o qlonglong +\row \o QImage::ScaleMode \o Qt::AspectRatioMode +\row \o QSize::ScaleMode \o Qt::AspectRatioMode +\row \o QSocket::Error \o Q3Socket::Error +\row \o QSocket::State \o Q3Socket::State +\row \o QStyle::SCFlags \o QStyle::SubControls +\row \o QStyle::SFlags \o QStyle::State +\row \o QTS \o QTextStream +\row \o QUrlDrag \o QUriDrag +\row \o QWidget::FocusPolicy \o Qt::FocusPolicy +\row \o Q_LLONG \o qlonglong +\row \o Q_ULLONG \o qulonglong +\row \o Qt::Dock \o Qt::ToolBarDock +\row \o Qt::MacintoshVersion \o QSysInfo::MacVersion +\row \o Qt::TextFlags \o Qt::TextFlag +\row \o Qt::WindowsVersion \o QSysInfo::WinVersion diff --git a/doc/src/porting4.qdoc b/doc/src/porting4.qdoc new file mode 100644 index 0000000..c8a9e2b --- /dev/null +++ b/doc/src/porting4.qdoc @@ -0,0 +1,4215 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page porting4.html + \title Porting to Qt 4 + \contentspage {Porting Guides}{Contents} + \previouspage Porting Guides + \nextpage Porting to Qt 4 - Virtual Functions + \ingroup porting + \brief An overview of issues and techniques to consider when porting from Qt 3 to Qt 4. + +\omit + ### QFileInfo::PermissionSpec -> QFile::Permission(s?) + ### refer to porting4-renamedfunctions.qdoc + ### QApplication library mutex is gone + ### no integral conversion for containers? strings? + ### QVector etc. are initialized to 0 by default? + ### How to port from Qt 2.3 to Qt 4. + ### missing sort() functions? + ### QToolTipGroup + ### QServerSocket -> Q3ServerSocket + + ### remove these when the classes are re-ported + + ### QApplication::eventLoop() + + \row \o void QCheckListItem::paintCell(QPainter *, const QColorGroup &, int, int, int)\row \o void Q3CheckListItem::paintCell(QPainter *, const QPalette &, int, int, int) + \row \o void QCheckListItem::paintFocus(QPainter *, const QColorGroup &, const QRect &) \o void Q3CheckListItem::paintFocus(QPainter *, const QPalette &, const QRect &) + \row \o QDataTable: a whole bunch of virtual functions have a different signature + + < Function: void QIconViewItem::paintFocus(QPainter *, const QColorGroup &) + > Function: void QIconViewItem::paintFocus(QPainter *, const QPalette &) + + < Function: void QIconViewItem::paintItem(QPainter *, const QColorGroup &) + > Function: void QIconViewItem::paintItem(QPainter *, const QPalette &) + + < Function: bool QUrlOperator::checkValid() + + < Function: void QWSInputMethod::setFont(const QFont &) + + ### OpenMode or OpenMode + + ### QWSDecoration +\endomit + + This document describes the process of porting applications from + Qt 3 to Qt 4. + If you haven't yet made the decision about porting, or are unsure + about whether it is worth it, take a look at the \l{What's New in + Qt 4}{key features} offered by Qt 4. See also + \l{Moving from Qt 3 to Qt 4} for tips on how to write Qt 3 code + that is easy to port to Qt 4. + + \bold{Other porting guides:} + + \list + \o \l{Moving from Qt 3 to Qt 4} \mdash covers some high level topics relevant + to developers porting from Qt 3 to Qt 4. + \o \l{Porting to Qt 4 - Drag and Drop} \mdash covers differences in the + way drag and drop is handled between Qt 3 and Qt 4. + \o \l{Porting .ui Files to Qt 4} \mdash describes the new format used to + describe forms created with \QD. + \o \l{Porting to Graphics View} \mdash provides a class-by-class overview + of the differences between Qt 3's canvas API and Qt 4's Graphics + View framework. + \o \l{qt3to4 - The Qt 3 to 4 Porting Tool} \mdash provides an overview + of a tool aimed at helping developers start the process of porting an + application to Qt 4. + \endlist + + The Qt 4 series is not binary compatible with the 3 series. This + means programs compiled for Qt 3 must be recompiled to work with + Qt 4. Qt 4 is also not completely \e source compatible with 3, + however nearly all points of incompatibility cause compiler + errors or run-time messages (rather than mysterious results). Qt + 4 includes many additional features and discards obsolete + functionality. Porting from Qt 3 to Qt 4 requires some effort, + but once completed the considerable additional power and + flexibility of Qt 4 is available for use in your applications. + + To port code from Qt 3 to Qt 4: + + \list 1 + + \o Briefly read the porting notes below to get an idea of what to expect. + + \o Be sure that your code compiles and runs well on all your target + platforms with Qt 3. + + \o Add the line \c{QT += qt3support} to your \c .pro file if you use + \c qmake; otherwise, edit your makefile or project file to + link against the Qt3Support library and add \c -DQT3_SUPPORT to your + compiler flags. (You might also need to specify other + libraries. See \l{What's New in Qt 4} for details.) + + \o Run the \l qt3to4 porting tool. The tool will go through your + source code and adapt it to Qt 4. + + \o Follow the instructions in the \l{Porting .ui Files to Qt 4} + page to port Qt Designer files. + + \o Recompile with Qt 4. For each error, search below for related + identifiers (e.g., function names, class names). This document + mentions all relevant identifiers to help you get the information + you need at the cost of being a little verbose. + + \endlist + + The \l qt3to4 porting tool replaces occurrences of Qt 3 classes + that don't exist anymore in Qt 4 with the corresponding Qt 3 + support class; for example, \c QListBox is turned into \c + Q3ListBox. + + At some point, you might want to stop linking against the Qt 3 + support library (\l{Qt3Support}) and take advantage of Qt 4's + new features. The instructions below explain how to do that for + each compatibility class. + + In addition to the Qt3Support classes (such as \c Q3Action, \c + Q3ListBox, and \c Q3ValueList), Qt 4 provides compatibility + functions when it's possible for an old API to cohabit with the + new one. For example, QString provides a + QString::simplifyWhiteSpace() compatibility function that's + implemented inline and that simply calls QString::simplified(). + \bold{The compatibility functions are not documented here; instead, + they are documented for each class.} + + If you have the line \c{QT += qt3support} in your \c .pro file, \c + qmake will automatically define the \c QT3_SUPPORT symbol, turning + on compatibility function support. You can also define the symbol + manually (e.g., if you don't want to link against the \c + Qt3Support library), or you can define \c QT3_SUPPORT_WARNINGS + instead, telling the compiler to emit a warning when a + compatibility function is called. (This works only with GCC 3.2+ + and MSVC 7.) + + If you get stuck, ask on the + \l{http://lists.trolltech.com/qt-interest/}{qt-interest} + mailing list. If you are a licensed customer, you can also contact + Qt's technical support team. + +\omit + ### what to do with slots that aren't slots anymore + ### what to do with virtual functions that aren't virtual anymore + ### what to do with virtual functions that changed signature +\endomit + +\omit + ### -- stuff that vanished? + ### implicit sharing + ### uint -> int indexes +\endomit + + Table of contents: + + \tableofcontents{4} + +\omit + \section1 Header Files + + ### New style of headers + + \table + \header \o Old header \o New header + \row \o \c{} \o \c{} or \c{} + \endtable + + ### Some headers don't include each other anymore... +\endomit + + \section1 Casting and Object Types + + In Qt 3, it was possible to use the \c qt_cast() function to determine + whether instances of QObject subclasses could be safely cast to derived + types of those subclasses. For example, if a QFrame instance is passed + to a function whose signature specifies a QWidget pointer as its argument, + \c qt_cast() could be used to obtain a QFrame pointer so that the + instance's functions can be accessed. + + In Qt 4, much of this functionality is provided by the qobject_cast() + function, and additional functions also provide similar functionality for + certain non-QObject types: + + \table + \header \o Qt 3 function \o Qt 4 function + \row \o T *qt_cast(QObject *) \o \l{qobject_cast()}{T *qobject_cast(QObject *)} + \row \o \o \l{qgraphicsitem_cast()}{T qgraphicsitem_cast(QGraphicsItem *)} + \row \o \o \l{qstyleoption_cast()}{T qstyleoption_cast(QStyleOption *)} + \row \o \o \l{qvariant_cast()}{T qvariant_cast(const QVariant &)} + \row \o \o \l{qdbus_cast()}{T qdbus_cast(const QDBusArgument &)} + \endtable + +\omit + \section1 Global Functions + + \table + \header \o Qt 3 function \o Qt 4 function + \row \o cstrcmp() \o strcmp() + \row \o cstrcpy() \o strcpy() + \row \o cstrlen() \o strlen() + \row \o cstrncmp() \o strncmp() + \row \o qmemmove() \o memmove() + \endtable + + qGLVersion() ### + + copyBlt() ### + bitBlt() + + #ifdef compat classes: + * QLayoutIterator + * QColorGroup + * QMenuItem + + QWidget visibleRect property compat + QWidget::BackgroundOrigin compat +\endomit + + \section1 Type Names + + The table below lists the classes that have been renamed in Qt 4. + If you compile your applications with \c QT3_SUPPORT defined, the + old names will be available. + + Whenever you see an occurrence of the name on the left, you can + safely replace it with the Qt 4 equivalent in your program. The + \l qt3to4 tool performs the conversion automatically. + + \table + \header \o Qt 3 class name \o Qt 4 class name + \input porting4-renamedclasses.qdocinc + \endtable + + The table below lists the enums and typedefs that have been + renamed in Qt 4. If you compile your applications with \c + QT3_SUPPORT defined, the old names will be available. + + Whenever you see an occurrence of the name on the left, you can + safely replace it with the Qt 4 equivalent in your program. The + \l qt3to4 tool performs the conversion + automatically. + + \table + \header \o Qt 3 type name \o Qt 4 type name + \input porting4-renamedtypes.qdocinc + \endtable + + \omit + ### + \row \o QButton::ToggleState \o Use QCheckBox::ToggleState instead. + \endomit + + \section1 Enum Values + + The table below lists the enum values that have been renamed in + Qt 4. If you compile your applications with \c QT3_SUPPORT defined, + the old names will be available. + + Whenever you see an occurrence of the name on the left, you can + safely replace it with the Qt 4 equivalent in your program. The + \l qt3to4 tool performs the conversion automatically. + + \table + \header \o Qt 3 enum value name \o Qt 4 enum value name + \input porting4-renamedenumvalues.qdocinc + \endtable + + In addition, the following \l{Qt::WindowFlags}{window flags} have + been either replaced with \l{Qt::WidgetAttribute}{widget + attributes} or have been deprecated: + + \table + \header \o Qt 3 type \o Qt 4 equivalent + \row \o Qt::WDestructiveClose \o Use QWidget::setAttribute(Qt::WA_DeleteOnClose) instead. + \row \o Qt::WStaticContents \o{1,2} Use QWidget::setAttribute(Qt::WA_StaticContents) instead. + \row \o Qt::WNorthWestGravity + \row \o Qt::WNoAutoErase \o{1,3} Use QWidget::setAttribute(Qt::WA_NoBackground) instead. + \row \o Qt::WResizeNoErase + \row \o Qt::WRepaintNoErase + \row \o Qt::WPaintClever \o Unnecessary in Qt 4. + \omit ### Check with Matthias \endomit + \row \o Qt::WMacNoSheet \o Unnecessary in Qt 4. + \omit ### Check with Sam \endomit + \endtable + + In Qt 4.1, the widget flags used to determine window modality were + replaced by a single enum that can be used to specify the modal + behavior of top-level widgets: + + \table + \header \o Qt 3 type \o Qt 4 equivalent + \row \o Qt::WShowModal \o Use QWidget::setWindowModality(Qt::ApplicationModal) instead. + \row \o Qt::WGroupLeader \o Use QWidget::setWindowModality(Qt::WindowModal) + for each child dialog of the group leader, but do not change the modality + of the group leader itself. + \endtable + + \target properties + \section1 Properties + + Some properties have been renamed in Qt 4, to make Qt's API more + consistent and more intuitive. For example, QWidget's \c caption + property has been renamed \c windowTitle to make it clear that it + refers to the title shown in the window's title bar. + + In addition, the property system has been extended to allow + properties to be redefined in subclasses with the \l Q_PROPERTY() + macro, removing the need for a \c Q_OVERRIDE() macro. + + The table below lists the Qt properties that have been renamed in + Qt 4. Occurrences of these in \e{Qt Designer} \c .ui files are + automatically converted to the new name by \c uic. + + \table + \header \o Qt 3 name \o Qt 4 name + \row \o QButton::accel \o QButton::shortcut + \row \o QButton::on \o QButton::checked + \row \o QButton::toggleButton \o QAbstractButton::checkable + \row \o QDial::lineStep \o QDial::singleStep + \row \o QDial::maxValue \o QDial::maximum + \row \o QDial::minValue \o QDial::minimum + \row \o QDialog::modal \o QDialog::isModal + \row \o QLineEdit::edited \o QLineEdit::modified + \row \o QLineEdit::hasMarkedText \o QLineEdit::hasSelectedText + \row \o QLineEdit::markedText \o QLineEdit::selectedText + \row \o QObject::name \o QObject::objectName + \row \o QProgressDialog::progress \o QProgressDialog::value + \row \o QProgressDialog::totalSteps \o QProgressDialog::maximum + \row \o QProgressDialog::wasCancelled \o QProgressDialog::wasCanceled + \row \o QPushButton::iconSet \o QPushButton::icon + \row \o QScrollBar::draggingSlider \o QScrollBar::sliderDown + \row \o QScrollBar::lineStep \o QScrollBar::singleStep + \row \o QScrollBar::maxValue \o QScrollBar::maximum + \row \o QScrollBar::minValue \o QScrollBar::minimum + \row \o QSlider::lineStep \o QSlider::singleStep + \row \o QSlider::maxValue \o QSlider::maximum + \row \o QSlider::minValue \o QSlider::minimum + \row \o QSpinBox::lineStep \o QSpinBox::singleStep + \row \o QSpinBox::maxValue \o QSpinBox::maximum + \row \o QSpinBox::minValue \o QSpinBox::minimum + \row \o QTabBar::currentTab \o QTabBar::currentIndex + \row \o QTabWidget::currentPage \o QTabWidget::currentWidget + \row \o QToolButton::iconSet \o QToolButton::icon + \row \o QToolButton::textLabel \o QToolButton::text + \row \o QWidget::caption \o QWidget::windowTitle + \row \o QWidget::icon \o QWidget::windowIcon + \row \o QWidget::iconText \o QWidget::windowIconText + \endtable + + A handful of properties in Qt 3 are no longer properties in Qt 4, + but the access functions still exist as part of the Qt 4 API. + These are not used by \e{Qt Designer}; the only case where you + need to worry about them is in highly dynamic applications that + use Qt's meta-object system to access properties. Here's the list + of these properties with the read and write functions that you + can use instead: + + \table + \header \o Qt 3 property \o Qt 4 read function \o Qt 4 write function + \row \o QSqlDatabase::connectOptions \o QSqlDatabase::connectOptions() \o QSqlDatabase::setConnectOptions() + \row \o QSqlDatabase::databaseName \o QSqlDatabase::databaseName() \o QSqlDatabase::setDatabaseName() + \row \o QSqlDatabase::hostName \o QSqlDatabase::hostName() \o QSqlDatabase::setHostName() + \row \o QSqlDatabase::password \o QSqlDatabase::password() \o QSqlDatabase::setPassword() + \row \o QSqlDatabase::port \o QSqlDatabase::port() \o QSqlDatabase::setPort() + \row \o QSqlDatabase::userName \o QSqlDatabase::userName() \o QSqlDatabase::setUserName() + \endtable + + Some properties have been removed from Qt 4, but the associated + access functions are provided if \c QT3_SUPPORT is defined to help + porting to Qt 4. When converting Qt 3 \c .ui files to Qt 4, \c uic + generates calls to the Qt 3 compatibility functions. Note that + this only applies to the properties of the Qt3Support library, + i.e. \c QT3_SUPPORT properties of the other libraries must be + ported manually when converting Qt 3 .ui files to Qt 4. + + The table below lists these properties with the read and write + functions that you can use instead. The documentation for the + individual functions explains how to replace them with + non-compatibility Qt 4 functions. + + \table + \header \o Qt 3 property \o Qt 4 read function (\c QT3_SUPPORT)\o Qt 4 write function (\c QT3_SUPPORT) + \row \o QMenuBar::separator \o QMenuBar::separator() \o QMenuBar::setSeparator() + \row \o QPushButton::menuButton \o QPushButton::isMenuButton() \o N/A + \row \o QTabWidget::margin \o QTabWidget::margin() \o QTabWidget::setMargin() + \row \o QTextEdit::textFormat \o QTextEdit::textFormat() \o QTextEdit::setTextFormat() + \row \o QWidget::backgroundBrush \o QWidget::backgroundBrush() \o N/A + \row \o QWidget::backgroundMode \o QWidget::backgroundMode() \o QWidget::setBackgroundMode() + \row \o QWidget::backgroundOrigin \o QWidget::backgroundOrigin() \o QWidget::setBackgroundOrigin() + \row \o QWidget::colorGroup \o QWidget::colorGroup() \o QWidget::setColorGroup() + \row \o QWidget::customWhatsThis \o QWidget::customWhatsThis() \o QWidget::setCustomWhatsThis() + \row \o QWidget::inputMethodEnabled \o QWidget::inputMethodEnabled() \o QWidget::setInputMethodEnabled() + \row \o QWidget::ownCursor \o QWidget::ownCursor() \o N/A + \row \o QWidget::ownFont \o QWidget::ownFont() \o N/A + \row \o QWidget::ownPalette \o QWidget::ownPalette() \o N/A + \row \o QWidget::paletteBackgroundColor \o QWidget::paletteBackgroundColor() \o QWidget::setPaletteBackgroundColor() + \row \o QWidget::paletteBackgroundPixmap \o QWidget::paletteBackgroundPixmap() \o QWidget::setPaletteBackgroundPixmap() + \row \o QWidget::paletteForegroundColor \o QWidget::paletteForegroundColor() \o QWidget::setPaletteForegroundColor() + \row \o QWidget::underMouse \o QWidget::underMouse() \o N/A + \endtable + + The following Qt 3 properties and their access functions are no + longer available in Qt 4. In most cases, Qt 4 provides similar + functionality. + + \table + \header \o Qt 3 property \o Qt 4 equivalent + \row \o QButton::autoRepeat \o N/A + \row \o QButton::autoResize \o Call QWidget:setFixedSize(QWidget::sizeHint()) whenever you change the contents. + \row \o QButton::exclusiveToggle \o See \l QAbstractButton::autoExclusive. + \row \o QButton::pixmap \o Use QAbstractButton::icon instead. + \row \o QButton::toggleState \o Use QCheckBox::setState() and QCheckBox::state() instead. + \row \o QButton::toggleType \o Use QCheckBox::setTristate() instead. + \row \o QComboBox::autoResize \o Call QWidget:setFixedSize(QWidget::sizeHint()) whenever you change the contents. + \row \o QFrame::contentsRect \o Use Q3Frame::contentsRect() instead. + \row \o QFrame::margin \o Use QWidget::setContentsMargins() instead. + \row \o QTabBar::keyboardFocusTab \o N/A + \row \o QToolButton::offIconSet \o Use the \l{QIcon::Off}{off component} of QAbstractButton::icon instead. + \row \o QToolButton::onIconSet \o Use the \l{QIcon::On}{on component} of QAbstractButton::icon instead. + \row \o QWidget::microFocusHint \o N/A + \endtable + +\omit + \section1 Inheritance Chain + + ### QMenuBar, etc. + + \section1 Null vs. Empty + + ### +\endomit + + \section1 Explicit Sharing + + Qt 4 is the first version of Qt that contains no \link + http://doc.trolltech.com/3.3/shclass.html explicitly shared + \endlink classes. All classes that were explicitly shared in Qt 3 + are \e implicitly shared in Qt 4: + + \list + \o QImage + \o QBitArray + \o QByteArray + \o Q3PointArray + \endlist + + This means that if you took a copy of an instance of the class + (using operator=() or the class's copy constructor), any + modification to the copy would affect the original and vice + versa. Needless to say, this behavior is rarely desirable. + + Fortunately, nearly all Qt 3 applications don't rely on explicit + sharing. When porting, you typically only need to remove calls to + detach() and/or copy(), which aren't necessary anymore. + + If you deliberately rely on explicit sharing in your application, + you can use pointers or references to achieve the same result in + Qt 4. + + \oldcode + void asciify(QByteArray array) + { + for (int i = 0; i < (int)array.size(); ++i) { + if ((uchar)array[i] >= 128) + array[i] = '?'; + } + } + \newcode + void asciify(QByteArray &array) + { + for (int i = 0; i < array.size(); ++i) { + if ((uchar)array[i] >= 128) + array[i] = '?'; + } + } + \endcode + + (Notice the \c & in the parameter declaration.) + +\omit + \section1 Qt Designer .ui Files + + ### +\endomit + + \section1 Painting and Redrawing Widgets + + When implementing custom widgets in Qt 3, it was possible to use + QPainter to draw on a widget outside paint events. This made it + possible to integrate Qt applications with third party libraries + and tools that impose their own rendering models. For example, + a widget might be repainted in a slot using data obtained from + an external source. + + In Qt 4, it is only possible to paint on a widget from within its + \l{QWidget::}{paintEvent()} handler function. This restriction simplifies + Qt's interaction with native window systems, improves the performance + of applications by reducing the number of redraw operations, and + also enables features to be implemented to improve the appearance of + widgets, such as a backing store. + + Generally, we recommend redesigning applications to perform all + painting operations in \l{QWidget::}{paintEvent()} functions, deferring + actual painting until the next time this function is called. + Applications can post paint events to trigger repaints, and it may be + possible to examine your widget's internal state to determine which + part of the widget needs to be repainted. + + If asynchronous repaints are used extensively by your application, + and it is not practical to redesign the rendering model to perform + all painting operations from within a widget's \l{QWidget::}{paintEvent()} + function, it may be necessary to consider using an intermediate painting + step. In this approach, one or more images can be updated asynchronously + and painted on the widget in the paint event. To avoid excessive + buffering, it may be worthwhile disabling the backing store by setting + the widget's Qt::WA_PaintOnScreen widget attribute. + + On certain platforms, the Qt::WA_PaintOutsidePaintEvent widget attribute + can be set to allow a widget to be painted from outside paint events. + + \note Setting widget attributes to disable key features of Qt's widget + rendering model may also cause other features to be disabled. + + \section1 QAccel + + The \c QAccel class has been renamed Q3Accel and moved to the + Qt3Support module. In new applications, you have three options: + + \list 1 + \o You can use QAction and set a key sequence using QAction::setShortcut(). + \o You can use QShortcut, a class that provides similar + functionality to Q3Accel. + \o You can use QWidget::grabShortcut() and process "shortcut" + events by reimplementing QWidget::event(). + \endlist + + The Q3Accel class also supports multiple accelerators using the + same object, by calling Q3Accel::insertItem() multiple times. In + Qt 4, the solution is to create multiple QShortcut objects. + + \section1 QAccessibleInterface + + The QAccessibleInterface class has undergone some API changes in + Qt 4, to make it more consistent with the rest of the Qt API. + + If you have classes that inherit QAccessibleInterface or one of + its subclasses (QAccessibleObject, QAccessibleWidget, etc.), you + must port them the new QAccessibleInterface API. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} + for a list of QAccessibleInterface virtual member functions in + Qt 3 that are no longer virtual in Qt 4. + + \section1 QAccessibleTitleBar + + The \c QAccessibleTitleBar has been renamed Q3AccessibleTitleBar + and moved to the Qt3Support library. + + \target qaction.section + \section1 QAction + + The QAction class has been redesigned in Qt 4 to integrate better + with the rest of the menu system. It unifies the old \c QMenuItem + class and the old \c QAction class into one class, avoiding + unnecessary data duplication and the need to learn two different + APIs. + + The old \c QAction and \c QActionGroup classes have been renamed + Q3Action and Q3ActionGroup and moved to Qt3Support. In addition, + the new QAction class has compatibility functions to ease + transition to Qt 4. Note that when using Q3ToolBar and + Q3PopupMenu, their actions must be \l {Q3Action}s. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} + for a list of QAction virtual member functions in Qt 3 that are + no longer virtual in Qt 4. + + \section1 QActionGroup + + The QAction class has been completely redesigned in Qt 4 to + integrate better with the rest of the menu system. See the + \l{#qaction.section}{section on QAction} for details. + + \section1 QApplication + + The QApplication class has been split into two classes: + QCoreApplication and QApplication. The new QApplication class + inherits QCoreApplication and adds GUI-related functionality. In + practice, this has no consequences for existing Qt applications. + + In addition, the following API changes were made: + + \list 1 + \o QApplication::allWidgets() and QApplication::topLevelWidgets() + used to return a pointer to a QWidgetList. Now they return a + QWidgetList. + + Also, QWidgetList has changed from being a typedef for + QPtrList to being a typedef for QList. + See the \l{#qwidgetlist.section}{section on QWidgetList} below + for details. + + \oldcode + QWidgetList *list = QApplication::topLevelWidgets(); + QWidgetListIt it(*list); + QWidget *widget; + while ((widget = it.current())) { + if (widget->inherits("MainWindow")) + ((MainWindow *)widget)->updateRecentFileItems(); + ++it; + } + delete list; + \newcode + QWidgetList list = QApplication::topLevelWidgets(); + for (int i = 0; i < list.size(); ++i) { + if (MainWindow *mainWin = qobject_cast(list.at(i))) + mainWin->updateRecentFileItems(); + } + \endcode + \o QApplication::setMainWidget() is no longer used. When all an application's + windows are closed, the application will exit normally. + \endlist + + \section1 QAquaStyle + + The \c QAquaStyle class first appeared in Qt 3.0, when the Qt for + Mac OS X port was first released. It emulated Apple's "Aqua" theme. + In Qt 3.1, QAquaStyle was obsoleted by QMacStyle, which uses Appearance + Manager to perform its drawing. + + The \c QAquaStyle class is no longer provided in Qt 4. Use + QMacStyle instead. + + \target qasciidict.section + \section1 QAsciiCache + + \c QAsciiCache has been renamed Q3AsciiCache and moved to + the Qt3Support library. It has been replaced by + QCache. + + For details, read the \l{#qcache.section}{section on QCache}, + mentally substituting QByteArray for QString. + + \section1 QAsciiDict + + QAsciiDict and QAsciiDictIterator have been renamed + Q3AsciiDict and Q3AsciiDictIterator and moved to the + Qt3Support library. They have been replaced by the + more modern QHash and QMultiHash classes and + their associated iterator classes. + + When porting old code that uses Q3AsciiDict to Qt 4, there are + four classes that you can use: + + \list + \o QMultiHash + \o QMultiHash + \o QHash + \o QHash + \endlist + + For details, read the \l{#qdict.section}{section on QDict}, + mentally substituting QByteArray for QString. + + \section1 QAsyncIO + + The \c QAsyncIO class was used internally in Qt 2.x in + conjunction with QImageConsumer. It was obsoleted in Qt 3.0. + + \input porting4-obsoletedmechanism.qdocinc + + \section1 QBackInsertIterator + + The undocumented \c QBackInsertIterator class has been removed + from the Qt library. If you need it in your application, feel + free to copy the source code from the Qt 3 \c header + file. + + \section1 QBitArray + + In Qt 3, QBitArray inherited from QByteArray. In Qt 4, QBitArray + is a totally independent class. This makes very little difference + to the user, except that the new QBitArray doesn't provide any of + QByteArray's byte-based API anymore. These calls will result in a + compile-time error, except calls to QBitArray::truncate(), whose + parameter was a number of \e bytes in Qt 3 and a number of bits + in Qt 4. + + QBitArray was an explicitly shared class in Qt 3. See \l{Explicit + Sharing} for more information. + + The \c QBitVal class has been renamed QBitRef. + + \section1 QButton + + The \c QButton class has been replaced by QAbstractButton in Qt + 4. Classes like QPushButton and QRadioButton inherit from + QAbstractButton. As a help when porting older Qt applications, + the Qt3Support library contains a Q3Button class + implemented in terms of the new QAbstractButton. + + If you used the \c QButton class as a base class for your own + button type and want to port your code to the newer + QAbstractButton, you need to be aware that QAbstractButton has no + equivalent for the Q3Button::drawButton(QPainter *) virtual + function. The solution is to reimplement QWidget::paintEvent() in + your QAbstractButton subclass as follows: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 0 + + \table + \header \o Q3Button function \o QAbstractButton equivalent + \row \o Q3Button::autoResize() \o Call QWidget:setFixedSize(QWidget::sizeHint()) whenever you change the contents. + \row \o Q3Button::isExclusiveToggle() \o Use QAbstractButton::group() or QAbstractButton::autoExclusive() instead. + \row \o Q3Button::pixmap() const \o QAbstractButton::icon() + \row \o Q3Button::setAutoResize() \o N/A + \row \o Q3Button::setPixmap(const QPixmap &) \o QAbstractButton::setIcon(const QIcon &) + \row \o Q3Button::setState(ToggleState) \o See remark below + \row \o Q3Button::setToggleType(ToggleType) \o See remark below + \row \o Q3Button::state() \o See remark below + \row \o Q3Button::stateChanged(int) \o See remark below + \row \o Q3Button::toggleType() \o See remark below + \endtable + + Remarks: + + \list 1 + \o In Qt 3, \c QButton had a "toggle type", which could be + QButton::SingleShot, QButton::Toggle, or QButton::Tristate. + The new QAbstractButton class doesn't support "tristate" + directly; this feature is implemented in QCheckBox instead. + The two other "toggle types" (\c QButton::SingleShot and \c + QButton::Toggle) are replaced by a QAbstractButton::checkable + property. + \o In Qt 3, QButton had a "toggle state", which could be \c + QButton::Off, \c QButton::NoChange, or \c QButton::On. In Qt + 4, this mechanism has been moved to QCheckBox. + \endlist + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of \c QButton virtual member functions in Qt 3 that aren't + virtual in Qt 4. + + See \l{#properties}{Properties} for a list of \c QButton properties + in Qt 3 that have changed in Qt 4. + + \section1 QButtonGroup + + The \c QButtonGroup class has been completely redesigned in Qt 4. + For compatibility, the old \c QButtonGroup class has been renamed + Q3ButtonGroup and has been moved to Qt3Support. + Likewise, the \c QHButtonGroup and \c QVButtonGroup convenience + subclasses have been renamed \c Q3HButtonGroup and \c Q3VButtonGroup and + moved to the Qt3Support library. + + The old \c QButtonGroup, as well as Q3ButtonGroup, can be used in two ways: + + \list 1 + \o The button group is the parent widget of a number of buttons, + i.e. the button group is the parent argument in the button + constructor. The buttons are assigned identifiers 0, 1, 2, etc., + in the order they are created. A Q3ButtonGroup can display a frame + and a title because it inherits Q3GroupBox. + \o The button group is an invisible widget and the contained + buttons have some other parent widget. In this usage, each + button must be manually inserted, using + Q3ButtonGroup::insert(), into the button group and given an + ID number. + \endlist + + Unlike Q3ButtonGroup, the new QButtonGroup doesn't inherit + QWidget. It is very similar to a "hidden Q3ButtonGroup". + + If you use a Q3ButtonGroup, Q3HButtonGroup, or Q3VButtonGroup as + a widget and want to port to Qt 4, you can replace it with + QGroupBox. In Qt 4, radio buttons with the same parent are + automatically part of an exclusive group, so you normally don't + need to do anything else. See also the + \l{#qgroupbox.section}{section on QGroupBox} below. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QButtonGroup virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \target qbytearray.section + \section1 QByteArray + + In Qt 3, QByteArray was simply a typedef for QMemArray. In + Qt 4, QByteArray is a class in its own right, with a higher-level + API in the style of QString. + + Here are the main issues to be aware of when porting to Qt 4: + + \list 1 + \o The QMemArray(int size) constructor has been replaced with + QByteArray(int size, char ch). The second argument specifies + which character should be used for initializing the array; + pass '\\0' if you have no specific needs. + + \oldcode + QByteArray ba(64); + \newcode + QByteArray ba(64, '\0'); + \endcode + + \o QMemArray::at() returned a non-const reference, whereas the + new QByteArray::at() returns a const value. Code like + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 1 + + will no longer compile. Instead, use QByteArray::operator[]: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 2 + + \o The QMemArray::contains(char) function has been renamed + QByteArray::count(char). In addition, there now exists a + QByteArray::contains(char) function that returns a boolean + value. Replace old calls to contains() with either count() or + contains(), depending on whether you care about the specific + number of occurrences of a character in the byte array or + only care about whether the array contains that character or + not. + + \o The new QByteArray has no assign() function. Calls to + QMemArray::assign(const QMemArray &) can be replaced by calls + to QByteArray::operator=(). Calls to QMemArray::assign(const + T *, uint) have no equivalent in Qt 4; if you use it, the + solution is either to use QByteArray::fromRawData() and to + call free() yourself to avoid a memory leak, or to use the + QByteArray(const char *, int) constructor, which will take a + deep copy of the data. + + \o QMemArray::bsearch() and QMemArray::sort() have no equivalent + in the new QByteArray class. Use \l qBinaryFind() and \l qSort() + if you need that functionality. + \endlist + + QByteArray was an explicitly shared class in Qt 3. See + \l{Explicit Sharing} for more information. + + \target qcache.section + \section1 QCache + + QCache has been renamed Q3Cache and moved to Qt3Support. + The new QCache class has a different API, and takes different + template parameters: QCache. + + When porting to Qt 4, QCache is the obvious + substitute for Q3Cache. The following table summarizes the API + differences. + + \table + \header \o Q3Cache function \o QCache equivalent + \row \o Q3Cache::Q3Cache(int maxCost, int size, bool caseSensitive) \o See remark below + \row \o Q3Cache::autoDelete() \o N/A + \row \o Q3Cache::count() \o QCache::count() or QCache::size() (equivalent) + \row \o Q3Cache::setAutoDelete() \o See remark below + \row \o Q3Cache::size() \o N/A + \row \o Q3Cache::statistics() \o N/A + \row \o Q3Cache::operator=() \o See remark below + \endtable + + Remarks: + + \list 1 + \o Q3Cache requires the user to allocate a specific number of + buckets by passing a prime number (17 by default) to the + constructor. In contrast, the new QCache's hash table + automatically grows and shrinks as needed, and the + constructor doesn't take a prime number. + + \o Q3Cache supportes case-insensitive lookups by passing false as + second argument to the constructor. This feature has no + equivalent in QMultiHash. Instead, call QString::toLower() + before you insert or lookup a key in the hash. + + \o The Q3Cache::insert() function returns a \c bool value that + indicates whether or not the item actually was inserted in + the cache. If the item wasn't inserted, it was the caller's + responsibility to delete the item. The new QCache::insert() + function returns \c void and either adds it to the cache or + deletes it right away. Old code like + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 3 + + becomes + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 4 + + \o The new QCache class \e always takes ownership of the items + it stores (i.e. auto-delete is always on). If you use Q3Cache + with auto-delete turned off (the rarely useful default), you + cannot use QCache as a direct substitute. One unelegant trick + that works well in practice is to use QCache + instead of QCache. In that case, QCache owns the + pointers, not the objects that the pointers refer to. For + example, + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 5 + + becomes + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 6 + + An alternative is to stick to using Q3Cache. + \endlist + + QCacheIterator has been renamed Q3CacheIterator and moved + to the Qt3Support library. The new QCache class + doesn't offer any iterator types. + + \section1 QCanvas + + The canvas module classes have been + renamed and moved to the Qt3Support library. + + \table + \header \o Qt 3 class name \o Compatibility class in Qt 4 + \row \o \c QCanvas \o Q3Canvas + \row \o \c QCanvasEllipse \o Q3CanvasEllipse + \row \o \c QCanvasItem \o Q3CanvasItem + \row \o \c QCanvasItemList \o Q3CanvasItemList + \row \o \c QCanvasLine \o Q3CanvasLine + \row \o \c QCanvasPixmap \o Q3CanvasPixmap + \row \o \c QCanvasPixmapArray \o Q3CanvasPixmapArray + \row \o \c QCanvasPolygon \o Q3CanvasPolygon + \row \o \c QCanvasPolygonalItem \o Q3CanvasPolygonalItem + \row \o \c QCanvasRectangle \o Q3CanvasRectangle + \row \o \c QCanvasSpline \o Q3CanvasSpline + \row \o \c QCanvasSprite \o Q3CanvasSprite + \row \o \c QCanvasText \o Q3CanvasText + \row \o \c QCanvasView \o Q3CanvasView + \endtable + + \l{The Graphics View Framework} replaces QCanvas. For more on porting to + Graphics View, see \l{Porting to Graphics View}. + + \section1 QColor + + In Qt 4, QColor is a value type like QPoint or QRect. Graphics + system-specific code has been implemented in QColormap. + + The \c QColor::maxColors() function has been replaced + by QColormap::size(). + + The \c QColor::numBitPlanes() function has been replaced + by QColormap::depth(). + + The \c QColor::setNamedColor() function no longer supports + the named color in the same way as Qt 3. Qt 4's + \l{QColor::}{setNamedColor()} uses the new W3C convention + as stated + \l{http://www.w3.org/TR/SVG/types.html#ColorKeywords}{here}. + + \table + \header \o{4,1} Predefined Qt Colors + \row \o Qt::color0 \o Qt::color1 \o Qt::black \o Qt::white + \row \o Qt::darkGray \o Qt::gray \o Qt::lightGray \o Qt::red + \row \o Qt::green \o Qt::blue \o Qt::cyan \o Qt::magenta + \row \o Qt::yellow \o Qt::darkRed \o Qt::darkGreen \o Qt::darkBlue + \row \o Qt::darkCyan \o Qt::darkMagenta \o Qt::darkYellow \o Qt::transparent + \endtable + + The predefined colors listed in the table above were static + QColor objects in Qt 3. In Qt 4, they are enum values of type + Qt::GlobalColor. Thanks to the implicit QColor(Qt::GlobalColor) + constructor, the enum values are automatically converted to + \l{QColor}s in most contexts. Occasionally, you might need a + cast. + + \oldcode + QColor lightCyan = Qt::cyan.light(180); + \newcode + QColor lightCyan = QColor(Qt::cyan).light(180); + \endcode + + \section1 QColorGroup + + In Qt 3, a QPalette consisted of three QColorGroup objects. In Qt + 4, the (rarely used) QColorGroup abstraction has been eliminated. + For source compatibility, a QColorGroup class is available when + \c QT3_SUPPORT is defined. + + The new QPalette still works in terms of color groups, specified + through enum values (QPalette::Active, QPalette::Disabled, and + QPalette::Inactive). It also has the concept of a \e current + color group, which you can set using + QPalette::setCurrentColorGroup(). + + The QPalette object returned by QWidget::palette() returns a + QPalette initialized with the correct current color group for the + widget. This means that if you had code like + + \badcode + painter.setBrush(colorGroup().brush(QColorGroup::Text)); + \endcode + + you can simply replace colorGroup() with palette(): + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 7 + + \section1 QColorDrag + + The \c QColorDrag class has been renamed Q3ColorDrag and moved to + the Qt3Support library. In Qt 4, use QMimeData + instead and call QMimeData::setColor() to set the color. + + \section1 QComboBox + + In Qt 3, the list box used to display the contents of a \c QComboBox + widget could be accessed by using the \c listBox() function. In Qt 4, + the standard list box is provided by a QListView widget, and can be + accessed with the \l{QComboBox::view()}{view()} function. + + \omit ### \endomit + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QComboBox virtual member functions in Qt 3 that are no longer + virtual in Qt 4. + + \section1 QCString + + In Qt 3, QCString inherited from QByteArray. The main drawback + of this approach is that the user had the responsibility of + ensuring that the string is '\\0'-terminated. Another important + issue was that conversions between \c QCString and QByteArray often + gave confusing results. (See the + \l{http://doc.trolltech.com/qq/qq05-achtung.html#qcstringisastringofchars}{Achtung! + Binary and Character Data} article in \e{Qt Quarterly} for an + overview of the pitfalls.) + + Qt 4 solves that problem by merging the QByteArray and \c QCString + classes into one class called QByteArray. Most functions that + were in \c QCString previously have been moved to QByteArray. The + '\\0' issue is handled by having QByteArray allocate one extra + byte that it always sets to '\\0'. For example: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 8 + + The Qt3Support library contains a class called + Q3CString that inherits from the new QByteArray class and that + extends it to provide an API that is as close to the old \c QCString + class as possible. Note that the following functions aren't + provided by Q3CString: + + \list + \o QCString::find(const QRegExp &, int) + \o QCString::findRev(const QRegExp &, int) + \o QCString::contains(const QRegExp &) + \o QCString::replace(const QRegExp &, const char *) + \endlist + + The following functions have lost their last parameter, which + specified whether the search was case sensitive or not: + + \list + \o QByteArray::find(char, int) + \o QByteArray::find(const char *, int) + \o QByteArray::findRev(char, int) + \o QByteArray::findRev(const char *, int) + \o QByteArray::contains(char) + \o QByteArray::contains(const char *) + \endlist + + In both cases, the solution is to convert the \c QCString to a + QString and use the corresponding QString functions instead. + + Also be aware that \c QCString::size() (inherited from + QByteArray) used to return the size of the character data \e + including the '\\0'-terminator, whereas the new + QByteArray::size() is just a synonym for QByteArray::length(). + This brings QByteArray in line with QString. + + When porting to Qt 4, occurrences of \c QCString should be + replaced with QByteArray or QString. The following table + summarizes the API differences between the Q3CString + class and the Qt 4 QByteArray and QString classes: + + \table + \header \o Q3CString function \o Qt 4 equivalent + \row \o Q3CString::Q3CString(const char *, uint) \o See remark below + \row \o Q3CString::Q3CString(int) \o QByteArray::QByteArray(int, char) + \row \o Q3CString::leftJustify() \o QString::leftJustified() + \row \o Q3CString::length() \o QByteArray::length() or QByteArray::size() (equivalent) + \row \o Q3CString::lower() \o QByteArray::toLower() + \row \o Q3CString::rightJustify() \o QString::rightJustified() + \row \o Q3CString::setExpand() \o See remark below + \row \o Q3CString::simplifyWhiteSpace() \o QByteArray::simplified() + \row \o Q3CString::sprintf() \o QString::sprintf() + \row \o Q3CString::stripWhiteSpace() \o QByteArray::trimmed() + \row \o Q3CString::toDouble() \o QString::toDouble() + \row \o Q3CString::toFloat() \o QString::toFloat() + \row \o Q3CString::toInt() \o QString::toInt() + \row \o Q3CString::toLong() \o QString::toLong() + \row \o Q3CString::toShort() \o QString::toShort() + \row \o Q3CString::toUInt() \o QString::toUInt() + \row \o Q3CString::toULong() \o QString::toULong() + \row \o Q3CString::toUShort() \o QString::toUShort() + \row \o Q3CString::upper() \o QByteArray::toUpper() + \endtable + + Remarks: + + \list 1 + \o Q3CString(const char *str, uint max) constructs a string of + length strlen(str) or \e max - 1, whichever is shorter. + QByteArray(const char *data, int size) constructs a byte + array containing exactly \e size bytes. + + \oldcode + QCString str1("Hello", 4); // "Hel" + QCString str2("Hello world!", n); + \newcode + QByteArray str1("Hello", 3); + QByteArray str2("Hello world!"); + str2.truncate(n - 1); + \endcode + + \o Q3CString::setExpand(uint index, char ch) has no equivalent in + Qt 4. + + \oldcode + QCString str("Hello world"); + str.setExpand(16, '\n'); // "Hello world \n" + \newcode + QByteArray str("Hello world"); + while (str.size() < 16) + str += ' '; + str += '\n'; + \endcode + \endlist + + Since the old \c QCString class inherited from QByteArray, + everything that is said in the \l{#qbytearray.section}{QByteArray + section} applies for \c QCString as well. + + \section1 QCustomEvent + + In Qt 3, developers could create a custom event by constructing + a new QCustomEvent, and send relevant data to other components in + the application by passing a void pointer, either on construction or + using the setData() function. Objects could receive custom events + by reimplementing the \l{QObject::customEvent()}{customEvent()} + function, and access the stored data using the event's data() + function. + + In Qt 4, custom events are created by subclassing + QEvent. Event-specific data can be stored in a way that is + appropriate for your application. Custom events are still + delivered to each object's + \l{QObject::customEvent()}{customEvent()} handler function, but as + QEvent objects rather than as deprecated QCustomEvent objects. + + \section1 QDataBrowser + + The \c QDataBrowser class has been renamed Q3DataBrowser and + moved to the Qt3Support library. In Qt 4.2, you should use the + QDataWidgetMapper class to create data-aware forms. + + See \l{QtSql Module} for an overview of the new SQL + classes. + + \section1 QDataPump + + The \c QDataPump class was used internally in Qt 2.x in + conjunction with QImageConsumer. It was obsoleted in Qt 3.0. + + \input porting4-obsoletedmechanism.qdocinc + + \section1 QDataSink + + The \c QDataSink class was used internally in Qt 2.x in conjunction + with QImageConsumer. It was obsoleted in Qt 3.0. + + \input porting4-obsoletedmechanism.qdocinc + + \section1 QDataSource + + The \c QDataSource class was used internally in Qt 2.x in + conjunction with QImageConsumer. It was obsoleted in Qt 3.0. + \input porting4-obsoletedmechanism.qdocinc + + \section1 QDataTable + + The \c QDataTable class has been renamed Q3DataTable and moved to + the Qt3Support library. In Qt 4.2, you should use the + QDataWidgetMapper class to create data-aware forms. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QDataView + + The \c QDataView class has been renamed Q3DataView and moved to + the Qt3Support library. In Qt 4.2, you should use the + QDataWidgetMapper class to create data-aware forms. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QDateEdit + + The QDateEdit class in Qt 4 is a convenience class based on + QDateTimeEdit. The old class has been renamed Q3DateEdit and moved + to the Qt3Support library. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of \c QDateEdit virtual member functions in Qt 3 that are + no longer virtual in Qt 4. + + \section1 QDateTimeEditBase + + The \c QDateTimeEditBase class has been renamed + Q3DateTimeEditBase and moved to Qt3Support. Use QDateTimeEdit or + QAbstractSpinBox instead. + + \section1 QDateTimeEdit + + The old \c QDateTimeEdit class has been renamed + Q3DateTimeEditBase and moved to Qt3Support. The new QDateTimeEdit + in Qt 4 has been rewritten from scratch to provide a more + flexible and powerful API. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QDateTimeEdit virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \section1 QDeepCopy + + The \c QDeepCopy class in Qt 3 provided a means of ensuring that + implicitly shared and explicitly shared classes referenced unique + data. This was necessary because the reference counting in Qt's + container classes was done in a thread-unsafe manner. + + With Qt 4, \c QDeepCopy has been renamed Q3DeepCopy and + moved to the Qt3Support library. Removing it from + existing code is straightforward. + + \oldcode + QString str1 = "I am a string"; + QDeepCopy str2 = str1; + QString str3 = QDeepCopy(str2); + \newcode + QString str1 = "I am a string"; + QString str2 = str1; + QString str3 = str2; + \endcode + + \section1 QDial + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QDial virtual member functions in Qt 3 that are no longer + virtual in Qt 4. + + See \l{#properties}{Properties} for a list of QDial properties in + Qt 3 that have changed in Qt 4. + + \target qdict.section + \section1 QDict + + \c QDict has been renamed Q3Dict and moved to Qt3Support. + It has been replaced by the more modern QHash and + QMultiHash classes. + + When porting old code that uses QDict to Qt 4, there are four + classes that you can use: + + \table + \header \o Qt 4 class \o When to use it + \row \o QMultiHash + + \o Since Q3Dict is pointer-based and allows duplicate + keys, this is usually the most straightforward conversion. + + \row \o QMultiHash + + \o If type \c T is an \l{assignable data type}, you can use + \c T as the value type rather than \c{T *}. This often + leads to nicer code. + + \row \o QHash + + \o{1,2} If you don't use duplicate keys, you can use QHash + instead of QMultiHash. QMultiHash inherits from QHash. + + \row \o QHash + \endtable + + The APIs of Q3Dict and QMultiHash are quite + similar. The main issue is that Q3Dict supports auto-delete + whereas QMultiHash doesn't. + + \omit + (See \l{What's Wrong with + Auto-Delete} for an explanation of why the Qt 4 containers don't + offer that feature.) + \endomit + + The following table summarizes the API differences between the + two classes: + + \table + \header \o Q3Dict function \o QMultiHash equivalent + \row \o Q3Dict::Q3Dict(int size, bool caseSensitive) \o See remarks below + \row \o Q3Dict::autoDelete() \o N/A + \row \o Q3Dict::count() \o QMultiHash::count() or QMultiHash::size() (equivalent) + \row \o Q3Dict::find(const QString &) \o QMultiHash::value(const QString &) + \row \o Q3Dict::remove(const QString &) \o QMultiHash::take(const QString &) + \row \o Q3Dict::resize(uint) \o QMultiHash::reserve(int) + \row \o Q3Dict::setAutoDelete() \o See discussion below + \row \o Q3Dict::size() \o QMultiHash::capacity() + \row \o Q3Dict::statistics() \o N/A + \row \o Q3Dict::operator[](const QString &) \o See remark below + \endtable + + Remarks: + + \list 1 + \o Q3Dict requires the user to allocate a specific number of + buckets by passing a prime number (17 by default) to the + constructor and/or calling Q3Dict::resize() later on. In + contrast, QMultiHash's hash table automatically grows and + shrinks as needed, and the constructor doesn't take a prime + number. + + \o Q3Dict supportes case-insensitive lookups by passing false as + second argument to the constructor. This feature has no + equivalent in QMultiHash. Instead, call QString::toLower() + before you insert or lookup a key in the hash. + + \o Q3Dict::size() and QMultiHash::size() have different semantics. + The former returns the number of buckets in the container, whereas + the latter returns the number of \e items in the container. + + \o If there are multiple items with the same key, + Q3Dict::remove() removes only the most recently inserted item, + whereas QMultiHash::remove() removes all items that share a + particular key. To remove only the most recently inserted item, + call QMultiHash::take(). + + \o Q3Dict has only one [] operator (Q3Dict::operator[]()), + providing const access to an item's value. QMultiHash also + has a non-const overload that can be used on the left side of + the assignment operator. If you use the [] operator on a + non-const QHash with an unexisting item, QHash will created + an element and initialize it to be a null pointer. For that + reason, Q3Dict::operator[] should be converted to + QMultiHash::value(), not QMultiHash::operator[]. + + \endlist + + If you use Q3Dict's auto-delete feature (by calling + Q3Dict::setAutoDelete(true)), you need to do some more work. You + have two options: Either you call \c delete yourself whenever you + remove an item from the container, or you use + QMultiHash instead of QMultiHash (i.e. + store values directly instead of pointers to values). Here, we'll + see when to call \c delete. + + The following table summarizes the idioms that you need to watch + out for if you want to call \c delete yourself. + + \table + \header \o Q3Dict idiom \o QMultiHash idiom + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 9 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 10 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 11 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 12 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 13 + + (also called from Q3Dict's destructor) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 14 + + In 99% of cases, the following idiom also works: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 15 + + However, it may lead to crashes if \c hash is referenced from + the value type's destructor, because \c hash contains + dangling pointers until clear() is called. + \endtable + + Be aware that Q3Dict's destructor automatically calls clear(). If + you have a Q3Dict data member in a custom class and use the + auto-delete feature, you will need to call \c delete on all the + items in the container from your class destructor to avoid a + memory leak. + + Finally, \c QDictIterator (renamed Q3DictIterator) must + also be ported. There are no fewer than four iterator classes + that can be used as a replacement: QHash::const_iterator, + QHash::iterator, QHashIterator, and QMutableHashIterator. The + most straightforward class to use when porting is + QHashIterator. The following table summarizes the + API differences: + + \table + \header \o Q3DictIterator functions \o Qt 4 equivalent + \row \o Q3DictIterator::count() \o QHash::count() or QHash::size() + \row \o Q3DictIterator::current() \o QHashIterator::value() + \row \o Q3DictIterator::currentKey() \o QHashIterator::key() + \row \o Q3DictIterator::isEmpty() \o QHash::isEmpty() + \row \o Q3DictIterator::toFirst() \o QHashIterator::toFront() + \row \o Q3DictIterator::operator()() \o QHashIterator::value() + \row \o Q3DictIterator::operator*() \o QHashIterator::value() + \row \o Q3DictIterator::operator++() \o See remark below + \endtable + + Be aware that QHashIterator has a different way of iterating than + Q3DictIterator. A typical loop with Q3DictIterator looks like this: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 16 + + Here's the equivalent QHashIterator loop: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 17 + + See \l{Java-style iterators} for details. + + \section1 QDir + + The following functions used to have a boolean \c{acceptAbsPath} + parameter that defaulted to true: + + \list + \i QDir::filePath() + \i QDir::absFilePath() + \i QDir::cd() + \i QDir::mkdir() + \i QDir::rmdir() + \i QDir::remove() + \i QDir::rename() + \i QDir::exists() + \endlist + + In Qt 3, if \c acceptAbsPath is true, a file name starting with + '/' is be returned without change; if \c acceptAbsPath is false, + an absolute path is prepended to the file name. For example: + + \table + \header \i Current directory \i File name \i \c acceptAbsPath \i File path + \row \i{1,2} /home/tsmith \i{1,2} index.html \i true \i /home/tsmith/index.html + \row \i false \i /home/tsmith/index.html + \row \i{1,2} /home/tsmith \i{1,2} /index.html \i true \i /index.html + \row \i false \i /home/tsmith/index.html + \endtable + + In Qt 4, this parameter is no longer available. If you use it + in your code, you can check that QDir::isRelativePath() returns + false instead. + + \oldcode + QDir dir("/home/tsmith"); + QString path = dir.filePath(fileName, false); + \newcode + QDir dir("/home/tsmith"); + QString path; + if (dir.isRelativePath(fileName)) + path = dir.filePath(fileName); + else + path = fileName; + \endcode + + QDir::encodedEntryList() has been removed. + + fileInfoList(), entryInfoList(), and drives() now return a QList + and not a QPtrList *. Code using these methods will not work with + the Qt3Support library and must be adapted instead. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QDir virtual member functions in Qt 3 that are no longer + virtual in Qt 4. + + QDir::match() now always matches case insensitively. + + QDir::homeDirPath() has been removed. Use QDir::home() instead, and + extract the path separately. + + \section1 QDns + + Qt 3 used its own implementation of the DNS protocol and provided + a low-level \c QDns class. Qt 4's QHostInfo class uses the system's \c + gethostbyname() function from a thread instead. + + The old \c QDns class has been renamed Q3Dns and moved to the + Qt3Support library. The new QHostInfo class has a + radically different API: It consists mainly of two static + functions, one of which is blocking (QHostInfo::fromName()), the + other non-blocking (QHostInfo::lookupHost()). See the QHostInfo + class documentation for details. + + \section1 QDockArea + + The \c QDockArea class has been renamed Q3DockArea and moved to + the Qt3Support library. In Qt 4, QMainWindow handles + the dock and toolbar areas itself. See the QMainWindow + documentation for details. + + \section1 QDockWindow + + The old \c QDockWindow class has been renamed Q3DockWindow and + moved to the Qt3Support library. In Qt 4, there is a + new QDockWidget class with a different API. See the class + documentation for details. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QDockWidget virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \note \l{Q3DockWindow}'s + \l{Q3DockWindow::setHorizontallyStretchable()}{horizontallyStretchable} + property can be achieved in QDockWidget with + \l{QWidget#Size Hints and Size Policies}{size policies}. + + \section1 QDragObject + + The \c QDragObject class has been renamed Q3DragObject and + moved to the Qt3Support library. In Qt 4, it has been + replaced by the QMimeData class. See the class documentation for + details. + + Note that the Q3DragObject::DragCopyOrMove drag and drop mode is + interpreted differently to Qt 3's QDragObject::DragCopyOrMove mode. + In Qt 3, a move operation was performed by default, and the user had + to hold down the \key{Ctrl} key to perform a copy operation. + In Qt 4, a copy operation is performed by default; the user has to + hold down the \key{Shift} key to perform a move operation. + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QDropSite + + The \c QDropSite class has been renamed Q3DropSite and moved to + the Qt3Support library. + + The QDropSite class has been obsolete ever since Qt 2.0. The only + thing it does is call QWidget::setAcceptDrops(true). + + \oldcode + class MyWidget : public QWidget, public QDropSite + { + public: + MyWidget(const QWidget *parent) + : QWidget(parent), QDropSite(this) + { + } + ... + } + \newcode + class MyWidget : public QWidget + { + public: + MyWidget(const QWidget *parent) + : QWidget(parent) + { + setAcceptDrops(true); + } + ... + } + \endcode + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QEditorFactory + + The \c QEditorFactory class has been renamed Q3EditorFactory and + moved to the Qt3Support library. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QEventLoop + + In Qt 3, \c QEventLoop combined the Qt event loop and the event + dispatching. In Qt 4, these tasks are now assigned to two + distinct classes: QEventLoop and QAbstractEventDispatcher. + + If you subclassed QEventLoop to integrate with another library's + event loop, you must subclass QAbstractEventDispatcher instead. See + the class documentation for details. + + Developers using \c{QEventLoop::loopLevel()} in Qt 3 should use + QCoreApplication::loopLevel() instead. Note that this function is + marked as obsolete, but it is expected to be available for the + lifetime of Qt 4. + \omit ### mention virtual functions that aren't virtual anymore \endomit + + \omit + \section1 QFile + + The QFile::readLine(QString&, Q_ULONG) method from qt3 has been removed + in qt4, but this change in the QFile interface is not documented in the + porting documentation as of qt-4.0.0-b1. + \endomit + + \section1 QFileDialog + + The QFileDialog class in Qt 4 has been totally rewritten. It + provides most of the functionality of the old \c QFileDialog + class, but with a different API. Some functionality, such as the + ability to preview files, is expected to be added in a later Qt 4 + release. + + The old \c QFileDialog, \c QFileIconProvider, and \c QFilePreview + classes has been renamed Q3FileDialog, Q3FileIconProvider, and + Q3FilePreview and have been moved to Qt3Support. You can use them + if you need some functionality not provided yet by the new + QFileDialog class. + + The following table lists which functions have been renamed or + removed in Qt 4. + + \table + \header \o Old function \o Qt 4 equivalent + \row \o Q3FileDialog::addFilter(const QString &) \o See remark below + \row \o Q3FileDialog::addLeftWidget(QWidget *) \o N/A + \row \o Q3FileDialog::addRightWidget(QWidget *) \o N/A + \row \o Q3FileDialog::addToolButton(QAbstractButton *, bool separator) \o N/A + \row \o Q3FileDialog::addWidgets(QLabel *, QWidget *, QPushButton *) \o N/A + \row \o Q3FileDialog::dir() \o QFileDialog::directory() + \row \o Q3FileDialog::dirPath() \o QFileDialog::directory().path() + \row \o Q3FileDialog::iconProvider() \o N/A + \row \o Q3FileDialog::isContentsPreviewEnabled() \o N/A + \row \o Q3FileDialog::isInfoPreviewEnabled() \o N/A + \row \o Q3FileDialog::previewMode() \o N/A + \row \o Q3FileDialog::rereadDir() \o N/A + \row \o Q3FileDialog::resortDir() \o N/A + \row \o Q3FileDialog::selectAll(bool) \o N/A + \row \o Q3FileDialog::setContentsPreview(QWidget *, Q3FilePreview *) \o N/A + \row \o Q3FileDialog::setContentsPreviewEnabled(bool) \o N/A + \row \o Q3FileDialog::setDir(const QString &) \o QFileDialog::setDirectory(const QString &) + \row \o Q3FileDialog::setFilters(const char **) \o Q3FileDialog::setFilters(const QStringList &) + \row \o Q3FileDialog::setIconProvider(Q3FileIconProvider *) \o N/A + \row \o Q3FileDialog::setInfoPreview(QWidget *, Q3FilePreview *) \o N/A + \row \o Q3FileDialog::setInfoPreviewEnabled(bool) \o N/A + \row \o Q3FileDialog::setPreviewMode(PreviewMode) \o N/A + \row \o Q3FileDialog::setSelectedFilter(const QString &) \o QFileDialog::selectFilter(const QString &) + \row \o Q3FileDialog::setSelectedFilter(int) \o See remark below + \row \o Q3FileDialog::setSelection(const QString &) \o QFileDialog::selectFile(const QString &) + \row \o Q3FileDialog::setShowHiddenFiles(bool) \o showHidden() + \row \o Q3FileDialog::setUrl(const QUrlOperator &) \o N/A + \row \o Q3FileDialog::showHiddenFiles() \o N/A + \row \o Q3FileDialog::url() \o QUrl::fromLocalFile(QFileDialog::directory()) + \header \o Old signals \o Qt 4 equivalent + \row \o Q3FileDialog::fileHighlighted(const QString &) \o N/A + \row \o Q3FileDialog::fileSelected(const QString &) \o QFileDialog::filesSelected(const QStringList &) + \row \o Q3FileDialog::dirEntered(const QString &) \o N/A + \row \o Q3FileDialog::filterSelected(const QString &) \o N/A + \endtable + + Remarks: + + \list 1 + \o The Q3FileDialog::addFilter(const QString &) function has no + direct equivalent in the new QFileDialog. Use + QFileDialog::setFilters() instead. + + \oldcode + fileDialog->addFilter(tr("JPEG files (*.jpg *.jpeg)")); + \newcode + QStringList filters = fileDialog->filters(); + filters << tr("JPEG files (*.jpg *.jpeg)"); + fileDialog->setFilters(filters); + \endcode + + \o The Q3FileDialog::setSelectedFilter(int) overload has no direct + equivalent in the new QFileDialog. Use + QFileDialog::selectFilter(const QString &) instead. + + \oldcode + fileDialog->setSelectedFilter(3); + \newcode + fileDialog->selectFilter(fileDialog->filters().at(3)); + \endcode + \endlist + + There are no equivalent virtual functions to the two + Q3FileDialog::setSelectedFilter() virtual functions in the QFileDialog + API. In addition, these functions have been renamed or removed, as + described above. + + \section1 QFocusData + + The QFocusData class is not available in Qt 4. Some of its + functionality is available via the QWidget::nextInFocusChain() + and QWidget::focusNextPrevChild() functions. + + \section1 QFocusEvent + + The setReason() function is no longer present in Qt 4. It is + necessary to define the reason when constructing a focus event. + + \section1 QFont + + \c QFont::Script has been moved to QFontDatabase::WritingSystem. + + \section1 QFrame + + The QFrame class has been made more lightweight in Qt 4, by + reducing the number of properties and virtual functions. The + reduction in the number of virtual functions is significant + because QFrame is the base class of many Qt classes. + + Here's an overview of the changes: + + \list + \o QFrame no longer has a \c margin property (which wasn't + honored by Qt's layout managers anyway). + + \o QFrame no longer has a frameChanged() function, reimplement + QFrame::resizeEvent() instead. + + \o QFrame used to have drawFrame(QPainter *) and + drawContents(QPainter *) virtual functions. These are now + gone. In Qt 4, the frame is drawn by the QFrame::paintEvent() + function. If you want to change the way QFrame paints itself, + reimplement this function. To draw the contents of the frame, + reimplement QFrame:paintEvent() and call the base class + implementation of the function before you use the + \l {QWidget::}{contentsRect()} function inherited from QWidget, + to retrieve the rectangle to paint on. + + \endlist + + To help with porting, the Qt3Support library contains a Q3Frame + class that inherits QFrame and provides a similar API to the old + QFrame class. If you derived from QFrame in your application, you + might want to use Q3Frame as a base class as a first step in the + porting process, and later move on to the new QFrame class. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QFrame virtual member functions in Qt 3 that are no longer + virtual in Qt 4. + + \section1 QFtp + + QFtp no longer inherits from QNetworkProtocol. See the + \l{#qnetworkprotocol.section}{section on QNetworkProtocol} for + details. + + The old \c QFtp class has been renamed Q3Ftp and moved to the + Qt3Support library. + + \target qglayoutiterator.section + \section1 QGLayoutIterator + + The QGLayoutIterator class no longer exists in Qt 4. This makes + only a difference if you implemented custom layout managers + (i.e., QLayout subclasses). + + The new approach is much simpler: It consists in reimplementing + QLayout::itemAt() and QLayout::takeAt(). These functions operate + on indexes, eliminating the need for a layout iterator class. + + \section1 QGrid + + The \c QGrid class is now only available as Q3Grid in Qt 4. You + can achieve the same result as \c QGrid by creating a QWidget + with a grid layout: + + \oldcode + QGrid *grid = new QGrid(2, Qt::Horizontal); + QPushButton *child1 = new QPushButton(grid); + QPushButton *child2 = new QPushButton(grid); + QPushButton *child3 = new QPushButton(grid); + QPushButton *child4 = new QPushButton(grid); + \newcode + QWidget *grid = new QWidget; + QPushButton *child1 = new QPushButton(grid); + QPushButton *child2 = new QPushButton(grid); + QPushButton *child3 = new QPushButton(grid); + QPushButton *child4 = new QPushButton(grid); + + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(child1, 0, 0); + layout->addWidget(child2, 0, 1); + layout->addWidget(child3, 1, 0); + layout->addWidget(child4, 1, 1); + grid->setLayout(layout); + \endcode + + \section1 QGridLayout + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QGridLayout virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \section1 QGridView + + The \c QGridView class has been renamed Q3GridView and moved to + the Qt3Support library. In Qt 4, we recommend that + you use QTableView or QAbstractItemView for presenting tabular + data. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \target qgroupbox.section + \section1 QGroupBox + + The QGroupBox class has been redesigned in Qt 4. Many of the + features of the old \c QGroupBox class can be obtained by using + the Q3GroupBox class from the Qt3Support library. + + The new QGroupBox is more lightweight. It doesn't attempt to + duplicate functionality already provided by QGridLayout, and it + does not inherit from QFrame. As a result, the following members + have been removed: + + \list + \o Q3GroupBox::setColumns(), Q3GroupBox::columns() + \o Q3GroupBox::setOrientation(), Q3GroupBox::orientation() + \o Q3GroupBox::setInsideMargin(), Q3GroupBox::insideMargin() + \o Q3GroupBox::addSpace() + \endlist + + Naturally, the \c columns and \c orientation properties have also + been removed. + + If you rely on some of the missing functionality in your + application, you can use Q3GroupBox instead of QGroupBox as a + help to porting. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of QGroupBox virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \section1 QHBox + + The \c QHBox class is now only available as Q3HBox in Qt 4. You + can achieve the same result as \c QHBox by creating a QWidget + with an horizontal layout: + + \oldcode + QHBox *hbox = new QHBox; + QPushButton *child1 = new QPushButton(hbox); + QPushButton *child2 = new QPushButton(hbox); + \newcode + QWidget *hbox = new QWidget; + QPushButton *child1 = new QPushButton; + QPushButton *child2 = new QPushButton; + + QHBoxLayout *layout = new QHBoxLayout; + layout->addWidget(child1); + layout->addWidget(child2); + hbox->setLayout(layout); + \endcode + + Note that child widgets are not automatically placed into the widget's + layout; you will need to manually add each widget to the QHBoxLayout. + + \section1 QHeader + + The \c QHeader class has been renamed Q3Header and moved to + the Qt3Support library. In Qt 4, it is replaced + by the QHeaderView class. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \section1 QHGroupBox + + The \c QHGroupBox class has been renamed Q3HGroupBox and moved to + the Qt3Support library. + Qt 4 does not provide a specific replacement class for \c QHGroupBox + since QGroupBox is designed to be a generic container widget. As a + result, you need to supply your own layout for any child widgets. + + See \l{#QGroupBox} for more information about porting code that uses + group boxes. + + \section1 QHttp + + QHttp no longer inherits from QNetworkProtocol. See the See the + \l{#qnetworkprotocol.section}{section on QNetworkProtocol} for + details. + + The old \c QHttp, \c QHttpHeader, \c QHttpRequestHeader, and \c + QHttpResponseHeader classes have been renamed Q3Http, + Q3HttpHeader, Q3HttpRequestHeader, and Q3HttpResponseHeader and + have been moved to the Qt3Support library. + + \section1 QIconFactory + + The QIconFactory class is no longer part of Qt. It has been replaced by + the QIconEngine class. + + \section1 QIconSet + + The QIconSet class is no longer part of Qt. It has been replaced by + the QIcon class. + + \section1 QIconView + + The \c QIconView, \c QIconViewItem, \c QIconDrag, and \c + QIconDragItem classes has been renamed Q3IconView, + Q3IconViewItem, Q3IconDrag, and Q3IconDragItem and moved to the + Qt3Support library. New Qt applications should use + QListWidget or its base class QListView instead, and call + QListView::setViewMode(QListView::IconMode) to obtain an "icon + view" look. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \omit + ### + + \section1 QImage + + QImage::fromMimeSource(const QString &) -> qImageFromMimeSource(const QString &) + \endomit + + \section1 QImageDrag + + The \c QImageDrag class has been renamed Q3ImageDrag and moved to + the Qt3Support library. In Qt 4, use QMimeData + instead and call QMimeData::setImage() to set the image. + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QImageIO + + The \c QImageIO class has been split into two classes: + QImageReader and QImageWriter. The table below shows the + correspondance between the two APIs: + + \table + \header \o Qt 3 function \o Qt 4 equivalents + \row \o QImageIO::description() \o QImageWriter::description() + \row \o QImageIO::fileName() \o QImageReader::fileName() and QImageWriter::fileName() + \row \o QImageIO::format() \o QImageReader::format() and QImageWriter::format() + \row \o QImageIO::gamma() \o QImageWriter::gamma() + \row \o QImageIO::image() \o Return value of QImageReader::read() + \row \o QImageIO::inputFormats() \o QImageReader::supportedImageFormats() + \row \o QImageIO::ioDevice() \o QImageReader::device() and QImageWriter::device() + \row \o QImageIO::outputFormats() \o QImageWriter::supportedImageFormats() + \row \o QImageIO::parameters() \o N/A + \row \o QImageIO::quality() \o QImageWriter::quality() + \row \o QImageIO::read() \o QImageReader::read() + \row \o QImageIO::setDescription() \o QImageWriter::setDescription() + \row \o QImageIO::setFileName() \o QImageReader::setFileName() and QImageWriter::setFileName() + \row \o QImageIO::setFormat() \o QImageReader::setFormat() and QImageWriter::setFormat() + \row \o QImageIO::setGamma() \o QImageWriter::setGamma() + \row \o QImageIO::setIODevice() \o QImageReader::setDevice() and QImageWriter::setDevice() + \row \o QImageIO::setImage() \o Argument to QImageWriter::write() + \row \o QImageIO::setParameters() \o N/A + \row \o QImageIO::setQuality() \o QImageWriter::setQuality() + \row \o QImageIO::setStatus() \o N/A + \row \o QImageIO::status() \o QImageReader::error() and QImageWriter::error() + \row \o QImageIO::write() \o QImageWriter::write() + \endtable + + \section1 QIntCache + + QIntCache has been moved to Qt3Support. It has been replaced + by QCache. + + For details, read the \l{#qcache.section}{section on QCache}, + mentally substituting \c int for QString. + + \section1 QIntDict + + QIntDict and QIntDictIterator have been moved to + Qt3Support. They have been replaced by the more modern QHash and QMultiHash classes and their associated iterator + classes. + + When porting old code that uses QIntDict to Qt 4, there are + four classes that you can use: + + \list + \o QMultiHash + \o QMultiHash + \o QHash + \o QHash + \endlist + + For details, read the \l{#qdict.section}{section on QDict}, + mentally substituting \c int for QString. + + \target qiodevice.section + \section1 QIODevice + + The QIODevice class's API has been simplified to make it easier + to subclass and to make it work more smoothly with asynchronous + devices such as QTcpSocket and QProcess. + + The following virtual functions have changed name or signature: + + \table + \header \o Qt 3 function \o Comment + \row \o QIODevice::at() const \o Renamed QIODevice::pos(). + \row \o QIODevice::at(Offset) \o Renamed QIODevice::seek(). + \row \o QIODevice::open(int) \o The parameter is now of type QIODevice::OpenMode. + \row \o QIODevice::readBlock(char *, Q_ULONG) \o QIODevice::read(char *, qint64) + \row \o QIODevice::writeBlock(const char *, Q_ULONG) \o QIODevice::write(const char *, qint64) + \endtable + + \note QIODevice::open(QIODevice::OpenMode) is no longer pure virtual. + + The following functions are no longer virtual or don't exist anymore: + + \table + \row \o QIODevice::getch() \o Renamed QIODevice::getChar() and implemented in terms of QIODevice::readData(). + \row \o QIODevice::putch(int) \o Renamed QIODevice::putChar() and implemented in terms of QIODevice::writeData(). + \row \o QIODevice::readAll() \o Implemented in terms of QIODevice::readData(). + \row \o QIODevice::readLine(char *, Q_ULONG) \o Implemented in terms of QIODevice::readData() + \row \o QIODevice::ungetch(int) \o Renamed QIODevice::ungetChar() and simulated using an internal unget buffer. + \endtable + + The \c IO_xxx flags have been revised, and the protected setFlags() + function removed. Most of the flags have been + eliminated because errors are best handled by implementing certain + functions in QIODevice subclasses rather than through the base classes. + The file access flags, such as \c IO_ReadOnly and \c IO_WriteOnly, have + been moved to the QIODevice class to avoid polluting the global + namespace. The table below shows the correspondence between the + Qt 3 \c IO_xxx flags and the Qt 4 API: + + \table + \header \o Qt 3 constant \o Qt 4 equivalent + \row \o IO_Direct \o Use !QIODevice::isSequential() instead (notice the \e not). + \row \o IO_Sequential \o Use QIODevice::isSequential() instead. + \row \o IO_Combined \o N/A + \row \o IO_TypeMask \o N/A + \row \o IO_Raw \o QIODevice::Unbuffered + \row \o IO_Async \o N/A + \row \o IO_ReadOnly \o QIODevice::ReadOnly + \row \o IO_WriteOnly \o QIODevice::WriteOnly + \row \o IO_ReadWrite \o QIODevice::ReadWrite + \row \o IO_Append \o QIODevice::Append + \row \o IO_Truncate \o QIODevice::Truncate + \row \o IO_Translate \o QIODevice::Text + \row \o IO_ModeMask \o N/A + \row \o IO_Open \o Use QIODevice::isOpen() instead. + \row \o IO_StateMask \o N/A + \row \o IO_Ok \o N/A + \row \o IO_ReadError \o N/A + \row \o IO_WriteError \o N/A + \row \o IO_FatalError \o N/A + \row \o IO_ResourceError \o N/A + \row \o IO_OpenError \o N/A + \row \o IO_ConnectError \o N/A + \row \o IO_AbortError \o N/A + \row \o IO_TimeOutError \o N/A + \row \o IO_UnspecifiedError \o N/A + \endtable + + \section1 QIODeviceSource + + The QIODeviceSource class was used internally in Qt 2.x in + conjunction with QImageConsumer. It was obsoleted in Qt 3.0. + \input porting4-obsoletedmechanism.qdocinc + + \section1 QLabel + + QLabel doesn't enable word-wrap automatically anymore when rich + text is used. You can enable it by calling + QLabel::setWordWrap() or by setting the + \l{QLabel::wordWrap}{wordWrap} property. The reason for this + change is that the old behavior was confusing to many users. + + Also, QLabel no longer offers an \c autoResize property. Instead, + you can call QWidget::setFixedSize() on the label, with + QLabel::sizeHint() as the argument, whenever you change the + contents of the QLabel. + + See also \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} + for a list of QLabel virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \section1 QLayout + + In Qt 4, margins are always handled by layouts; there is no + QLayout::setSupportsMargin() function anymore. + + The deleteAllItems() function is now only available if + \c QT3_SUPPORT is defined. If you maintain a QList of layout + items, you can use qDeleteAll() to remove all the items in one + go. + + In Qt 3, it was possible to change the resizing behavior for layouts + in top-level widgets by adjusting the layout's \c resizeMode property. + In Qt 4, this property has been replaced by the QLayout::sizeConstraint + property which provides more control over how the layout behaves when + resized. + + See also the \l{#qlayoutiterator.section}{section on + QLayoutIterator} and the \l{#qglayoutiterator.section}{section on + QGLayoutIterator}. + + \target qlayoutiterator.section + \section1 QLayoutIterator + + The QLayoutIterator class is obsoleted in Qt 4. It is available + only if \c QT3_SUPPORT is defined. It can be replaced by the + QLayout::itemAt() and QLayout::takeAt() functions, which operate + on indexes. + + \oldcode + QLayoutIterator it = layout()->iterator(); + QLayoutItem *child; + while ((child = it.current()) != 0) { + if (child->widget() == myWidget) { + it.takeCurrent(); + return; + ++it; + } + \newcode + int i = 0; + QLayoutItem *child; + while ((child = layout()->itemAt(i)) != 0) { + if (child->widget() == myWidget) { + layout()->takeAt(i); + return; + } + ++i; + } + \endcode + + \section1 QLineEdit + + See \l{#properties}{Properties} for a list of QLineEdit + properties in Qt 3 that have changed in Qt 4. + + The default value of QLineEdit's \l{QLineEdit::dragEnabled()}{dragEnabled} + property was \c true in Qt 3. In Qt 4, the default value is \c false. + + Note that QLineEdit in Qt 4 is no longer a subclass of QFrame. + If you need to visually style a line edit with a frame, we recommend + either using a QFrame as a container for a QLineEdit or customizing + the line edit with a \l{Qt Style Sheets}{style sheet}. + + \section1 QListBox + + The \c QListBox, \c QListBoxItem, \c QListBoxText, and \c + QListBoxPixmap classes have been renamed Q3ListBox, + Q3ListBoxItem, Q3ListBoxText, and Q3ListBoxPixmap and have been + moved to the Qt3Support library. New Qt applications + should use QListWidget or its base class QListView instead. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \section1 QListView + + The \c QListView, \c QListViewItem, \c QCheckListItem, and \c + QListViewItemIterator classes have been renamed Q3ListView, + Q3ListViewItem, Q3CheckListItem, and Q3ListViewItemIterator, and + have been moved to the Qt3Support library. New Qt + applications should use one of the following four classes + instead: QTreeView or QTreeWidget for tree-like structures; + QListWidget or the new QListView class for one-dimensional lists. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \section1 QLocalFs + + The \c QLocalFs class is no longer part of the public Qt API. It + has been renamed Q3LocalFs and moved to Qt3Support. Use QDir, + QFileInfo, or QFile instead. + + \section1 QMainWindow + + The QMainWindow class has been redesigned in Qt 4 to provide a + more modern look and feel and more flexibility. The API has + changed to reflect that. The old \c QMainWindow class has been + renamed Q3MainWindow and moved to Qt3Support. See the QMainWindow + class documentation for details. + + \omit ### More detail \endomit + + \target qmemarray.section + \section1 QMemArray + + QMemArray has been moved to Qt3Support. It has been replaced + by the QVector class. + + The following table summarizes the API differences between the + two classes. + + \table + \row \o QMemArray::assign(const QMemArray &) \o QVector::operator=() + \row \o QMemArray::assign(const T *, uint) \o See remark below + \row \o QMemArray::duplicate(const QMemArray &) \o QVector::operator=() + \row \o QMemArray::duplicate(const T *, uint) \o See remark below + \row \o QMemArray::setRawData(const T *, uint) \o N/A + \row \o QMemArray::resetRawData(const T *, uint) \o N/A + \row \o QMemArray::find(const T &, uint) \o QVector::indexOf(const T &, int) + \row \o QMemArray::contains(const T &) \o QVector::count(const T &) + \row \o QMemArray::sort() \o \l qSort() + \row \o QMemArray::bsearch(const T &d) \o \l qBinaryFind() + \row \o QMemArray::at(uint) \o QVector::operator[]() + \row \o QMemArray::operator const T *() \o QVector::constData() + \endtable + + Remarks: + + \list 1 + \o QMemArray::assign(const T *, uint) and QMemArray::duplicate(const T *, uint) + can be replaced by QVector::resize() and qCopy(). + + \oldcode + QMemArray array; + ... + array.assign(data, size); + \newcode + QVector vector; + ... + vector.resize(size); + qCopy(data, data + size, vector.begin()); + \endcode + + \o QMemArray is an explicitly shared class, whereas QVector is + implicitly shared. See \l{Explicit Sharing} for more + information. + \endlist + + \section1 QMenuBar + + In Qt 3, QMenuBar inherited from QFrame and QMenuData; in Qt 4, it is + a direct subclass of QWidget. Applications that provided customized + menu bars will need to take advantage of the styling features described + in the \l{Qt Style Sheets} document. + + It is not possible to add widgets to menu bars in Qt 4. + + \section1 QMenuData + + In Qt 4, the QMenu class provides a menu widget that can be used in all + the places where menus are used in an application. Unlike \c QMenuData, + QMenu is designed around the concept of actions, provided by the QAction + class, instead of the identifiers used in Qt 3. + + In Qt 3, it was possible to insert widgets directly into menus by using + a specific \c QMenuData::insertItem() overload. In Qt 4.2 and later, + the QWidgetAction class can be used to wrap widgets for use in Qt 4's + action-based APIs. + + \section1 QMessageBox + + The QMessageBox::iconPixmap() function used to return a "const + QPixmap *". In Qt 4, it returns a QPixmap. + + \section1 QMimeSourceFactory + + The \c QMimeSourceFactory has been renamed Q3MimeSourceFactory + and moved to the Qt3Support library. New Qt applications should + use Qt 4's \l{Resource System} instead. + + \section1 QMovie + + The QMovie API has been revised in Qt 4 to make it more + consistent with the other Qt classes (notably QImageReader). The + table below summarizes the changes. + + \table + \header \o Qt 3 function \o Qt 4 equivalent + \row \o QMovie::connectResize() \o Connect to QMovie::resized() + \row \o QMovie::connectStatus() \o Connect to QMovie::stateChanged() + \row \o QMovie::connectUpdate() \o Connect to QMovie::updated() + \row \o QMovie::disconnectResize() \o Disconnect from QMovie::resized() + \row \o QMovie::disconnectStatus() \o Disconnect from QMovie::stateChanged() + \row \o QMovie::disconnectUpdate() \o Disconnect from QMovie::updated() + \row \o QMovie::finished() \o Use QMovie::state() instead + \row \o QMovie::frameImage() \o Use QMovie::currentImage() instead + \row \o QMovie::frameNumber() \o Use QMovie::currentFrameNumber() instead + \row \o QMovie::framePixmap() \o Use QMovie::currentPixmap() instead + \row \o QMovie::getValidRect() \o Use frameRect() instead + \row \o QMovie::isNull() \o Use QMovie::isValid() instead + \row \o QMovie::pause() \o Use QMovie::setPaused(true) instead + \row \o QMovie::paused() \o Use QMovie::state() instead + \row \o QMovie::pushData() \o N/A + \row \o QMovie::pushSpace() \o N/A + \row \o QMovie::restart() \o Use QMovie::jumpToFrame(0) instead + \row \o QMovie::running() \o Use QMovie::state() instead + \row \o QMovie::step() \o Use QMovie::jumpToFrame() and QMovie::setPaused() instead + \row \o QMovie::step() \o Use QMovie::jumpToNextFrame() instead + \row \o QMovie::steps() \o Use QMovie::currentFrameNumber() and QMovie::frameCount() instead + \row \o QMovie::unpause() \o Use QMovie::setPaused(false) instead + \endtable + + \section1 QMultiLineEdit + + The \c QMultiLineEdit class in Qt 3 was a convenience QTextEdit + subclass that provided an interface compatible with Qt 2's + QMultiLineEdit class. In Qt 4, it is called Q3MultiLineEdit, it + inherits Q3TextEdit, and it is part of Qt3Support. Use QTextEdit + in new code. + + \target qnetworkprotocol.section + \section1 QNetworkProtocol + + The QNetworkProtocol, QNetworkProtocolFactoryBase, + QNetworkProtocolFactory, and QNetworkOperation classes are no + longer part of the public Qt API. They have been renamed + Q3NetworkProtocol, Q3NetworkProtocolFactoryBase, + Q3NetworkProtocolFactory, and Q3NetworkOperation and have been + moved to the Qt3Support library. + + In Qt 4 applications, you can use classes like QFtp and QHttp + directly to perform file-related actions on a remote host. + + \section1 QObject + + QObject::children() now returns a QObjectList instead of a + pointer to a QObjectList. See also the comments on QObjectList + below. + + Use QObject::findChildren() (or qFindChildren() if you need MSVC 6 + compatibility) instead of QObject::queryList(). For example: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 18 + + QObject::killTimers() has been removed because it was unsafe to + use in subclass. (A subclass normally doesn't know whether the + base class uses timers or not.) + + The \c QObject::name property has been renamed + QObject::objectName. + + \c QObject::objectTrees() has been removed. If you are primarly + interested in widgets, use QApplication::allWidgets() or + QApplication::topLevelWidgets(). + + \section1 QObjectDictionary + + The QObjectDictionary class is a synonym for + QAsciiDict. See the \l{#qasciidict.section}{section + on QAsciiDict}. + + \section1 QObjectList + + In Qt 3, the QObjectList class was a typedef for + QPtrList. In Qt 4, it is a typedef for QList. + See the \l{#qptrlist.section}{section on QPtrList}. + + \section1 QPaintDevice + + To reimplement painter backends one previously needed to reimplement + the virtual function QPaintDevice::cmd(). This function is taken out + and should is replaced with the function QPaintDevice::paintEngine() + and the abstract class QPaintEngine. QPaintEngine provides virtual + functions for all drawing operations that can be performed on a + painter backend. + + bitBlt() and copyBlt() are now only compatibility functions. Use + QPainter::drawPixmap() instead. + + \section1 QPaintDeviceMetrics + + All functions that used to be provided by the \c + QPaintDeviceMetrics class have now been moved to QPaintDevice. + + \oldcode + QPaintDeviceMetrics metrics(widget); + int deviceDepth = metrics.depth(); + \newcode + int deviceDepth = widget->depth(); + \endcode + + For compatibility, the old \c QPaintDeviceMetrics class has been + renamed Q3PaintDeviceMetrics and moved to Qt3Support. + + \section1 QPainter + + The QPainter class has undergone some changes in Qt 4 because of + the way rectangles are drawn. In Qt 4, the result of drawing a + QRect with a pen width of 1 pixel is 1 pixel wider and 1 pixel + taller than in Qt 3. + + For compatibility, we provide a Q3Painter class in Qt3Support + that provides the old semantics. See the Q3Painter documentation + for details and for the reasons why we had to make this change. + + The \l{http://doc.trolltech.com/3.3/qpainter.html#CoordinateMode-enum}{QPainter::CoordinateMode} + enum has been removed in Qt 4. All clipping + operations are now defined using logical coordinates and are subject + to transformation operations. + + The + \l{http://doc.trolltech.com/3.3/qpainter.html#RasterOP-enum}{QPainter::RasterOP} + enum has been replaced with QPainter::CompositionMode. + + \section1 QPicture + + In Qt 3, a QPicture could be saved in the SVG file format. In Qt + 4, the SVG support is provided by the QtSvg module, which + includes classes for \e displaying the contents of SVG files. + + If you would like to generate SVG files, you can use the Q3Picture + compatibility class or the QSvgGenerator class introduced in Qt 4.3. + + \section1 QPixmap + + The mask() function has been changed to return a reference to a QBitmap + rather than a pointer. As a result, it is no longer possible simply to + test for a null pointer when determining whether a pixmap has a mask. + Instead, you need to explicitly test whether the mask bitmap is null or + not. + + \oldcode + if (pixmap.mask()) + widget->setMask(*pixmap.mask()); + \newcode + if (!pixmap.mask().isNull()) + widget->setMask(pixmap.mask()); + \endcode + + The \c QPixmap::setOptimization() and \c QPixmap::setDefaultOptimization() + mechanism is no longer available in Qt 4. + +\omit + QPixmap::fromMimeSource(const QString &) -> qPixmapFromMimeSource(const QString &) +\endomit + + \section1 QPointArray + + The \c QPointArray class has been renamed QPolygon in Qt 4 and + has undergone significant changes. In Qt 3, \c QPointArray + inherited from QMemArray. In Qt 4, QPolygon inherits from + QVector. Everything mentioned in the + \l{#qmemarray.section}{section on QMemArray} apply for + QPointArray as well. + + The Qt3Support library contains a Q3PointArray class + that inherits from QPolygon and provides a few functions that + existed in \c QPointArray but no longer exist in QPolygon. These + functions include Q3PointArray::makeArc(), + Q3PointArray::makeEllipse(), and Q3PointArray::cubicBezier(). + In Qt 4, we recommend that you use QPainterPath for representing + arcs, ellipses, and Bezier curves, rather than QPolygon. + + The QPolygon::setPoints() and QPolygon::putPoints() functions + return \c void in Qt 4. The corresponding Qt 3 functions returned + a \c bool indicating whether the array was successfully resized + or not. This can now be checked by checking QPolygon::size() + after the call. + +\omit + X11 Specific: + + ::appDisplay() -> QX11Info::display() + QPaintDevice::x11Display() -> QX11Info::display() + QPaintDevice::x11AppDisplay() -> QX11Info::display() + QPaintDevice::x11Screen() -> QX11Info::appScreen() + QPaintDevice::x11AppScreen() -> ??? + QPaintDevice::x11Depth() -> QX11Info::appDepth() + QPaintDevice::x11ColorMap() -> QX11Info::appColorMap() + QPaintDevice::x11DefaultColorMap() -> ??? + QPaintDevice::x11Visual() -> QX11Info::appVisual() + QPaintDevice::x11DefaultVisual() -> ??? + + QPaintDevice::x11AppDpiX() -> QX11Info::appDpiX() + QPaintDevice::x11AppDpiY() -> QX11Info::appDpiY() + QPaintDevice::x11SetAppDpiX() -> QX11Info::setAppDpiX() + QPaintDevice::x11SetAppDpiY() -> QX11Info::setAppDpiY() + + QPaintDevice::x11AppDepth() -> ??? + QPaintDevice::x11AppCells() -> ??? + QPaintDevice::x11AppRootWindow() -> ??? + QPaintDevice::x11AppColorMap() -> ??? + QPaintDevice::x11AppDefaultColorMap() -> ??? + QPaintDevice::x11AppVisual() -> ??? + QPaintDevice::x11AppDefaultVisual() -> ??? + + End of X11 Specific +\endomit + + \section1 QPopupMenu + + For most purposes, QPopupMenu has been replaced by QMenu in Qt + 4. For compatibility with older applications, Q3PopupMenu provides + the old API and features that are specific to pop-up menus. Note + that, when using Q3PopupMenu, the menu's actions must be \l + {Q3Action}s. + + In Qt 3, it was common practice to add entries to pop-up menus using the + insertItem() function, maintaining identifiers for future use; for + example, to dynamically change menu items. + In Qt 4, menu entries are completely represented + by actions for consistency with other user interface components, such as + toolbar buttons. Create new menus with the QMenu class, and use the + overloaded QMenu::addAction() functions to insert new entries. + If you need to manage a set of actions created for a particular menu, + we suggest that you construct a QActionGroup and add them to that. + + The \l{Qt Examples#Main Windows}{Main Window examples} provided + show how to use Qt's action system to construct menus, toolbars, and other + common user interface elements. + + \section1 QPrinter + + The QPrinter class now expects printing to be set up from a + QPrintDialog. + + \section1 QProcess + + The QProcess class has undergone major improvements in Qt 4. It + now inherits QIODevice, which makes it possible to combine + QProcess with a QTextStream or a QDataStream. + + The old \c QProcess class has been renamed Q3Process and moved to + the Qt3Support library. + + \section1 QProgressBar + + The QProgressBar API has been significantly improved in Qt 4. The + old \c QProgressBar API is available as Q3ProgressBar in the + Qt3Support library. + + \section1 QProgressDialog + + The QProgressDialog API has been significantly improved in Qt 4. + The old \c QProgressDialog API is available as Q3ProgressDialog + in the Qt3Support library. + + See \l{#properties}{Properties} for a list of QProgressDialog + properties in Qt 3 that have changed in Qt 4. + + \section1 QPtrCollection + + The \c QPtrCollection abstract base class has been renamed + Q3PtrCollection moved to the Qt3Support library. + There is no direct equivalent in Qt 4. + + \omit + ### + The QPtrCollection entry is unsatisfactory. The xref is missing + its list and saying "no direct equivalent" with so suggestions + seems feeble. + \endomit + + See \l{Generic Containers} for a list of Qt 4 containers. + + \section1 QPtrDict + + \c QPtrDict and \c QPtrDictIterator have been renamed + Q3PtrDict and Q3PtrDictIterator and have been moved to the + Qt3Support library. They have been replaced by the + more modern QHash and QMultiHash classes and + their associated iterator classes. + + When porting old code that uses Q3PtrDict to Qt 4, there are + four classes that you can use: + + \list + \o QMultiHash + \o QMultiHash + \o QHash + \o QHash + \endlist + + (You can naturally use other types than \c{void *} for the key + type, e.g. \c{QWidget *}.) + + To port Q3PtrDict to Qt 4, read the \l{#qdict.section}{section + on QDict}, mentally substituting \c{void *} for QString. + + \target qptrlist.section + \section1 QPtrList + + QPtrList, QPtrListIterator, and QPtrListStdIterator have + been moved to the Qt3Support library. They have been + replaced by the more modern QList and QLinkedList classes and + their associated iterator classes. + + When porting to Qt 4, you have the choice of using QList or + QLinkedList as alternatives to QValueList. QList has an + index-based API and provides very fast random access + (QList::operator[]), whereas QLinkedList has an iterator-based + API. + + The following table summarizes the API differences between + QPtrList and QList: + + \table + \header \o QPtrList function \o QList equivalent + \row \o QPtrList::contains(const T *) \o QList::count(T *) + \row \o QPtrList::containsRef(const T *) \o QList::count(T *) + \row \o QPtrList::find(const T *) \o See remark below + \row \o QPtrList::findRef(const T *) \o See remark below + \row \o QPtrList::getFirst() \o QList::first() + \row \o QPtrList::getLast() \o QList::last() + \row \o QPtrList::inSort(const T *) \o N/A + \row \o QPtrList::remove(const T *) \o QList::removeAll(T *) + \row \o QPtrList::remove(uint) \o QList::removeAt(int) + \row \o QPtrList::removeNode(QLNode *) \o N/A + \row \o QPtrList::removeRef(const T *) \o QList::removeAll(T *) + \row \o QPtrList::sort() \o See remark below + \row \o QPtrList::takeNode(QLNode *) \o N/A + \row \o QPtrList::toVector(QGVector *) \o See remark below + \endtable + + Remarks: + + \list 1 + \o QPtrList::toVector(QGVector *) can be replaced by + QVector::resize() and qCopy(). + + \oldcode + QPtrList list; + ... + QPtrVector vector; + list.toVector(&vector); + \newcode + QList list; + ... + QVector vector; + vector.resize(list.size()); + qCopy(list.begin(), list.end(), vector.begin()); + \endcode + + \o QPtrList::sort() relied on the virtual compareItems() to + sort items. In Qt 4, you can use \l qSort() instead and pass + your "compare item" function as an argument. + + \o QPtrList::find(const T *) returns an iterator, whereas + QList::indexOf(T *) returns an index. To convert an index + into an iterator, add the index to QList::begin(). + + \o QPtrList::removeFirst() and QPtrList::removeLast() return a \c + bool that indicates whether the element was removed or not. + The corresponding QList functions return \c void. You can + achieve the same result by calling QList::isEmpty() before + attempting to remove an item. + \endlist + + If you use QPtrList's auto-delete feature (by calling + QPtrList::setAutoDelete(true)), you need to do some more work. + You have two options: Either you call \c delete yourself whenever + you remove an item from the container, or you can use QList + instead of QList (i.e. store values directly instead of + pointers to values). Here, we'll see when to call \c delete. + + \omit + (See \l{What's Wrong with Auto-Delete} for an explanation of why + the Qt 4 containers don't offer that feature.) + \endomit + + The following table summarizes the idioms that you need to watch + out for if you want to call \c delete yourself. + + \table + \header \o QPtrList idiom \o QList idiom + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 19 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 20 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 21 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 22 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 23 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 24 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 25 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 26 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 27 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 28 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 29 + (removes the current item) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 30 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 31 + + (also called from QPtrList's destructor) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 32 + + In 99% of cases, the following idiom also works: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 33 + + However, it may lead to crashes if \c list is referenced from + the value type's destructor, because \c list contains + dangling pointers until clear() is called. + \endtable + + Be aware that QPtrList's destructor automatically calls clear(). + If you have a QPtrList data member in a custom class and use the + auto-delete feature, you will need to call \c delete on all the + items in the container from your class destructor to avoid a + memory leak. + + QPtrList had the concept of a "current item", which could be used + for traversing the list without using an iterator. When porting + to Qt 4, you can use the Java-style QListIterator (or + QMutableListIterator) class instead. The following table + summarizes the API differences: + + \table + \header \o QPtrList function \o QListIterator equivalent + \row \o QPtrList::at() \o N/A + \row \o QPtrList::current() \o QMutableListIterator::value() + \row \o QPtrList::currentNode() \o N/A + \row \o QPtrList::findNext(const T *) \o QListIterator::findNext(const T *) + \row \o QPtrList::findNextRef(const T *) \o QListIterator::findNext(const T *) + \row \o QPtrList::first() \o QPtrList::toFront() + \row \o QPtrList::last() \o QPtrList::toBack() + \row \o QPtrList::next() \o QPtrList::next() + \row \o QPtrList::prev() \o QPtrList::previous() + \row \o QPtrList::remove() \o QMutableListIterator::remove() + \row \o QPtrList::take() \o QMutableListIterator::remove() + \endtable + + Be aware that QListIterator has a different way of iterating than + QPtrList. A typical loop with QPtrList looks like this: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 34 + + Here's the equivalent QListIterator loop: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 35 + + Finally, QPtrListIterator must also be ported. There are no + fewer than four iterator classes that can be used as a + replacement: QList::const_iterator, QList::iterator, + QListIterator, and QMutableListIterator. The most straightforward + class to use when porting is QMutableListIterator (if you + modify the list through the iterator) or QListIterator (if + you don't). The following table summarizes the API differences: + + \table + \header \o QPtrListIterator function \o Qt 4 equivalent + \row \o QPtrListIterator::atFirst() \o !QListIterator::hasPrevious() (notice the \c{!}) + \row \o QPtrListIterator::atLast() \o !QListIterator::hasNext() (notice the \c{!}) + \row \o QPtrListIterator::count() \o QList::count() or QList::size() + \row \o QPtrListIterator::current() \o QMutableListIterator::value() + \row \o QPtrListIterator::isEmpty() \o QList::isEmpty() + \row \o QPtrListIterator::toFirst() \o QListIterator::toFront() + \row \o QPtrListIterator::toLast() \o QListIterator::toBack() + \row \o QPtrListIterator::operator() \o QMutableListIterator::value() + \row \o QPtrListIterator::operator*() \o QMutableListIterator::value() + \endtable + + Again, be aware that QListIterator has a different way of + iterating than QPtrList. A typical loop with QPtrList looks like + this: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 36 + + Here's the equivalent QListIterator loop: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 37 + + Finally, QPtrListStdIterator must also be ported. This is + easy, because QList also provides STL-style iterators + (QList::iterator and QList::const_iterator). + + \section1 QPtrQueue + + QPtrQueue has been moved to the Qt3Support library. + It has been replaced by the more modern QQueue class. + + The following table summarizes the differences between + QPtrQueue and QQueue: + + \table + \header \o QPtrQueue function \o QQueue equivalent + \row \o QPtrQueue::autoDelete() \o See discussion below + \row \o QPtrQueue::count() \o QQueue::count() or QQueue::size() (equivalent) + \row \o QPtrQueue::current() \o QQueue::head() + \row \o QPtrQueue::remove() \o QQueue::dequeue() + \row \o QPtrQueue::setAutoDelete() \o See discussion below + \endtable + + If you use QPtrQueue's auto-delete feature (by calling + QPtrQueue::setAutoDelete(true)), you need to do some more work. + You have two options: Either you call \c delete yourself whenever + you remove an item from the container, or you can use QQueue + instead of QQueue (i.e. store values directly instead of + pointers to values). Here, we will show when to call \c delete. + + \omit + (See \l{What's Wrong with Auto-Delete} for an explanation of why + the Qt 4 containers don't offer that feature.) + \endomit + + \table + \header \o QPtrQueue idiom \o QQueue idiom + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 38 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 39 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 40 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 41 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 42 + + (also called from QPtrQueue's destructor) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 43 + + In 99% of cases, the following idiom also works: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 44 + + However, it may lead to crashes if \c queue is referenced + from the value type's destructor, because \c queue contains + dangling pointers until clear() is called. + \endtable + + \section1 QPtrStack + + QPtrStack has been moved to the Qt3Support library. + It has been replaced by the more modern QStack class. + + The following table summarizes the differences between + QPtrStack and QStack: + + \table + \header \o QPtrStack function \o QStack equivalent + \row \o QPtrStack::autoDelete() \o See discussion below + \row \o QPtrStack::count() \o QStack::count() or QStack::size() (equivalent) + \row \o QPtrStack::current() \o QStack::top() + \row \o QPtrStack::remove() \o QStack::pop() + \row \o QPtrStack::setAutoDelete() \o See discussion below + \endtable + + If you use QPtrStack's auto-delete feature (by calling + QPtrStack::setAutoDelete(true)), you need to do some more work. + You have two options: Either you call \c delete yourself whenever + you remove an item from the container, or you can use QStack + instead of QStack (i.e. store values directly instead of + pointers to values). Here, we will show when to call \c delete. + + \omit + (See \l{What's Wrong with Auto-Delete} for an explanation of why + the Qt 4 containers don't offer that feature.) + \endomit + + \table + \header \o QPtrStack idiom \o QStack idiom + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 45 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 46 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 47 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 48 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 49 + + (also called from QPtrStack's destructor) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 50 + + In 99% of cases, the following idiom also works: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 51 + + However, it may lead to crashes if \c stack is referenced + from the value type's destructor, because \c stack contains + dangling pointers until clear() is called. + \endtable + + \section1 QPtrVector + + QPtrVector has been moved to Qt3Support. It has been replaced + by the more modern QVector class. + + When porting to Qt 4, you can use QVector as an alternative + to QPtrVector. The APIs of QPtrVector and QVector are + somewhat similar. The main issue is that QPtrVector supports + auto-delete whereas QVector doesn't. + + \omit + (See \l{What's Wrong with Auto-Delete} for an explanation of why + the Qt 4 containers don't offer that feature.) + \endomit + + The following table summarizes the API differences between the + two classes: + + \table + \header \o QPtrVector function \o QVector equivalent + \row \o QPtrVector::autoDelete() \o See discussion below + \row \o QPtrVector::bsearch(const T *) \o \l qBinaryFind() + \row \o QPtrVector::contains(const T *) \o QVector::count(T *) + \row \o QPtrVector::containsRef(const T *) \o QVector::count(T *) + \row \o QPtrVector::count() \o See remark below + \row \o QPtrVector::insert(uint, T *) \o See remark below + \row \o QPtrVector::isNull() \o N/A + \row \o QPtrVector::remove(uint) \o See remark below + \row \o QPtrVector::setAutoDelete() \o See discussion below + \row \o QPtrVector::sort() \o \l qSort() + \row \o QPtrVector::take(uint) \o See remark below + \row \o QPtrVector::toList(QGList *) \o QList::QList(const QVector &) + \endtable + + Remarks: + + \list 1 + \o QPtrVector::insert(uint, T *) sets an item to store a certain + pointer value. This is \e not the same as QVector::insert(int, T *), + which creates space for the item by moving following items by + one position. Use \c{vect[i] = ptr} to set a QVector item to + a particular value. + \o QPtrVector::remove(uint) sets an item to be 0. This is \e not + the same as QVector::removeAt(int), which entirely erases the + item, reducing the size of the vector. Use \c{vect[i] = 0} to + set a QVector item to 0. + \o Likewise, QPtrVector::take(uint) sets an item to be 0 and + returns the previous value of the item. Again, this is easy to + achieve using QVector::operator[](). + \o QPtrVector::count() returns the number of non-null items in + the vector, whereas QVector::count() (like QVector::size()) + returns the number of items (null or non-null) in the vector. + Fortunately, it's not too hard to simulate QPtrVector::count(). + + \oldcode + int numValidItems = vect.count(); + \newcode + int numValidItems = vect.size() - vect.count(0); + \endcode + \endlist + + If you use QVector's auto-delete feature (by calling + QVector::setAutoDelete(true)), you need to do some more work. You + have two options: Either you call \c delete yourself whenever you + remove an item from the container, or you use QVector instead + of QVector (i.e. store values directly instead of pointers + to values). Here, we'll see when to call \c delete. + + The following table summarizes the idioms that you need to watch + out for if you want to call \c delete yourself. + + \table + \header \o QPtrVector idiom \o QVector idiom + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 52 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 53 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 54 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 55 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 56 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 57 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 58 + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 59 + \row + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 60 + + (also called from QPtrVector's destructor) + + \o + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 61 + + In 99% of cases, the following idiom also works: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 62 + + However, it may lead to crashes if \c vect is referenced from + the value type's destructor, because \c vect contains + dangling pointers until clear() is called. + \endtable + + Be aware that QPtrVector's destructor automatically calls + clear(). If you have a QPtrVector data member in a custom class + and use the auto-delete feature, you will need to call \c delete + on all the items in the container from your class destructor to + avoid a memory leak. + + \section1 QPushButton + + See \l{#properties}{Properties} for a list of QPushButton + properties in Qt 3 that have changed in Qt 4. + + \section1 QRangeControl + + In Qt 3, various "range control" widgets (QDial, QScrollBar, + QSlider, and QSpin) inherited from both QWidget and + \c QRangeControl. + + In Qt 4, \c QRangeControl has been replaced with the new + QAbstractSlider and QAbstractSpinBox classes, which inherit from + QWidget and provides similar functionality. Apart from eliminating + unnecessary multiple inheritance, the new design allows + QAbstractSlider to provide signals, slots, and properties. + + The old \c QRangeControl class has been renamed Q3RangeControl + and moved to the Qt3Support library, together with + the (undocumented) \c QSpinWidget class. + + If you use \c QRangeControl as a base class in your application, + you can switch to use QAbstractSlider or QAbstractSpinBox instead. + + \oldcode + class VolumeControl : public QWidget, public QRangeControl + { + ... + protected: + void valueChange() { + update(); + emit valueChanged(value()); + } + void rangeChange() { + update(); + } + void stepChange() { + update(); + } + }; + \newcode + class VolumeControl : public QAbstractSlider + { + ... + protected: + void sliderChange(SliderChange change) { + update(); + if (change == SliderValueChange) + emit valueChanged(value()); + } + }; + \endcode + + \section1 QRegExp + + The search() and searchRev() functions have been renamed to indexIn() + and lastIndexIn() respectively. + + \section1 QRegion + + The following changes have been made to QRegion in Qt 4: + + \list + \o There is no longer any difference between a \e null region and + an \e empty region. Use isEmpty() in most places where you + would have used a null QRegion. + \o QRegion::rects() used to return a QMemArray. It now returns + a QVector. + \endlist + + \section1 QScrollBar + + See \l{#properties}{Properties} for a list of QScrollBar + properties in Qt 3 that have changed in Qt 4. + + \section1 QScrollView + + The \c QScrollView class has been renamed Q3ScrollView and moved + to the Qt3Support library. It has been replaced by + the QAbstractScrollArea and QScrollArea classes. + + Note that Qt 4 in general uses the QScrollArea::widget() function + where Qt 3 used QScrollView::viewport(). The rationale for this is + that it is no longer possible to draw directly on a scroll + area. The QScrollArea::widget() function returns the widget set on + the scroll area. + + \c QScrollView was designed to work around the 16-bit limitation + on widget coordinates found on most window systems. In Qt 4, this + is done transparently for \e all widgets, so there is no longer a + need for such functionality in \c QScrollView. For that reason, + the new QAbstractScrollArea and QScrollArea classes are much more + lightweight, and concentrate on handling scroll bars. + + \section1 QServerSocket + + The \c QServerSocket class has been renamed Q3ServerSocket and + moved to the Qt3Support library. In Qt 4, it has been + replaced by QTcpServer. + + With Q3ServerSocket, connections are accepted by reimplementing a + virtual function (Q3ServerSocket::newConnection()). With + QTcpServer, on the other hand, you don't need to subclass. + Instead, simply connect to the QTcpServer::newConnection() + signal. + + \section1 QSettings + + The QSettings class has been rewritten to be more robust and to + respect existing standards (e.g., the INI file format). The API + has also been extensively revised. The old API is still provided + when Qt 3 support is enabled. + + Since the format and location of settings have changed between Qt + 3 and Qt 4, the Qt 4 version of your application won't recognize + settings written using Qt 3. + + \section1 QShared + + The \c QShared class has been obsoleted by the more powerful + QSharedData and QSharedDataPointer as a means of creating custom + implicitly shared classes. It has been renamed Q3Shared moved to + the Qt3Support library. + + An easy way of porting to Qt 4 is to include this class into your + project and to use it instead of \c QShared: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63 + + If possible, we recommend that you use QSharedData and + QSharedDataPointer instead. They provide thread-safe reference + counting and handle all the reference counting behind the scenes, + eliminating the risks of forgetting to increment or decrement the + reference count. + + \section1 QSignal + + The QSignal class has been renamed to Q3Signal and moved to the + Qt3Support library. The preferred approach is to create your own + QObject subclass with a signal that has the desired signature. + Alternatively, you can call QMetaObject::invokeMethod() if you + want to invoke a slot. + + \section1 QSimpleRichText + + QSimpleRichText has been obsoleted by QTextDocument. It has + bene renamed Q3SimpleRichText and moved to the Qt3Support + library. + + Previously, you would do the following with Q3SimpleRichText: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63a + + However, with QTextDocument, you use the following code instead: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63b + + See \l{Rich Text Processing} for an overview of the Qt 4 rich + text classes. + + \section1 QSlider + + The QSlider::sliderStart() and QSlider::sliderRect() functions + have been removed. + + The slider's rect can now be retrieved using the code snippet below: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63c + + In addition, the direction of a vertical QSlider has changed, + i.e. the bottom is now the minimum, and the top the maximum. You + can use the QAbstractSlider::invertedAppearance property to + control this behavior. + + See \l{#properties}{Properties} for a list of QSlider properties + in Qt 3 that have changed in Qt 4. + + \section1 QSocket + + The \c QSocket class has been renamed Q3Socket and moved to the + Qt3Support library. In Qt 4, it has been replaced by + the QTcpSocket class, which inherits most of its functionality + from QAbstractSocket. + + \section1 QSocketDevice + + The \c QSocketDevice class has been renamed Q3SocketDevice and + moved to the Qt3Support library. In Qt 4, there is no + direct equivalent to Q3SocketDevice: + + \list + \o If you use Q3SocketDevice in a thread to perform blocking network + I/O (a technique encouraged by the \e{Qt Quarterly} article + \l{http://doc.trolltech.com/qq/qq09-networkthread.html}{Unblocking Networking}), + you can now use QTcpSocket, QFtp, or QHttp instead, which can now be used from + non-GUI threads. + + \o If you use Q3SocketDevice for UDP, you can now use QUdpSocket instead. + + \o If you use Q3SocketDevice for other uses, Qt 4 offers no + alternative right now. However, there is a \c QAbstractSocketEngine + internal class that offers a low-level socket API similar to + Q3SocketDevice. Should the need for such functionality arise in + Qt 4 applications, we will consider making this class public in a + future release. + \endlist + + \section1 QSortedList + + The QSortedList class has been deprecated since Qt 3.0. In Qt + 4, it has been moved to the Qt3Support library. + + In new code, we recommend that you use QList instead and use + \l qSort() to sort the items. + + \section1 QSplitter + + The function setResizeMode() has been moved into Qt3Support. Set + the stretch factor in the widget's size policy to get equivalent + functionality. + + The obsolete function drawSplitter() has been removed. Use + QStyle::drawPrimitive() to acheive similar functionality. + + \section1 QSpinBox + + See \l{#properties}{Properties} for a list of QSpinBox properties + in Qt 3 that have changed in Qt 4. + + \section1 QSqlCursor + + The \c QSqlCursor class has been renamed Q3SqlCursor and moved to + the Qt3Support library. In Qt 4, you can use + QSqlQuery, QSqlQueryModel, or QSqlTableModel, depending on + whether you want a low-level or a high-level interface for + accessing databases. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlDatabase + + QSqlDatabase is now a smart pointer that is passed around by + value. Simply replace all QSqlDatabase pointers by QSqlDatabase + objects. + + \section1 QSqlEditorFactory + + The \c QSqlEditorFactory class has been renamed + Q3SqlEditorFactory and moved to Qt3Support. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlError + + The enum \c{Type} was renamed to \c{ErrorType}, The values were renamed as well: + + \list + \o None - use NoError instead + \o Connection - use ConnectionError instead + \o Statement - use StatementError instead + \o Transaction - use TransactionError instead + \o Unknown - use UnknownError instead + \endlist + + \section1 QSqlFieldInfo + + The QSqlFieldInfo class has been moved to Qt3Support. Its + functionality is now provided by the QSqlField class. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlForm + + The \c QSqlForm class has been renamed Q3SqlForm and moved to the + Qt3Support library. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlPropertyMap + + The \c QSqlPropertyMap class has been renamed Q3SqlPropertyMap + moved to the Qt3Support library. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlQuery + + QSqlQuery::prev() was renamed to QSqlQuery::previous(). + QSqlQuery::prev() remains, but it just calls previous(). + QSqlQuery no longer has any virtual methods, i.e., exec(), + value(), seek(), next(), prev(), first(), last(), and the + destructor are no longer virtual. + + \section1 QSqlRecord + + QSqlRecord behaves like a vector now, QSqlRecord::insert() will + actually insert a new field instead of replacing the existing + one. + + \section1 QSqlRecordInfo + + The QSqlRecordInfo class has been moved to Qt3Support. Its + functionality is now provided by the QSqlRecord class. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QSqlSelectCursor + + The \c QSqlSelectCursor class has been renamed Q3SqlSelectCursor + and moved to the Qt3Support library. + + See \l{QtSql Module} for an overview of the new SQL classes. + + \section1 QStoredDrag + + The \c QStoredDrag class has been renamed Q3StoredDrag and moved + to the Qt3Support library. In Qt 4, use QMimeData + instead and call QMimeData::setData() to set the data. + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QStr(I)List + + The QStrList and QStrIList convenience classes have been + deprecated since Qt 2.0. In Qt 4, they have been moved to the + Qt3Support library. If you used any of these, we + recommend that you use QStringList or QList instead. + + \section1 QStr(I)Vec + + The QStrVec and QStrIVec convenience classes have been deprecated + since Qt 2.0. In Qt 4, they have been moved to Qt3Support. If you + used any of these, we recommend that you use QStringList or + QList instead. + + \section1 QString + + Here are the main issues to be aware of when porting QString to + Qt 4: + + \list 1 + \o The QString::QString(QChar) constructor performed implicit + conversion in Qt 3. Now, you will need a cast to convert a + QChar to a QString. + + \o The QString::QString(const QByteArray &) constructor used to + stop at the first '\\0' it encountered, for compatibility + with Qt 1. This quirk has now been fixed; in Qt 4, the + resulting QString always has the same length as the + QByteArray that was passed to the constructor. + + \o The QString::null static constant has been deprecated in Qt + 4. For compatibility, Qt 4 provides a QString::null symbol + that behaves more or less the same as the old constant. The + new idiom is to write QString() instead of QString::null, or + to call clear(). + + \oldcode + str1 = QString::null; + if (str2 == QString::null) + do_something(QString::null); + \newcode + str1.clear(); + if (str2.isNull()) + do_something(QString()); + \endcode + + In new code, we recommend that you don't rely on the + distinction between a null string and a (non-null) empty + string. See \l{Distinction Between Null and Empty Strings} + for details. + + \o QString::latin1() and QString::ascii() have been replaced + with QString::toLatin1() and QString::toAscii(), which return + a QByteArray instead of a (non-reentrant) \c{const char *}. + For consistency, QString::utf8() and QString::local8Bit(), + which already returned a QByteArray (actually a \c QCString), + have been renamed QString::toUtf8() and + QString::toLocal8Bit(). + + To obtain a \c{const char *} pointer to ASCII or Latin-1 data, + use QString::toAscii() or QString::toLatin1() to obtain a + QByteArray containing the data, then call QByteArray::constData() + to access the character data directly. Note that the pointer + returned by this function is only valid for the lifetime of the + byte array; you should avoid taking a pointer to the data + contained in temporary objects. + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 64 + + In the above example, the \c goodData pointer is valid for the lifetime + of the \c asciiData byte array. If you need to keep a copy of the data + in a non-Qt data structure, use standard C memory allocation and string + copying functions to do so \e before destroying the byte array. + + \o QString::at() returned a non-const reference, whereas the + new QString::at() returns a const value. Code like + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 65 + + will no longer compile. Instead, use QString::operator[]: + + \snippet doc/src/snippets/code/doc_src_porting4.qdoc 66 + + \o The QString::contains(\e x) function (where \e x is a + character or a string) has been renamed QString::count(\e x). + In addition, there now exists a set of QString::contains() + functions that returns a boolean value. Replace old calls to + contains() with either count() or contains(), depending on + whether you care about the specific number of occurrences of + a character in the string or only care about whether the + string contains that character or not. + + \o Many functions in QString had a \c bool parameter that + specified case sensitivity. In Qt 4, in the interest of code + readability and maintainability, the \c bool parameters have + been replaced by the Qt::CaseSensitivity enum, which can take + the values Qt::CaseSensitive and Qt::CaseInsensitive. + + \oldcode + if (url.startsWith("http:", false)) + ... + \newcode + if (url.startsWith("http:", Qt::CaseInsensitive)) + ... + \endcode + + \o The QString::setExpand(uint, QChar) function, which already + was obsolete in Qt 3, is no longer available. Use + QString::operator[] instead. + + \oldcode + str.setExpand(32, '$'); + \newcode + str[32] = '$'; + \endcode + + \o The \c QT_NO_ASCII_CAST and \c QT_NO_CAST_ASCII macros have + been renamed \c QT_NO_CAST_TO_ASCII and \c + QT_NO_CAST_FROM_ASCII, respectively. + + \o The QString::data() used to return the same as + QString::ascii(). It now returns a pointer to the Unicode + data stored in the QString object. Call QString::ascii() if + you want the old behavior. + + \o QString::arg() now converts two-digit place markers, allowing + up to 99 place markers to be used in any given string. + + \o Comparisons between QStrings and \c NULL in order to determine + whether strings are empty are no longer allowed. + Use \l{QString::}{isEmpty()} instead. + + \endlist + + \section1 QStringList + + QStringList now inherits from QList and can no longer be + converted to a QValueList. Since QValueList inherits QList a + cast will work as expected. + + This change implies some API incompatibilities for QStringList. + For example, at() returns the string, not an iterator. See the + \l{#qvaluelist.section}{section on QValueList} for details. + + The static QStringList::split() function for splitting strings into + lists of smaller strings has been replaced by QString::split(), + which returns a QStringList. + + \section1 QStyle + + The QStyle API has been overhauled and improved. Most of the information on + why this change was done is described in \l{The Qt 4 Style API}{the QStyle overview}. + + Since QStyle is mostly used internally by Qt's widgets and styles and since + it is not essential to the good functioning of an application, there is no + compatibility path. This means that we have changed many enums and + functions and the qt3to4 porting tool will not change much in your qstyle + code. To ease the pain, we list some of the major changes here. + + QStyleOption has taken on a more central role and is no longer an optional + argument, please see the QStyleOption documentation for more information. + + The QStyle::StyleFlags have been renamed QStyle::StateFlags and are now prefixed State_ + instead of Style_, in addition the Style_ButtonDefault flag has moved to + QStyleOptionButton. + + The QStyle::PrimitiveElement enumeration has undergone extensive change. + Some of the enums were moved to QStyle::ControlElement, some were removed + and all were renamed. This renaming is not done by the qt3to4 porting tool, + so you must do it yourself. The table below shows how things look + now. + + \table + \header \o Old name \o New name \o Remark + \row \o \c PE_ButtonCommand \o QStyle::PE_PanelButtonCommand + \row \o \c PE_ButtonDefault \o QStyle::PE_FrameDefaultButton + \row \o \c PE_ButtonBevel \o QStyle::PE_PanelButtonBevel + \row \o \c PE_ButtonTool \o QStyle::PE_PanelButtonTool + \row \o \c PE_ButtonDropDown \o QStyle::PE_IndicatorButtonDropDown + \row \o \c PE_FocusRect \o QStyle::PE_FrameFocusRect + \row \o \c PE_ArrowUp \o QStyle::PE_IndicatorArrowUp + \row \o \c PE_ArrowDown \o QStyle::PE_IndicatorArrowDown + \row \o \c PE_ArrowRight \o QStyle::PE_IndicatorArrowRight + \row \o \c PE_ArrowLeft \o QStyle::PE_IndicatorArrowLeft + \row \o \c PE_SpinBoxUp \o QStyle::PE_IndicatorSpinUp + \row \o \c PE_SpinBoxDown \o QStyle::PE_IndicatorSpinDown + \row \o \c PE_SpinBoxPlus \o QStyle::PE_IndicatorSpinPlus + \row \o \c PE_SpinBoxMinus \o QStyle::PE_IndicatorSpinMinus + \row \o \c PE_SpinBoxSlider \o QStyle::CE_SpinBoxSlider \o uses QStyle::drawControl() + \row \o \c PE_Indicator \o QStyle::PE_IndicatorCheckBox + \row \o \c PE_IndicatorMask \o N/A \o use QStyle::styleHint() to retrieve mask + \row \o \c PE_ExclusiveIndicator \o QStyle::PE_IndicatorRadioButton + \row \o \c PE_ExclusiveIndicatorMask \o N/A \o use QStyle::styleHint() to retrieve mask + \row \o \c PE_DockWindowHandle \o QStyle::PE_IndicatorToolBarHandle + \row \o \c PE_DockWindowSeparator \o QStyle::PE_Q3DockWindowSeparator + \row \o \c PE_DockWindowResizeHandle \o QStyle::PE_IndicatorDockWindowResizeHandle + \row \o \c PE_DockWindowTitle \o QStyle::CE_DockWindowTitle \o uses QStyle::drawControl() + \row \o \c PE_Splitter \o QStyle::CE_Splitter \o uses QStyle::drawControl() + \row \o \c PE_Panel \o QStyle::PE_Frame + \row \o \c PE_PanelMenu \o QStyle::PE_FrameMenu + \row \o \c PE_PanelMenuBar \o QStyle::PE_PanelMenuBar + \row \o \c PE_PanelDockWindow \o QStyle::PE_FrameDockWindow + \row \o \c PE_TabBarBase \o QStyle::PE_FrameTabBarBase + \row \o \c PE_HeaderSection \o QStyle::CE_HeaderSection \o uses QStyle::drawControl() + \row \o \c PE_HeaderArrow \o QStyle::PE_IndicatorHeaderArrow + \row \o \c PE_StatusBarSection \o QStyle::PE_FrameStatusBar + \row \o \c PE_Separator \o QStyle::PE_Q3Separator + \row \o \c PE_SizeGrip \o QStyle::CE_SizeGrip \o uses QStyle::drawControl() + \row \o \c PE_CheckMark \o QStyle::PE_IndicatorMenuCheckMark + \row \o \c PE_ScrollBarAddLine \o QStyle::CE_ScrollBarAddLine \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarSubLine \o QStyle::CE_ScrollBarSubLine \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarAddPage \o QStyle::CE_ScrollBarAddPage \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarSubPage \o QStyle::CE_ScrollBarSubPage \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarSlider \o QStyle::CE_ScrollBarSlider \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarFirst \o QStyle::CE_ScrollBarFirst \o uses QStyle::drawControl() + \row \o \c PE_ScrollBarLast \o QStyle::CE_ScrollBarLast \o uses QStyle::drawControl() + \row \o \c PE_ProgressBarChunk \o QStyle::PE_IndicatorProgressChunk + \row \o \c PE_PanelLineEdit \o QStyle::PE_FrameLineEdit + \row \o \c PE_PanelTabWidget \o QStyle::PE_FrameTabWidget + \row \o \c PE_WindowFrame \o QStyle::PE_FrameWindow + \row \o \c PE_CheckListController \o QStyle::PE_Q3CheckListController + \row \o \c PE_CheckListIndicator \o QStyle::PE_Q3CheckListIndicator + \row \o \c PE_CheckListExclusiveIndicato\o QStyle::PE_Q3CheckListExclusiveIndicator + \row \o \c PE_PanelGroupBox \o QStyle::PE_FrameGroupBox + \row \o \c PE_TreeBranch \o QStyle::PE_IndicatorBranch + \row \o \c PE_RubberBand \o QStyle::CE_RubberBand \o uses QStyle::drawControl() + \row \o \c PE_PanelToolBar \o QStyle::PE_PanelToolBar + \row \o \c PE_ToolBarHandle \o QStyle::PE_IndicatorToolBarHandle + \row \o \c PE_ToolBarSeparator \o QStyle::PE_IndicatorToolBarSeparator + \endtable + + The QStyle::drawControlMask() and QStyle::drawComplexControlMask() + functions have been removed. They are replaced with a style hint. + + The QStyle::drawItem() overloads that took both a pixmap and a string have + been removed. Use QStyle::drawItemText() and QStyle::drawItemPixmap() directly. + + The QStyle::itemRect() overload that took both a pixmap and a string is also removed, use + either QStyle::itemTextRect() or QStyle::itemPixmapRect() instead. + + \section1 QStyleSheet + + The QStyleSheet and QStyleSheetItem classes have been renamed + Q3StyleSheet and Q3StyleSheetItem, and have been moved to the + Qt3Support library. + + See \l{Rich Text Processing} for an overview of the Qt 4 rich + text classes, and \l{Qt Style Sheets} for a description of + CSS-like style sheet support in Qt 4.2 and above. + + \section1 QSyntaxHighlighter + + The \c QSyntaxHighlighter class from Qt 3 has been renamed + Q3SyntaxHighlighter and moved to the Qt3Support library. Since Qt + 4.1, it has been replaced by a new QSyntaxHighlighter class based + on Qt 4's new rich text engine. + + \section1 QTabBar + + See \l{#properties}{Properties} for a list of QTabBar properties + in Qt 3 that have changed in Qt 4. + + \section1 QTabDialog + + The \c QTabDialog class is no longer part of the public Qt API. + It has been renamed Q3TabDialog and moved to Qt3Support. In Qt 4 + applications, you can easily obtain the same result by combining + a QTabWidget with a QDialog and provide \l{QPushButton}s + yourself. + + See also the \l{dialogs/tabdialog} example, which shows how to + implement tab dialogs in Qt 4. + + \section1 QTabWidget + + See \l{#properties}{Properties} for a list of QTabWidget + properties in Qt 3 that have changed in Qt 4. + + \section1 QTable + + The \c QTable, \c QTableItem, \c QComboTableItem, \c + QCheckTableItem, and \c QTableSelection classes have been renamed + Q3Table, Q3TableItem, Q3ComboTableItem, Q3CheckTableItem, and + Q3TableSelection and moved to the Qt3Support library. + New Qt applications should use the new QTableWidget or QTableView + class instead. + + Some of these classes behave differently with respect to the way + they handle \c NULL pointers. For example, Q3TableItem::setPixmap() + no longer accepts \c NULL or 0 to indicate that the item should + contain a null pixmap; in this case, a null pixmap should be + constructed and passed explicitly to the function. + + See \l{Model/View Programming} for an overview of the new item + view classes. + + \section1 QTextCodec + + The loadCharmap() and loadCharmapFromFile() functions are no longer + available in Qt 4. You need to create your own codec if you want to + create a codec based on a POSIX2 charmap definition. + + \section1 QTextDrag + + The \c QTextDrag class has been renamed Q3TextDrag and moved to + the Qt3Support library. In Qt 4, use QMimeData + instead and call QMimeData::setText() to set the data. + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QTextEdit + + The old QTextEdit and QTextBrowser classes have been renamed + Q3TextEdit and Q3TextBrowser, and have been moved to Qt3Support. + The new QTextEdit and QTextBrowser have a somewhat different API. + + The \c QTextEdit::setWrapPolicy() function has been renamed to \l{QTextEdit::setWordWrapMode()}{setWordWrapMode()} and the + \c QTextEdit::setWrapColumnOrWidth() function has been renamed to \l{QTextEdit::setLineWrapColumnOrWidth()} + {setLineWrapColumnOrWidth()}. The Q3TextEdit::setWrapPolicy() and Q3TextEdit::setWrapColumnOrWidth() still provide this + functionality in the Q3TextEdit class. + + + See \l{Rich Text Processing} for an overview of the Qt 4 rich + text classes. + + \section1 QTextIStream + + The QTextIStream convenience class is no longer provided in Qt 4. Use + QTextStream directly instead. + + \section1 QTextOStream + + The QTextOStream convenience class is no longer provided in Qt 4. Use + QTextStream directly instead. + + \section1 QTextOStreamIterator + + The undocumented \c QTextOStreamIterator class has been removed + from the Qt library. If you need it in your application, feel + free to copy the source code from the Qt 3 \c header + file. + + \section1 QTextStream + + QTextStream has undergone a number of API and implementation enhancements, + and some of the changes affect QTextStream's behavior: + + \list + \o QTextStream now uses buffered writing, which means that you need to + call QTextStream::flush(), or use the streaming manipulators \c endl or + \c flush if you need QTextStream to flush its write buffer. The stream is + flushed automatically if QTextStream is deleted or when the device is + closed. + \o QTextStream now uses buffered reading, so if you read a line from the + stream, QTextStream will read as much as it can from the device to + fill up its internal read buffer. This speeds up reading significantly, + but Qt 3 code that mixed QTextStream access and direct device access + may need to be updated. + \o While QTextStream in Qt 3 always translated end-of-line characters from + Windows style ("\\r\\n") to Unix style ("\\n") on Windows, QTextStream in + Qt 4 only does this on devices opened with the \c{QIODevice::Text} mode + (formerly \c{IO_Translate}). + \endlist + + Note that when using a QTextStream on a QFile in Qt 4, calling + QIODevice::reset() on the QFile will not have the expected result + because QTextStream now buffers the file. Use the + QTextStream::seek() function instead. + + \section1 QTextView + + The \c QTextView class has been renamed Q3TextView and moved to the + Qt3Support library. + + \section1 QTimeEdit + + The QTimeEdit class in Qt 4 is a convenience class based on + QDateTimeEdit. The old class has been renamed Q3TimeEdit and moved + to the Qt3Support library. + + See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for + a list of \c QTimeEdit virtual member functions in Qt 3 that are no + longer virtual in Qt 4. + + \section1 QTimer + + Windows restricts the granularity of timers, but starting with Qt 4, + we emulate a finer time resolution. On Windows XP we use the + multimedia timer API, which gives us 1 millisecond resolution for + QTimer. + + Note that other versions of Windows have a lower timer resolution, + and that code relying on underlying system timer restrictions + encounters no such limitations using Qt 4 (e.g., setting an + interval of 0 millisecond results in Qt occupying all of the + processor time when no GUI events need processing). + + \section1 QToolBar + + The old \c QToolBar class, which worked with the old \c + QMainWindow and \c QDockArea classes and inherited from \c + QDockWindow, has been renamed Q3ToolBar and moved to + Qt3Support. Note that, when using Q3ToolBar, the toolbar's actions + must be \l {Q3Action}s. + + Use the new QToolBar class in new applications. + + \note \l{Q3ToolBar}'s + \l{Q3DockWindow::setHorizontallyStretchable()}{horizontallyStretchable} + property can be achieved in QToolBar with + \l{QWidget#Size Hints and Size Policies}{size policies}. + + \section1 QToolButton + + See \l{#properties}{Properties} for a list of QToolButton properties + in Qt 3 that have changed in Qt 4. + + Note that many of the properties that could previously be set in + the constructor must now be set separately. + + \section1 QToolTip + + The QToolTip::setGloballyEnabled() function no longer exists. + Tooltips can be disabled by \l{QObject::installEventFilter()}{installing + an event filter} on qApp (the unique QApplication object) to block events + of type QEvent::ToolTip. + + \section1 QUriDrag + + The \c QUriDrag class has been renamed Q3UriDrag and moved to the + Qt3Support library. In Qt 4, use QMimeData instead + and call QMimeData::setUrl() to set the URL. + + See \l{Porting to Qt 4 - Drag and Drop} for a comparison between + the drag and drop APIs in Qt 3 and Qt 4. + + \section1 QUrl + + The QUrl class has been rewritten from scratch in Qt 4 to be more + standard-compliant. The old QUrl class has been renamed Q3Url and + moved to the Qt3Support library. + + The new QUrl class provides an extensive list of compatibility + functions to ease porting from Q3Url to QUrl. A few functions + require you to change your code: + + \list + \o Q3Url::Q3Url(const Q3Url &, const QString &, bool) can be + simulated by combining the URLs manually (using + QString::operator+(), for example). + \o Q3Url::setEncodedPathAndQuery(const QString &) is replaced by + QUrl::setPath() and QUrl::setEncodedQuery(). + \o Q3Url::encodedPathAndQuery() is replaced by QUrl::path() and + QUrl::encodedQuery(). + \o Q3Url::isLocalFile() can be simulated by checking that + QUrl::protocol() is "file". + \o Q3Url::toString(bool, bool) is replaced by + QUrl::toString(int), where the \c int parameter specifies a + combination of \l{QUrl::FormattingOptions}{formatting + options}. + \endlist + + \section1 QUrlOperator + + The \c QUrlOperator class is no longer part of the public Qt API. + It has been renamed Q3UrlOperator and moved to Qt3Support. + + From Qt 4.4, the Network Access API provides a subset of the features + provided by \c QUrlOperator that are mostly intended for use with + applications that use the HTTP and FTP protocols. See the + QNetworkRequest, QNetworkReply, and QNetworkAccessManager documentation + for further details. + + \target qvaluelist.section + \section1 QValueList + + The QValueList class has been replaced by QList and + QLinkedList in Qt 4. As a help when porting older Qt + applications, the Qt3Support library contains a + QValueList class implemented in terms of the new + QLinkedList. Similarly, it contains QValueListIterator and + QValueListConstIterator classes implemented in terms of + QLinkedList::iterator and QLinkedList::const_iterator. + + When porting to Qt 4, you have the choice of using QList or + QLinkedList as alternatives to QValueList. QList has an + index-based API and provides very fast random access + (QList::operator[]), whereas QLinkedList has an iterator-based + API. + + Here's a list of problem functions: + + \list + \o QValueList(const std::list &) doesn't exist in QList or + QLinkedList. You can simulate it by calling + \l{QLinkedList::append()}{append()} in a loop. + + \o QValueList::insert(iterator, size_type, const T& x) doesn't + exist in QList or QLinkedList. Call + \l{QLinkedList::insert()}{insert()} repeatedly instead. + + \o QValueList::fromLast() doesn't exist in QList or QLinkedList. Use + QValueList::end() instead. + + \oldcode + for (QValueList::iterator i = list.fromLast(); i != list.begin(); --i) + do_something(*i); + \newcode + QLinkedList::iterator i = list.end(); + while (i != list.begin()) { + --i; // decrement i before using it + do_something(*i); + } + \endcode + + \o QValueList::append() and QValueList::prepend() return an + iterator to the inserted item. QList's and QLinkedList's + corresponding functions don't, but it's not a problem because + QValueList::prepend() always returns begin() and append() + always returns QValueList::end() - 1. + + \o QValueList::at(\e i) return an iterator to the item at index + \e i. This corresponds to QList::begin() + \e i. + + \o QValueList::contains(const T &) corresponds to + QList::count(const T &) and QLinkedList::count(const T &). + \endlist + + \section1 QValueVector + + The QValueVector class has been replaced by QVector in Qt + 4. As a help when porting older Qt applications, the Qt3Support + library contains a Q3ValueVector class implemented in terms of + the new QVector. + + When porting from QValueVector to QVector, you might run + into the following incompatibilities: + + \list + \o QValueVector(const std::vector &) doesn't exist in QVector. + You can simulate it by calling QVector::append()} in a loop. + \o QValueVector::resize(int, const T &) doesn't exist in QVector. + If you want the new items to be initialized with a particular + value, use QVector::insert() instead. + \o QValueVector::at() on a non-const vector returns a non-const + reference. This corresponds to QVector::operator[](). + \o Both QValueVector::at() functions have an \e ok parameter of + type \c{bool *} that is set to true if the index is within + bounds. This functionality doesn't exist in QVector; instead, + check the index against QVector::size() yourself. + \endlist + + See \l{Generic Containers} for an overview of the Qt 4 container + classes. + + \section1 QVariant + + Some changes to the rest of the Qt library have + implications on QVariant: + + \list 1 + \o The \c QVariant::ColorGroup enum value is defined only + if \c QT3_SUPPORT is defined. + \o The \c QVariant::IconSet enum value has been renamed + QVariant::Icon. + \o The \c QVariant::CString enum value is now a synonym for + QVariant::ByteArray. + \endlist + + Also, the QVariant(bool, int) constructor has been replaced by QVariant(bool). + Old code like QVariant(true, 0) should be replaced with QVariant(true); otherwise, + the QVariant(int, void *) overload might accidentally be triggered. + + Many of QVariant's convenience functions in Qt 3, such as toColor() and + toKeySequence(), have been removed to enable QVariant to be part of the + QtCore module. QVariant is still able to hold values of these types. + + Types which are not supported by any of the QVariant constructors can be + stored as variants with the QVariant::fromValue() function. Types with no + suitable convenience function for unpacking can be retrieved with the + QVariant::value() function or passed directly to classes that implement + the QVariant() operator. + + \table + \header \o Qt 3 function \o Qt 4 function + \input porting4-removedvariantfunctions.qdocinc + \endtable + + See the QVariant::Type enum for a list of types supported by QVariant. + + \section1 QVBox + + The \c QVBox class is now only available as Q3VBox in Qt 4. You + can achieve the same result as \c QVBox by creating a QWidget + with a vertical layout: + + \oldcode + QVBox *vbox = new QVBox; + QPushButton *child1 = new QPushButton(vbox); + QPushButton *child2 = new QPushButton(vbox); + \newcode + QWidget *vbox = new QWidget; + QPushButton *child1 = new QPushButton; + QPushButton *child2 = new QPushButton; + + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(child1); + layout->addWidget(child2); + vbox->setLayout(layout); + \endcode + + Note that child widgets are not automatically placed into the widget's + layout; you will need to manually add each widget to the QVBoxLayout. + + \section1 QVGroupBox + + The \c QVGroupBox class has been renamed Q3VGroupBox and moved to + the Qt3Support library. + Qt 4 does not provide a specific replacement class for \c QVGroupBox + since QGroupBox is designed to be a generic container widget. As a + result, you need to supply your own layout for any child widgets. + + See \l{#QGroupBox} for more information about porting code that uses + group boxes. + + \section1 QWhatsThis + + The QWhatsThis class has been redesigned in Qt 4. The old \c + QWhatsThis class is available as Q3WhatsThis in Qt3Support. + + \section1 QWidget + + Widget background painting has been greatly improved, supporting + flicker-free updates and making it possible to have + semi-transparent widgets. This renders the following background + handling functions obsolete: + + \list + \o QWidget::repaint(bool noErase) - the \c noErase boolean parameter is gone + \o QWidget::setBackgroundMode(BackgroundMode m) + \o QWidget::backgroundBrush() const + \o QWidget::setBackgroundPixmap(const QPixmap &pm) + \o QWidget::backgroundPixmap() const + \o QWidget::setBackgroundColor(const QColor &c) + \o QWidget::backgroundColor() const + \o QWidget::foregroundColor() const + \o QWidget::eraseColor() const + \o QWidget::setEraseColor(const QColor &c) + \o QWidget::erasePixmap() const + \o QWidget::setErasePixmap(const QPixmap &p) + \o QWidget::paletteForegroundColor() + \o QWidget::setPaletteForegroundColor(const QColor &c) + \o QWidget::paletteBackgroundColor() + \o QWidget::setPaletteBackgroundColor(const QColor &c) + \o QWidget::paletteBackgroundPixmap() const + \o QWidget::setPaletteBackgroundPixmap(const QPixmap &p) + \o QWidget::erase() + \o QWidget::erase(const QRect &r) + \o QWidget::setBackgroundOrigin( BackgroundOrigin ) + \o QWidget::BackgroundOrigin backgroundOrigin() const + \o QWidget::backgroundOffset() + \endlist + + Sample code on how to do obtain similar behavior from Qt 4, previously + handled by some of the above functions can be found in the + \l{http://doc.trolltech.com/qwidget-qt3.html}{Qt 3 Support Members for QWidget} + page. + + A widget now receives change events in its QWidget::changeEvent() + handler. This makes the following virtual change handlers obsolete: + + \list + \o QWidget::styleChange - use QEvent::StyleChange + \o QWidget::enabledChange - use QEvent::EnabledChange + \o QWidget::paletteChange - use QEvent::PaletteChange + \o QWidget::fontChange - use QEvent::FontChange + \o QWidget::windowActivationChange - use QEvent::ActivationChange + \o QWidget::languageChange - use QEvent::LanguageChange + \endlist + + The following functions were slots, but are no more: + \list + \o QWidget::clearFocus() + \o QWidget::setMouseTracking() + \o QWidget::stackUnder(QWidget*) + \o QWidget::move(int x, int y) + \o QWidget::move(const QPoint &) + \o QWidget::resize(int w, int h) + \o QWidget::resize(const QSize &) + \o QWidget::setGeometry(int x, int y, int w, int h) + \o QWidget::setGeometry(const QRect &) + \o QWidget::adjustSize() + \o QWidget::update(int x, int y, int w, int h) + \o QWidget::update(const QRect&) + \o QWidget::repaint(bool erase) + \o QWidget::repaint(int x, int y, int w, int h, bool erase) + \o QWidget::repaint(const QRect &, bool erase) + \o QWidget::repaint(const QRegion &, bool erase) + \o QWidget::setCaption(const QString &) + \o QWidget::setIcon(const QPixmap &) + \o QWidget::setIconText(const QString &) + \endlist + + The following functions were incorrectly marked as virtual: + + \list + \o QWidget::close(bool alsoDelete) + \o QWidget::create(WId, bool, bool) + \o QWidget::destroy(bool) + \o QWidget::move(int x, int y) + \o QWidget::reparent(QWidget *parent, WFlags, const QPoint &, bool) + \o QWidget::resize(int w, int h) + \o QWidget::setAcceptDrops(bool on) + \o QWidget::setActiveWindow() + \o QWidget::setAutoMask(bool) + \o QWidget::setBackgroundColor(const QColor &) + \o QWidget::setBackgroundMode(BackgroundMode) + \o QWidget::setBackgroundOrigin(BackgroundOrigin) + \o QWidget::setBackgroundPixmap(const QPixmap &) + \o QWidget::setCaption(const QString &) + \o QWidget::setCursor(const QCursor &) + \o QWidget::setEnabled(bool) + \o QWidget::setEraseColor(const QColor &) + \o QWidget::setErasePixmap(const QPixmap &) + \o QWidget::setFocus() + \o QWidget::setFocusPolicy(FocusPolicy) + \o QWidget::setFocusProxy(QWidget *) + \o QWidget::setFont(const QFont &) + \o QWidget::setGeometry(const QRect &) + \o QWidget::setGeometry(int x, int y, int w, int h) + \o QWidget::setIcon(const QPixmap &) + \o QWidget::setIconText(const QString &) + \o QWidget::setKeyCompression(bool) + \o QWidget::setMask(const QBitmap &) + \o QWidget::setMask(const QRegion &) + \o QWidget::setMaximumSize(int maxw, int maxh) + \o QWidget::setMicroFocusHint(int x, int y, int w, int h, bool, QFont *f) + \o QWidget::setMinimumSize(int minw, int minh) + \o QWidget::setMouseTracking(bool enable) + \o QWidget::setPalette(const QPalette &) + \o QWidget::setPaletteBackgroundColor(const QColor &) + \o QWidget::setPaletteBackgroundPixmap(const QPixmap &) + \o QWidget::setSizeIncrement(int w, int h) + \o QWidget::setSizePolicy(QSizePolicy) + \o QWidget::setUpdatesEnabled(bool enable) + \o QWidget::setWState(uint) + \o QWidget::show() + \o QWidget::showFullScreen() + \o QWidget::showMaximized() + \o QWidget::showMinimized() + \o QWidget::showNormal() + \o QWidget::sizePolicy() + \o QWidget::unsetCursor() + \endlist + + The internal clearWState() function was removed. Use + QWidget::setAttribute() instead. + + setWFlags() was renamed QWidget::setWindowFlags(). + + clearWFlags() has no direct replacement. You can use + QWidget::setAttribute() instead. For example, + \c{setAttribute(..., false)} to clear an attribute. More information + is available \l{http://doc.trolltech.com/qwidget.html#setAttribute}{here}. + + testWFlags() was renamed to \l{QWidget::testAttribute()}{testAttribute()}. + + See \l{#properties}{Properties} for a list of QWidget properties + in Qt 3 that have changed in Qt 4. + + \section1 QWidgetFactory + + The \c QWidgetFactory class has been replaced by QFormBuilder in Qt 4. + + \section1 QWidgetIntDict + + The QWidgetIntDict class was a synonym for QIntDict. It + is no longer available in Qt 4. If you link against Qt3Support, + you can use Q3IntDict instead; otherwise, see the + \l{#qdict.section}{section on QDict}. + + \target qwidgetlist.section + \section1 QWidgetList + + In Qt 3, the QWidgetList class was a typedef for + QPtrList. In Qt 4, it is a typedef for QList. + See the \l{#qptrlist.section}{section on QPtrList}. + + \section1 QWidgetPlugin + + The QWidgetPlugin class is no longer available in Qt 4. To create + custom widget plugins, subclass QDesignerCustomWidgetInterface to + provide information about the custom widget, and build a plugin in + the way described in the \l{designer/customwidgetplugin}{Custom + Widget Plugin} example. + + \section1 QWidgetStack + + The QWidgetStack class is no longer part of the Qt public API. It + has been renamed Q3WidgetStack and moved to Qt3Support. In Qt 4 + applications, you can use QStackedWidget instead to obtain the + same results. + + \section1 QWizard + + The \c QWizard class was reintroduced in Qt 4.3. See the + \l{Trivial Wizard Example}, \l{License Wizard Example} and + \l{Class Wizard Example} for more details. + + \section1 QWorkspace + + The \c QWorkspace in Qt 4 class requires explicit adding of MDI + windows with QWorkspace::addWindow(). +*/ + +/*! + \page porting4-virtual-functions.html + \title Porting to Qt 4 - Virtual Functions + \contentspage {Porting Guides}{Contents} + \previouspage Porting to Qt 4 + \nextpage Porting to Qt 4 - Drag and Drop + \ingroup porting + \brief An overview of changes to virtual functions in Qt 4. + + \section1 Virtual Functions + + Virtual functions that changed their signature in Qt 4: + + \table + \header \o Qt 3 function signature \o Qt 4 function signature + \input porting4-modifiedvirtual.qdocinc + \endtable + + Virtual functions that are not virtual in Qt 4: + + \table + \header \o Qt 3 function \o Comment + \input porting4-removedvirtual.qdocinc + \endtable +*/ diff --git a/doc/src/printing.qdoc b/doc/src/printing.qdoc new file mode 100644 index 0000000..e1c337a --- /dev/null +++ b/doc/src/printing.qdoc @@ -0,0 +1,175 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page printing.html + \title Printing with Qt + \ingroup multimedia + \ingroup text-processing + \brief A guide to producing printed output with Qt's paint system and widgets. + + Qt provides extensive cross-platform support for printing. Using the printing + systems on each platform, Qt applications can print to attached printers and + across networks to remote printers. Qt's printing system also enables PostScript + and PDF files to be generated, providing the foundation for basic report + generation facilities. + + \tableofcontents + + \section1 Paint Devices and Printing + + In Qt, printers are represented by QPrinter, a paint device that provides + functionality specific to printing, such as support for multiple pages and + double-sided output. As a result, printing involves using a QPainter to paint + onto a series of pages in the same way that you would paint onto a custom + widget or image. + + \section2 Creating a QPrinter + + Although QPrinter objects can be constructed and set up without requiring user + input, printing is often performed as a result of a request by the user; + for example, when the user selects the \gui{File|Print...} menu item in a GUI + application. In such cases, a newly-constructed QPrinter object is supplied to + a QPrintDialog, allowing the user to specify the printer to use, paper size, and + other printing properties. + + \snippet examples/richtext/orderform/mainwindow.cpp 18 + + It is also possible to set certain default properties by modifying the QPrinter + before it is supplied to the print dialog. For example, applications that + generate batches of reports for printing may set up the QPrinter to + \l{QPrinter::setOutputFileName()}{write to a local file} by default rather than + to a printer. + + \section2 Painting onto a Page + + Once a QPrinter object has been constructed and set up, a QPainter can be used + to perform painting operations on it. We can construct and set up a painter in + the following way: + + \snippet doc/src/snippets/printing-qprinter/object.cpp 0 + + Since the QPrinter starts with a blank page, we only need to call the + \l{QPrinter::}{newPage()} function after drawing each page, except for the + last page. + + The document is sent to the printer, or written to a local file, when we call + \l{QPainter::}{end()}. + + \section2 Coordinate Systems + + QPrinter provides functions that can be used to obtain information about the + dimensions of the paper (the paper rectangle) and the dimensions of the + printable area (the page rectangle). These are given in logical device + coordinates that may differ from the physical coordinates used by the device + itself, indicating that the printer is able to render text and graphics at a + (typically higher) resolution than the user's display. + + Although we do not need to handle the conversion between logical and physical + coordinates ourselves, we still need to apply transformations to painting + operations because the pixel measurements used to draw on screen are often + too small for the higher resolutions of typical printers. + + \table + \row \o \bold{Printer and Painter Coordinate Systems} + + The \l{QPrinter::}{paperRect()} and \l{QPrinter::}{pageRect()} functions + provide information about the size of the paper used for printing and the + area on it that can be painted on. + + The rectangle returned by \l{QPrinter::}{pageRect()} usually lies inside + the rectangle returned by \l{QPrinter::}{paperRect()}. You do not need to + take the positions and sizes of these area into account when using a QPainter + with a QPrinter as the underlying paint device; the origin of the painter's + coordinate system will coincide with the top-left corner of the page + rectangle, and painting operations will be clipped to the bounds of the + drawable part of the page. + + \o \inlineimage printer-rects.png + \endtable + + The paint system automatically uses the correct device metrics when painting + text but, if you need to position text using information obtained from + font metrics, you need to ensure that the print device is specified when + you construct QFontMetrics and QFontMetricsF objects, or ensure that each QFont + used is constructed using the form of the constructor that accepts a + QPaintDevice argument. + + \section1 Printing from Complex Widgets + + Certain widgets, such as QTextEdit and QGraphicsView, display rich content + that is typically managed by instances of other classes, such as QTextDocument + and QGraphicsScene. As a result, it is these content handling classes that + usually provide printing functionality, either via a function that can be used + to perform the complete task, or via a function that accepts an existing + QPainter object. Some widgets provide convenience functions to expose underlying + printing features, avoiding the need to obtain the content handler just to call + a single function. + + The following table shows which class and function are responsible for + printing from a selection of different widgets. For widgets that do not expose + printing functionality directly, the content handling classes containing this + functionality can be obtained via a function in the corresponding widget's API. + + \table + \header \o Widget \o Printing function \o Accepts + \row \o QGraphicsView \o QGraphicsView::render() \o QPainter + \row \o QSvgWidget \o QSvgRenderer::render() \o QPainter + \row \o QTextEdit \o QTextDocument::print() \o QPrinter + \row \o QTextLayout \o QTextLayout::draw() \o QPainter + \row \o QTextLine \o QTextLine::draw() \o QPainter + \endtable + + QTextEdit requires a QPrinter rather than a QPainter because it uses information + about the configured page dimensions in order to insert page breaks at the most + appropriate places in printed documents. +*/ + +/*! + \page pdf-licensing.html + \title Notes about PDF Licensing + \ingroup licensing + \brief Details of restrictions on the use of PDF-related trademarks. + + Please note that Adobe\reg places restrictions on the use of its trademarks + (including logos) in conjunction with PDF; e.g. "Adobe PDF". Please refer + to \l{http://www.adobe.com}{www.adobe.com} for guidelines. +*/ diff --git a/doc/src/properties.qdoc b/doc/src/properties.qdoc new file mode 100644 index 0000000..0775b12 --- /dev/null +++ b/doc/src/properties.qdoc @@ -0,0 +1,263 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page properties.html + \title Qt's Property System + \ingroup architecture + \brief An overview of Qt's property system. + + Qt provides a sophisticated property system similar to the ones + supplied by some compiler vendors. However, as a compiler- and + platform-independent library, Qt does not rely on non-standard + compiler features like \c __property or \c [property]. The Qt + solution works with \e any standard C++ compiler on every platform + Qt supports. It is based on the \l {Meta-Object System} that also + provides inter-object communication via \l{signals and slots}. + + \section1 Requirements for Declaring Properties + + To declare a property, use the \l {Q_PROPERTY()} {Q_PROPERTY()} + macro in a class that inherits QObject. + + \snippet doc/src/snippets/code/doc_src_properties.qdoc 0 + + Here are some typical examples of property declarations taken from + class QWidget. + + \snippet doc/src/snippets/code/doc_src_properties.qdoc 1 + + A property behaves like a class data member, but it has additional + features accessible through the \l {Meta-Object System}. + + \list + + \o A \c READ accessor function is required. It is for reading the + property value. It must be const and must return either the + property's type or a pointer or reference to that type. e.g., + QWidget::focus is a read-only property with \c READ function + QWidget::hasFocus(). + + \o A \c WRITE accessor function is optional. It is for setting the + property value. It must return void and must take exactly one + argument, either of the property's type or a pointer or reference + to that type. e.g., QWidget::enabled has the \c WRITE function + QWidget::setEnabled(). Read-only properties do not need \c WRITE + functions. e.g., QWidget::focus has no \c WRITE function. + + \o A \c RESET function is optional. It is for setting the property + back to its context specific default value. e.g., QWidget::cursor + has the typical \c READ and \c WRITE functions, QWidget::cursor() + and QWidget::setCursor(), and it also has a \c RESET function, + QWidget::unsetCursor(), since no call to QWidget::setCursor() can + mean \e {reset to the context specific cursor}. The \c RESET + function musrt return void and take no parameters. + + \o The \c DESIGNABLE attribute indicates whether the property + should be visible in the property editor of GUI design tool (e.g., + \l {Qt Designer}). Most properties are \c DESIGNABLE (default + true). Instead of true or false, you can specify a boolean + member function. + + \o The \c SCRIPTABLE attribute indicates whether this property + should be accessible by a scripting engine (default true). + Instead of true or false, you can specify a boolean member + function. + + \o The \c STORED attribute indicates whether the property should + be thought of as existing on its own or as depending on other + values. It also indicates whether the property value must be saved + when storing the object's state. Most properties are \c STORED + (default true), but e.g., QWidget::minimumWidth() has \c STORED + false, because its value is just taken from the width component + of property QWidget::minimumSize(), which is a QSize. + + \o The \c USER attribute indicates whether the property is + designated as the user-facing or user-editable property for the + class. Normally, there is only one \c USER property per class + (default false). e.g., QAbstractButton::checked is the user + editable property for (checkable) buttons. Note that QItemDelegate + gets and sets a widget's \c USER property. + + \endlist + + The \c READ, \c WRITE, and \c RESET functions can be inherited. + They can also be virtual. When they are inherited in classes where + multiple inheritance is used, they must come from the first + inherited class. + + The property type can be any type supported by QVariant, or it can + be a user-defined type. In this example, class QDate is considered + to be a user-defined type. + + \snippet doc/src/snippets/code/doc_src_properties.qdoc 2 + + Because QDate is user-defined, you must include the \c{} + header file with the property declaration. + + For QMap, QList, and QValueList properties, the property value is + a QVariant whose value is the entire list or map. Note that the + Q_PROPERTY string cannot contain commas, because commas separate + macro arguments. Therefore, you must use \c QMap as the property + type instead of \c QMap. For consistency, also + use \c QList and \c QValueList instead of \c QList and + \c QValueList. + + \section1 Reading and Writing Properties with the Meta-Object System + + A property can be read and written using the generic functions + QObject::property() and QObject::setProperty(), without knowing + anything about the owning class except the property's name. In + the code snippet below, the call to QAbstractButton::setDown() and + the call to QObject::setProperty() both set property "down". + + \snippet doc/src/snippets/code/doc_src_properties.qdoc 3 + + Accessing a property through its \c WRITE accessor is the better + of the two, because it is faster and gives better diagnostics at + compile time, but setting the property this way requires that you + know about the class at compile time. Accessing properties by name + lets you access classes you don't know about at compile time. You + can \e discover a class's properties at run time by querying its + QObject, QMetaObject, and \l {QMetaProperty} {QMetaProperties}. + + \snippet doc/src/snippets/code/doc_src_properties.qdoc 4 + + In the above snippet, QMetaObject::property() is used to get \l + {QMetaProperty} {metadata} about each property defined in some + unknown class. The property name is fetched from the metadata and + passed to QObject::property() to get the \l {QVariant} {value} of + the property in the current \l {QObject}{object}. + + \section1 A Simple Example + + Suppose we have a class MyClass, which is derived from QObject and + which uses the Q_OBJECT macro in its private section. We want to + declare a property in MyClass to keep track of a priorty + value. The name of the property will be \e priority, and its type + will be an enumeration type named \e Priority, which is defined in + MyClass. + + We declare the property with the Q_PROPERTY() macro in the private + section of the class. The required \c READ function is named \c + priority, and we include a \c WRITE function named \c setPriority. + The enumeration type must be registered with the \l {Meta-Object + System} using the Q_ENUMS() macro. Registering an enumeration type + makes the enumerator names available for use in calls to + QObject::setProperty(). We must also provide our own declarations + for the \c READ and \c WRITE functions. The declaration of MyClass + then might look like this: + + \snippet doc/src/snippets/code/doc_src_properties.qdoc 5 + + The \c READ function is const and returns the property type. The + \c WRITE function returns void and has exactly one parameter of + the property type. The meta-object compiler enforces these + requirements. + + Given a pointer to an instance of MyClass or a pointer to an + instance of QObject that happens to be an instance of MyClass, we + have two ways to set its priority property. + + \snippet doc/src/snippets/code/doc_src_properties.qdoc 6 + + In the example, the enumeration type used for the property type + was locally declared in MyClass. Had it been declared in another + class, its fully qualified name (i.e., OtherClass::Priority) would + be required. In addition, that other class must also inherit + QObject and register the enum type using Q_ENUMS(). + + A similar macro, Q_FLAGS(), is also available. Like Q_ENUMS(), it + registers an enumeration type, but it marks the type as being a + set of \e flags, i.e. values that can be OR'd together. An I/O + class might have enumeration values \c Read and \c Write and then + QObject::setProperty() could accept \c{Read | Write}. Q_FLAGS() + should be used to register this enumeration type. + + \section1 Dynamic Properties + + QObject::setProperty() can also be used to add \e new properties + to an instance of a class at runtime. When it is called with a + name and a value, if a property with the given name exists in the + QObject, and if the given value is compatible with the property's + type, the value is stored in the property, and true is returned. + If the value is \e not compatible with the property's type, the + property is \e not changed, and false is returned. But if the + property with the given name doesn't exist in the QObject (i.e., + if it wasn't declared with Q_PROPERTY(), a new property with the + given name and value is automatically added to the QObject, but + false is still returned. This means that a return of false can't + be used to determine whether a particular property was actually + set, unless you know in advance that the property already exists + in the QObject. + + Note that \e dynamic properties are added on a per instance basis, + i.e., they are added to QObject, not QMetaObject. A property can + be removed from an instance by passing the property name and an + invalid QVariant value to QObject::setProperty(). The default + constructor for QVariant constructs an invalid QVariant. + + Dynamic properties can be queried with QObject::property(), just + like properties declared at compile time with Q_PROPERTY(). + + \sa {Meta-Object System}, {Signals and Slots} + + \section1 Properties and Custom Types + + Custom types used by properties need to be registered using the + Q_DECLARE_METATYPE() macro so that their values can be stored in + QVariant objects. This makes them suitable for use with both + static properties declared using the Q_PROPERTY() macro in class + definitions and dynamic properties created at run-time. + + \sa Q_DECLARE_METATYPE(), QMetaType, QVariant + + \section1 Adding Additional Information to a Class + + Connected to the property system is an additional macro, + Q_CLASSINFO(), that can be used to attach additional + \e{name}--\e{value} pairs to a class's meta-object, for example: + + \snippet doc/src/snippets/code/doc_src_properties.qdoc 7 + + Like other meta-data, class information is accessible at run-time + through the meta-object; see QMetaObject::classInfo() for details. +*/ diff --git a/doc/src/q3asciicache.qdoc b/doc/src/q3asciicache.qdoc new file mode 100644 index 0000000..fbbb21b --- /dev/null +++ b/doc/src/q3asciicache.qdoc @@ -0,0 +1,465 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3AsciiCache + \brief The Q3AsciiCache class is a template class that provides a cache based on char* keys. + \compat + + Q3AsciiCache is implemented as a template class. Define a template + instance Q3AsciiCache\ to create a cache that operates on + pointers to X (X*). + + A cache is a least recently used (LRU) list of cache items. The + cache items are accessed via \c char* keys. For Unicode keys use + the Q3Cache template instead, which uses QString keys. A Q3Cache + has the same performace as a Q3AsciiCache. + + Each cache item has a cost. The sum of item costs, totalCost(), + will not exceed the maximum cache cost, maxCost(). If inserting a + new item would cause the total cost to exceed the maximum cost, + the least recently used items in the cache are removed. + + Apart from insert(), by far the most important function is find() + (which also exists as operator[]()). This function looks up an + item, returns it, and by default marks it as being the most + recently used item. + + There are also methods to remove() or take() an object from the + cache. Calling \link Q3PtrCollection::setAutoDelete() + setAutoDelete(TRUE)\endlink tells the cache to delete items that + are removed. The default is to not delete items when then are + removed (i.e., remove() and take() are equivalent). + + When inserting an item into the cache, only the pointer is copied, + not the item itself. This is called a shallow copy. It is possible + to make the cache copy all of the item's data (known as a deep + copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a cache and reimplement newItem() if you want deep copies. + + When removing a cache item the virtual function + Q3PtrCollection::deleteItem() is called. Its default implementation + in Q3AsciiCache is to delete the item if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + There is a Q3AsciiCacheIterator which may be used to traverse the + items in the cache in arbitrary order. + + \sa Q3AsciiCacheIterator, Q3Cache, Q3IntCache +*/ + +/*! + \fn Q3AsciiCache::Q3AsciiCache( const Q3AsciiCache &c ) + + \internal + + Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. +*/ + + +/*! + \fn Q3AsciiCache::Q3AsciiCache( int maxCost, int size, bool caseSensitive, bool copyKeys ) + + Constructs a cache whose contents will never have a total cost + greater than \a maxCost and which is expected to contain less than + \a size items. + + \a size is actually the size of an internal hash array; it's + usually best to make it prime and at least 50% bigger than the + largest expected number of items in the cache. + + Each inserted item has an associated cost. When inserting a new + item, if the total cost of all items in the cache will exceed \a + maxCost, the cache will start throwing out the older (least + recently used) items until there is enough room for the new item + to be inserted. + + If \a caseSensitive is TRUE (the default), the cache keys are case + sensitive; if it is FALSE, they are case-insensitive. + Case-insensitive comparison only affects the 26 letters in + US-ASCII. If \a copyKeys is TRUE (the default), Q3AsciiCache makes + a copy of the cache keys, otherwise it copies just the const char + * pointer - slightly faster if you can guarantee that the keys + will never change, but very risky. +*/ + +/*! + \fn Q3AsciiCache::~Q3AsciiCache() + + Removes all items from the cache and destroys it. + All iterators that access this cache will be reset. +*/ + +/*! + \fn Q3AsciiCache& Q3AsciiCache::operator=( const Q3AsciiCache &c ) + + \internal + + Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn int Q3AsciiCache::maxCost() const + + Returns the maximum allowed total cost of the cache. + + \sa setMaxCost() totalCost() +*/ + +/*! + \fn int Q3AsciiCache::totalCost() const + + Returns the total cost of the items in the cache. This is an + integer in the range 0 to maxCost(). + + \sa setMaxCost() +*/ + +/*! + \fn void Q3AsciiCache::setMaxCost( int m ) + + Sets the maximum allowed total cost of the cache to \a m. If the + current total cost is greater than \a m, some items are removed + immediately. + + \sa maxCost() totalCost() +*/ + +/*! + \fn uint Q3AsciiCache::count() const + + Returns the number of items in the cache. + + \sa totalCost() size() +*/ + +/*! + \fn uint Q3AsciiCache::size() const + + Returns the size of the hash array used to implement the cache. + This should be a bit bigger than count() is likely to be. +*/ + +/*! + \fn bool Q3AsciiCache::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. +*/ + +/*! + \fn bool Q3AsciiCache::insert( const char *k, const type *d, int c, int p ) + + Inserts the item \a d into the cache using key \a k, and with an + associated cost of \a c. Returns TRUE if the item is successfully + inserted. Returns FALSE if the item is not inserted, for example, + if the cost of the item exceeds maxCost(). + + The cache's size is limited, and if the total cost is too high, + Q3AsciiCache will remove old, least recently used items until there + is room for this new item. + + Items with duplicate keys can be inserted. + + The parameter \a p is internal and should be left at the default + value (0). + + \warning If this function returns FALSE, you must delete \a d + yourself. Additionally, be very careful about using \a d after + calling this function, because any other insertions into the + cache, from anywhere in the application or within Qt itself, could + cause the object to be discarded from the cache and the pointer to + become invalid. +*/ + +/*! + \fn bool Q3AsciiCache::remove( const char *k ) + + Removes the item with key \a k and returns TRUE if the item was + present in the cache; otherwise returns FALSE. + + The item is deleted if auto-deletion has been enabled, i.e., if + you have called \link Q3PtrCollection::setAutoDelete() + setAutoDelete(TRUE)\endlink. + + If there are two or more items with equal keys, the one that was + inserted last is removed. + + All iterators that refer to the removed item are set to point to + the next item in the cache's traversal order. + + \sa take(), clear() +*/ + +/*! + \fn type *Q3AsciiCache::take( const char *k ) + + Takes the item associated with \a k out of the cache without + deleting it and returns a pointer to the item taken out, or 0 + if the key does not exist in the cache. + + If there are two or more items with equal keys, the one that was + inserted last is taken. + + All iterators that refer to the taken item are set to point to the + next item in the cache's traversal order. + + \sa remove(), clear() +*/ + +/*! + \fn void Q3AsciiCache::clear() + + Removes all items from the cache, and deletes them if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink has been + enabled. + + All cache iterators that operate on this cache are reset. + + \sa remove() take() +*/ + +/*! + \fn type *Q3AsciiCache::find( const char *k, bool ref ) const + + Returns the item with key \a k, or 0 if the key does not exist + in the cache. If \a ref is TRUE (the default), the item is moved + to the front of the least recently used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. +*/ + +/*! + \fn type *Q3AsciiCache::operator[]( const char *k ) const + + Returns the item with key \a k, or 0 if \a k does not exist in + the cache, and moves the item to the front of the least recently + used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. + + This is the same as find( k, TRUE ). + + \sa find() +*/ + +/*! + \fn void Q3AsciiCache::statistics() const + + A debug-only utility function. Prints out cache usage, hit/miss, + and distribution information using qDebug(). This function does + nothing in the release library. +*/ + +/*! + \class Q3AsciiCacheIterator + \brief The Q3AsciiCacheIterator class provides an iterator for Q3AsciiCache collections. + \compat + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. If new objects are inserted into the cache + while the iterator is active, the iterator may or may not see + them. + + Multiple iterators are completely independent, even when they + operate on the same Q3AsciiCache. Q3AsciiCache updates all iterators + that refer an item when that item is removed. + + Q3AsciiCacheIterator provides an operator++() and an operator+=() + to traverse the cache; current() and currentKey() to access the + current cache item and its key. It also provides atFirst() and + atLast(), which return TRUE if the iterator points to the first or + last item in the cache respectively. The isEmpty() function + returns TRUE if the cache is empty; and count() returns the number + of items in the cache. + + Note that atFirst() and atLast() refer to the iterator's arbitrary + ordering, not to the cache's internal least recently used list. + + \sa Q3AsciiCache +*/ + +/*! + \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator( const Q3AsciiCache &cache ) + + Constructs an iterator for \a cache. The current iterator item is + set to point to the first item in the \a cache. +*/ + +/*! + \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator (const Q3AsciiCacheIterator & ci) + + Constructs an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current() but moves + independently from there on. +*/ + +/*! + \fn Q3AsciiCacheIterator& Q3AsciiCacheIterator::operator=( const Q3AsciiCacheIterator &ci ) + + Makes this an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently thereafter. +*/ + +/*! + \fn uint Q3AsciiCacheIterator::count() const + + Returns the number of items in the cache over which this iterator + operates. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3AsciiCacheIterator::isEmpty() const + + Returns TRUE if the cache is empty, i.e. count() == 0; otherwise + returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3AsciiCacheIterator::atFirst() const + + Returns TRUE if the iterator points to the first item in the + cache; otherwise returns FALSE. Note that this refers to the + iterator's arbitrary ordering, not to the cache's internal least + recently used list. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3AsciiCacheIterator::atLast() const + + Returns TRUE if the iterator points to the last item in the cache; + otherwise returns FALSE. Note that this refers to the iterator's + arbitrary ordering, not to the cache's internal least recently + used list. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3AsciiCacheIterator::toFirst() + + Sets the iterator to point to the first item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toLast() isEmpty() +*/ + +/*! + \fn type *Q3AsciiCacheIterator::toLast() + + Sets the iterator to point to the last item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toFirst() isEmpty() +*/ + +/*! + \fn Q3AsciiCacheIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3AsciiCacheIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn const char *Q3AsciiCacheIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the cache or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator+=( uint jump ) + + Returns the item \a jump positions after the current item, or 0 + if it is beyond the last item. Makes this the current item. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item, or 0 + if it is before the first item. Makes this the current item. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator++() + + Prefix ++ makes the iterator point to the item just after + current(), and makes that the new current item for the iterator. If + current() was the last item, operator++() returns 0. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator--() + + Prefix -- makes the iterator point to the item just before + current(), and makes that the new current item for the iterator. If + current() was the first item, operator--() returns 0. +*/ + diff --git a/doc/src/q3asciidict.qdoc b/doc/src/q3asciidict.qdoc new file mode 100644 index 0000000..0b5b790 --- /dev/null +++ b/doc/src/q3asciidict.qdoc @@ -0,0 +1,416 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3AsciiDict + \brief The Q3AsciiDict class is a template class that provides a dictionary based on char* keys. + \compat + + Q3AsciiDict is implemented as a template class. Define a template + instance Q3AsciiDict\ to create a dictionary that operates on + pointers to X (X*). + + A dictionary is a collection of key-value pairs. The key is a + char* used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + Q3AsciiDict cannot handle Unicode keys; use the Q3Dict template + instead, which uses QString keys. A Q3Dict has the same + performace as a Q3AsciiDict. + + Example: + \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 0 + In this example we use a dictionary to keep track of the line + edits we're using. We insert each line edit into the dictionary + with a unique name and then access the line edits via the + dictionary. See Q3PtrDict, Q3IntDict and Q3Dict. + + See Q3Dict for full details, including the choice of dictionary + size, and how deletions are handled. + + \sa Q3AsciiDictIterator, Q3Dict, Q3IntDict, Q3PtrDict +*/ + + +/*! + \fn Q3AsciiDict::Q3AsciiDict( int size, bool caseSensitive, bool copyKeys ) + + Constructs a dictionary optimized for less than \a size entries. + + We recommend setting \a size to a suitably large prime number (a + bit larger than the expected number of entries). This makes the + hash distribution better and will improve lookup performance. + + When \a caseSensitive is TRUE (the default) Q3AsciiDict treats + "abc" and "Abc" as different keys; when it is FALSE "abc" and + "Abc" are the same. Case-insensitive comparison only considers the + 26 letters in US-ASCII. + + If \a copyKeys is TRUE (the default), the dictionary copies keys + using strcpy(); if it is FALSE, the dictionary just copies the + pointers. +*/ + +/*! + \fn Q3AsciiDict::Q3AsciiDict( const Q3AsciiDict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3AsciiDict::~Q3AsciiDict() + + Removes all items from the dictionary and destroys it. + + The items are deleted if auto-delete is enabled. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3AsciiDict &Q3AsciiDict::operator=(const Q3AsciiDict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared and then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy) unless newItem() has been reimplemented(). +*/ + +/*! + \fn uint Q3AsciiDict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3AsciiDict::size() const + + Returns the size of the internal hash array (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3AsciiDict::resize( uint newsize ) + + Changes the size of the hashtable to \a newsize. The contents of + the dictionary are preserved but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3AsciiDict::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0; + otherwise it returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3AsciiDict::insert( const char *key, const type *item ) + + Inserts the \a key with the \a item into the dictionary. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3AsciiDict::replace( const char *key, const type *item ) + + Replaces an item that has a key equal to \a key with \a item. + + If the item does not already exist, it will be inserted. + + \a item may not be 0. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 1 + + If there are two or more items with equal keys, then the most + recently inserted item will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3AsciiDict::remove( const char *key ) + + Removes the item associated with \a key from the dictionary. + Returns TRUE if successful, i.e. if the key existed in the + dictionary; otherwise returns FALSE. + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary traversal order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3AsciiDict::take( const char *key ) + + Takes the item associated with \a key out of the dictionary + without deleting it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the most + recently inserted item will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3AsciiDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that operate on dictionary are reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3AsciiDict::find( const char *key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + This function uses an internal hashing algorithm to optimize + lookup. + + If there are two or more items with equal keys, then the item that + was most recently inserted will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *Q3AsciiDict::operator[]( const char *key ) const + + Returns the item associated with \a key, or 0 if the key does + not exist in the dictionary. + + This function uses an internal hashing algorithm to optimize + lookup. + + If there are two or more items with equal keys, then the item that + was most recently inserted will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3AsciiDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3AsciiDict::read( QDataStream &s, + Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3AsciiDict::write(QDataStream &s, Q3PtrCollection::Item item) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3AsciiDictIterator + \brief The Q3AsciiDictIterator class provides an iterator for Q3AsciiDict collections. + \compat + + Q3AsciiDictIterator is implemented as a template class. Define a + template instance Q3AsciiDictIterator\ to create a dictionary + iterator that operates on Q3AsciiDict\ (dictionary of X*). + + Example: + \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 2 + In the example we insert some line edits into a dictionary, then + iterate over the dictionary printing the strings associated with + those line edits. + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. + + Multiple iterators may independently traverse the same dictionary. + A Q3AsciiDict knows about all the iterators that are operating on + the dictionary. When an item is removed from the dictionary, + Q3AsciiDict updates all the iterators that are referring to the + removed item to point to the next item in the (arbitrary) + traversal order. + + \sa Q3AsciiDict +*/ + +/*! + \fn Q3AsciiDictIterator::Q3AsciiDictIterator( const Q3AsciiDict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point on the first item in the \a dict. +*/ + +/*! + \fn Q3AsciiDictIterator::~Q3AsciiDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3AsciiDictIterator::count() const + + Returns the number of items in the dictionary this iterator + operates over. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3AsciiDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0, + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3AsciiDictIterator::toFirst() + + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. If the dictionary is + empty it sets the current item to 0 and returns 0. +*/ + +/*! + \fn Q3AsciiDictIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3AsciiDictIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn const char *Q3AsciiDictIterator::currentKey() const + + Returns a pointer to the key for the current iterator item. +*/ + +/*! + \fn type *Q3AsciiDictIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3AsciiDictIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3AsciiDictIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item, and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/q3cache.qdoc b/doc/src/q3cache.qdoc new file mode 100644 index 0000000..a54430f --- /dev/null +++ b/doc/src/q3cache.qdoc @@ -0,0 +1,461 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3Cache + \brief The Q3Cache class is a template class that provides a cache based on QString keys. + \compat + + A cache is a least recently used (LRU) list of cache items. Each + cache item has a key and a certain cost. The sum of item costs, + totalCost(), never exceeds the maximum cache cost, maxCost(). If + inserting a new item would cause the total cost to exceed the + maximum cost, the least recently used items in the cache are + removed. + + Q3Cache is a template class. Q3Cache\ defines a cache that + operates on pointers to X, or X*. + + Apart from insert(), by far the most important function is find() + (which also exists as operator[]()). This function looks up an + item, returns it, and by default marks it as being the most + recently used item. + + There are also methods to remove() or take() an object from the + cache. Calling setAutoDelete(TRUE) for a cache tells it to delete + items that are removed. The default is to not delete items when + they are removed (i.e., remove() and take() are equivalent). + + When inserting an item into the cache, only the pointer is copied, + not the item itself. This is called a shallow copy. It is possible + to make the cache copy all of the item's data (known as a deep + copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a cache and reimplement newItem() if you want deep copies. + + When removing a cache item, the virtual function + Q3PtrCollection::deleteItem() is called. The default + implementation deletes the item if auto-deletion is enabled, and + does nothing otherwise. + + There is a Q3CacheIterator that can be used to traverse the items + in the cache in arbitrary order. + + In Q3Cache, the cache items are accessed via QString keys, which + are Unicode strings. If you want to use non-Unicode, plain 8-bit + \c char* keys, use the Q3AsciiCache template. A Q3Cache has the + same performance as a Q3AsciiCache. + + \sa Q3CacheIterator, Q3AsciiCache, Q3IntCache +*/ + +/*! + \fn Q3Cache::Q3Cache( const Q3Cache &c ) + + \internal + + Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. +*/ + + +/*! + \fn Q3Cache::Q3Cache( int maxCost, int size, bool caseSensitive ) + + Constructs a cache whose contents will never have a total cost + greater than \a maxCost and which is expected to contain less than + \a size items. + + \a size is actually the size of an internal hash array; it's + usually best to make it a prime number and at least 50% bigger + than the largest expected number of items in the cache. + + Each inserted item has an associated cost. When inserting a new + item, if the total cost of all items in the cache will exceed \a + maxCost, the cache will start throwing out the older (least + recently used) items until there is enough room for the new item + to be inserted. + + If \a caseSensitive is TRUE (the default), the cache keys are case + sensitive; if it is FALSE, they are case-insensitive. + Case-insensitive comparison considers all Unicode letters. +*/ + +/*! + \fn Q3Cache::~Q3Cache() + + Removes all items from the cache and destroys it. All iterators + that access this cache will be reset. +*/ + +/*! + \fn Q3Cache& Q3Cache::operator=( const Q3Cache &c ) + + \internal + + Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn int Q3Cache::maxCost() const + + Returns the maximum allowed total cost of the cache. + + \sa setMaxCost() totalCost() +*/ + +/*! + \fn int Q3Cache::totalCost() const + + Returns the total cost of the items in the cache. This is an + integer in the range 0 to maxCost(). + + \sa setMaxCost() +*/ + +/*! + \fn void Q3Cache::setMaxCost( int m ) + + Sets the maximum allowed total cost of the cache to \a m. If the + current total cost is greater than \a m, some items are deleted + immediately. + + \sa maxCost() totalCost() +*/ + +/*! + \fn uint Q3Cache::count() const + + Returns the number of items in the cache. + + \sa totalCost() +*/ + +/*! + \fn uint Q3Cache::size() const + + Returns the size of the hash array used to implement the cache. + This should be a bit bigger than count() is likely to be. +*/ + +/*! + \fn bool Q3Cache::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. +*/ + +/*! + \fn bool Q3Cache::insert( const QString &k, const type *d, int c, int p ) + + Inserts the item \a d into the cache with key \a k and associated + cost, \a c. Returns TRUE if it is successfully inserted; otherwise + returns FALSE. + + The cache's size is limited, and if the total cost is too high, + Q3Cache will remove old, least recently used items until there is + room for this new item. + + The parameter \a p is internal and should be left at the default + value (0). + + \warning If this function returns FALSE (which could happen, e.g. + if the cost of this item alone exceeds maxCost()) you must delete + \a d yourself. Additionally, be very careful about using \a d + after calling this function because any other insertions into the + cache, from anywhere in the application or within Qt itself, could + cause the object to be discarded from the cache and the pointer to + become invalid. +*/ + +/*! + \fn bool Q3Cache::remove( const QString &k ) + + Removes the item associated with \a k, and returns TRUE if the + item was present in the cache; otherwise returns FALSE. + + The item is deleted if auto-deletion has been enabled, i.e., if + you have called setAutoDelete(TRUE). + + If there are two or more items with equal keys, the one that was + inserted last is removed. + + All iterators that refer to the removed item are set to point to + the next item in the cache's traversal order. + + \sa take(), clear() +*/ + +/*! + \fn type *Q3Cache::take( const QString &k ) + + Takes the item associated with \a k out of the cache without + deleting it, and returns a pointer to the item taken out, or 0 + if the key does not exist in the cache. + + If there are two or more items with equal keys, the one that was + inserted last is taken. + + All iterators that refer to the taken item are set to point to the + next item in the cache's traversal order. + + \sa remove(), clear() +*/ + +/*! + \fn void Q3Cache::clear() + + Removes all items from the cache and deletes them if auto-deletion + has been enabled. + + All cache iterators that operate this on cache are reset. + + \sa remove() take() +*/ + +/*! + \fn type *Q3Cache::find( const QString &k, bool ref ) const + + Returns the item associated with key \a k, or 0 if the key does + not exist in the cache. If \a ref is TRUE (the default), the item + is moved to the front of the least recently used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. +*/ + +/*! + \fn type *Q3Cache::operator[]( const QString &k ) const + + Returns the item associated with key \a k, or 0 if \a k does not + exist in the cache, and moves the item to the front of the least + recently used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. + + This is the same as find( k, TRUE ). + + \sa find() +*/ + +/*! + \fn void Q3Cache::statistics() const + + A debug-only utility function. Prints out cache usage, hit/miss, + and distribution information using qDebug(). This function does + nothing in the release library. +*/ + +/***************************************************************************** + Q3CacheIterator documentation + *****************************************************************************/ + +/*! + \class Q3CacheIterator qcache.h + \brief The Q3CacheIterator class provides an iterator for Q3Cache collections. + \compat + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. If new objects are inserted into the cache + while the iterator is active, the iterator may or may not see + them. + + Multiple iterators are completely independent, even when they + operate on the same Q3Cache. Q3Cache updates all iterators that + refer an item when that item is removed. + + Q3CacheIterator provides an operator++(), and an operator+=() to + traverse the cache. The current() and currentKey() functions are + used to access the current cache item and its key. The atFirst() + and atLast() return TRUE if the iterator points to the first or + last item in the cache respectively. The isEmpty() function + returns TRUE if the cache is empty, and count() returns the number + of items in the cache. + + Note that atFirst() and atLast() refer to the iterator's arbitrary + ordering, not to the cache's internal least recently used list. + + \sa Q3Cache +*/ + +/*! + \fn Q3CacheIterator::Q3CacheIterator( const Q3Cache &cache ) + + Constructs an iterator for \a cache. The current iterator item is + set to point to the first item in the \a cache. +*/ + +/*! + \fn Q3CacheIterator::Q3CacheIterator (const Q3CacheIterator & ci) + + Constructs an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently from there on. +*/ + +/*! + \fn Q3CacheIterator& Q3CacheIterator::operator=( const Q3CacheIterator &ci ) + + Makes this an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently thereafter. +*/ + +/*! + \fn uint Q3CacheIterator::count() const + + Returns the number of items in the cache on which this iterator + operates. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3CacheIterator::isEmpty() const + + Returns TRUE if the cache is empty, i.e. count() == 0; otherwise + it returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3CacheIterator::atFirst() const + + Returns TRUE if the iterator points to the first item in the + cache; otherwise returns FALSE. Note that this refers to the + iterator's arbitrary ordering, not to the cache's internal least + recently used list. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3CacheIterator::atLast() const + + Returns TRUE if the iterator points to the last item in the cache; + otherwise returns FALSE. Note that this refers to the iterator's + arbitrary ordering, not to the cache's internal least recently + used list. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3CacheIterator::toFirst() + + Sets the iterator to point to the first item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toLast() isEmpty() +*/ + +/*! + \fn type *Q3CacheIterator::toLast() + + Sets the iterator to point to the last item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toFirst() isEmpty() +*/ + +/*! + \fn Q3CacheIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3CacheIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn QString Q3CacheIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3CacheIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the cache or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3CacheIterator::operator+=( uint jump ) + + Returns the item \a jump positions after the current item, or 0 if + it is beyond the last item. Makes this the current item. +*/ + +/*! + \fn type *Q3CacheIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item, or 0 + if it is before the first item. Makes this the current item. +*/ + +/*! + \fn type *Q3CacheIterator::operator++() + + Prefix++ makes the iterator point to the item just after current() + and makes that the new current item for the iterator. If current() + was the last item, operator++() returns 0. +*/ + +/*! + \fn type *Q3CacheIterator::operator--() + + Prefix-- makes the iterator point to the item just before + current() and makes that the new current item for the iterator. If + current() was the first item, operator--() returns 0. +*/ + diff --git a/doc/src/q3dict.qdoc b/doc/src/q3dict.qdoc new file mode 100644 index 0000000..8a0c5b0 --- /dev/null +++ b/doc/src/q3dict.qdoc @@ -0,0 +1,446 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3Dict + \brief The Q3Dict class is a template class that provides a + dictionary based on QString keys. + \compat + + Q3Dict is implemented as a template class. Define a template + instance Q3Dict\ to create a dictionary that operates on + pointers to X (X *). + + A dictionary is a collection of key-value pairs. The key is a + QString used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + If you want to use non-Unicode, plain 8-bit \c char* keys, use the + Q3AsciiDict template. A Q3Dict has the same performance as a + Q3AsciiDict. If you want to have a dictionary that maps QStrings to + QStrings use QMap. + + The size() of the dictionary is very important. In order to get + good performance, you should use a suitably large prime number. + Suitable means equal to or larger than the maximum expected number + of dictionary items. Size is set in the constructor but may be + changed with resize(). + + Items are inserted with insert(); 0 pointers cannot be inserted. + Items are removed with remove(). All the items in a dictionary can + be removed with clear(). The number of items in the dictionary is + returned by count(). If the dictionary contains no items isEmpty() + returns TRUE. You can change an item's value with replace(). Items + are looked up with operator[](), or with find() which return a + pointer to the value or 0 if the given key does not exist. You can + take an item out of the dictionary with take(). + + Calling setAutoDelete(TRUE) for a dictionary tells it to delete + items that are removed. The default behavior is not to delete + items when they are removed. + + When an item is inserted, the key is converted (hashed) to an + integer index into an internal hash array. This makes lookup very + fast. + + Items with equal keys are allowed. When inserting two items with + the same key, only the last inserted item will be accessible (last + in, first out) until it is removed. + + The Q3DictIterator class can traverse the dictionary, but only in + an arbitrary order. Multiple iterators may independently traverse + the same dictionary. + + When inserting an item into a dictionary, only the pointer is + copied, not the item itself, i.e. a shallow copy is made. It is + possible to make the dictionary copy all of the item's data (a + deep copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement newItem() if you want deep + copies. + + When removing a dictionary item, the virtual function + Q3PtrCollection::deleteItem() is called. Q3Dict's default + implementation is to delete the item if auto-deletion is enabled. + + \sa Q3DictIterator, Q3AsciiDict, Q3IntDict, Q3PtrDict +*/ + + +/*! + \fn Q3Dict::Q3Dict( int size, bool caseSensitive ) + + Constructs a dictionary optimized for less than \a size entries. + + We recommend setting \a size to a suitably large prime number + (e.g. a prime that's slightly larger than the expected number of + entries). This makes the hash distribution better which will lead + to faster lookup. + + If \a caseSensitive is TRUE (the default), keys which differ only + by case are considered different. +*/ + +/*! + \fn Q3Dict::Q3Dict( const Q3Dict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3Dict::~Q3Dict() + + Removes all items from the dictionary and destroys it. If + setAutoDelete() is TRUE, each value is deleted. All iterators that + access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3Dict &Q3Dict::operator=(const Q3Dict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared, then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented. +*/ + +/*! + \fn uint Q3Dict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3Dict::size() const + + Returns the size of the internal hash array (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3Dict::resize( uint newsize ) + + Changes the size of the hash table to \a newsize. The contents of + the dictionary are preserved, but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3Dict::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0; + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3Dict::insert( const QString &key, const type *item ) + + Inserts the key \a key with value \a item into the dictionary. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3Dict::replace( const QString &key, const type *item ) + + Replaces the value of the key, \a key with \a item. + + If the item does not already exist, it will be inserted. + + \a item may not be 0. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 0 + + If there are two or more items with equal keys, then the last item + that was inserted will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3Dict::remove( const QString &key ) + + Removes the item with \a key from the dictionary. Returns TRUE if + successful, i.e. if the item is in the dictionary; otherwise + returns FALSE. + + If there are two or more items with equal keys, then the last item + that was inserted will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary's traversal order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3Dict::take( const QString &key ) + + Takes the item with \a key out of the dictionary without deleting + it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the last item + that was inserted will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3Dict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that operate on the dictionary are reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3Dict::find( const QString &key ) const + + Returns the item with key \a key, or 0 if the key does not exist + in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *Q3Dict::operator[]( const QString &key ) const + + Returns the item with key \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3Dict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3Dict::read( QDataStream &s, Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3Dict::write( QDataStream &s, Q3PtrCollection::Item item ) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3DictIterator + \brief The Q3DictIterator class provides an iterator for Q3Dict collections. + \compat + + Q3DictIterator is implemented as a template class. Define a + template instance Q3DictIterator\ to create a dictionary + iterator that operates on Q3Dict\ (dictionary of X*). + + The traversal order is arbitrary; when we speak of the "first", + "last" and "next" item we are talking in terms of this arbitrary + order. + + Multiple iterators may independently traverse the same dictionary. + A Q3Dict knows about all the iterators that are operating on the + dictionary. When an item is removed from the dictionary, Q3Dict + updates all iterators that are referring to the removed item to + point to the next item in the (arbitrary) traversal order. + + Example: + \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 1 + In the example we insert some pointers to line edits into a + dictionary, then iterate over the dictionary printing the strings + associated with the line edits. + + \sa Q3Dict +*/ + +/*! + \fn Q3DictIterator::Q3DictIterator( const Q3Dict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point to the first item in the dictionary, \a dict. First + in this context means first in the arbitrary traversal order. +*/ + +/*! + \fn Q3DictIterator::~Q3DictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3DictIterator::count() const + + Returns the number of items in the dictionary over which the + iterator is operating. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3DictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0; + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3DictIterator::toFirst() + + Resets the iterator, making the first item the first current item. + First in this context means first in the arbitrary traversal + order. Returns a pointer to this item. + + If the dictionary is empty it sets the current item to 0 and + returns 0. +*/ + +/*! + \fn type *Q3DictIterator::operator*() + \internal +*/ + +/*! + \fn Q3DictIterator::operator type*() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + + +/*! + \fn type *Q3DictIterator::current() const + + Returns a pointer to the current iterator item's value. +*/ + +/*! + \fn QString Q3DictIterator::currentKey() const + + Returns the current iterator item's key. +*/ + +/*! + \fn type *Q3DictIterator::operator()() + + Makes the next item current and returns the original current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3DictIterator::operator++() + + Prefix ++ makes the next item current and returns the new current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3DictIterator::operator+=( uint jump ) + \internal + Sets the current item to the item \a jump positions after the current item, + and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is empty, + it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/q3intcache.qdoc b/doc/src/q3intcache.qdoc new file mode 100644 index 0000000..bba79f1 --- /dev/null +++ b/doc/src/q3intcache.qdoc @@ -0,0 +1,446 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3IntCache + \brief The Q3IntCache class is a template class that provides a cache based on long keys. + \compat + + Q3IntCache is implemented as a template class. Define a template + instance Q3IntCache\ to create a cache that operates on + pointers to X, or X*. + + A cache is a least recently used (LRU) list of cache items, + accessed via \c long keys. Each cache item has a cost. The sum + of item costs, totalCost(), will not exceed the maximum cache + cost, maxCost(). If inserting a new item would cause the total + cost to exceed the maximum cost, the least recently used items in + the cache are removed. + + Apart from insert(), by far the most important function is find() + (which also exists as operator[]). This function looks up an + item, returns it, and by default marks it as being the most + recently used item. + + There are also methods to remove() or take() an object from the + cache. Calling setAutoDelete(TRUE) for a cache tells it to delete + items that are removed. The default is to not delete items when + they are removed (i.e. remove() and take() are equivalent). + + When inserting an item into the cache, only the pointer is copied, + not the item itself. This is called a shallow copy. It is possible + to make the cache copy all of the item's data (known as a deep + copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement newItem() if you want deep + copies. + + When removing a cache item, the item will be automatically + deleted if auto-deletion is enabled. + + There is a Q3IntCacheIterator which may be used to traverse the + items in the cache in arbitrary order. + + \sa Q3IntCacheIterator, Q3Cache, Q3AsciiCache +*/ + +/*! + \fn Q3IntCache::Q3IntCache( const Q3IntCache &c ) + + \internal + + Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn Q3IntCache::Q3IntCache( int maxCost, int size ) + + Constructs a cache whose contents will never have a total cost + greater than \a maxCost and which is expected to contain less than + \a size items. + + \a size is actually the size of an internal hash array; it's + usually best to make it prime and at least 50% bigger than the + largest expected number of items in the cache. + + Each inserted item is associated with a cost. When inserting a new + item, if the total cost of all items in the cache will exceed \a + maxCost, the cache will start throwing out the older (least + recently used) items until there is enough room for the new item + to be inserted. +*/ + +/*! + \fn Q3IntCache::~Q3IntCache() + + Removes all items from the cache and then destroys the int cache. + If auto-deletion is enabled the cache's items are deleted. All + iterators that access this cache will be reset. +*/ + +/*! + \fn Q3IntCache& Q3IntCache::operator=( const Q3IntCache &c ) + + \internal + + Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn int Q3IntCache::maxCost() const + + Returns the maximum allowed total cost of the cache. + + \sa setMaxCost() totalCost() +*/ + +/*! + \fn int Q3IntCache::totalCost() const + + Returns the total cost of the items in the cache. This is an + integer in the range 0 to maxCost(). + + \sa setMaxCost() +*/ + +/*! + \fn void Q3IntCache::setMaxCost( int m ) + + Sets the maximum allowed total cost of the cache to \a m. If the + current total cost is greater than \a m, some items are removed + immediately. + + \sa maxCost() totalCost() +*/ + +/*! + \fn uint Q3IntCache::count() const + + Returns the number of items in the cache. + + \sa totalCost() +*/ + +/*! + \fn uint Q3IntCache::size() const + + Returns the size of the hash array used to implement the cache. + This should be a bit larger than count() is likely to be. +*/ + +/*! + \fn bool Q3IntCache::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. +*/ + +/*! + \fn bool Q3IntCache::insert( long k, const type *d, int c, int p ) + + Inserts the item \a d into the cache with key \a k and assigns it + a cost of \a c (default 1). Returns TRUE if it succeeds; otherwise + returns FALSE. + + The cache's size is limited, and if the total cost is too high, + Q3IntCache will remove old, least-used items until there is room + for this new item. + + The parameter \a p is internal and should be left at the default + value (0). + + \warning If this function returns FALSE (for example, the cost \c, + exceeds maxCost()), you must delete \a d yourself. Additionally, + be very careful about using \a d after calling this function. Any + other insertions into the cache, from anywhere in the application + or within Qt itself, could cause the object to be discarded from + the cache and the pointer to become invalid. +*/ + +/*! + \fn bool Q3IntCache::remove( long k ) + + Removes the item associated with \a k, and returns TRUE if the + item was present in the cache; otherwise returns FALSE. + + The item is deleted if auto-deletion has been enabled, i.e. if you + have called setAutoDelete(TRUE). + + If there are two or more items with equal keys, the one that was + inserted most recently is removed. + + All iterators that refer to the removed item are set to point to + the next item in the cache's traversal order. + + \sa take(), clear() +*/ + +/*! + \fn type * Q3IntCache::take( long k ) + + Takes the item associated with \a k out of the cache without + deleting it, and returns a pointer to the item taken out or 0 if + the key does not exist in the cache. + + If there are two or more items with equal keys, the one that was + inserted most recently is taken. + + All iterators that refer to the taken item are set to point to the + next item in the cache's traversal order. + + \sa remove(), clear() +*/ + +/*! + \fn void Q3IntCache::clear() + + Removes all items from the cache, and deletes them if + auto-deletion has been enabled. + + All cache iterators that operate this on cache are reset. + + \sa remove() take() +*/ + +/*! + \fn type * Q3IntCache::find( long k, bool ref ) const + + Returns the item associated with \a k, or 0 if the key does not + exist in the cache. If \a ref is TRUE (the default), the item is + moved to the front of the least recently used list. + + If there are two or more items with equal keys, the one that was + inserted most recently is returned. +*/ + +/*! + \fn type * Q3IntCache::operator[]( long k ) const + + Returns the item associated with \a k, or 0 if \a k does not exist + in the cache, and moves the item to the front of the least + recently used list. + + If there are two or more items with equal keys, the one that was + inserted most recently is returned. + + This is the same as find( k, TRUE ). + + \sa find() +*/ + +/*! + \fn void Q3IntCache::statistics() const + + A debug-only utility function. Prints out cache usage, hit/miss, + and distribution information using qDebug(). This function does + nothing in the release library. +*/ + +/*! + \class Q3IntCacheIterator + \brief The Q3IntCacheIterator class provides an iterator for Q3IntCache collections. + \compat + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. If new objects are inserted into the cache + while the iterator is active, the iterator may or may not see + them. + + Multiple iterators are completely independent, even when they + operate on the same Q3IntCache. Q3IntCache updates all iterators + that refer an item when that item is removed. + + Q3IntCacheIterator provides an operator++(), and an operator+=() to + traverse the cache; current() and currentKey() to access the + current cache item and its key; atFirst() atLast(), which return + TRUE if the iterator points to the first/last item in the cache; + isEmpty(), which returns TRUE if the cache is empty; and count(), + which returns the number of items in the cache. + + Note that atFirst() and atLast() refer to the iterator's arbitrary + ordering, not to the cache's internal least recently used list. + + \sa Q3IntCache +*/ + +/*! + \fn Q3IntCacheIterator::Q3IntCacheIterator( const Q3IntCache &cache ) + + Constructs an iterator for \a cache. The current iterator item is + set to point to the first item in the \a cache (or rather, the + first item is defined to be the item at which this constructor + sets the iterator to point). +*/ + +/*! + \fn Q3IntCacheIterator::Q3IntCacheIterator (const Q3IntCacheIterator & ci) + + Constructs an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently from there on. +*/ + +/*! + \fn Q3IntCacheIterator& Q3IntCacheIterator::operator=( const Q3IntCacheIterator &ci ) + + Makes this an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently thereafter. +*/ + +/*! + \fn uint Q3IntCacheIterator::count() const + + Returns the number of items in the cache on which this iterator + operates. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3IntCacheIterator::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3IntCacheIterator::atFirst() const + + Returns TRUE if the iterator points to the first item in the + cache; otherwise returns FALSE. Note that this refers to the + iterator's arbitrary ordering, not to the cache's internal least + recently used list. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3IntCacheIterator::atLast() const + + Returns TRUE if the iterator points to the last item in the cache; + otherwise returns FALSE. Note that this refers to the iterator's + arbitrary ordering, not to the cache's internal least recently + used list. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3IntCacheIterator::toFirst() + + Sets the iterator to point to the first item in the cache and + returns a pointer to the item. + + Sets the iterator to 0, and returns 0, if the cache is empty. + + \sa toLast() isEmpty() +*/ + +/*! + \fn type *Q3IntCacheIterator::toLast() + + Sets the iterator to point to the last item in the cache and + returns a pointer to the item. + + Sets the iterator to 0, and returns 0, if the cache is empty. + + \sa toFirst() isEmpty() +*/ + +/*! + \fn Q3IntCacheIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3IntCacheIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn long Q3IntCacheIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the cache or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator+=( uint jump ) + + Returns the item \a jump positions after the current item, or 0 if + it is beyond the last item. Makes this the current item. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item, or 0 + if it is beyond the first item. Makes this the current item. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator++() + + Prefix ++ makes the iterator point to the item just after + current(), and makes it the new current item for the iterator. If + current() was the last item, operator--() returns 0. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator--() + + Prefix -- makes the iterator point to the item just before + current(), and makes it the new current item for the iterator. If + current() was the first item, operator--() returns 0. +*/ diff --git a/doc/src/q3intdict.qdoc b/doc/src/q3intdict.qdoc new file mode 100644 index 0000000..8f0aabf --- /dev/null +++ b/doc/src/q3intdict.qdoc @@ -0,0 +1,390 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3IntDict + \brief The Q3IntDict class is a template class that provides a dictionary based on long keys.\ + \compat + + Q3IntDict is implemented as a template class. Define a template + instance Q3IntDict\ to create a dictionary that operates on + pointers to X (X*). + + A dictionary is a collection of key-value pairs. The key is an \c + long used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + Example: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 0 + + See Q3Dict for full details, including the choice of dictionary + size, and how deletions are handled. + + \sa Q3IntDictIterator, Q3Dict, Q3AsciiDict, Q3PtrDict +*/ + + +/*! + \fn Q3IntDict::Q3IntDict( int size ) + + Constructs a dictionary using an internal hash array of size \a + size. + + Setting \a size to a suitably large prime number (equal to or + greater than the expected number of entries) makes the hash + distribution better which leads to faster lookup. +*/ + +/*! + \fn Q3IntDict::Q3IntDict( const Q3IntDict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3IntDict::~Q3IntDict() + + Removes all items from the dictionary and destroys it. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3IntDict &Q3IntDict::operator=(const Q3IntDict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared and then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented. +*/ + +/*! + \fn uint Q3IntDict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3IntDict::size() const + + Returns the size of the internal hash array (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3IntDict::resize( uint newsize ) + + Changes the size of the hashtable to \a newsize. The contents of + the dictionary are preserved, but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3IntDict::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3IntDict::insert( long key, const type *item ) + + Insert item \a item into the dictionary using key \a key. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3IntDict::replace( long key, const type *item ) + + If the dictionary has key \a key, this key's item is replaced with + \a item. If the dictionary doesn't contain key \a key, \a item is + inserted into the dictionary using key \a key. + + \a item may not be 0. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 1 + + If there are two or more items with equal keys, then the most + recently inserted item will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3IntDict::remove( long key ) + + Removes the item associated with \a key from the dictionary. + Returns TRUE if successful, i.e. if the \a key is in the + dictionary; otherwise returns FALSE. + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary's traversal + order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3IntDict::take( long key ) + + Takes the item associated with \a key out of the dictionary + without deleting it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the most + recently inserted item will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary's traversing order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3IntDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that access this dictionary will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3IntDict::find( long key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to operator[]. + + \sa operator[]() +*/ + +/*! + \fn type *Q3IntDict::operator[]( long key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3IntDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3IntDict::read( QDataStream &s, Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3IntDict::write( QDataStream &s, Q3PtrCollection::Item item ) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3IntDictIterator + \brief The Q3IntDictIterator class provides an iterator for Q3IntDict collections. + \compat + + Q3IntDictIterator is implemented as a template class. Define a + template instance Q3IntDictIterator\ to create a dictionary + iterator that operates on Q3IntDict\ (dictionary of X*). + + Example: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 2 + + Note that the traversal order is arbitrary; you are not guaranteed the + order shown above. + + Multiple iterators may independently traverse the same dictionary. + A Q3IntDict knows about all the iterators that are operating on the + dictionary. When an item is removed from the dictionary, Q3IntDict + updates all iterators that refer the removed item to point to the + next item in the traversal order. + + \sa Q3IntDict +*/ + +/*! + \fn Q3IntDictIterator::Q3IntDictIterator( const Q3IntDict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point to the 'first' item in the \a dict. The first item + refers to the first item in the dictionary's arbitrary internal + ordering. +*/ + +/*! + \fn Q3IntDictIterator::~Q3IntDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3IntDictIterator::count() const + + Returns the number of items in the dictionary this iterator + operates over. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3IntDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise eturns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3IntDictIterator::toFirst() + + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. The first item + refers to the first item in the dictionary's arbitrary internal + ordering. If the dictionary is empty it sets the current item to + 0 and returns 0. +*/ + +/*! + \fn Q3IntDictIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3IntDictIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn long Q3IntDictIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3IntDictIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3IntDictIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3IntDictIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item, and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/q3memarray.qdoc b/doc/src/q3memarray.qdoc new file mode 100644 index 0000000..5ab7895 --- /dev/null +++ b/doc/src/q3memarray.qdoc @@ -0,0 +1,523 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3MemArray + \brief The Q3MemArray class is a template class that provides arrays of simple types. + \compat + + Q3MemArray is implemented as a template class. Define a template + instance Q3MemArray\ to create an array that contains X items. + + Q3MemArray stores the array elements directly in the array. It can + only deal with simple types (i.e. C++ types, structs, and classes + that have no constructors, destructors, or virtual functions). + Q3MemArray uses bitwise operations to copy and compare array + elements. + + The Q3PtrVector collection class is also a kind of array. Like most + old Qt collection classes, it uses pointers to the contained items. + + Q3MemArray uses explicit sharing with a + reference count. If more than one array shares common data and one + of the arrays is modified, all the arrays are modified. + + The benefit of sharing is that a program does not need to duplicate + data when it is not required, which results in lower memory use + and less copying of data. + + Example: + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 0 + + Program output: + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 1 + + Note concerning the use of Q3MemArray for manipulating structs or + classes: Compilers will often pad the size of structs of odd sizes + up to the nearest word boundary. This will then be the size + Q3MemArray will use for its bitwise element comparisons. Because + the remaining bytes will typically be uninitialized, this can + cause find() etc. to fail to find the element. Example: + + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 2 + + To work around this, make sure that you use a struct where + sizeof() returns the same as the sum of the sizes of the members + either by changing the types of the struct members or by adding + dummy members. + + Q3MemArray data can be traversed by iterators (see begin() and + end()). The number of items is returned by count(). The array can + be resized with resize() and filled using fill(). + + You can make a shallow copy of the array with assign() (or + operator=()) and a deep copy with duplicate(). + + Search for values in the array with find() and contains(). For + sorted arrays (see sort()) you can search using bsearch(). + + You can set the data directly using setRawData() and + resetRawData(), although this requires care. +*/ + +/*! \fn Q3MemArray::operator QVector() const + + Automatically converts the Q3MemArray into a QVector. +*/ + +/*! \typedef Q3MemArray::Iterator + A Q3MemArray iterator. + \sa begin() end() +*/ +/*! \typedef Q3MemArray::ConstIterator + A const Q3MemArray iterator. + \sa begin() end() +*/ +/*! \typedef Q3MemArray::ValueType + \internal +*/ + +/*! + \fn Q3MemArray::Q3MemArray() + + Constructs a null array. + + \sa isNull() +*/ + +/*! + \fn Q3MemArray::Q3MemArray( int size ) + + Constructs an array with room for \a size elements. Makes a null + array if \a size == 0. + + The elements are left uninitialized. + + \sa resize(), isNull() +*/ + +/*! + \fn Q3MemArray::Q3MemArray( const Q3MemArray &a ) + + Constructs a shallow copy of \a a. + + \sa assign() +*/ + +/*! + \fn Q3MemArray::Q3MemArray(const QVector &vector) + + Constructs a copy of \a vector. +*/ + +/*! + \fn Q3MemArray::Q3MemArray(int arg1, int arg2) + + Constructs an array \e{without allocating} array space. The + arguments \a arg1 and \a arg2 should be zero. Use at your own + risk. +*/ + +/*! + \fn Q3MemArray::~Q3MemArray() + + Dereferences the array data and deletes it if this was the last + reference. +*/ + +/*! + \fn Q3MemArray &Q3MemArray::operator=( const Q3MemArray &a ) + + Assigns a shallow copy of \a a to this array and returns a + reference to this array. + + Equivalent to assign( a ). +*/ + +/*! + \fn type *Q3MemArray::data() const + + Returns a pointer to the actual array data. + + The array is a null array if data() == 0 (null pointer). + + \sa isNull() +*/ + +/*! + \fn uint Q3MemArray::nrefs() const + + Returns the reference count for the shared array data. This + reference count is always greater than zero. +*/ + +/*! + \fn uint Q3MemArray::size() const + + Returns the size of the array (maximum number of elements). + + The array is a null array if size() == 0. + + \sa isNull(), resize() +*/ + +/*! + \fn uint Q3MemArray::count() const + + Returns the same as size(). + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::isEmpty() const + + Returns TRUE if the array is empty; otherwise returns FALSE. + + isEmpty() is equivalent to isNull() for Q3MemArray (unlike + QString). +*/ + +/*! + \fn bool Q3MemArray::isNull() const + + Returns TRUE if the array is null; otherwise returns FALSE. + + A null array has size() == 0 and data() == 0. +*/ + +/*! + \fn bool Q3MemArray::resize( uint size, Optimization optim ) + + Resizes (expands or shrinks) the array to \a size elements. The + array becomes a null array if \a size == 0. + + Returns TRUE if successful, or FALSE if the memory cannot be + allocated. + + New elements are not initialized. + + \a optim is either Q3GArray::MemOptim (the default) or + Q3GArray::SpeedOptim. When optimizing for speed rather than memory + consumption, the array uses a smart grow and shrink algorithm that + might allocate more memory than is actually needed for \a size + elements. This speeds up subsequent resize operations, for example + when appending many elements to an array, since the space has + already been allocated. + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::resize( uint size ) + + \overload + + Resizes (expands or shrinks) the array to \a size elements. The + array becomes a null array if \a size == 0. + + Returns TRUE if successful, i.e. if the memory can be allocated; + otherwise returns FALSE. + + New elements are not initialized. + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::truncate( uint pos ) + + Truncates the array at position \a pos. + + Returns TRUE if successful, i.e. if the memory can be allocated; + otherwise returns FALSE. + + Equivalent to resize(\a pos). + + \sa resize() +*/ + +/*! + \fn bool Q3MemArray::fill( const type &v, int size ) + + Fills the array with the value \a v. If \a size is specified as + different from -1, then the array will be resized before being + filled. + + Returns TRUE if successful, i.e. if \a size is -1, or \a size is + != -1 and the memory can be allocated; otherwise returns FALSE. + + \sa resize() +*/ + +/*! + \fn void Q3MemArray::detach() + + Detaches this array from shared array data; i.e. it makes a + private, deep copy of the data. + + Copying will be performed only if the \link nrefs() reference + count\endlink is greater than one. + + \sa copy() +*/ + +/*! + \fn Q3MemArray Q3MemArray::copy() const + + Returns a deep copy of this array. + + \sa detach(), duplicate() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::assign( const Q3MemArray &a ) + + Shallow copy. Dereferences the current array and references the + data contained in \a a instead. Returns a reference to this array. + + \sa operator=() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::assign( const type *data, uint size ) + + \overload + + Shallow copy. Dereferences the current array and references the + array data \a data, which contains \a size elements. Returns a + reference to this array. + + Do not delete \a data later; Q3MemArray will call free() on it + at the right time. +*/ + +/*! + \fn Q3MemArray &Q3MemArray::duplicate( const Q3MemArray &a ) + + Deep copy. Dereferences the current array and obtains a copy of + the data contained in \a a instead. Returns a reference to this + array. + + \sa copy() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::duplicate( const type *data, uint size ) + + \overload + + Deep copy. Dereferences the current array and obtains a copy of + the array data \a data instead. Returns a reference to this array. + The size of the array is given by \a size. + + \sa copy() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::setRawData( const type *data, uint size ) + + Sets raw data and returns a reference to the array. + + Dereferences the current array and sets the new array data to \a + data and the new array size to \a size. Do not attempt to resize + or re-assign the array data when raw data has been set. Call + resetRawData(\a data, \a size) to reset the array. + + Setting raw data is useful because it sets Q3MemArray data without + allocating memory or copying data. + + Example I (intended use): + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 3 + + Example II (you don't want to do this): + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 4 + + \warning If you do not call resetRawData(), Q3MemArray will attempt + to deallocate or reallocate the raw data, which might not be too + good. Be careful. + + \sa resetRawData() +*/ + +/*! + \fn void Q3MemArray::resetRawData( const type *data, uint size ) + + Removes internal references to the raw data that was set using + setRawData(). This means that Q3MemArray no longer has access to + the \a data, so you are free to manipulate \a data as you wish. + You can now use the Q3MemArray without affecting the original \a + data, for example by calling setRawData() with a pointer to some + other data. + + The arguments must be the \a data and length, \a size, that were + passed to setRawData(). This is for consistency checking. + + \sa setRawData() +*/ + +/*! + \fn int Q3MemArray::find( const type &v, uint index ) const + + Finds the first occurrence of \a v, starting at position \a index. + + Returns the position of \a v, or -1 if \a v could not be found. + + \sa contains() +*/ + +/*! + \fn int Q3MemArray::contains( const type &v ) const + + Returns the number of times \a v occurs in the array. + + \sa find() +*/ + +/*! + \fn void Q3MemArray::sort() + + Sorts the array elements in ascending order, using bitwise + comparison (memcmp()). + + \sa bsearch() +*/ + +/*! + \fn int Q3MemArray::bsearch( const type &v ) const + + In a sorted array (as sorted by sort()), finds the first + occurrence of \a v by using a binary search. For a sorted + array this is generally much faster than find(), which does + a linear search. + + Returns the position of \a v, or -1 if \a v could not be found. + + \sa sort(), find() +*/ + +/*! + \fn type &Q3MemArray::operator[]( int index ) const + + Returns a reference to the element at position \a index in the + array. + + This can be used to both read and set an element. Equivalent to + at(). + + \sa at() +*/ + +/*! + \fn type &Q3MemArray::at( uint index ) const + + Returns a reference to the element at position \a index in the array. + + This can be used to both read and set an element. + + \sa operator[]() +*/ + +/*! + \fn Q3MemArray::operator const type *() const + + Cast operator. Returns a pointer to the array. + + \sa data() +*/ + +/*! + \fn bool Q3MemArray::operator==( const Q3MemArray &a ) const + + Returns TRUE if this array is equal to \a a; otherwise returns + FALSE. + + The two arrays are compared bitwise. + + \sa operator!=() +*/ + +/*! + \fn bool Q3MemArray::operator!=( const Q3MemArray &a ) const + + Returns TRUE if this array is different from \a a; otherwise + returns FALSE. + + The two arrays are compared bitwise. + + \sa operator==() +*/ + +/*! + \fn Iterator Q3MemArray::begin() + + Returns an iterator pointing at the beginning of this array. This + iterator can be used in the same way as the iterators of + Q3ValueList and QMap, for example. +*/ + +/*! + \fn Iterator Q3MemArray::end() + + Returns an iterator pointing behind the last element of this + array. This iterator can be used in the same way as the iterators + of Q3ValueList and QMap, for example. +*/ + +/*! + \fn ConstIterator Q3MemArray::begin() const + + \overload + + Returns a const iterator pointing at the beginning of this array. + This iterator can be used in the same way as the iterators of + Q3ValueList and QMap, for example. +*/ + +/*! + \fn ConstIterator Q3MemArray::end() const + + \overload + + Returns a const iterator pointing behind the last element of this + array. This iterator can be used in the same way as the iterators + of Q3ValueList and QMap, for example. +*/ diff --git a/doc/src/q3popupmenu.qdoc b/doc/src/q3popupmenu.qdoc new file mode 100644 index 0000000..137115e --- /dev/null +++ b/doc/src/q3popupmenu.qdoc @@ -0,0 +1,76 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PopupMenu + \brief The Q3PopupMenu class is a thin compatibility wrapper around QMenu. + \compat + + Use QMenu in new applications. Note that the menu's actions must + be \l {Q3Action}s. +*/ + +/*! + \fn Q3PopupMenu::Q3PopupMenu(QWidget *parent, const char *name) + + Constructs a menu with the given \a parent and \a name. +*/ + +/*! + \fn int Q3PopupMenu::exec() + + Pops up the menu and returns the ID of the action that was + selected. + + \sa QMenu::exec() +*/ + +/*! + \fn int Q3PopupMenu::exec(const QPoint & pos, int indexAtPoint) + + Pops up the menu at coordinate \a pos and returns the ID of the + action that was selected. + + If \a indexAtPoint is specified, the menu will pop up with the + item at index \a indexAtPoint under the mouse cursor. + + \sa QMenu::exec() +*/ diff --git a/doc/src/q3ptrdict.qdoc b/doc/src/q3ptrdict.qdoc new file mode 100644 index 0000000..a7e3545 --- /dev/null +++ b/doc/src/q3ptrdict.qdoc @@ -0,0 +1,388 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrDict + \brief The Q3PtrDict class is a template class that provides a dictionary based on void* keys. + \compat + + Q3PtrDict is implemented as a template class. Define a template + instance Q3PtrDict\ to create a dictionary that operates on + pointers to X (X*). + + A dictionary is a collection of key-value pairs. The key is a + void* used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + Example: + \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 0 + In this example we use a dictionary to add an extra property (a + char*) to the line edits we're using. + + See Q3Dict for full details, including the choice of dictionary + size, and how deletions are handled. + + \sa Q3PtrDictIterator, Q3Dict, Q3AsciiDict, Q3IntDict +*/ + + +/*! + \fn Q3PtrDict::Q3PtrDict( int size ) + + Constructs a dictionary using an internal hash array with the size + \a size. + + Setting \a size to a suitably large prime number (equal to or + greater than the expected number of entries) makes the hash + distribution better and improves lookup performance. +*/ + +/*! + \fn Q3PtrDict::Q3PtrDict( const Q3PtrDict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3PtrDict::~Q3PtrDict() + + Removes all items from the dictionary and destroys it. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3PtrDict &Q3PtrDict::operator=(const Q3PtrDict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared and then each item in \a dict is + inserted into the dictionary. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented. +*/ + +/*! + \fn uint Q3PtrDict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3PtrDict::size() const + + Returns the size of the internal hash table (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3PtrDict::resize( uint newsize ) + + Changes the size of the hash table to \a newsize. The contents of + the dictionary are preserved, but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3PtrDict::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3PtrDict::insert( void *key, const type *item ) + + Inserts the \a key with the \a item into the dictionary. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3PtrDict::replace( void *key, const type *item ) + + If the dictionary has key \a key, this key's item is replaced with + \a item. If the dictionary doesn't contain key \a key, \a item is + inserted into the dictionary using key \a key. + + \a item may not be 0. + + Equivalent to + \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 1 + + If there are two or more items with equal keys, then the most + recently inserted item will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3PtrDict::remove( void *key ) + + Removes the item associated with \a key from the dictionary. + Returns TRUE if successful, i.e. if \a key is in the dictionary; + otherwise returns FALSE. + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary traversal order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3PtrDict::take( void *key ) + + Takes the item associated with \a key out of the dictionary + without deleting it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3PtrDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that access this dictionary will be + reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3PtrDict::find( void *key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to operator[]. + + \sa operator[]() +*/ + +/*! + \fn type *Q3PtrDict::operator[]( void *key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3PtrDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3PtrDict::read( QDataStream &s, Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrDict::write( QDataStream &s, Q3PtrCollection::Item item) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3PtrDictIterator + \brief The Q3PtrDictIterator class provides an iterator for Q3PtrDict collections. + \compat + + Q3PtrDictIterator is implemented as a template class. Define a + template instance Q3PtrDictIterator\ to create a dictionary + iterator that operates on Q3PtrDict\ (dictionary of X*). + + Example: + \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 2 + In the example we insert some line edits into a dictionary, + associating a string with each. We then iterate over the + dictionary printing the associated strings. + + Multiple iterators may independently traverse the same dictionary. + A Q3PtrDict knows about all the iterators that are operating on the + dictionary. When an item is removed from the dictionary, Q3PtrDict + updates all iterators that refer the removed item to point to the + next item in the traversing order. + + \sa Q3PtrDict +*/ + +/*! + \fn Q3PtrDictIterator::Q3PtrDictIterator( const Q3PtrDict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point on the first item in the \a dict. +*/ + +/*! + \fn Q3PtrDictIterator::~Q3PtrDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3PtrDictIterator::count() const + + Returns the number of items in the dictionary this iterator + operates on. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3PtrDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3PtrDictIterator::toFirst() + + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. If the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ + +/*! + \fn Q3PtrDictIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3PtrDictIterator::current() const + + Returns a pointer to the current iterator item's value. +*/ + +/*! + \fn void *Q3PtrDictIterator::currentKey() const + + Returns the current iterator item's key. +*/ + +/*! + \fn type *Q3PtrDictIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrDictIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrDictIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/q3ptrlist.qdoc b/doc/src/q3ptrlist.qdoc new file mode 100644 index 0000000..7eb4265 --- /dev/null +++ b/doc/src/q3ptrlist.qdoc @@ -0,0 +1,1157 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrList + \brief The Q3PtrList class is a template class that provides a list. + \compat + + Q3ValueList is an STL-compatible alternative to this class. + + Define a template instance Q3PtrList\ to create a list that + operates on pointers to X (X*). + + The list class is indexable and has a \link at() current + index\endlink and a \link current() current item\endlink. The + first item corresponds to index position 0. The current index is + -1 if the current item is 0. + + Items are inserted with prepend(), insert() or append(). Items are + removed with remove(), removeRef(), removeFirst() and + removeLast(). You can search for an item using find(), findNext(), + findRef() or findNextRef(). The list can be sorted with sort(). + You can count the number of occurrences of an item with contains() + or containsRef(). You can get a pointer to the current item with + current(), to an item at a particular index position in the list + with at() or to the first or last item with getFirst() and + getLast(). You can also iterate over the list with first(), + last(), next() and prev() (which all update current()). The list's + deletion property is set with setAutoDelete(). + + \target example + Example: + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 0 + + The output is + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 1 + + Q3PtrList has several member functions for traversing the list, but + using a Q3PtrListIterator can be more practical. Multiple list + iterators may traverse the same list, independently of each other + and of the current list item. + + In the example above we make the call setAutoDelete(true). + Enabling auto-deletion tells the list to delete items that are + removed. The default is to not delete items when they are removed + but this would cause a memory leak in the example because there + are no other references to the list items. + + When inserting an item into a list only the pointer is copied, not + the item itself, i.e. a shallow copy. It is possible to make the + list copy all of the item's data (deep copy) when an item is + inserted. insert(), inSort() and append() call the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a list and reimplement newItem() to have deep copies. + + When removing an item from a list, the virtual function + Q3PtrCollection::deleteItem() is called. Q3PtrList's default + implementation is to delete the item if auto-deletion is enabled. + + The virtual function compareItems() can be reimplemented to + compare two list items. This function is called from all list + functions that need to compare list items, for instance + remove(const type*). If you only want to deal with pointers, there + are functions that compare pointers instead, for instance + removeRef(const type*). These functions are somewhat faster than + those that call compareItems(). + + List items are stored as \c void* in an internal Q3LNode, which + also holds pointers to the next and previous list items. The + functions currentNode(), removeNode(), and takeNode() operate + directly on the Q3LNode, but they should be used with care. The + data component of the node is available through Q3LNode::getData(). + + The Q3StrList class is a list of \c char*. + It reimplements newItem(), deleteItem() and compareItems(). (But + see QStringList for a list of Unicode QStrings.) + + \sa Q3PtrListIterator +*/ + + +/*! + \fn Q3PtrList::Q3PtrList() + + Constructs an empty list. +*/ + +/*! + \fn Q3PtrList::Q3PtrList( const Q3PtrList &list ) + + Constructs a copy of \a list. + + Each item in \a list is \link append() appended\endlink to this + list. Only the pointers are copied (shallow copy). +*/ + +/*! + \fn Q3PtrList::~Q3PtrList() + + Removes all items from the list and destroys the list. + + All list iterators that access this list will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3PtrList &Q3PtrList::operator=(const Q3PtrList &list) + + Assigns \a list to this list and returns a reference to this list. + + This list is first cleared and then each item in \a list is \link + append() appended\endlink to this list. Only the pointers are + copied (shallow copy) unless newItem() has been reimplemented. +*/ + +/*! + \fn bool Q3PtrList::operator==(const Q3PtrList &list ) const + + Compares this list with \a list. Returns TRUE if the lists contain + the same data; otherwise returns FALSE. +*/ + +/*! + \fn uint Q3PtrList::count() const + + Returns the number of items in the list. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3PtrList::operator!=(const Q3PtrList &list ) const + + Compares this list with \a list. Returns TRUE if the lists contain + different data; otherwise returns FALSE. +*/ + + +/*! + \fn void Q3PtrList::sort() + + Sorts the list by the result of the virtual compareItems() + function. + + The heap sort algorithm is used for sorting. It sorts n items with + O(n*log n) comparisons. This is the asymptotic optimal solution of + the sorting problem. + + If the items in your list support operator<() and operator==(), + you might be better off with Q3SortedList because it implements the + compareItems() function for you using these two operators. + + \sa inSort() +*/ + +/*! + \fn bool Q3PtrList::isEmpty() const + + Returns TRUE if the list is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3PtrList::insert( uint index, const type *item ) + + Inserts the \a item at position \a index in the list. + + Returns TRUE if successful, i.e. if \a index is in range; + otherwise returns FALSE. The valid range is 0 to count() + (inclusively). The item is appended if \a index == count(). + + The inserted item becomes the current list item. + + \a item must not be 0. + + \sa append(), current(), replace() +*/ + +/*! + \fn bool Q3PtrList::replace( uint index, const type *item ) + + Replaces the item at position \a index with the new \a item. + + Returns TRUE if successful, i.e. \a index is in the range 0 to + count()-1. + + \sa append(), current(), insert() +*/ + +/*! + \fn void Q3PtrList::inSort( const type *item ) + + Inserts the \a item at its sorted position in the list. + + The sort order depends on the virtual compareItems() function. All + items must be inserted with inSort() to maintain the sorting + order. + + The inserted item becomes the current list item. + + \a item must not be 0. + + \warning Using inSort() is slow. An alternative, especially if you + have lots of items, is to simply append() or insert() them and + then use sort(). inSort() takes up to O(n) compares. That means + inserting n items in your list will need O(n^2) compares whereas + sort() only needs O(n*log n) for the same task. So use inSort() + only if you already have a presorted list and want to insert just + a few additional items. + + \sa insert(), compareItems(), current(), sort() +*/ + +/*! + \fn void Q3PtrList::append( const type *item ) + + Inserts the \a item at the end of the list. + + The inserted item becomes the current list item. This is + equivalent to \c{insert( count(), item )}. + + \a item must not be 0. + + \sa insert(), current(), prepend() +*/ + +/*! + \fn void Q3PtrList::prepend( const type *item ) + + Inserts the \a item at the start of the list. + + The inserted item becomes the current list item. This is + equivalent to \c{insert( 0, item )}. + + \a item must not be 0. + + \sa append(), insert(), current() +*/ + +/*! + \fn bool Q3PtrList::remove( uint index ) + + Removes the item at position \a index in the list. + + Returns TRUE if successful, i.e. if \a index is in range; + otherwise returns FALSE. The valid range is \c{0..(count() - 1)} + inclusive. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa take(), clear(), setAutoDelete(), current() removeRef() +*/ + +/*! + \fn bool Q3PtrList::remove() + + \overload + + Removes the current list item. + + Returns TRUE if successful, i.e. if the current item isn't 0; + otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa take(), clear(), setAutoDelete(), current() removeRef() +*/ + +/*! + \fn bool Q3PtrList::remove( const type *item ) + + \overload + + Removes the first occurrence of \a item from the list. + + Returns TRUE if successful, i.e. if \a item is in the list; + otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call removeRef(). + + If \a item is NULL then the current item is removed from the list. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa removeRef(), take(), clear(), setAutoDelete(), compareItems(), + current() +*/ + +/*! + \fn bool Q3PtrList::removeRef( const type *item ) + + Removes the first occurrence of \a item from the list. + + Returns TRUE if successful, i.e. if \a item is in the list; + otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 2 + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa remove(), clear(), setAutoDelete(), current() +*/ + +/*! + \fn void Q3PtrList::removeNode( Q3LNode *node ) + + Removes the \a node from the list. + + This node must exist in the list, otherwise the program may crash. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The first item in the list will become the new current list item. + The current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the item succeeding this item or to the preceding item if + the removed item was the last item. + + \warning Do not call this function unless you are an expert. + + \sa takeNode(), currentNode() remove() removeRef() +*/ + +/*! + \fn bool Q3PtrList::removeFirst() + + Removes the first item from the list. Returns TRUE if successful, + i.e. if the list isn't empty; otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The first item in the list becomes the new current list item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa removeLast(), setAutoDelete(), current() remove() +*/ + +/*! + \fn bool Q3PtrList::removeLast() + + Removes the last item from the list. Returns TRUE if successful, + i.e. if the list isn't empty; otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The last item in the list becomes the new current list item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa removeFirst(), setAutoDelete(), current() +*/ + +/*! + \fn type *Q3PtrList::take( uint index ) + + Takes the item at position \a index out of the list without + deleting it (even if \link setAutoDelete() auto-deletion\endlink + is enabled). + + Returns a pointer to the item taken out of the list, or 0 if the + index is out of range. The valid range is \c{0..(count() - 1)} + inclusive. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the taken item will be set to + point to the new current item. + + \sa remove(), clear(), current() +*/ + +/*! + \fn type *Q3PtrList::take() + + \overload + + Takes the current item out of the list without deleting it (even + if \link setAutoDelete() auto-deletion\endlink is enabled). + + Returns a pointer to the item taken out of the list, or 0 if + the current item is 0. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the taken item will be set to + point to the new current item. + + \sa remove(), clear(), current() +*/ + +/*! + \fn type *Q3PtrList::takeNode( Q3LNode *node ) + + Takes the \a node out of the list without deleting its item (even + if \link setAutoDelete() auto-deletion\endlink is enabled). + Returns a pointer to the item taken out of the list. + + This node must exist in the list, otherwise the program may crash. + + The first item in the list becomes the new current list item. + + All list iterators that refer to the taken item will be set to + point to the item succeeding this item or to the preceding item if + the taken item was the last item. + + \warning Do not call this function unless you are an expert. + + \sa removeNode(), currentNode() +*/ + +/*! + \fn void Q3PtrList::clear() + + Removes all items from the list. + + The removed items are deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + All list iterators that access this list will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn int Q3PtrList::find( const type *item ) + + Finds the first occurrence of \a item in the list. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call findRef(). + + \sa findNext(), findRef(), compareItems(), current() +*/ + +/*! + \fn int Q3PtrList::findNext( const type *item ) + + Finds the next occurrence of \a item in the list, starting from + the current list item. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call findNextRef(). + + \sa find(), findNextRef(), compareItems(), current() +*/ + +/*! + \fn int Q3PtrList::findRef( const type *item ) + + Finds the first occurrence of \a item in the list. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + Calling this function is much faster than find() because find() + compares \a item with each list item using compareItems(), whereas + this function only compares the pointers. + + \sa findNextRef(), find(), current() +*/ + +/*! + \fn int Q3PtrList::findNextRef( const type *item ) + + Finds the next occurrence of \a item in the list, starting from + the current list item. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + Calling this function is much faster than findNext() because + findNext() compares \a item with each list item using + compareItems(), whereas this function only compares the pointers. + + \sa findRef(), findNext(), current() +*/ + +/*! + \fn uint Q3PtrList::contains( const type *item ) const + + Returns the number of occurrences of \a item in the list. + + The compareItems() function is called when looking for the \a item + in the list. If compareItems() is not reimplemented, it is more + efficient to call containsRef(). + + This function does not affect the current list item. + + \sa containsRef(), compareItems() +*/ + +/*! + \fn uint Q3PtrList::containsRef( const type *item ) const + + Returns the number of occurrences of \a item in the list. + + Calling this function is much faster than contains() because + contains() compares \a item with each list item using + compareItems(), whereas his function only compares the pointers. + + This function does not affect the current list item. + + \sa contains() +*/ + +/*! + \fn type *Q3PtrList::at( uint index ) + + Returns a pointer to the item at position \a index in the list, or + 0 if the index is out of range. + + Sets the current list item to this item if \a index is valid. The + valid range is \c{0..(count() - 1)} inclusive. + + This function is very efficient. It starts scanning from the first + item, last item, or current item, whichever is closest to \a + index. + + \sa current() +*/ + +/*! + \fn int Q3PtrList::at() const + + \overload + + Returns the index of the current list item. The returned value is + -1 if the current item is 0. + + \sa current() +*/ + +/*! + \fn type *Q3PtrList::current() const + + Returns a pointer to the current list item. The current item may + be 0 (implies that the current index is -1). + + \sa at() +*/ + +/*! + \fn Q3LNode *Q3PtrList::currentNode() const + + Returns a pointer to the current list node. + + The node can be kept and removed later using removeNode(). The + advantage is that the item can be removed directly without + searching the list. + + \warning Do not call this function unless you are an expert. + + \sa removeNode(), takeNode(), current() +*/ + +/*! + \fn type *Q3PtrList::getFirst() const + + Returns a pointer to the first item in the list, or 0 if the list + is empty. + + This function does not affect the current list item. + + \sa first(), getLast() +*/ + +/*! + \fn type *Q3PtrList::getLast() const + + Returns a pointer to the last item in the list, or 0 if the list + is empty. + + This function does not affect the current list item. + + \sa last(), getFirst() +*/ + +/*! + \fn type *Q3PtrList::first() + + Returns a pointer to the first item in the list and makes this the + current list item; returns 0 if the list is empty. + + \sa getFirst(), last(), next(), prev(), current() +*/ + +/*! + \fn type *Q3PtrList::last() + + Returns a pointer to the last item in the list and makes this the + current list item; returns 0 if the list is empty. + + \sa getLast(), first(), next(), prev(), current() +*/ + +/*! + \fn type *Q3PtrList::next() + + Returns a pointer to the item succeeding the current item. Returns + 0 if the current item is 0 or equal to the last item. + + Makes the succeeding item current. If the current item before this + function call was the last item, the current item will be set to + 0. If the current item was 0, this function does nothing. + + \sa first(), last(), prev(), current() +*/ + +/*! + \fn type *Q3PtrList::prev() + + Returns a pointer to the item preceding the current item. Returns + 0 if the current item is 0 or equal to the first item. + + Makes the preceding item current. If the current item before this + function call was the first item, the current item will be set to + 0. If the current item was 0, this function does nothing. + + \sa first(), last(), next(), current() +*/ + +/*! + \fn void Q3PtrList::toVector( Q3GVector *vec ) const + + Stores all list items in the vector \a vec. + + The vector must be of the same item type, otherwise the result + will be undefined. +*/ + +/*! + \typedef Q3PtrList::iterator + + \internal +*/ + +/*! + \typedef Q3PtrList::Iterator + + \internal +*/ + +/*! + \typedef Q3PtrList::ConstIterator + + \internal +*/ + +/*! + \typedef Q3PtrList::const_iterator + + \internal +*/ + +/*! + \fn Q3PtrList::constBegin() const + + \internal +*/ + +/*! + \fn Q3PtrList::constEnd() const + + \internal +*/ + +/*! + \fn Q3PtrList::erase(Iterator) + + \internal +*/ + + +/***************************************************************************** + Q3PtrListIterator documentation + *****************************************************************************/ + +/*! + \class Q3PtrListIterator + \brief The Q3PtrListIterator class provides an iterator for + Q3PtrList collections. + \compat + + Define a template instance Q3PtrListIterator\ to create a list + iterator that operates on Q3PtrList\ (list of X*). + + The following example is similar to the + example in the Q3PtrList class documentation, + but it uses Q3PtrListIterator. The class Employee is + defined there. + + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 3 + + The output is + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 4 + + Using a list iterator is a more robust way of traversing the list + than using the Q3PtrList member functions \link Q3PtrList::first() + first\endlink(), \link Q3PtrList::next() next\endlink(), \link + Q3PtrList::current() current\endlink(), etc., as many iterators can + traverse the same list independently. + + An iterator has its own current list item and can get the next and + previous list items. It doesn't modify the list in any way. + + When an item is removed from the list, all iterators that point to + that item are updated to point to Q3PtrList::current() instead to + avoid dangling references. + + \sa Q3PtrList +*/ + +/*! + \fn Q3PtrListIterator::Q3PtrListIterator( const Q3PtrList &list ) + + Constructs an iterator for \a list. The current iterator item is + set to point on the first item in the \a list. +*/ + +/*! + \fn Q3PtrListIterator::~Q3PtrListIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3PtrListIterator::count() const + + Returns the number of items in the list this iterator operates on. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3PtrListIterator::isEmpty() const + + Returns TRUE if the list is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3PtrListIterator::atFirst() const + + Returns TRUE if the current iterator item is the first list item; + otherwise returns FALSE. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3PtrListIterator::atLast() const + + Returns TRUE if the current iterator item is the last list item; + otherwise returns FALSE. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3PtrListIterator::toFirst() + + Sets the current iterator item to point to the first list item and + returns a pointer to the item. Sets the current item to 0 and + returns 0 if the list is empty. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3PtrListIterator::toLast() + + Sets the current iterator item to point to the last list item and + returns a pointer to the item. Sets the current item to 0 and + returns 0 if the list is empty. + + \sa toFirst(), atLast() +*/ + +/*! + \fn Q3PtrListIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3PtrListIterator::operator*() + + Asterisk operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3PtrListIterator::current() const + + Returns a pointer to the current iterator item. If the iterator is + positioned before the first item in the list or after the last + item in the list, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the list or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the list or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item and returns a pointer to that item. + + If that item is beyond the last item or if the list is empty, it + sets the current item to 0 and returns 0 +*/ + +/*! + \fn type *Q3PtrListIterator::operator--() + + Prefix - makes the preceding item current and returns the new + current item. + + If the current iterator item was the first item in the list or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item or 0 + if it is beyond the first item. Makes this the current item. +*/ + +/*! + \fn Q3PtrListIterator& Q3PtrListIterator::operator=( const Q3PtrListIterator &it ) + + Assignment. Makes a copy of the iterator \a it and returns a + reference to this iterator. +*/ + +/*! + \class Q3StrList + \brief The Q3StrList class provides a doubly-linked list of char*. + \compat + + If you want a string list of \l{QString}s use QStringList. + + This class is a Q3PtrList\ instance (a list of char*). + + Q3StrList can make deep or shallow copies of the strings that are + inserted. + + A deep copy means that memory is allocated for the string and then + the string data is copied into that memory. A shallow copy is just + a copy of the pointer value and not of the string data itself. + + The disadvantage of shallow copies is that because a pointer can + be deleted only once, the program must put all strings in a + central place and know when it is safe to delete them (i.e. when + the strings are no longer referenced by other parts of the + program). This can make the program more complex. The advantage of + shallow copies is that they consume far less memory than deep + copies. It is also much faster to copy a pointer (typically 4 or 8 + bytes) than to copy string data. + + A Q3StrList that operates on deep copies will, by default, turn on + auto-deletion (see setAutoDelete()). Thus, by default Q3StrList + will deallocate any string copies it allocates. + + The virtual compareItems() function is reimplemented and does a + case-sensitive string comparison. The inSort() function will + insert strings in sorted order. In general it is fastest to insert + the strings as they come and sort() at the end; inSort() is useful + when you just have to add a few extra strings to an already sorted + list. + + The Q3StrListIterator class is an iterator for Q3StrList. +*/ + +/*! + \fn Q3StrList::operator QList() const + + Automatically converts a Q3StrList into a QList. +*/ + +/*! + \fn Q3StrList::Q3StrList( bool deepCopies ) + + Constructs an empty list of strings. Will make deep copies of all + inserted strings if \a deepCopies is TRUE, or use shallow copies + if \a deepCopies is FALSE. +*/ + +/*! + \fn Q3StrList::Q3StrList(const Q3StrList &list) + \fn Q3StrList::Q3StrList(const QList &list) + + Constructs a copy of \a list. +*/ + +/*! + \fn Q3StrList::~Q3StrList() + + Destroys the list. All strings are removed. +*/ + +/*! + \fn Q3StrList& Q3StrList::operator=(const Q3StrList& list) + \fn Q3StrList &Q3StrList::operator=(const QList &list) + + Assigns \a list to this list and returns a reference to this list. +*/ + +/*! + \class Q3StrIList + \brief The Q3StrIList class provides a doubly-linked list of char* + with case-insensitive comparison. + \compat + + This class is a Q3PtrList\ instance (a list of char*). + + Q3StrIList is identical to Q3StrList except that the virtual + compareItems() function is reimplemented to compare strings + case-insensitively. The inSort() function inserts strings in a + sorted order. In general it is fastest to insert the strings as + they come and sort() at the end; inSort() is useful when you just + have to add a few extra strings to an already sorted list. + + The Q3StrListIterator class works for Q3StrIList. + + \sa QStringList +*/ + +/*! + \fn Q3StrIList::Q3StrIList( bool deepCopies ) + + Constructs a list of strings. Will make deep copies of all + inserted strings if \a deepCopies is TRUE, or use shallow copies + if \a deepCopies is FALSE. +*/ + +/*! + \fn Q3StrIList::~Q3StrIList() + + Destroys the list. All strings are removed. +*/ + +/*! + \fn int Q3PtrList::compareItems( Q3PtrCollection::Item item1, + Q3PtrCollection::Item item2 ) + + This virtual function compares two list items. + + Returns: + \list + \i zero if \a item1 == \a item2 + \i nonzero if \a item1 != \a item2 + \endlist + + This function returns \e int rather than \e bool so that + reimplementations can return three values and use it to sort by: + + \list + \i 0 if \a item1 == \a item2 + \i \> 0 (positive integer) if \a item1 \> \a item2 + \i \< 0 (negative integer) if \a item1 \< \a item2 + \endlist + + inSort() requires that compareItems() is implemented as described + here. + + This function should not modify the list because some const + functions call compareItems(). + + The default implementation compares the pointers. +*/ + +/*! + \fn QDataStream& Q3PtrList::read( QDataStream& s, + Q3PtrCollection::Item& item ) + + Reads a list item from the stream \a s and returns a reference to + the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrList::write( QDataStream& s, + Q3PtrCollection::Item item ) const + + Writes a list item, \a item to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ + +/*! \fn iterator Q3PtrList::begin() +\internal +*/ +/*! \fn const_iterator Q3PtrList::begin() const +\internal +*/ +/*! \fn iterator Q3PtrList::end() +\internal +*/ +/*! \fn const_iterator Q3PtrList::end() const +\internal +*/ + +/*! + \class Q3StrListIterator + \brief The Q3StrListIterator class is an iterator for the Q3StrList + and Q3StrIList classes. + \compat + + This class is a Q3PtrListIterator\ instance. It can traverse + the strings in the Q3StrList and Q3StrIList classes. +*/ + + +/* + \class Q3PtrListAutoDelete + \brief The Q3PtrListAutoDelete class is a template class that provides a list that auto-deletes its data. + \compat + + A Q3PtrListAutoDelete is identical to a Q3PtrList with + setAutoDelete(TRUE). +*/ diff --git a/doc/src/q3ptrqueue.qdoc b/doc/src/q3ptrqueue.qdoc new file mode 100644 index 0000000..8a3ef22 --- /dev/null +++ b/doc/src/q3ptrqueue.qdoc @@ -0,0 +1,230 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrQueue + \brief The Q3PtrQueue class is a template class that provides a queue. + \compat + + Q3ValueVector can be used as an STL-compatible alternative to this + class. + + A template instance Q3PtrQueue\ is a queue that operates on + pointers to X (X*). + + A queue is a first in, first out structure. Items are added to the + tail of the queue with enqueue() and retrieved from the head with + dequeue(). You can peek at the head item without dequeing it using + head(). + + You can control the queue's deletion policy with setAutoDelete(). + + For compatibility with the Q3PtrCollection classes, current() and + remove() are provided; both operate on the head(). + + \sa Q3PtrList Q3PtrStack +*/ + +/*! + \fn Q3PtrQueue::Q3PtrQueue () + + Creates an empty queue with autoDelete() set to FALSE. +*/ + +/*! + \fn Q3PtrQueue::Q3PtrQueue( const Q3PtrQueue& queue ) + + Creates a queue from \a queue. + + Only the pointers are copied; the items are not. The autoDelete() + flag is set to FALSE. +*/ + +/*! + \fn Q3PtrQueue::~Q3PtrQueue() + + Destroys the queue. Items in the queue are deleted if autoDelete() + is TRUE. +*/ + +/*! + \fn Q3PtrQueue& Q3PtrQueue::operator= (const Q3PtrQueue& queue) + + Assigns \a queue to this queue and returns a reference to this + queue. + + This queue is first cleared and then each item in \a queue is + enqueued to this queue. Only the pointers are copied. + + \warning The autoDelete() flag is not modified. If it is TRUE for + both \a queue and this queue, deleting the two lists will cause \e + double-deletion of the items. +*/ + +/*! + \fn bool Q3PtrQueue::isEmpty() const + + Returns TRUE if the queue is empty; otherwise returns FALSE. + + \sa count() dequeue() head() +*/ + +/*! + \fn void Q3PtrQueue::enqueue (const type* d) + + Adds item \a d to the tail of the queue. + + \sa count() dequeue() +*/ + +/*! + \fn type* Q3PtrQueue::dequeue () + + Takes the head item from the queue and returns a pointer to it. + Returns 0 if the queue is empty. + + \sa enqueue() count() +*/ + +/*! + \fn bool Q3PtrQueue::remove() + + Removes the head item from the queue, and returns TRUE if there + was an item, i.e. the queue wasn't empty; otherwise returns FALSE. + + The item is deleted if autoDelete() is TRUE. + + \sa head() isEmpty() dequeue() +*/ + +/*! + \fn void Q3PtrQueue::clear() + + Removes all items from the queue, and deletes them if autoDelete() + is TRUE. + + \sa remove() +*/ + +/*! + \fn uint Q3PtrQueue::count() const + + Returns the number of items in the queue. + + \sa isEmpty() +*/ + +/*! + \fn type* Q3PtrQueue::head() const + + Returns a pointer to the head item in the queue. The queue is not + changed. Returns 0 if the queue is empty. + + \sa dequeue() isEmpty() +*/ + +/*! + \fn Q3PtrQueue::operator type*() const + + Returns a pointer to the head item in the queue. The queue is not + changed. Returns 0 if the queue is empty. + + \sa dequeue() isEmpty() +*/ + +/*! + \fn type* Q3PtrQueue::current() const + + Returns a pointer to the head item in the queue. The queue is not + changed. Returns 0 if the queue is empty. + + \sa dequeue() isEmpty() +*/ + +/*! + \fn bool Q3PtrQueue::autoDelete() const + + Returns the setting of the auto-delete option. The default is + FALSE. + + \sa setAutoDelete() +*/ + +/*! + \fn void Q3PtrQueue::setAutoDelete( bool enable ) + + Sets the queue to auto-delete its contents if \a enable is TRUE + and not to delete them if \a enable is FALSE. + + If auto-deleting is turned on, all the items in a queue are + deleted when the queue itself is deleted. This can be quite + convenient if the queue has the only pointer to the items. + + The default setting is FALSE, for safety. If you turn it on, be + careful about copying the queue: you might find yourself with two + queues deleting the same items. + + \sa autoDelete() +*/ + +/*! + \fn QDataStream& Q3PtrQueue::read( QDataStream& s, + Q3PtrCollection::Item& item ) + + Reads a queue item, \a item, from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrQueue::write( QDataStream& s, + Q3PtrCollection::Item item ) const + + Writes a queue item, \a item, to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ diff --git a/doc/src/q3ptrstack.qdoc b/doc/src/q3ptrstack.qdoc new file mode 100644 index 0000000..fcece9f --- /dev/null +++ b/doc/src/q3ptrstack.qdoc @@ -0,0 +1,217 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrStack + \brief The Q3PtrStack class is a template class that provides a stack. + \compat + + Q3ValueStack is an STL-compatible alternative to this class. + + Define a template instance Q3PtrStack\ to create a stack that + operates on pointers to X, (X*). + + A stack is a last in, first out (LIFO) structure. Items are added + to the top of the stack with push() and retrieved from the top + with pop(). Use top() to get a reference to the top element + without changing the stack. + + You can control the stack's deletion policy with setAutoDelete(). + + For compatibility with the Q3PtrCollection classes current() and + remove() are provided; they both operate on the top(). + + \sa Q3PtrList Q3PtrQueue +*/ + +/*! + \fn Q3PtrStack::Q3PtrStack () + + Creates an empty stack. +*/ + +/*! + \fn Q3PtrStack::Q3PtrStack (const Q3PtrStack& s) + + Creates a stack by making a shallow copy of another stack \a s. +*/ + +/*! + \fn Q3PtrStack::~Q3PtrStack () + + Destroys the stack. All items will be deleted if autoDelete() is + true. +*/ + +/*! + \fn Q3PtrStack& Q3PtrStack::operator= (const Q3PtrStack& s) + + Sets the contents of this stack by making a shallow copy of + another stack \a s. Elements currently in this stack will be + deleted if autoDelete() is true. +*/ + +/*! + \fn bool Q3PtrStack::isEmpty () const + + Returns true if the stack contains no elements; otherwise returns + false. +*/ + +/*! + \fn void Q3PtrStack::push (const type* d) + + Adds an element \a d to the top of the stack. Last in, first out. +*/ + +/*! + \fn type* Q3PtrStack::pop () + + Removes the top item from the stack and returns it. The stack must + not be empty. +*/ + +/*! + \fn bool Q3PtrStack::remove () + + Removes the top item from the stack and deletes it if autoDelete() + is true. Returns true if there was an item to pop; otherwise + returns false. + + \sa clear() +*/ + +/*! + \fn void Q3PtrStack::clear() + + Removes all items from the stack, deleting them if autoDelete() is + true. + + \sa remove() +*/ + +/*! + \fn uint Q3PtrStack::count() const + + Returns the number of items in the stack. + + \sa isEmpty() +*/ + +/*! + \fn type* Q3PtrStack::top () const + + Returns a pointer to the top item on the stack (most recently + pushed). The stack is not changed. Returns 0 if the stack is + empty. +*/ + +/*! + \fn Q3PtrStack::operator type* ()const + + Returns a pointer to the top item on the stack (most recently + pushed). The stack is not changed. Returns 0 if the stack is + empty. +*/ + +/*! + \fn type* Q3PtrStack::current () const + + Returns a pointer to the top item on the stack (most recently + pushed). The stack is not changed. Returns 0 if the stack is + empty. +*/ + +/*! + \fn bool Q3PtrStack::autoDelete() const + + The same as Q3PtrCollection::autoDelete(). Returns true if + the auto-delete option is set. If the option is set, the + stack auto-deletes its contents. + + \sa setAutoDelete() +*/ + +/*! + \fn void Q3PtrStack::setAutoDelete(bool enable) + + Defines whether this stack auto-deletes its contents. The same as + Q3PtrCollection::setAutoDelete(). If \a enable is true, auto-delete + is turned on. + + If auto-deleting is turned on, all the items in the stack are + deleted when the stack itself is deleted. This is convenient if + the stack has the only pointers to the items. + + The default setting is false, for safety. If you turn it on, be + careful about copying the stack, or you might find yourself with + two stacks deleting the same items. + + Note that the auto-delete setting may also affect other functions in + subclasses. For example, a subclass that has a remove() function + will remove the item from its data structure, and if auto-delete is + enabled, will also delete the item. + + \sa autoDelete() +*/ + +/*! + \fn QDataStream& Q3PtrStack::read(QDataStream& s, Q3PtrCollection::Item& item) + + Reads a stack item, \a item, from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrStack::write(QDataStream& s, + Q3PtrCollection::Item item) const + + Writes a stack item, \a item, to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ diff --git a/doc/src/q3ptrvector.qdoc b/doc/src/q3ptrvector.qdoc new file mode 100644 index 0000000..b539219 --- /dev/null +++ b/doc/src/q3ptrvector.qdoc @@ -0,0 +1,427 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrVector + \brief The Q3PtrVector class is a template collection class that + provides a vector (array). + \compat + + Q3ValueVector is an STL-compatible alternative to this class. + + Q3PtrVector is implemented as a template class. Defines a template + instance Q3PtrVector\ to create a vector that contains pointers + to X (X*). + + A vector is the same as an array. The main difference between + Q3PtrVector and Q3MemArray is that Q3PtrVector stores pointers to the + elements, whereas Q3MemArray stores the elements themselves (i.e. + Q3MemArray is value-based and Q3PtrVector is pointer-based). + + Items are added to the vector using insert() or fill(). Items are + removed with remove(). You can get a pointer to an item at a + particular index position using at(). + + Unless otherwise stated, all functions that remove items from the + vector will also delete the element pointed to if \link + setAutoDelete() auto-deletion\endlink is enabled. By default, + auto-deletion is disabled; see setAutoDelete(). This behavior can + be changed in a subclass by reimplementing the virtual function + deleteItem(). + + Functions that compare items (find() and sort() for example) will + do so using the virtual function compareItems(). The default + implementation of this function only compares the pointer values. + Reimplement compareItems() in a subclass to get searching and + sorting based on the item contents. You can perform a linear + search for a pointer in the vector using findRef(), or a binary + search (of a sorted vector) using bsearch(). You can count the + number of times an item appears in the vector with contains() or + containsRef(). + + \sa Q3MemArray +*/ + +/*! + \fn Q3PtrVector::Q3PtrVector() + + Constructs a null vector. + + \sa isNull() +*/ + +/*! + \fn Q3PtrVector::Q3PtrVector(uint size) + + Constructs an vector with room for \a size items. Makes a null + vector if \a size == 0. + + All \a size positions in the vector are initialized to 0. + + \sa size(), resize(), isNull() +*/ + +/*! + \fn Q3PtrVector::Q3PtrVector(const Q3PtrVector &v) + + Constructs a copy of \a v. Only the pointers are copied (i.e. + shallow copy). +*/ + +/*! + \fn Q3PtrVector::~Q3PtrVector() + + Removes all items from the vector, and destroys the vector itself. + + \sa clear() +*/ + +/*! + \fn Q3PtrVector &Q3PtrVector::operator=(const Q3PtrVector &v) + + Assigns \a v to this vector and returns a reference to this + vector. + + This vector is first cleared and then all the items from \a v are + copied into the vector. Only the pointers are copied (i.e. shallow + copy). + + \sa clear() +*/ + +/*! + \fn type **Q3PtrVector::data() const + + Returns a pointer to the actual vector data, which is an array of + type*. + + The vector is a null vector if data() == 0 (null pointer). + + \sa isNull() +*/ + +/*! + \fn uint Q3PtrVector::size() const + + Returns the size of the vector, i.e. the number of vector + positions. This is also the maximum number of items the vector can + hold. + + The vector is a null vector if size() == 0. + + \sa isNull(), resize(), count() +*/ + +/*! + \fn uint Q3PtrVector::count() const + + Returns the number of items in the vector. The vector is empty if + count() == 0. + + \sa isEmpty(), size(), isNull() +*/ + +/*! + \fn bool Q3PtrVector::isEmpty() const + + Returns true if the vector is empty; otherwise returns false. + + \sa count() +*/ + +/*! + \fn bool Q3PtrVector::isNull() const + + Returns true if the vector is null; otherwise returns false. + + A null vector has size() == 0 and data() == 0. + + \sa size() +*/ + +/*! + \fn bool Q3PtrVector::resize(uint size) + + Resizes (expands or shrinks) the vector to \a size elements. The + vector becomes a null vector if \a size == 0. + + Any items at position \a size or beyond in the vector are removed. + New positions are initialized to 0. + + Returns true if successful, i.e. if the memory was successfully + allocated; otherwise returns false. + + \sa size(), isNull() +*/ + +/*! + \fn bool Q3PtrVector::insert(uint i, const type *d) + + Sets position \a i in the vector to contain the item \a d. \a i + must be less than size(). Any previous element in position \a i is + removed. + + Returns true if \a i is within range; otherwise returns false. + + \sa at() +*/ + +/*! + \fn bool Q3PtrVector::remove(uint i) + + Removes the item at position \a i in the vector, if there is one. + \a i must be less than size(). + + Returns true if \a i is within range; otherwise returns false. + + \sa take(), at() +*/ + +/*! + \fn type* Q3PtrVector::take(uint i) + + Returns the item at position \a i in the vector, and removes that + item from the vector. \a i must be less than size(). If there is + no item at position \a i, 0 is returned. + + Unlike remove(), this function does \e not call deleteItem() for + the removed item. + + \sa remove(), at() +*/ + +/*! + \fn void Q3PtrVector::clear() + + Removes all items from the vector, and destroys the vector itself. + + The vector becomes a null vector. + + \sa isNull() +*/ + +/*! + \fn bool Q3PtrVector::fill(const type *d, int size) + + Inserts item \a d in all positions in the vector. Any existing + items are removed. If \a d is 0, the vector becomes empty. + + If \a size >= 0, the vector is first resized to \a size. By + default, \a size is -1. + + Returns true if successful, i.e. \a size is the same as the + current size, or \a size is larger and the memory has successfully + been allocated; otherwise returns false. + + \sa resize(), insert(), isEmpty() +*/ + +/*! + \fn void Q3PtrVector::sort() + + Sorts the items in ascending order. Any empty positions will be + put last. + + Compares items using the virtual function compareItems(). + + \sa bsearch() +*/ + +/*! + \fn int Q3PtrVector::bsearch(const type* d) const + + In a sorted array, finds the first occurrence of \a d using a + binary search. For a sorted array, this is generally much faster + than find(), which performs a linear search. + + Returns the position of \a d, or -1 if \a d could not be found. \a + d must not be 0. + + Compares items using the virtual function compareItems(). + + \sa sort(), find() +*/ + + +/*! + \fn int Q3PtrVector::findRef(const type *d, uint i) const + + Finds the first occurrence of the item pointer \a d in the vector + using a linear search. The search starts at position \a i, which + must be less than size(). \a i is by default 0; i.e. the search + starts at the start of the vector. + + Returns the position of \a d, or -1 if \a d could not be found. + + This function does \e not use compareItems() to compare items. + + Use the much faster bsearch() to search a sorted vector. + + \sa find(), bsearch() +*/ + +/*! + \fn int Q3PtrVector::find(const type *d, uint i) const + + Finds the first occurrence of item \a d in the vector using a + linear search. The search starts at position \a i, which must be + less than size(). \a i is by default 0; i.e. the search starts at + the start of the vector. + + Returns the position of \a d, or -1 if \a d could not be found. + + Compares items using the virtual function compareItems(). + + Use the much faster bsearch() to search a sorted vector. + + \sa findRef(), bsearch() +*/ + + +/*! + \fn uint Q3PtrVector::containsRef(const type *d) const + + Returns the number of occurrences of the item pointer \a d in the + vector. + + This function does \e not use compareItems() to compare items. + + \sa findRef() +*/ + +/*! + \fn uint Q3PtrVector::contains(const type *d) const + + Returns the number of occurrences of item \a d in the vector. + + Compares items using the virtual function compareItems(). + + \sa containsRef() +*/ + +/*! + \fn type *Q3PtrVector::operator[](int i) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). + + Equivalent to at(\a i). + + \sa at() +*/ + +/*! + \fn type *Q3PtrVector::at(uint i) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). +*/ + + +/*! + \fn void Q3PtrVector::toList(Q3GList *list) const + + \internal + + Copies all items in this vector to the list \a list. \a list is + first cleared and then all items are appended to \a list. + + \sa Q3PtrList, Q3PtrStack, Q3PtrQueue +*/ + +/*! + \fn int Q3PtrVector::compareItems(Q3PtrCollection::Item d1, + Q3PtrCollection::Item d2) + + This virtual function compares two list items. + + Returns: + \list + \i zero if \a d1 == \a d2 + \i nonzero if \a d1 != \a d2 + \endlist + + This function returns \e int rather than \e bool so that + reimplementations can return one of three values and use it to + sort by: + \list + \i 0 if \a d1 == \a d2 + \i \> 0 (positive integer) if \a d1 \> \a d2 + \i \< 0 (negative integer) if \a d1 \< \a d2 + \endlist + + The sort() and bsearch() functions require compareItems() to be + implemented as described here. + + This function should not modify the vector because some const + functions call compareItems(). +*/ + +/*! + \fn QDataStream& Q3PtrVector::read(QDataStream &s, + Q3PtrCollection::Item &item) + + Reads a vector item, \a item, from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrVector::write(QDataStream &s, + Q3PtrCollection::Item item) const + + Writes a vector item, \a item, to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ + +/*! + \fn bool Q3PtrVector::operator==(const Q3PtrVector &v) const + + Returns true if this vector and \a v are equal; otherwise returns + false. +*/ diff --git a/doc/src/q3sqlfieldinfo.qdoc b/doc/src/q3sqlfieldinfo.qdoc new file mode 100644 index 0000000..1b152c0 --- /dev/null +++ b/doc/src/q3sqlfieldinfo.qdoc @@ -0,0 +1,234 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3SqlFieldInfo + \brief The Q3SqlFieldInfo class stores meta data associated with a SQL field. + + \compat + + Q3SqlFieldInfo objects only store meta data; field values are + stored in QSqlField objects. + + All values must be set in the constructor, and may be retrieved + using isRequired(), type(), length(), precision(), defaultValue(), + name(), isGenerated() and typeID(). + + \sa Q3SqlRecordInfo +*/ + +/*! + \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QString& name, + QVariant::Type typ, + int required, + int len, + int prec, + const QVariant& defValue, + int typeID, + bool generated, + bool trim, + bool calculated) + + Constructs a Q3SqlFieldInfo with the following parameters: + \table + \row \i \a name \i the name of the field. + \row \i \a typ \i the field's type in a QVariant. + \row \i \a required \i greater than 0 if the field is required, 0 + if its value can be NULL and less than 0 if it cannot be + determined whether the field is required or not. + \row \i \a len \i the length of the field. Note that for + non-character types some databases return either the length in + bytes or the number of digits. -1 signifies that the length cannot + be determined. + \row \i \a prec \i the precision of the field, or -1 if the field + has no precision or it cannot be determined. + \row \i \a defValue \i the default value that is inserted into + the table if none is specified by the user. QVariant() if there is + no default value or it cannot be determined. + \row \i \a typeID \i the internal typeID of the database system + (only useful for low-level programming). 0 if unknown. + \row \i \a generated \i TRUE indicates that this field should be + included in auto-generated SQL statments, e.g. in Q3SqlCursor. + \row \i \a trim \i TRUE indicates that widgets should remove + trailing whitespace from character fields. This does not affect + the field value but only its representation inside widgets. + \row \i \a calculated \i TRUE indicates that the value of this + field is calculated. The value of calculated fields can by + modified by subclassing Q3SqlCursor and overriding + Q3SqlCursor::calculateField(). + \endtable +*/ + +/*! + \fn Q3SqlFieldInfo::~Q3SqlFieldInfo() + + Destroys the object and frees any allocated resources. +*/ + +/*! + \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QSqlField & other) + + Creates a Q3SqlFieldInfo object with the type and the name of the + QSqlField \a other. +*/ + +/*! + \fn bool Q3SqlFieldInfo::operator==(const Q3SqlFieldInfo& other) const + + Assigns \a other to this field info and returns a reference to it. +*/ + +/*! + \fn QSqlField Q3SqlFieldInfo::toField() const + + Returns an empty QSqlField based on the information in this + Q3SqlFieldInfo. +*/ + +/*! + \fn int Q3SqlFieldInfo::isRequired() const + + Returns a value greater than 0 if the field is required (NULL + values are not allowed), 0 if it isn't required (NULL values are + allowed) or less than 0 if it cannot be determined whether the + field is required or not. +*/ + +/*! + \fn QVariant::Type Q3SqlFieldInfo::type() const + + Returns the field's type or QVariant::Invalid if the type is + unknown. +*/ + +/*! + \fn int Q3SqlFieldInfo::length() const + + Returns the field's length. For fields storing text the return + value is the maximum number of characters the field can hold. For + non-character fields some database systems return the number of + bytes needed or the number of digits allowed. If the length cannot + be determined -1 is returned. +*/ + +/*! + \fn int Q3SqlFieldInfo::precision() const + + Returns the field's precision or -1 if the field has no precision + or it cannot be determined. +*/ + +/*! + \fn QVariant Q3SqlFieldInfo::defaultValue() const + + Returns the field's default value or an empty QVariant if the + field has no default value or the value couldn't be determined. + The default value is the value inserted in the database when it + is not explicitly specified by the user. +*/ + +/*! + \fn QString Q3SqlFieldInfo::name() const + + Returns the name of the field in the SQL table. +*/ + +/*! + \fn int Q3SqlFieldInfo::typeID() const + + Returns the internal type identifier as returned from the database + system. The return value is 0 if the type is unknown. +*/ + +/*! + \fn bool Q3SqlFieldInfo::isGenerated() const + + Returns TRUE if the field should be included in auto-generated + SQL statments, e.g. in Q3SqlCursor; otherwise returns FALSE. + + \sa setGenerated() +*/ + +/*! + \fn bool Q3SqlFieldInfo::isTrim() const + + Returns TRUE if trailing whitespace should be removed from + character fields; otherwise returns FALSE. + + \sa setTrim() +*/ + +/*! + \fn bool Q3SqlFieldInfo::isCalculated() const + + Returns TRUE if the field is calculated; otherwise returns FALSE. + + \sa setCalculated() +*/ + +/*! + \fn void Q3SqlFieldInfo::setTrim(bool trim) + + If \a trim is TRUE widgets should remove trailing whitespace from + character fields. This does not affect the field value but only + its representation inside widgets. + + \sa isTrim() +*/ + +/*! + \fn void Q3SqlFieldInfo::setGenerated(bool generated) + + \a generated set to FALSE indicates that this field should not appear + in auto-generated SQL statements (for example in Q3SqlCursor). + + \sa isGenerated() +*/ + +/*! + \fn void Q3SqlFieldInfo::setCalculated(bool calculated) + + \a calculated set to TRUE indicates that this field is a calculated + field. The value of calculated fields can by modified by subclassing + Q3SqlCursor and overriding Q3SqlCursor::calculateField(). + + \sa isCalculated() +*/ diff --git a/doc/src/q3sqlrecordinfo.qdoc b/doc/src/q3sqlrecordinfo.qdoc new file mode 100644 index 0000000..f8f6cd5 --- /dev/null +++ b/doc/src/q3sqlrecordinfo.qdoc @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3SqlRecordInfo + \brief The Q3SqlRecordInfo class encapsulates a set of database field meta data. + + \compat + + This class is a list that holds a set of database field meta + data. Use contains() to see if a given field name exists in the + record, and use find() to get a QSqlFieldInfo record for a named + field. + + \sa Q3SqlFieldInfo +*/ + +/*! + \fn Q3SqlRecordInfo::Q3SqlRecordInfo() + + Constructs an empty record info object. +*/ + +/*! + \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const Q3SqlFieldInfoList& other) + \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const QSqlRecord& other) + + Constructs a copy of \a other. +*/ + +/*! + \fn size_type Q3SqlRecordInfo::contains(const QString& fieldName) const + + Returns the number of times a field called \a fieldName occurs in + the record. Returns 0 if no field by that name could be found. +*/ + +/*! + \fn Q3SqlFieldInfo Q3SqlRecordInfo::find(const QString& fieldName) const + + Returns a QSqlFieldInfo object for the first field in the record + which has the field name \a fieldName. If no matching field is + found then an empty QSqlFieldInfo object is returned. +*/ + +/*! + \fn QSqlRecord Q3SqlRecordInfo::toRecord() const + + Returns an empty QSqlRecord based on the field information + in this Q3SqlRecordInfo. +*/ diff --git a/doc/src/q3valuelist.qdoc b/doc/src/q3valuelist.qdoc new file mode 100644 index 0000000..be315c2 --- /dev/null +++ b/doc/src/q3valuelist.qdoc @@ -0,0 +1,569 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3ValueList + \brief The Q3ValueList class is a value-based template class that + provides lists. + \compat + + Q3ValueList is a Qt implementation of an STL-like list container. + It can be used in your application if the standard \c list is not + available for your target platforms. + + Q3ValueList\ defines a template instance to create a list of + values that all have the class T. Note that Q3ValueList does not + store pointers to the members of the list; it holds a copy of + every member. This is why these kinds of classes are called "value + based"; Q3PtrList and Q3Dict are "pointer based". + + Q3ValueList contains and manages a collection of objects of type T + and provides iterators that allow the contained objects to be + addressed. Q3ValueList owns the contained items. For more relaxed + ownership semantics, see Q3PtrCollection and friends which are + pointer-based containers. + + Some classes cannot be used within a Q3ValueList, for example, all + classes derived from QObject and thus all classes that implement + widgets. Only values can be used in a Q3ValueList. To qualify as a + value the class must provide: + \list + \i a copy constructor; + \i an assignment operator; + \i a default constructor, i.e. a constructor that does not take any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases this is sufficient. + + In addition, some compilers (e.g. Sun CC) might require that the + class provides an equality operator (operator==()). + + Q3ValueList's function naming is consistent with the other Qt + classes (e.g. count(), isEmpty()). Q3ValueList also provides extra + functions for compatibility with STL algorithms, such as size() + and empty(). Programmers already familiar with the STL \c list may + prefer to use the STL-compatible functions. + + Example: + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 0 + + + Notice that the latest changes to Mary's salary did not affect the + value in the list because the list created a copy of Mary's entry. + + There are several ways to find items in the list. The begin() and + end() functions return iterators to the beginning and end of the + list. The advantage of getting an iterator is that you can move + forward or backward from this position by + incrementing/decrementing the iterator. The iterator returned by + end() points to the item which is one \e past the last item in the + container. The past-the-end iterator is still associated with the + list it belongs to, however it is \e not dereferenceable; + operator*() will not return a well-defined value. If the list is + empty(), the iterator returned by begin() will equal the iterator + returned by end(). + + It is safe to have multiple iterators a the list at the same + time. If some member of the list is removed, only iterators + pointing to the removed member become invalid. Inserting into the + list does not invalidate any iterator. For convenience, the + function last() returns a reference to the last item in the list, + and first() returns a reference to the the first item. If the + list is empty(), both last() and first() have undefined behavior + (your application will crash or do unpredictable things). Use + last() and first() with caution, for example: + + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 1 + + Because Q3ValueList is value-based there is no need to be careful + about deleting items in the list. The list holds its own copies + and will free them if the corresponding member or the list itself + is deleted. You can force the list to free all of its items with + clear(). + + Q3ValueList is shared implicitly, which means it can be copied in + constant time, i.e. O(1). If multiple Q3ValueList instances share + the same data and one needs to modify its contents, this modifying + instance makes a copy and modifies its private copy; therefore it + does not affect the other instances; this takes O(n) time. This is + often called "copy on write". If a Q3ValueList is being used in a + multi-threaded program, you must protect all access to the list. + See \l QMutex. + + There are several ways to insert items into the list. The + prepend() and append() functions insert items at the beginning and + the end of the list respectively. The insert() function comes in + several flavors and can be used to add one or more items at + specific positions within the list. + + Items can also be removed from the list in several ways. There + are several variants of the remove() function, which removes a + specific item from the list. The remove() function will find and + remove items according to a specific item value. + + \sa Q3ValueListIterator +*/ + +/*! \typedef Q3ValueList::iterator + The list's iterator type, Q3ValueListIterator. */ +/*! \typedef Q3ValueList::const_iterator + The list's const iterator type, Q3ValueListConstIterator. */ +/*! \typedef Q3ValueList::value_type + The type of the object stored in the list, T. */ +/*! \typedef Q3ValueList::pointer + The pointer to T type. */ +/*! \typedef Q3ValueList::const_pointer + The const pointer to T type. */ +/*! \typedef Q3ValueList::reference + The reference to T type. */ +/*! \typedef Q3ValueList::const_reference + The const reference to T type. */ +/*! \typedef Q3ValueList::size_type + An unsigned integral type, used to represent various sizes. */ +/*! \typedef Q3ValueList::difference_type + \internal +*/ +/*! + \fn Q3ValueList::Q3ValueList() + + Constructs an empty list. +*/ + +/*! + \fn Q3ValueList::Q3ValueList( const Q3ValueList& l ) + \fn Q3ValueList::Q3ValueList( const QList& l ) + \fn Q3ValueList::Q3ValueList( const QLinkedList& l ) + + Constructs a copy of \a l. +*/ + +/*! + \fn Q3ValueList::Q3ValueList( const std::list& l ) + + Contructs a copy of \a l. + + This constructor is provided for compatibility with STL + containers. +*/ + +/*! + \fn Q3ValueList::~Q3ValueList() + + Destroys the list. References to the values in the list and all + iterators of this list become invalidated. Note that it is + impossible for an iterator to check whether or not it is valid: + Q3ValueList is highly tuned for performance, not for error + checking. +*/ + +/*! + \fn bool Q3ValueList::operator== ( const Q3ValueList& l ) const + + Compares both lists. + + Returns TRUE if this list and \a l are equal; otherwise returns + FALSE. +*/ + +/*! + \fn bool Q3ValueList::operator== ( const std::list& l ) const + + \overload + + Returns TRUE if this list and \a l are equal; otherwise returns + FALSE. + + This operator is provided for compatibility with STL containers. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator= ( const Q3ValueList& l ) + + Assigns \a l to this list and returns a reference to this list. + + All iterators of the current list become invalidated by this + operation. The cost of such an assignment is O(1) since Q3ValueList + is implicitly shared. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator= ( const QList& l ) + + Assigns \a l to this list and returns a reference to this list. + + All iterators of the current list become invalidated by this + operation. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator= ( const std::list& l ) + + \overload + + Assigns the contents of \a l to the list. + + All iterators of the current list become invalidated by this + operation. +*/ + +/*! + \fn bool Q3ValueList::operator!= ( const Q3ValueList& l ) const + + Compares both lists. + + Returns TRUE if this list and \a l are unequal; otherwise returns + FALSE. +*/ + +/*! + \fn iterator Q3ValueList::insert( typename Q3ValueList::Iterator it, const T& x ) + + Inserts the value \a x in front of the item pointed to by the + iterator, \a it. + + Returns an iterator pointing at the inserted item. + + \sa append(), prepend() +*/ + +/*! + \fn uint Q3ValueList::remove( const T& x ) + + \overload + + Removes all items that have value \a x and returns the number of + removed items. +*/ + +/*! + \fn QDataStream& operator>>( QDataStream& s, Q3ValueList& l ) + + \relates Q3ValueList + + Reads a list, \a l, from the stream \a s. The type T stored in the + list must implement the streaming operator. +*/ + +/*! + \fn QDataStream& operator<<( QDataStream& s, const Q3ValueList& l ) + + \overload + \relates Q3ValueList + + Writes a list, \a l, to the stream \a s. The type T stored in the + list must implement the streaming operator. +*/ + +/*! + \fn void Q3ValueList::insert( typename Q3ValueList::Iterator pos, + typename Q3ValueList::size_type n, const T& x ) + + \overload + + Inserts \a n copies of \a x before position \a pos. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator<< ( const T& x ) + + Adds the value \a x to the end of the list. + + Returns a reference to the list. +*/ + +/*! + \fn const T& Q3ValueList::operator[] ( typename Q3ValueList::size_type i ) const + + Returns a const reference to the item with index \a i in the list. + It is up to you to check whether this item really exists. You can + do that easily with the count() function. However this operator + does not check whether \a i is in range and will deliver undefined + results if it does not exist. + + \warning This function uses a linear search and can be extremely + slow for large lists. Q3ValueList is not optimized for random item + access. If you need random access use a different container, such + as Q3ValueVector. +*/ + +/*! + \fn T& Q3ValueList::operator[] ( typename Q3ValueList::size_type i ) + + \overload + + Returns a non-const reference to the item with index \a i. +*/ + +/*! + \fn const_iterator Q3ValueList::at( typename Q3ValueList::size_type i ) const + + Returns an iterator pointing to the item at position \a i in the + list, or an undefined value if the index is out of range. + + \warning This function uses a linear search and can be extremely + slow for large lists. Q3ValueList is not optimized for random item + access. If you need random access use a different container, such + as Q3ValueVector. +*/ + +/*! + \fn iterator Q3ValueList::at( typename Q3ValueList::size_type i ) + + \overload + + Returns an iterator pointing to the item at position \a i in the + list, or an undefined value if the index is out of range. + +*/ + +/*! + \fn iterator Q3ValueList::fromLast() + + \overload + + Returns an iterator to the last item in the list, or end() if + there is no last item. + + Use the end() function instead. For example: + + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 2 + +*/ + +/*! + \fn const_iterator Q3ValueList::fromLast() const + + Returns an iterator to the last item in the list, or end() if + there is no last item. + + Use the end() function instead. For example: + + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 3 + +*/ + +/*! + \fn Q3ValueList Q3ValueList::operator+( const Q3ValueList& l ) const + + Creates a new list and fills it with the items of this list. Then + the items of \a l are appended. Returns the new list. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator+= ( const Q3ValueList& l ) + + Appends the items of \a l to this list. Returns a reference to + this list. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator+= ( const T& x ) + + \overload + + Appends the value \a x to the list. Returns a reference to the + list. +*/ + +/*! + \fn iterator Q3ValueList::append( const T& x ) + + Inserts \a x at the end of the list. + + \sa insert(), prepend() +*/ + +/*! + \fn iterator Q3ValueList::prepend( const T& x ) + + Inserts \a x at the beginning of the list. + + \sa insert(), append() +*/ + +/*! + \fn iterator Q3ValueList::remove( typename Q3ValueList::Iterator it ) + + Removes the item pointed to by \a it from the list. No iterators + other than \a it or other iterators pointing at the same item as + \a it are invalidated. Returns an iterator to the next item after + \a it, or end() if there is no such item. + + \sa clear() +*/ + +/*! + \fn uint Q3ValueList::contains( const T& x ) const + + Returns the number of occurrences of the value \a x in the list. +*/ + +/*! + \class Q3ValueListIterator + \brief The Q3ValueListIterator class provides an iterator for Q3ValueList. + \compat + + An iterator is a class for accessing the items of a container + class: a generalization of the index in an array. A pointer + into a "const char *" and an index into an "int[]" are both + iterators, and the general idea is to provide that functionality + for any data structure. + + The Q3ValueListIterator class is an iterator for Q3ValueList + instantiations. You can create the appropriate iterator type by + using the \c iterator typedef provided by Q3ValueList. + + The only way to access the items in a Q3ValueList is to use an + iterator. + + Example (see Q3ValueList for the complete code): + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 4 + + Q3ValueList is highly optimized for performance and memory usage. + This means that you must be careful: Q3ValueList does not know + about all its iterators and the iterators don't know to which list + they belong. This makes things very fast, but if you're not + careful, you can get spectacular bugs. Always make sure iterators + are valid before dereferencing them or using them as parameters to + generic algorithms in the STL. + + Using an invalid iterator is undefined (your application will + probably crash). Many Qt functions return const value lists; to + iterate over these you should make a copy and iterate over the + copy. + + For every Iterator there is a ConstIterator. When accessing a + Q3ValueList in a const environment or if the reference or pointer + to the list is itself const, then you must use the ConstIterator. + Its semantics are the same as the Iterator, but it only returns + const references. + + \sa Q3ValueList, Q3ValueListConstIterator +*/ + +/*! + \fn Q3ValueListIterator::Q3ValueListIterator() + + Constructs an unitialized iterator. +*/ + +/*! + \fn Q3ValueListIterator::Q3ValueListIterator(const Q3ValueListIterator &o) + \fn Q3ValueListIterator::Q3ValueListIterator(const typename QLinkedList::iterator &o) + + Constucts a copy of iterator \a o. +*/ + +/*! + \class Q3ValueListConstIterator + \brief The Q3ValueListConstIterator class provides a const iterator + for Q3ValueList. + \compat + + In contrast to Q3ValueListIterator, this class is used to iterate + over a const list. It does not allow modification of the values of + the list since that would break const semantics. + + You can create the appropriate const iterator type by using the \c + const_iterator typedef provided by Q3ValueList. + + For more information on Q3ValueList iterators, see + Q3ValueListIterator. + + \sa Q3ValueListIterator, Q3ValueList +*/ + +/*! + \fn Q3ValueListConstIterator::Q3ValueListConstIterator() + + Constructs an unitialized iterator. +*/ + +/*! + \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const Q3ValueListConstIterator &o) + \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList::const_iterator &o) + \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList::iterator &o) + + Constructs a copy of iterator \a o. +*/ + +/*! + \typedef Q3ValueList::Iterator + + This iterator is an instantiation of Q3ValueListIterator for the + same type as this Q3ValueList. In other words, if you instantiate + Q3ValueList, Iterator is a Q3ValueListIterator. Several + member function use it, such as Q3ValueList::begin(), which returns + an iterator pointing to the first item in the list. + + Functionally, this is almost the same as ConstIterator. The only + difference is that you cannot use ConstIterator for non-const + operations, and that the compiler can often generate better code + if you use ConstIterator. + + \sa Q3ValueListIterator ConstIterator +*/ + +/*! + \typedef Q3ValueList::ConstIterator + + This iterator is an instantiation of Q3ValueListConstIterator for + the same type as this Q3ValueList. In other words, if you + instantiate Q3ValueList, ConstIterator is a + Q3ValueListConstIterator. Several member function use it, such + as Q3ValueList::begin(), which returns an iterator pointing to the + first item in the list. + + Functionally, this is almost the same as Iterator. The only + difference is you cannot use ConstIterator for non-const + operations, and that the compiler can often generate better code + if you use ConstIterator. + + \sa Q3ValueListIterator Iterator +*/ + +/*! + \fn Q3ValueList::operator QList() const + + Automatically converts a Q3ValueList into a QList. +*/ diff --git a/doc/src/q3valuestack.qdoc b/doc/src/q3valuestack.qdoc new file mode 100644 index 0000000..40847ab --- /dev/null +++ b/doc/src/q3valuestack.qdoc @@ -0,0 +1,149 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3ValueStack + \brief The Q3ValueStack class is a value-based template class that provides a stack. + \compat + + Define a template instance Q3ValueStack\ to create a stack of + values that all have the class X. + + Note that Q3ValueStack does not store pointers to the members of + the stack; it holds a copy of every member. That is why these + kinds of classes are called "value based"; Q3PtrStack, Q3PtrList, + Q3Dict, etc., are "pointer based". + + A stack is a last in, first out (LIFO) structure. Items are added + to the top of the stack with push() and retrieved from the top + with pop(). The top() function provides access to the topmost item + without removing it. + + Example: + \snippet doc/src/snippets/code/doc_src_q3valuestack.qdoc 0 + + Q3ValueStack is a specialized Q3ValueList provided for convenience. + All of Q3ValueList's functionality also applies to Q3PtrStack, for + example the facility to iterate over all elements using + Q3ValueStack::Iterator. See Q3ValueListIterator for further + details. + + Some classes cannot be used within a Q3ValueStack, for example + everything derived from QObject and thus all classes that + implement widgets. Only values can be used in a Q3ValueStack. To + qualify as a value, the class must provide + \list + \i a copy constructor; + \i an assignment operator; + \i a default constructor, i.e. a constructor that does not take any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases this is sufficient. +*/ + + +/*! + \fn Q3ValueStack::Q3ValueStack() + + Constructs an empty stack. +*/ + +/*! + \fn Q3ValueStack::~Q3ValueStack() + + Destroys the stack. References to the values in the stack and all + iterators of this stack become invalidated. Because Q3ValueStack is + highly tuned for performance, you won't see warnings if you use + invalid iterators because it is impossible for an iterator to + check whether or not it is valid. +*/ + + +/*! + \fn void Q3ValueStack::push( const T& d ) + + Adds element, \a d, to the top of the stack. Last in, first out. + + This function is equivalent to append(). + + \sa pop(), top() +*/ + +/*! + \fn T& Q3ValueStack::top() + + Returns a reference to the top item of the stack or the item + referenced by end() if no such item exists. Note that you must not + change the value the end() iterator points to. + + This function is equivalent to last(). + + \sa pop(), push(), Q3ValueList::fromLast() +*/ + + +/*! + \fn const T& Q3ValueStack::top() const + + \overload + + Returns a reference to the top item of the stack or the item + referenced by end() if no such item exists. + + This function is equivalent to last(). + + \sa pop(), push(), Q3ValueList::fromLast() +*/ + +/*! + \fn T Q3ValueStack::pop() + + Removes the top item from the stack and returns it. + + \sa top() push() +*/ + + + + + diff --git a/doc/src/q3valuevector.qdoc b/doc/src/q3valuevector.qdoc new file mode 100644 index 0000000..1af2bf3 --- /dev/null +++ b/doc/src/q3valuevector.qdoc @@ -0,0 +1,274 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3ValueVector + \brief The Q3ValueVector class is a value-based template class that provides a dynamic array. + \compat + + Q3ValueVector is a Qt implementation of an STL-like vector + container. It can be used in your application if the standard \c + vector is not available for your target platforms. + + Q3ValueVector\ defines a template instance to create a vector + of values that all have the class T. Q3ValueVector does not store + pointers to the members of the vector; it holds a copy of every + member. Q3ValueVector is said to be value based; in contrast, + Q3PtrList and Q3Dict are pointer based. + + Q3ValueVector contains and manages a collection of objects of type + T and provides random access iterators that allow the contained + objects to be addressed. Q3ValueVector owns the contained + elements. For more relaxed ownership semantics, see Q3PtrCollection + and friends, which are pointer-based containers. + + Q3ValueVector provides good performance if you append or remove + elements from the end of the vector. If you insert or remove + elements from anywhere but the end, performance is very bad. The + reason for this is that elements must to be copied into new + positions. + + Some classes cannot be used within a Q3ValueVector: for example, + all classes derived from QObject and thus all classes that + implement widgets. Only values can be used in a Q3ValueVector. To + qualify as a value the class must provide: + \list + \i a copy constructor; + \i an assignment operator; + \i a default constructor, i.e., a constructor that does not take any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases this is sufficient. + + Q3ValueVector uses an STL-like syntax to manipulate and address the + objects it contains. + + Example: + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 0 + + Program output: + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 1 + + As you can see, the most recent change to Joe's salary did not + affect the value in the vector because the vector created a copy + of Joe's entry. + + Many Qt functions return const value vectors; to iterate over + these you should make a copy and iterate over the copy. + + There are several ways to find items in the vector. The begin() + and end() functions return iterators to the beginning and end of + the vector. The advantage of getting an iterator is that you can + move forward or backward from this position by + incrementing/decrementing the iterator. The iterator returned by + end() points to the element which is one past the last element in + the container. The past-the-end iterator is still associated with + the vector it belongs to, however it is \e not dereferenceable; + operator*() will not return a well-defined value. If the vector is + empty(), the iterator returned by begin() will equal the iterator + returned by end(). + + The fastest way to access an element of a vector is by using + operator[]. This function provides random access and will return + a reference to the element located at the specified index. Thus, + you can access every element directly, in constant time, providing + you know the location of the element. It is undefined to access + an element that does not exist (your application will probably + crash). For example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 2 + + Whenever inserting, removing or referencing elements in a vector, + always make sure you are referring to valid positions. For + example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 3 + + The iterators provided by vector are random access iterators, + therefore you can use them with many generic algorithms, for + example, algorithms provided by the STL. + + It is safe to have multiple iterators on the vector at the same + time. Since Q3ValueVector manages memory dynamically, all iterators + can become invalid if a memory reallocation occurs. For example, + if some member of the vector is removed, iterators that point to + the removed element and to all following elements become + invalidated. Inserting into the middle of the vector will + invalidate all iterators. For convenience, the function back() + returns a reference to the last element in the vector, and front() + returns a reference to the first element. If the vector is + empty(), both back() and front() have undefined behavior (your + application will crash or do unpredictable things). Use back() and + front() with caution, for example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 4 + + Because Q3ValueVector manages memory dynamically, it is recommended + that you contruct a vector with an initial size. Inserting and + removing elements happens fastest when: + \list + \i Inserting or removing elements happens at the end() of the + vector; + \i The vector does not need to allocate additional memory. + \endlist + + By creating a Q3ValueVector with a sufficiently large initial size, + there will be less memory allocations. Do not use an initial size + that is too big, since it will still take time to construct all + the empty entries, and the extra space will be wasted if it is + never used. + + Because Q3ValueVector is value-based there is no need to be careful + about deleting elements in the vector. The vector holds its own + copies and will free them if the corresponding member or the + vector itself is deleted. You can force the vector to free all of + its items with clear(). + + Q3ValueVector is shared implicitly, which means it can be copied in + constant time. If multiple Q3ValueVector instances share the same + data and one needs to modify its contents, this modifying instance + makes a copy and modifies its private copy; it thus does not + affect the other instances. This is often called "copy on write". + If a Q3ValueVector is being used in a multi-threaded program, you + must protect all access to the vector. See QMutex. + + There are several ways to insert elements into the vector. The + push_back() function insert elements into the end of the vector, + and is usually fastest. The insert() function can be used to add + elements at specific positions within the vector. + + Items can be also be removed from the vector in several ways. + There are several variants of the erase() function which removes a + specific element, or range of elements, from the vector. + + Q3ValueVector stores its elements in contiguous memory. This means + that you can use a Q3ValueVector in any situation that requires an + array. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector() + + Constructs an empty vector without any elements. To create a + vector which reserves an initial amount of space for elements, use + \c Q3ValueVector(size_type n). +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( const Q3ValueVector& v ) + + Constructs a copy of \a v. + + This operation costs O(1) time because Q3ValueVector is implicitly + shared. + + The first modification to the vector does takes O(n) time, because + the elements must be copied. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( const std::vector& v ) + + This operation costs O(n) time because \a v is copied. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( QVector::size_type n, const T& val ) + + Constructs a vector with an initial size of \a n elements. Each + element is initialized with the value of \a val. +*/ + +/*! + \fn Q3ValueVector& Q3ValueVector::operator=( const Q3ValueVector& v ) + + Assigns \a v to this vector and returns a reference to this vector. + + All iterators of the current vector become invalidated by this + operation. The cost of such an assignment is O(1) since + Q3ValueVector is implicitly shared. +*/ + +/*! + \fn Q3ValueVector& Q3ValueVector::operator=( const std::vector& v ) + + \overload + + Assigns \a v to this vector and returns a reference to this vector. + + All iterators of the current vector become invalidated by this + operation. The cost of this assignment is O(n) since \a v is + copied. +*/ + +/*! + \fn T &Q3ValueVector::at( int i , bool* ok ) + + Returns a reference to the element with index \a i. If \a ok is + non-null, and the index \a i is out of range, *\a ok is set to + FALSE and the returned reference is undefined. If the index \a i + is within the range of the vector, and \a ok is non-null, *\a ok + is set to TRUE and the returned reference is well defined. +*/ + +/*! + \fn const T &Q3ValueVector::at( int i , bool* ok ) const + + \overload + + Returns a const reference to the element with index \a i. If \a ok + is non-null, and the index \a i is out of range, *\a ok is set to + FALSE and the returned reference is undefined. If the index \a i + is within the range of the vector, and \a ok is non-null, *\a ok + is set to TRUE and the returned reference is well defined. +*/ + +/*! + \fn void Q3ValueVector::resize( int n, const T& val = T() ) + + Changes the size of the vector to \a n. If \a n is greater than + the current size(), elements are added to the end and initialized + with the value of \a val. If \a n is less than size(), elements + are removed from the end. If \a n is equal to size() nothing + happens. +*/ diff --git a/doc/src/qalgorithms.qdoc b/doc/src/qalgorithms.qdoc new file mode 100644 index 0000000..459fb81 --- /dev/null +++ b/doc/src/qalgorithms.qdoc @@ -0,0 +1,648 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \headerfile + \title Generic Algorithms + \ingroup architecture + + \brief The header provides generic template-based algorithms. + + Qt provides a number of global template functions in \c + that work on containers and perform well-know + algorithms. You can use these algorithms with any \l {container + class} that provides STL-style iterators, including Qt's QList, + QLinkedList, QVector, QMap, and QHash classes. + + These functions have taken their inspiration from similar + functions available in the STL \c header. Most of them + have a direct STL equivalent; for example, qCopyBackward() is the + same as STL's copy_backward() algorithm. + + If STL is available on all your target platforms, you can use the + STL algorithms instead of their Qt counterparts. One reason why + you might want to use the the STL algorithms is that STL provides + dozens and dozens of algorithms, whereas Qt only provides the most + important ones, making no attempt to duplicate functionality that + is already provided by the C++ standard. + + Most algorithms take \l {STL-style iterators} as parameters. The + algorithms are generic in the sense that they aren't bound to a + specific iterator class; you can use them with any iterators that + meet a certain set of requirements. + + Let's take the qFill() algorithm as an example. Unlike QVector, + QList has no fill() function that can be used to fill a list with + a particular value. If you need that functionality, you can use + qFill(): + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 0 + + qFill() takes a begin iterator, an end iterator, and a value. + In the example above, we pass \c list.begin() and \c list.end() + as the begin and end iterators, but this doesn't have to be + the case: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 1 + + Different algorithms can have different requirements for the + iterators they accept. For example, qFill() accepts two + \l {forward iterators}. The iterator types required are specified + for each algorithm. If an iterator of the wrong type is passed (for + example, if QList::ConstIterator is passed as an \l {output + iterator}), you will always get a compiler error, although not + necessarily a very informative one. + + Some algorithms have special requirements on the value type + stored in the containers. For example, qEqual() requires that the + value type supports operator==(), which it uses to compare items. + Similarly, qDeleteAll() requires that the value type is a + non-const pointer type (for example, QWidget *). The value type + requirements are specified for each algorithm, and the compiler + will produce an error if a requirement isn't met. + + \target binaryFind example + + The generic algorithms can be used on other container classes + than those provided by Qt and STL. The syntax of STL-style + iterators is modeled after C++ pointers, so it's possible to use + plain arrays as containers and plain pointers as iterators. A + common idiom is to use qBinaryFind() together with two static + arrays: one that contains a list of keys, and another that + contains a list of associated values. For example, the following + code will look up an HTML entity (e.g., \c &) in the \c + name_table array and return the corresponding Unicode value from + the \c value_table if the entity is recognized: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 2 + + This kind of code is for advanced users only; for most + applications, a QMap- or QHash-based approach would work just as + well: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 3 + + \section1 Types of Iterators + + The algorithms have certain requirements on the iterator types + they accept, and these are specified individually for each + function. The compiler will produce an error if a requirement + isn't met. + + \section2 Input Iterators + + An \e{input iterator} is an iterator that can be used for reading + data sequentially from a container. It must provide the following + operators: \c{==} and \c{!=} for comparing two iterators, unary + \c{*} for retrieving the value stored in the item, and prefix + \c{++} for advancing to the next item. + + The Qt containers' iterator types (const and non-const) are all + input iterators. + + \section2 Output Iterators + + An \e{output iterator} is an iterator that can be used for + writing data sequentially to a container or to some output + stream. It must provide the following operators: unary \c{*} for + writing a value (i.e., \c{*it = val}) and prefix \c{++} for + advancing to the next item. + + The Qt containers' non-const iterator types are all output + iterators. + + \section2 Forward Iterators + + A \e{forward iterator} is an iterator that meets the requirements + of both input iterators and output iterators. + + The Qt containers' non-const iterator types are all forward + iterators. + + \section2 Bidirectional Iterators + + A \e{bidirectional iterator} is an iterator that meets the + requirements of forward iterators but that in addition supports + prefix \c{--} for iterating backward. + + The Qt containers' non-const iterator types are all bidirectional + iterators. + + \section2 Random Access Iterators + + The last category, \e{random access iterators}, is the most + powerful type of iterator. It supports all the requirements of a + bidirectional iterator, and supports the following operations: + + \table + \row \i \c{i += n} \i advances iterator \c i by \c n positions + \row \i \c{i -= n} \i moves iterator \c i back by \c n positions + \row \i \c{i + n} or \c{n + i} \i returns the iterator for the item \c + n positions ahead of iterator \c i + \row \i \c{i - n} \i returns the iterator for the item \c n positions behind of iterator \c i + \row \i \c{i - j} \i returns the number of items between iterators \c i and \c j + \row \i \c{i[n]} \i same as \c{*(i + n)} + \row \i \c{i < j} \i returns true if iterator \c j comes after iterator \c i + \endtable + + QList and QVector's non-const iterator types are random access iterators. + + \sa {container classes}, +*/ + +/*! \fn OutputIterator qCopy(InputIterator begin1, InputIterator end1, OutputIterator begin2) + \relates + + Copies the items from range [\a begin1, \a end1) to range [\a + begin2, ...), in the order in which they appear. + + The item at position \a begin1 is assigned to that at position \a + begin2; the item at position \a begin1 + 1 is assigned to that at + position \a begin2 + 1; and so on. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 4 + + \sa qCopyBackward(), {input iterators}, {output iterators} +*/ + +/*! \fn BiIterator2 qCopyBackward(BiIterator1 begin1, BiIterator1 end1, BiIterator2 end2) + \relates + + Copies the items from range [\a begin1, \a end1) to range [..., + \a end2). + + The item at position \a end1 - 1 is assigned to that at position + \a end2 - 1; the item at position \a end1 - 2 is assigned to that + at position \a end2 - 2; and so on. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 5 + + \sa qCopy(), {bidirectional iterators} +*/ + +/*! \fn bool qEqual(InputIterator1 begin1, InputIterator1 end1, InputIterator2 begin2) + \relates + + Compares the items in the range [\a begin1, \a end1) with the + items in the range [\a begin2, ...). Returns true if all the + items compare equal; otherwise returns false. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 6 + + This function requires the item type (in the example above, + QString) to implement \c operator==(). + + \sa {input iterators} +*/ + +/*! \fn void qFill(ForwardIterator begin, ForwardIterator end, const T &value) + \relates + + Fills the range [\a begin, \a end) with \a value. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 7 + + \sa qCopy(), {forward iterators} +*/ + +/*! \fn void qFill(Container &container, const T &value) + \relates + + \overload + + This is the same as qFill(\a{container}.begin(), \a{container}.end(), \a value); +*/ + +/*! \fn InputIterator qFind(InputIterator begin, InputIterator end, const T &value) + \relates + + Returns an iterator to the first occurrence of \a value in a + container in the range [\a begin, \a end). Returns \a end if \a + value isn't found. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 8 + + This function requires the item type (in the example above, + QString) to implement \c operator==(). + + If the items in the range are in ascending order, you can get + faster results by using qLowerBound() or qBinaryFind() instead of + qFind(). + + \sa qBinaryFind(), {input iterators} +*/ + +/*! \fn void qFind(const Container &container, const T &value) + \relates + + \overload + + This is the same as qFind(\a{container}.begin(), \a{container}.end(), value); +*/ + +/*! \fn void qCount(InputIterator begin, InputIterator end, const T &value, Size &n) + \relates + + Returns the number of occurrences of \a value in the range [\a begin, \a end), + which is returned in \a n. \a n is never initialized, the count is added to \a n. + It is the caller's responsibility to initialize \a n. + + Example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 9 + + This function requires the item type (in the example above, + \c int) to implement \c operator==(). + + \sa {input iterators} +*/ + +/*! \fn void qCount(const Container &container, const T &value, Size &n) +\relates + +\overload + +Instead of operating on iterators, as in the other overload, this function +operates on the specified \a container to obtain the number of instances +of \a value in the variable passed as a reference in argument \a n. +*/ + +/*! \fn void qSwap(T &var1, T &var2) + \relates + + Exchanges the values of variables \a var1 and \a var2. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 10 +*/ + +/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end) + \relates + + Sorts the items in range [\a begin, \a end) in ascending order + using the quicksort algorithm. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 11 + + The sort algorithm is efficient on large data sets. It operates + in \l {linear-logarithmic time}, O(\e{n} log \e{n}). + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + If neither of the two items is "less than" the other, the items are + taken to be equal. It is then undefined which one of the two + items will appear before the other after the sort. + + \sa qStableSort(), {random access iterators} +*/ + +/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + For example, here's how to sort the strings in a QStringList + in case-insensitive alphabetical order: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 12 + + To sort values in reverse order, pass + \l{qGreater()}{qGreater()} as the \a lessThan parameter. For + example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 13 + + If neither of the two items is "less than" the other, the items are + taken to be equal. It is then undefined which one of the two + items will appear before the other after the sort. + + An alternative to using qSort() is to put the items to sort in a + QMap, using the sort key as the QMap key. This is often more + convenient than defining a \a lessThan function. For example, the + following code shows how to sort a list of strings case + insensitively using QMap: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 14 + + \sa QMap +*/ + +/*! \fn void qSort(Container &container) + \relates + + \overload + + This is the same as qSort(\a{container}.begin(), \a{container}.end()); +*/ + +/*! + \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end) + \relates + + Sorts the items in range [\a begin, \a end) in ascending order + using a stable sorting algorithm. + + If neither of the two items is "less than" the other, the items are + taken to be equal. The item that appeared before the other in the + original container will still appear first after the sort. This + property is often useful when sorting user-visible data. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 15 + + The sort algorithm is efficient on large data sets. It operates + in \l {linear-logarithmic time}, O(\e{n} log \e{n}). + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + \sa qSort(), {random access iterators} +*/ + +/*! + \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + For example, here's how to sort the strings in a QStringList + in case-insensitive alphabetical order: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 16 + + Note that earlier versions of Qt allowed using a lessThan function that took its + arguments by non-const reference. From 4.3 and on this is no longer possible, + the arguments has to be passed by const reference or value. + + To sort values in reverse order, pass + \l{qGreater()}{qGreater()} as the \a lessThan parameter. For + example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 17 + + If neither of the two items is "less than" the other, the items are + taken to be equal. The item that appeared before the other in the + original container will still appear first after the sort. This + property is often useful when sorting user-visible data. +*/ + +/*! + \fn void qStableSort(Container &container) + \relates + + \overload + + This is the same as qStableSort(\a{container}.begin(), \a{container}.end()); +*/ + +/*! \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) + \relates + + Performs a binary search of the range [\a begin, \a end) and + returns the position of the first ocurrence of \a value. If no + such item is found, returns the position where it should be + inserted. + + The items in the range [\a begin, \e end) must be sorted in + ascending order; see qSort(). + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 18 + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + qLowerBound() can be used in conjunction with qUpperBound() to + iterate over all occurrences of the same value: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 19 + + \sa qUpperBound(), qBinaryFind() +*/ + +/*! + \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + Note that the items in the range must be sorted according to the order + specified by the \a lessThan object. +*/ + +/*! + \fn void qLowerBound(const Container &container, const T &value) + \relates + + \overload + + This is the same as qLowerBound(\a{container}.begin(), \a{container}.end(), value); +*/ + +/*! \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) + \relates + + Performs a binary search of the range [\a begin, \a end) and + returns the position of the one-past-the-last occurrence of \a + value. If no such item is found, returns the position where the + item should be inserted. + + The items in the range [\a begin, \e end) must be sorted in + ascending order; see qSort(). + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 20 + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + qUpperBound() can be used in conjunction with qLowerBound() to + iterate over all occurrences of the same value: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 21 + + \sa qLowerBound(), qBinaryFind() +*/ + +/*! + \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + Note that the items in the range must be sorted according to the order + specified by the \a lessThan object. +*/ + +/*! + \fn void qUpperBound(const Container &container, const T &value) + \relates + + \overload + + This is the same as qUpperBound(\a{container}.begin(), \a{container}.end(), value); +*/ + + +/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value) + \relates + + Performs a binary search of the range [\a begin, \a end) and + returns the position of an occurrence of \a value. If there are + no occurrences of \a value, returns \a end. + + The items in the range [\a begin, \a end) must be sorted in + ascending order; see qSort(). + + If there are many occurrences of the same value, any one of them + could be returned. Use qLowerBound() or qUpperBound() if you need + finer control. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 22 + + This function requires the item type (in the example above, + QString) to implement \c operator<(). + + See the \l{#binaryFind example}{detailed + description} for an example usage. + + \sa qLowerBound(), qUpperBound(), {random access iterators} +*/ + +/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + Note that the items in the range must be sorted according to the order + specified by the \a lessThan object. +*/ + +/*! + \fn void qBinaryFind(const Container &container, const T &value) + \relates + + \overload + + This is the same as qBinaryFind(\a{container}.begin(), \a{container}.end(), value); +*/ + + +/*! + \fn void qDeleteAll(ForwardIterator begin, ForwardIterator end) + \relates + + Deletes all the items in the range [\a begin, \a end) using the + C++ \c delete operator. The item type must be a pointer type (for + example, \c{QWidget *}). + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 23 + + Notice that qDeleteAll() doesn't remove the items from the + container; it merely calls \c delete on them. In the example + above, we call clear() on the container to remove the items. + + This function can also be used to delete items stored in + associative containers, such as QMap and QHash. Only the objects + stored in each container will be deleted by this function; objects + used as keys will not be deleted. + + \sa {forward iterators} +*/ + +/*! + \fn void qDeleteAll(const Container &c) + \relates + + \overload + + This is the same as qDeleteAll(\a{c}.begin(), \a{c}.end()). +*/ + +/*! \fn LessThan qLess() + \relates + + Returns a functional object, or functor, that can be passed to qSort() + or qStableSort(). + + Example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 24 + + \sa {qGreater()}{qGreater()} +*/ + +/*! \fn LessThan qGreater() + \relates + + Returns a functional object, or functor, that can be passed to qSort() + or qStableSort(). + + Example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 25 + + \sa {qLess()}{qLess()} +*/ diff --git a/doc/src/qaxcontainer.qdoc b/doc/src/qaxcontainer.qdoc new file mode 100644 index 0000000..48c76fc --- /dev/null +++ b/doc/src/qaxcontainer.qdoc @@ -0,0 +1,260 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QAxContainer + \title QAxContainer Module + \contentspage Qt's Modules + \previouspage QtTest + \nextpage QAxServer + \ingroup modules + + \brief The QAxContainer module is a Windows-only extension for + accessing ActiveX controls and COM objects. + + The QAxContainer module is part of the \l ActiveQt framework. It + provides a library implementing a QWidget subclass, QAxWidget, + that acts as a container for ActiveX controls, and a QObject + subclass, QAxObject, that can be used to easily access non-visual + COM objects. Scripting COM objects embedded using these classes + is possible through the QAxScript, QAxScriptManager and + QAxScriptEngine classes, and a set of \l{Tools for ActiveQt}{tools} + makes it easy to access COM objects programmatically. + + The module consists of six classes + \list 1 + \o QAxBase is an abstract class that provides an API to initialize + and access a COM object or ActiveX control. + \o QAxObject provides a QObject that wraps a COM object. + \o QAxWidget is a QWidget that wraps an ActiveX control. + \o QAxScriptManager, QAxScript and QAxScriptEngine provide an + interface to the Windows Script Host. + \endlist + + Some \l{Qt Examples#ActiveQt}{example applications} that use + standard ActiveX controls to provide high-level user interface + functionality are provided. + + \sa {ActiveQt Framework} + + Topics: + + \tableofcontents + + \section1 Using the Library + + To build Qt applications that can host COM objects and ActiveX controls + link the application against the QAxContainer module by adding + + \snippet doc/src/snippets/code/doc_src_qaxcontainer.qdoc 0 + + to your application's \c .pro file. + + \section2 Distributing QAxContainer Applications + + The QAxContainer library is static, so there is no need to redistribute + any additional files when using this module. Note however that the + ActiveX server binaries you are using might not be installed on the + target system, so you have to ship them with your package and register + them during the installation process of your application. + + \section1 Instantiating COM Objects + + To instantiate a COM object use the QAxBase::setControl() API, or pass + the name of the object directly into the constructor of the QAxBase + subclass you are using. + + The control can be specified in a variety of formats, but the fastest + and most powerful format is to use the class ID (CLSID) of the object + directly. The class ID can be prepended with information about a remote + machine that the object should run on, and can include a license key + for licensed controls. + + \section2 Typical Error Messages + + ActiveQt prints error messages to the debug output when it + encounters error situations at runtime. Usually you must run + your program in the debugger to see these messages (e.g. in Visual + Studio's Debug output). + + \section3 Requested control could not be instantiated + + The control requested in QAxBase::setControl() is not installed + on this system, or is not accessible for the current user. + + The control might require administrator rights, or a license key. + If the control is licensed, pass the license key to QAxBase::setControl + as documented. + + \section1 Accessing the Object API + + ActiveQt provides a Qt API to the COM object, and replaces COM + datatypes with Qt equivalents. + + There are four ways to call APIs on the COM object: + + \list + \o Generating a C++ namespace + \o Call-by-name + \o Through a script engine + \o Using the native COM interfaces + \endlist + + \section2 Generating a C++ Namespace + + To generate a C++ namespace for the type library you want to access, + use the \l dumpcpp tool. Run this tool manually on the type library you + want to use, or integrate it into the build system by adding the type + libraries to the \c TYPELIBS variable in your application's \c .pro file: + + \snippet doc/src/snippets/code/doc_src_qaxcontainer.qdoc 1 + + Note that \l dumpcpp might not be able to expose all APIs in the type + library. + + Include the resulting header file in your code to access the + object APIs through the generated C++ classes. See the + \l{activeqt/qutlook}{Qutlook} example for more information. + + \section2 Call-by-Name + + Use QAxBase::dynamicCall() and QAxBase::querySubObject() as well as + the QObject::setProperty() and QObject::property() APIs to call the + methods and properties of the COM object through their name. Use the + \l dumpdoc tool to get the documentation of the Qt API for any COM + object and its subobjects; note that not all of the COM object's APIs + might be available. + + See the \l{activeqt/webbrowser}{Webbrowser} example for more information. + + \section2 Calling Function Through a Script Engine + + A Qt application can host any ActiveScript engine installed on the system. + The script engine can then run script code that accesses the COM objects. + + To instantiate a script engine, use QAxScriptManager::addObject() to + register the COM objects you want to access from script, and + QAxScriptManager::load() to load the script code into the engine. Then + call the script functions using QAxScriptManager::call() or + QAxScript::call(). + + Which APIs of the COM object are available through scripting depends on + the script language used. + + The \l{testcon - An ActiveX Test Container (ActiveQt)}{ActiveX Test Container} + demonstrates loading of script files. + + \section2 Calling a Function Using the Native COM Interfaces + + To call functions of the COM object that can not be accessed via any + of the above methods it is possible to request the COM interface directly + using QAxBase::queryInterface(). To get a C++ definition of the respective + interface classes use the \c #import directive with the type library + provided with the control; see your compiler manual for details. + + \section2 Typical Error Messages + + ActiveQt prints error messages to the debug output when it + encounters error situations at runtime. Usually you must run + your program in the debugger to see these messages (e.g. in Visual + Studio's Debug output). + + \section3 QAxBase::internalInvoke: No such method + + A QAxBase::dynamicCall() failed - the function prototype did not + match any function available in the object's API. + + \section3 Error calling IDispatch member: Non-optional parameter missing + + A QAxBase::dynamicCall() failed - the function prototype was correct, + but too few parameters were provided. + + \section3 Error calling IDispatch member: Type mismatch in parameter n + + A QAxBase::dynamicCall() failed - the function prototype was correct, + but the paramter at index \c n was of the wrong type and could + not be coerced to the correct type. + + \section3 QAxScriptManager::call(): No script provides this function + + You try to call a function that is provided through an engine + that doesn't provide introspection (ie. ActivePython or + ActivePerl). You need to call the function directly on the + respective QAxScript object. + + \section1 License Information + + The QAxContainer module is not covered by the \l{GNU General Public License (GPL)}, + the \l{GNU Lesser General Public License (LGPL)}, or the + \l{Qt Commercial Editions}{Qt Commercial License}. Instead, it is distributed under + the following license. + + \legalese + Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).\br + All rights reserved. + + Contact: Qt Software Information (qt-info@nokia.com)\br + + You may use this file under the terms of the BSD license as follows:\br + + "Redistribution and use in source and binary forms, with or without modification, + are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, this list + of conditions and the following disclaimer.\br + * Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or other + materials provided with the distribution.\br + * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor the names of + its contributors may be used to endorse or promote products derived from this + software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT + SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." + \endlegalese +*/ diff --git a/doc/src/qaxserver.qdoc b/doc/src/qaxserver.qdoc new file mode 100644 index 0000000..f0c317b --- /dev/null +++ b/doc/src/qaxserver.qdoc @@ -0,0 +1,898 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QAxServer + \title QAxServer Module + \contentspage Qt's Modules + \previouspage QAxContainer + \nextpage QtDBus module + \ingroup modules + + \brief The QAxServer module is a Windows-only static library that + you can use to turn a standard Qt binary into a COM server. + + The QAxServer module is part of the \l ActiveQt framework. It + consists of three classes: + + \list + \o QAxFactory defines a factory for the creation of COM objects. + \o QAxBindable provides an interface between the Qt widget and the + COM object. + \o QAxAggregated can be subclassed to implement additional COM interfaces. + \endlist + + Some \l{Qt Examples#ActiveQt}{example implementations} of ActiveX + controls and COM objects are provided. + + \sa {ActiveQt Framework} + + Topics: + + \tableofcontents + + \section1 Using the Library + + To turn a standard Qt application into a COM server using the + QAxServer library you must add \c qaxserver as a CONFIG setting + in your \c .pro file. + + An out-of-process executable server is generated from a \c .pro + file like this: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 0 + + To build an in-process server, use a \c .pro file like this: + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 1 + + The files \c qaxserver.rc and \c qaxserver.def are part of the + framework and can be used from their usual location (specify a + path in the \c .pro file), or copied into the project directory. + You can modify these files as long as it includes any file as the + type library entry, ie. you can add version information or specify + a different toolbox icon. + + The \c qaxserver configuration will cause the \c qmake tool to add the + required build steps to the build system: + + \list + \o Link the binary against \c qaxserver.lib instead of \c qtmain.lib + \o Call the \l idc tool to generate an IDL file for the COM server + \o Compile the IDL into a type library using the MIDL tool (part of the + compiler installation) + \o Attach the resulting type library as a binary resource to the server + binary (again using the \l idc tool) + \o Register the server + \endlist + + Note that the QAxServer build system is not supported on Windows 98/ME + (attaching of resources to a binary is not possible there), but a server + built on Windows NT/2000/XP will work on previous Windows versions as well. + + To skip the post-processing step, also set the \c qaxserver_no_postlink + configuration. + + Additionally you can specify a version number using the \c VERSION + variable, e.g. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 2 + + The version number specified will be used as the version of the type + library and of the server when registering. + + \section2 Out-of-Process vs. In-Process + + Whether your COM server should run as a stand-alone executable + or as a shared library in the client process depends mainly on the + type of COM objects you want to provide in the server. + + An executable server has the advantage of being able to run as a + stand-alone application, but adds considerable overhead to the + communication between the COM client and the COM object. If the + control has a programming error only the server process running + the control will crash, and the client application will probably + continue to run. Not all COM clients support executable servers. + + An in-process server is usually smaller and has faster startup + time. The communication between client and server is done directly + through virtual function calls and does not introduce the overhead + required for remote procedure calls. However, if the server crashes the + client application is likely to crash as well, and not every + functionality is available for in-process servers (i.e. register in + the COM's running-object-table). + + Both server types can use Qt either as a shared library, or statically + linked into the server binary. + + \section2 Typical Errors During the Post-Build Steps + + For the ActiveQt specific post-processing steps to work the + server has to meet some requirements: + + \list + \o All controls exposed can be created with nothing but a QApplication + instance being present + \o The initial linking of the server includes a temporary type + library resource + \o All dependencies required to run the server are in the system path + (or in the path used by the calling environment; note that Visual + Studio has its own set of environment variables listed in the + Tools|Options|Directories dialog). + \endlist + + If those requirements are not met one ore more of the following + errors are likely to occur: + + \section3 The Server Executable Crashes + + To generate the IDL the widgets exposed as ActiveX controls need to + be instantiated (the constructor is called). At this point, nothing + else but a QApplication object exists. Your widget constructor must + not rely on any other objects to be created, e.g. it should check for + null-pointers. + + To debug your server run it with -dumpidl outputfile and check where + it crashes. + + Note that no functions of the control are called. + + \section3 The Server Executable Is Not a Valid Win32 Application + + Attaching the type library corrupted the server binary. This is a + bug in Windows and happens only with release builds. + + The first linking step has to link a dummy type library into the + executable that can later be replaced by idc. Add a resource file + with a type library to your project as demonstrated in the examples. + + \section3 "Unable to locate DLL" + + The build system needs to run the server executable to generate + the interface definition, and to register the server. If a dynamic + link library the server links against is not in the path this + might fail (e.g. Visual Studio calls the server using the + enivronment settings specified in the "Directories" option). Make + sure that all DLLs required by your server are located in a + directory that is listed in the path as printed in the error + message box. + + \section3 "Cannot open file ..." + + The ActiveX server could not shut down properly when the last + client stopped using it. It usually takes about two seconds for + the application to terminate, but you might have to use the task + manager to kill the process (e.g. when a client doesn't release + the controls properly). + + \section1 Implementing Controls + + To implement a COM object with Qt, create a subclass of QObject + or any existing QObject subclass. If the class is a subclass of QWidget, + the COM object will be an ActiveX control. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 3 + + The Q_OBJECT macro is required to provide the meta object information + about the widget to the ActiveQt framework. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 4 + + Use the Q_CLASSINFO() macro to specify the COM identifiers for the COM + object. \c ClassID and \c InterfaceID are required, while \c EventsID is + only necessary when your object has signals. To generate these identifiers, + use system tools like \c uuidgen or \c guidgen. + + You can specify additional attributes for each of your classes; see + \l{Class Information and Tuning} for details. + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 5 + + Use the Q_PROPERTY() macro to declare properties for the ActiveX control. + + Declare a standard constructor taking a parent object, and functions, + signals and slots like for any QObject subclass. + \footnote + If a standard constructor is not present the compiler will issue + an error "no overloaded function takes 2 parameters" when using + the default factory through the QAXFACTORY_DEFAULT() macro. If you + cannot provide a standard constructor you must implement a + QAxFactory custom factory and call the constructor you have in + your implementation of QAxFactory::create. + \endfootnote + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 6 + + The ActiveQt framework will expose properties and public slots as ActiveX + properties and methods, and signals as ActiveX events, and convert between + the Qt data types and the equivalent COM data types. + + \section2 Data Types + + The Qt data types that are supported for properties are: + + \table + \header + \o Qt data type + \o COM property + \row + \o bool + \o VARIANT_BOOL + \row + \o QString + \o BSTR + \row + \o int + \o int + \row + \o uint + \o unsigned int + \row + \o double + \o double + \row + \o \l qlonglong + \o CY + \row + \o \l qulonglong + \o CY + \row + \o QColor + \o OLE_COLOR + \row + \o QDate + \o DATE + \row + \o QDateTime + \o DATE + \row + \o QTime + \o DATE + \row + \o QFont + \o IFontDisp* + \row + \o QPixmap + \o IPictureDisp* + \footnote + COM cannot marshal IPictureDisp accross process boundaries, + so QPixmap properties cannot be called for out-of-process servers. You + can however marshal the image data via e.g. temporary files. See the + Microsoft + \link http://support.microsoft.com/default.aspx?scid=kb;[LN];Q150034 KB article + Q150034 \endlink for more information. + \endfootnote + \row + \o QVariant + \o VARIANT + \row + \o QVariantList (same as QList\) + \o SAFEARRAY(VARIANT) + \row + \o QStringList + \o SAFEARRAY(BSTR) + \row + \o QByteArray + \o SAFEARRAY(BYTE) + \row + \o QRect + \o User defined type + \row + \o QSize + \o User defined type + \row + \o QPoint + \o User defined type + \endtable + + The Qt data types that are supported for parameters in signals and + slots are: + \table + \header + \o Qt data type + \o COM parameter + \row + \o bool + \o [in] VARIANT_BOOL + \row + \o bool& + \o [in, out] VARIANT_BOOL* + \row + \o QString, const QString& + \o [in] BSTR + \row + \o QString& + \o [in, out] BSTR* + \row + \o QString& + \o [in, out] BSTR* + \row + \o int + \o [in] int + \row + \o int& + \o [in,out] int + \row + \o uint + \o [in] unsigned int + \row + \o uint& + \o [in, out] unsigned int* + \row + \o double + \o [in] double + \row + \o double& + \o [in, out] double* + \row + \o QColor, const QColor& + \o [in] OLE_COLOR + \row + \o QColor& + \o [in, out] OLE_COLOR* + \row + \o QDate, const QDate& + \o [in] DATE + \row + \o QDate& + \o [in, out] DATE* + \row + \o QDateTime, const QDateTime& + \o [in] DATE + \row + \o QDateTime& + \o [in, out] DATE* + \row + \o QFont, const QFont& + \o [in] IFontDisp* + \row + \o QFont& + \o [in, out] IFontDisp** + \row + \o QPixmap, const QPixmap& + \o [in] IPictureDisp* + \row + \o QPixmap& + \o [in, out] IPictureDisp** + \row + \o QList\, const QList\& + \o [in] SAFEARRAY(VARIANT) + \row + \o QList\& + \o [in, out] SAFEARRAY(VARIANT)* + \row + \o QStringList, const QStringList& + \o [in] SAFEARRAY(BSTR) + \row + \o QStringList& + \o [in, out] SAFEARRAY(BSTR)* + \row + \o QByteArray, const QByteArray& + \o [in] SAFEARRAY(BYTE) + \row + \o QByteArray& + \o [in, out] SAFEARRAY(BYTE)* + \row + \o QObject* + \o [in] IDispatch* + \row + \o QRect& + \footnote + OLE needs to marshal user defined types by reference (ByRef), and cannot + marshal them by value (ByVal). This is why const-references and object + parameters are not supported for QRect, QSize and QPoint. Also note that + servers with this datatype require Windows 98 or DCOM 1.2 to be installed. + \endfootnote + \o [in, out] struct QRect (user defined) + \row + \o QSize& + \o [in, out] struct QSize (user defined) + \row + \o QPoint& + \o [in, out] struct QPoint (user defined) + \endtable + + Also supported are exported enums and flags (see Q_ENUMS() and + Q_FLAGS()). The in-parameter types are also supported as + return values. + + Properties and signals/slots that have parameters using any other + data types are ignored by the ActiveQt framework. + + \section2 Sub-Objects + + COM objects can have multiple sub-objects that can represent a sub element + of the COM object. A COM object representing a multi-document spread sheet + application can for example provide one sub-object for each spread sheet. + + Any QObject subclass can be used as the type for a sub object in ActiveX, as + long as it is known to the QAxFactory. Then the type can be used in properties, + or as the return type or paramter of a slot. + + \section2 Property Notification + + To make the properties bindable for the ActiveX client, use multiple + inheritance from the QAxBindable class: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 7 + + When implementing the property write functions, use the + QAxBindable class's requestPropertyChange() and propertyChanged() + functions to allow ActiveX clients to bind to the control + properties. + \footnote + This is not required, but gives the client more control over + the ActiveX control. + \endfootnote + + \section1 Serving Controls + + To make a COM server available to the COM system it must be registered + in the system registry using five unique identifiers. + These identifiers are provided by tools like \c guidgen or \c uuidgen. + The registration information allows COM to localize the binary providing + a requested ActiveX control, marshall remote procedure calls to the + control and read type information about the methods and properties exposed + by the control. + + To create the COM object when the client asks for it the server must export + an implementation of a QAxFactory. The easist way to do this is to use a set + of macros: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 8 + + This will export \c MyWidget and \c MyWidget2 as COM objects that can be + created by COM clients, and will register \c MySubType as a type that can + be used in properties and parameters of \c MyWidget and \c MyWidget2. + + The \link QAxFactory QAxFactory class documentation \endlink explains + how to use this macro, and how to implement and use custom factories. + + For out-of-process executable servers you can implement a main() + function to instantiate a QApplication object and enter the event + loop just like any normal Qt application. By default the + application will start as a standard Qt application, but if you + pass \c -activex on the command line it will start as an ActiveX + server. Use QAxFactory::isServer() to create and run a standard + application interface, or to prevent a stand-alone execution: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 9 + + This is however not necessary as ActiveQt provides a default implementation + of a main function. The default implemenation calls QAxFactory::startServer(), + creates a QApplication instance and calls exec(). + + To build the ActiveX server executable run \c qmake + to generate the makefile, and use your compiler's + make tool as for any other Qt application. The make process will + also register the controls in the system registry by calling the + resulting executable with the \c -regserver command line option. + + If the ActiveX server is an executable, the following command line + options are supported: + \table + \header \o Option \o Result + \row \o \c -regserver \o Registers the server in the system registry + \row \o \c -unregserver \o Unregisters the server from the system registry + \row \o \c -activex \o Starts the application as an ActiveX server + \row \o \c{-dumpidl -version x.y} \o Writes the server's IDL to the + specified file. The type library will have version x.y + \endtable + + In-process servers can be registered using the \c regsvr32 tool available + on all Windows systems. + + \section2 Typical Compile-Time Problems + + The compiler/linker errors listed are based on those issued by the + Microsoft Visual C++ 6.0 compiler. + + \section3 "No overloaded function takes 2 parameters" + + When the error occurs in code that uses the QAXFACTORY_DEFAULT() + macro, the widget class had no constructor that can be used by the + default factory. Either add a standard widget constructor or + implement a custom factory that doesn't require one. + + When the error occurs in code that uses the QAXFACTORY_EXPORT() + macro, the QAxFactory subclass had no appropriate constructor. + Provide a public class constructor like + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 10 + + for your factory class. + + \section3 "Syntax error: bad suffix on number" + + The unique identifiers have not been passed as strings into the + QAXFACTORY_EXPORT() or QAXFACTORY_DEFAULT() macro. + + \section3 "Unresolved external symbol _ucm_instantiate" + + The server does not export an implementation of a QAxFactory. Use + the QAXFACTORY_EXPORT() macro in one of the project's + implementation files to instantiate and export a factory, or use + the QAXFACTORY_DEFAULT() macro to use the default factory. + + \section3 "_ucm_initialize already defined in ..." + + The server exports more than one implementation of a QAxFactory, + or exports the same implementation twice. If you use the default + factory, the QAXFACTORY_DEFAULT() macro must only be used once in + the project. Use a custom QAxFactory implementation and the + QAXFACTORY_EXPORT() macro if the server provides multiple ActiveX + controls. + + \section2 Distributing QAxServer Binaries + + ActiveX servers written with Qt can use Qt either as a shared + library, or have Qt linked statically into the binary. Both ways + will produce rather large packages (either the server binary + itself becomes large, or you have to ship the Qt DLL). + + \section3 Installing Stand-Alone Servers + + When your ActiveX server can also run as a stand-alone application, + run the server executable with the \c -regserver command line + parameter after installing the executable on the target system. + After that the controls provided by the server will be available to + ActiveX clients. + + \section3 Installing In-Process Servers + + When your ActiveX server is part of an installation package, use the + \c regsvr32 tool provided by Microsoft to register the controls on + the target system. If this tool is not present, load the DLL into + your installer process, resolve the \c DllRegisterServer symbol and + call the function: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 11 + + \section3 Distributing Servers over the Internet + + If you want to use controls in your server in web-pages you need to + make the server available to the browser used to view your page, and + you need to specify the location of the server package in your page. + + To specify the location of a server, use the CODEBASE attribute in + the OBJECT tag of your web-site. The value can point to the server + file itself, to an INF file listing other files the server requires + (e.g. the Qt DLL), or a compressed CAB archive. + + INF and CAB files are documented in almost every book available about + ActiveX and COM programming as well as in the MSDN library and various + other Online resources. The examples include INF files that can be used + to build CAB archives: + + \snippet examples/activeqt/simple/simple.inf 0 + + The CABARC tool from Microsoft can easily generate CAB archives: + + \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 12 + + The INF files assume a static build of Qt, so no dependencies to other DLLs + are listed in the INF files. To distribute an ActiveX server depending on + DLLs you must add the dependencies, and provide the library files + with the archive. + + \section1 Using the Controls + + To use the ActiveX controls, e.g. to embed them in a web page, use + the \c