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..b62f244 --- /dev/null +++ b/demos/spreadsheet/spreadsheet.pro @@ -0,0 +1,33 @@ +###################################################################### +# 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 + 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..920e8a0 --- /dev/null +++ b/demos/sqlbrowser/sqlbrowser.pro @@ -0,0 +1,23 @@ +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 + +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..128cd6a --- /dev/null +++ b/demos/textedit/textedit.cpp @@ -0,0 +1,688 @@ +/**************************************************************************** +** +** 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))); + + connect(QApplication::clipboard(), SIGNAL(dataChanged()), this, SLOT(clipboardDataChanged())); + + 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); + actionPaste->setEnabled(!QApplication::clipboard()->text().isEmpty()); +} + +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() +{ + actionPaste->setEnabled(!QApplication::clipboard()->text().isEmpty()); +} + +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..1ef4256 --- /dev/null +++ b/demos/textedit/textedit.pro @@ -0,0 +1,21 @@ +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 + 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..e26d07c --- /dev/null +++ b/demos/undo/undo.pro @@ -0,0 +1,17 @@ +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 + 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/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