From f4978a5894212dd655a91dbb0db02a89070bb165 Mon Sep 17 00:00:00 2001 From: Tom Cooksey Date: Mon, 27 Jul 2009 16:44:27 +0200 Subject: Refactor QImage/QPixmap cleanup hooks into a seperate class The new class alows more than one hook to be installed at a time and, for QPixmaps, the hook is told which pixmap is getting deleted. Reviewed-By: Samuel --- src/gui/image/image.pri | 6 +- src/gui/image/qimage.cpp | 17 +--- src/gui/image/qimagepixmapcleanuphooks.cpp | 110 +++++++++++++++++++++ src/gui/image/qimagepixmapcleanuphooks_p.h | 89 +++++++++++++++++ src/gui/image/qpixmap.cpp | 20 +--- src/opengl/qgl.cpp | 25 ++++- src/opengl/qgl_p.h | 3 +- .../gfxdrivers/directfb/qdirectfbpaintengine.cpp | 5 +- 8 files changed, 238 insertions(+), 37 deletions(-) create mode 100644 src/gui/image/qimagepixmapcleanuphooks.cpp create mode 100644 src/gui/image/qimagepixmapcleanuphooks_p.h diff --git a/src/gui/image/image.pri b/src/gui/image/image.pri index bf348af..b9c36dc 100644 --- a/src/gui/image/image.pri +++ b/src/gui/image/image.pri @@ -25,7 +25,9 @@ HEADERS += \ image/qpixmapcache_p.h \ image/qpixmapdata_p.h \ image/qpixmapdatafactory_p.h \ - image/qpixmapfilter_p.h + image/qpixmapfilter_p.h \ + image/qimagepixmapcleanuphooks_p.h \ + SOURCES += \ image/qbitmap.cpp \ @@ -47,6 +49,8 @@ SOURCES += \ image/qmovie.cpp \ image/qpixmap_raster.cpp \ image/qnativeimage.cpp \ + image/qimagepixmapcleanuphooks.cpp \ + win32 { SOURCES += image/qpixmap_win.cpp diff --git a/src/gui/image/qimage.cpp b/src/gui/image/qimage.cpp index dd56765..f40bc7b 100644 --- a/src/gui/image/qimage.cpp +++ b/src/gui/image/qimage.cpp @@ -49,6 +49,7 @@ #include "qimagewriter.h" #include "qstringlist.h" #include "qvariant.h" +#include "qimagepixmapcleanuphooks_p.h" #include #include #include @@ -106,14 +107,6 @@ static inline bool checkPixelSize(const QImage::Format format) } -// ### Qt 5: remove -typedef void (*_qt_image_cleanup_hook)(int); -Q_GUI_EXPORT _qt_image_cleanup_hook qt_image_cleanup_hook = 0; - -// ### Qt 5: rename -typedef void (*_qt_image_cleanup_hook_64)(qint64); -Q_GUI_EXPORT _qt_image_cleanup_hook_64 qt_image_cleanup_hook_64 = 0; - static QImage rotated90(const QImage &src); static QImage rotated180(const QImage &src); static QImage rotated270(const QImage &src); @@ -257,8 +250,8 @@ QImageData * QImageData::create(const QSize &size, QImage::Format format, int nu QImageData::~QImageData() { - if (is_cached && qt_image_cleanup_hook_64) - qt_image_cleanup_hook_64((((qint64) ser_no) << 32) | ((qint64) detach_no)); + if (is_cached) + QImagePixmapCleanupHooks::executeImageHooks((((qint64) ser_no) << 32) | ((qint64) detach_no)); delete paintEngine; if (data && own_data) free(data); @@ -1342,8 +1335,8 @@ QImage::operator QVariant() const void QImage::detach() { if (d) { - if (d->is_cached && qt_image_cleanup_hook_64 && d->ref == 1) - qt_image_cleanup_hook_64(cacheKey()); + if (d->is_cached && d->ref == 1) + QImagePixmapCleanupHooks::executeImageHooks(cacheKey()); if (d->ref != 1 || d->ro_data) *this = copy(); diff --git a/src/gui/image/qimagepixmapcleanuphooks.cpp b/src/gui/image/qimagepixmapcleanuphooks.cpp new file mode 100644 index 0000000..7d1c5fb --- /dev/null +++ b/src/gui/image/qimagepixmapcleanuphooks.cpp @@ -0,0 +1,110 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtGui module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "qimagepixmapcleanuphooks_p.h" +#include "qpixmapdata_p.h" + + +// Legacy, single instance hooks: ### Qt 5: remove +typedef void (*_qt_pixmap_cleanup_hook)(int); +typedef void (*_qt_pixmap_cleanup_hook_64)(qint64); +typedef void (*_qt_image_cleanup_hook)(int); +Q_GUI_EXPORT _qt_pixmap_cleanup_hook qt_pixmap_cleanup_hook = 0; +Q_GUI_EXPORT _qt_pixmap_cleanup_hook_64 qt_pixmap_cleanup_hook_64 = 0; +Q_GUI_EXPORT _qt_image_cleanup_hook qt_image_cleanup_hook = 0; +Q_GUI_EXPORT _qt_image_cleanup_hook_64 qt_image_cleanup_hook_64 = 0; + + +QImagePixmapCleanupHooks* qt_image_and_pixmap_cleanup_hooks = 0; + + +QImagePixmapCleanupHooks::QImagePixmapCleanupHooks() +{ + qt_image_and_pixmap_cleanup_hooks = this; +} + +QImagePixmapCleanupHooks *QImagePixmapCleanupHooks::instance() +{ + if (!qt_image_and_pixmap_cleanup_hooks) + qt_image_and_pixmap_cleanup_hooks = new QImagePixmapCleanupHooks; + return qt_image_and_pixmap_cleanup_hooks; +} + +void QImagePixmapCleanupHooks::addPixmapHook(_qt_pixmap_cleanup_hook_pm hook) +{ + pixmapHooks.append(hook); +} + +void QImagePixmapCleanupHooks::addImageHook(_qt_image_cleanup_hook_64 hook) +{ + imageHooks.append(hook); +} + +void QImagePixmapCleanupHooks::removePixmapHook(_qt_pixmap_cleanup_hook_pm hook) +{ + pixmapHooks.removeAll(hook); +} + +void QImagePixmapCleanupHooks::removeImageHook(_qt_image_cleanup_hook_64 hook) +{ + imageHooks.removeAll(hook); +} + + +void QImagePixmapCleanupHooks::executePixmapHooks(QPixmap* pm) +{ + for (int i = 0; i < qt_image_and_pixmap_cleanup_hooks->pixmapHooks.count(); ++i) + qt_image_and_pixmap_cleanup_hooks->pixmapHooks[i](pm); + + if (qt_pixmap_cleanup_hook_64) + qt_pixmap_cleanup_hook_64(pm->cacheKey()); +} + + +void QImagePixmapCleanupHooks::executeImageHooks(qint64 key) +{ + for (int i = 0; i < qt_image_and_pixmap_cleanup_hooks->imageHooks.count(); ++i) + qt_image_and_pixmap_cleanup_hooks->imageHooks[i](key); + + if (qt_image_cleanup_hook_64) + qt_image_cleanup_hook_64(key); +} + diff --git a/src/gui/image/qimagepixmapcleanuphooks_p.h b/src/gui/image/qimagepixmapcleanuphooks_p.h new file mode 100644 index 0000000..e765e69 --- /dev/null +++ b/src/gui/image/qimagepixmapcleanuphooks_p.h @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtGui module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef QIMAGEPIXMAP_CLEANUPHOOKS_P_H +#define QIMAGEPIXMAP_CLEANUPHOOKS_P_H + +// +// W A R N I N G +// ------------- +// +// This file is not part of the Qt API. It exists purely as an +// implementation detail. This header file may change from version to +// version without notice, or even be removed. +// +// We mean it. +// + +#include + +QT_BEGIN_NAMESPACE + +typedef void (*_qt_image_cleanup_hook_64)(qint64); +typedef void (*_qt_pixmap_cleanup_hook_pm)(QPixmap*); + +class QImagePixmapCleanupHooks; +extern QImagePixmapCleanupHooks* qt_image_and_pixmap_cleanup_hooks; + +class Q_GUI_EXPORT QImagePixmapCleanupHooks +{ +public: + QImagePixmapCleanupHooks(); + + static QImagePixmapCleanupHooks *instance(); + + void addPixmapHook(_qt_pixmap_cleanup_hook_pm); + void addImageHook(_qt_image_cleanup_hook_64); + + void removePixmapHook(_qt_pixmap_cleanup_hook_pm); + void removeImageHook(_qt_image_cleanup_hook_64); + + static void executePixmapHooks(QPixmap*); + static void executeImageHooks(qint64 key); + +private: + QList<_qt_image_cleanup_hook_64> imageHooks; + QList<_qt_pixmap_cleanup_hook_pm> pixmapHooks; +}; + +QT_END_NAMESPACE + +#endif // QIMAGEPIXMAP_CLEANUPHOOKS_P_H diff --git a/src/gui/image/qpixmap.cpp b/src/gui/image/qpixmap.cpp index 18829f4..2674cac 100644 --- a/src/gui/image/qpixmap.cpp +++ b/src/gui/image/qpixmap.cpp @@ -43,6 +43,7 @@ #include "qpixmap.h" #include "qpixmapdata_p.h" +#include "qimagepixmapcleanuphooks_p.h" #include "qbitmap.h" #include "qcolormap.h" @@ -81,14 +82,6 @@ QT_BEGIN_NAMESPACE // ### Qt 5: remove -typedef void (*_qt_pixmap_cleanup_hook)(int); -Q_GUI_EXPORT _qt_pixmap_cleanup_hook qt_pixmap_cleanup_hook = 0; - -// ### Qt 5: rename -typedef void (*_qt_pixmap_cleanup_hook_64)(qint64); -Q_GUI_EXPORT _qt_pixmap_cleanup_hook_64 qt_pixmap_cleanup_hook_64 = 0; - -// ### Qt 5: remove Q_GUI_EXPORT qint64 qt_pixmap_id(const QPixmap &pixmap) { return pixmap.cacheKey(); @@ -1357,8 +1350,8 @@ bool QPixmap::isDetached() const void QPixmap::deref() { if (data && !data->ref.deref()) { // Destroy image if last ref - if (data->is_cached && qt_pixmap_cleanup_hook_64) - qt_pixmap_cleanup_hook_64(cacheKey()); + if (data->is_cached) + QImagePixmapCleanupHooks::executePixmapHooks(this); delete data; data = 0; } @@ -1897,9 +1890,6 @@ int QPixmap::defaultDepth() #endif } -typedef void (*_qt_pixmap_cleanup_hook_64)(qint64); -extern _qt_pixmap_cleanup_hook_64 qt_pixmap_cleanup_hook_64; - /*! Detaches the pixmap from shared pixmap data. @@ -1925,8 +1915,8 @@ void QPixmap::detach() rasterData->image.detach(); } - if (data->is_cached && qt_pixmap_cleanup_hook_64 && data->ref == 1) - qt_pixmap_cleanup_hook_64(cacheKey()); + if (data->is_cached && data->ref == 1) + QImagePixmapCleanupHooks::executePixmapHooks(this); #if defined(Q_WS_MAC) QMacPixmapData *macData = id == QPixmapData::MacClass ? static_cast(data) : 0; diff --git a/src/opengl/qgl.cpp b/src/opengl/qgl.cpp index edda6b6..8bb72d5 100644 --- a/src/opengl/qgl.cpp +++ b/src/opengl/qgl.cpp @@ -86,6 +86,7 @@ #include #include #include +#include #include "qcolormap.h" #include "qfile.h" #include "qlibrary.h" @@ -1407,15 +1408,17 @@ QGLTextureCache::QGLTextureCache() { Q_ASSERT(qt_gl_texture_cache == 0); qt_gl_texture_cache = this; - qt_pixmap_cleanup_hook_64 = cleanupHook; - qt_image_cleanup_hook_64 = cleanupHook; + + QImagePixmapCleanupHooks::instance()->addPixmapHook(pixmapCleanupHook); + QImagePixmapCleanupHooks::instance()->addImageHook(imageCleanupHook); } QGLTextureCache::~QGLTextureCache() { qt_gl_texture_cache = 0; - qt_pixmap_cleanup_hook_64 = 0; - qt_image_cleanup_hook_64 = 0; + + QImagePixmapCleanupHooks::instance()->removePixmapHook(pixmapCleanupHook); + QImagePixmapCleanupHooks::instance()->removeImageHook(imageCleanupHook); } void QGLTextureCache::insert(QGLContext* ctx, qint64 key, QGLTexture* texture, int cost) @@ -1471,11 +1474,23 @@ QGLTextureCache* QGLTextureCache::instance() a hook that removes textures from the cache when a pixmap/image is deref'ed */ -void QGLTextureCache::cleanupHook(qint64 cacheKey) +void QGLTextureCache::imageCleanupHook(qint64 cacheKey) +{ + // ### remove when the GL texture cache becomes thread-safe + if (qApp->thread() != QThread::currentThread()) + return; + QGLTexture *texture = instance()->getTexture(cacheKey); + if (texture && texture->clean) + instance()->remove(cacheKey); +} + + +void QGLTextureCache::pixmapCleanupHook(QPixmap* pixmap) { // ### remove when the GL texture cache becomes thread-safe if (qApp->thread() != QThread::currentThread()) return; + const qint64 cacheKey = pixmap->cacheKey(); QGLTexture *texture = instance()->getTexture(cacheKey); if (texture && texture->clean) instance()->remove(cacheKey); diff --git a/src/opengl/qgl_p.h b/src/opengl/qgl_p.h index 85dae0d..a83cc63 100644 --- a/src/opengl/qgl_p.h +++ b/src/opengl/qgl_p.h @@ -458,7 +458,8 @@ public: static QGLTextureCache *instance(); static void deleteIfEmpty(); - static void cleanupHook(qint64 cacheKey); + static void imageCleanupHook(qint64 cacheKey); + static void pixmapCleanupHook(QPixmap* pixmap); private: QCache m_cache; diff --git a/src/plugins/gfxdrivers/directfb/qdirectfbpaintengine.cpp b/src/plugins/gfxdrivers/directfb/qdirectfbpaintengine.cpp index b264ac0..2ed890b 100644 --- a/src/plugins/gfxdrivers/directfb/qdirectfbpaintengine.cpp +++ b/src/plugins/gfxdrivers/directfb/qdirectfbpaintengine.cpp @@ -53,6 +53,7 @@ #include #include #include +#include class SurfaceCache; class QDirectFBPaintEnginePrivate : public QRasterPaintEnginePrivate @@ -699,9 +700,7 @@ void QDirectFBPaintEngine::initImageCache(int size) { Q_ASSERT(size >= 0); imageCache.setMaxCost(size); - typedef void (*_qt_image_cleanup_hook_64)(qint64); - extern Q_GUI_EXPORT _qt_image_cleanup_hook_64 qt_image_cleanup_hook_64; - qt_image_cleanup_hook_64 = ::cachedImageCleanupHook; + QImagePixmapCleanupHooks::instance()->addImageHook(cachedImageCleanupHook); } #endif // QT_DIRECTFB_IMAGECACHE -- cgit v0.12 From 78f079016e0dd9b455d74c6a84cfbdb859fd1094 Mon Sep 17 00:00:00 2001 From: Tom Cooksey Date: Tue, 28 Jul 2009 11:35:59 +0200 Subject: Move uninit & readonly into a flags member of QX11PixmapData Also add 2 new flags and a new member to store any GL bound pixmap surface (GLXPixmap or EGLPixmapSurface). Reviewed-By: Samuel --- src/gui/image/qpixmap.cpp | 4 ++-- src/gui/image/qpixmap_x11.cpp | 23 +++++++++++------------ src/gui/image/qpixmap_x11_p.h | 12 ++++++++++-- src/gui/painting/qwindowsurface_x11.cpp | 4 ++-- 4 files changed, 25 insertions(+), 18 deletions(-) diff --git a/src/gui/image/qpixmap.cpp b/src/gui/image/qpixmap.cpp index 2674cac..82835d5 100644 --- a/src/gui/image/qpixmap.cpp +++ b/src/gui/image/qpixmap.cpp @@ -649,7 +649,7 @@ void QPixmap::resize_helper(const QSize &s) QX11PixmapData *x11Data = data->classId() == QPixmapData::X11Class ? static_cast(data) : 0; if (x11Data) { pm.x11SetScreen(x11Data->xinfo.screen()); - uninit = x11Data->uninit; + uninit = x11Data->flags & QX11PixmapData::Uninitialized; } #elif defined(Q_WS_MAC) QMacPixmapData *macData = data->classId() == QPixmapData::MacClass ? static_cast(data) : 0; @@ -1936,7 +1936,7 @@ void QPixmap::detach() #if defined(Q_WS_X11) if (data->classId() == QPixmapData::X11Class) { QX11PixmapData *d = static_cast(data); - d->uninit = false; + d->flags &= ~QX11PixmapData::Uninitialized; // reset the cache data if (d->hd2) { diff --git a/src/gui/image/qpixmap_x11.cpp b/src/gui/image/qpixmap_x11.cpp index 86cf515..be3d070 100644 --- a/src/gui/image/qpixmap_x11.cpp +++ b/src/gui/image/qpixmap_x11.cpp @@ -313,7 +313,7 @@ int Q_GUI_EXPORT qt_x11_preferred_pixmap_depth = 0; QX11PixmapData::QX11PixmapData(PixelType type) : QPixmapData(type, X11Class), hd(0), - uninit(true), read_only(false), x11_mask(0), picture(0), mask_picture(0), hd2(0), + flags(Uninitialized), x11_mask(0), picture(0), mask_picture(0), hd2(0), gl_surface(0), share_mode(QPixmap::ImplicitlyShared), pengine(0) { } @@ -1217,7 +1217,7 @@ void QX11PixmapData::release() XFreePixmap(xinfo.display(), hd2); hd2 = 0; } - if (!read_only) + if (!(flags & Readonly)) XFreePixmap(xinfo.display(), hd); hd = 0; } @@ -1876,7 +1876,7 @@ QPixmap QX11PixmapData::transformed(const QTransform &transform, } else { // color pixmap QPixmap pm; QX11PixmapData *x11Data = static_cast(pm.data); - x11Data->uninit = false; + x11Data->flags &= ~QX11PixmapData::Uninitialized; x11Data->xinfo = xinfo; x11Data->d = d; x11Data->w = w; @@ -2018,7 +2018,7 @@ QPixmap QPixmap::grabWindow(WId window, int x, int y, int w, int h) QPixmap pm(data); - data->uninit = false; + data->flags &= ~QX11PixmapData::Uninitialized; pm.x11SetScreen(scr); GC gc = XCreateGC(dpy, pm.handle(), 0, 0); @@ -2060,7 +2060,7 @@ QPaintEngine* QX11PixmapData::paintEngine() const { QX11PixmapData *that = const_cast(this); - if (read_only && share_mode == QPixmap::ImplicitlyShared) { + if ((flags & Readonly) && share_mode == QPixmap::ImplicitlyShared) { // if someone wants to draw onto us, copy the shared contents // and turn it into a fully fledged QPixmap ::Pixmap hd_copy = XCreatePixmap(X11->display, RootWindow(X11->display, xinfo.screen()), @@ -2082,7 +2082,7 @@ QPaintEngine* QX11PixmapData::paintEngine() const XFreeGC(X11->display, gc); } that->hd = hd_copy; - that->read_only = false; + that->flags &= ~QX11PixmapData::Readonly; } if (!that->pengine) @@ -2133,7 +2133,7 @@ void QX11PixmapData::copy(const QPixmapData *data, const QRect &rect) setSerialNumber(++qt_pixmap_serial); - uninit = false; + flags &= ~Uninitialized; xinfo = x11Data->xinfo; d = x11Data->d; w = rect.width(); @@ -2201,7 +2201,7 @@ void QX11PixmapData::convertToARGB32(bool preserveContents) return; // Q_ASSERT(count == 1); - if (read_only && share_mode == QPixmap::ExplicitlyShared) + if ((flags & Readonly) && share_mode == QPixmap::ExplicitlyShared) return; Pixmap pm = XCreatePixmap(X11->display, RootWindow(X11->display, xinfo.screen()), @@ -2211,10 +2211,10 @@ void QX11PixmapData::convertToARGB32(bool preserveContents) if (picture) { if (preserveContents) XRenderComposite(X11->display, PictOpSrc, picture, 0, p, 0, 0, 0, 0, 0, 0, w, h); - if (!read_only) + if (!(flags & Readonly)) XRenderFreePicture(X11->display, picture); } - if (hd && !read_only) + if (hd && !(flags & Readonly)) XFreePixmap(X11->display, hd); if (x11_mask) { XFreePixmap(X11->display, x11_mask); @@ -2252,9 +2252,8 @@ QPixmap QPixmap::fromX11Pixmap(Qt::HANDLE pixmap, QPixmap::ShareMode mode) QX11PixmapData *data = new QX11PixmapData(depth == 1 ? QPixmapData::BitmapType : QPixmapData::PixmapType); data->setSerialNumber(++qt_pixmap_serial); - data->read_only = true; + data->flags = QX11PixmapData::Readonly; data->share_mode = mode; - data->uninit = false; data->w = width; data->h = height; data->is_null = (width <= 0 || height <= 0); diff --git a/src/gui/image/qpixmap_x11_p.h b/src/gui/image/qpixmap_x11_p.h index 3de9a0f..835fea4 100644 --- a/src/gui/image/qpixmap_x11_p.h +++ b/src/gui/image/qpixmap_x11_p.h @@ -99,6 +99,7 @@ private: friend class QX11PaintEngine; friend class QX11WindowSurface; friend class QRasterWindowSurface; + friend class QGLContextPrivate; // Needs to access xinfo, gl_surface & flags void release(); @@ -108,14 +109,21 @@ private: Qt::HANDLE hd; - uint uninit : 1; - uint read_only : 1; + enum Flag { + NoFlags = 0x0, + Uninitialized = 0x1, + Readonly = 0x2, + InvertedWhenBoundToTexture = 0x4, + GlSurfaceCreatedWithAlpha = 0x8 + }; + uint flags; QX11Info xinfo; Qt::HANDLE x11_mask; Qt::HANDLE picture; Qt::HANDLE mask_picture; Qt::HANDLE hd2; // sorted in the default display depth + Qt::HANDLE gl_surface; #ifndef QT_NO_XRENDER void convertToARGB32(bool preserveContents = true); #endif diff --git a/src/gui/painting/qwindowsurface_x11.cpp b/src/gui/painting/qwindowsurface_x11.cpp index d8b0d9e..95f6ce3 100644 --- a/src/gui/painting/qwindowsurface_x11.cpp +++ b/src/gui/painting/qwindowsurface_x11.cpp @@ -154,7 +154,7 @@ void QX11WindowSurface::setGeometry(const QRect &rect) QX11PixmapData *oldData = static_cast(d_ptr->device.pixmapData()); Q_ASSERT(oldData); - if (!oldData->uninit && hasStaticContents()) { + if (!(oldData->flags & QX11PixmapData::Uninitialized) && hasStaticContents()) { // Copy the content of the old pixmap into the new one. QX11PixmapData *newData = new QX11PixmapData(QPixmapData::PixmapType); newData->resize(size.width(), size.height()); @@ -175,7 +175,7 @@ void QX11WindowSurface::setGeometry(const QRect &rect) dx, dy, qMin(boundingRect.width(), size.width()), qMin(boundingRect.height(), size.height()), dx, dy); XFreeGC(X11->display, tmpGc); - newData->uninit = false; + newData->flags &= ~QX11PixmapData::Uninitialized; d_ptr->device = QPixmap(newData); } else { -- cgit v0.12 From 65702aa6b44568946b8c3924a45b9362401d893c Mon Sep 17 00:00:00 2001 From: Tom Cooksey Date: Tue, 28 Jul 2009 15:57:36 +0200 Subject: Refactor texture_from_pixmap to not re-create the gl surface each bind Make a clear seperation between the GL texture and the GLX pixmap. A GLXPixmap is valid in any GL context and thus does not need to be re-created every time the pixmap has changed. Reviewed-By: Samuel --- src/gui/image/qpixmapdata_p.h | 1 + src/opengl/qgl.cpp | 24 ++++-- src/opengl/qgl_p.h | 11 ++- src/opengl/qgl_x11.cpp | 194 ++++++++++++++++++++++++++---------------- src/opengl/qgl_x11egl.cpp | 10 ++- 5 files changed, 152 insertions(+), 88 deletions(-) diff --git a/src/gui/image/qpixmapdata_p.h b/src/gui/image/qpixmapdata_p.h index 29dafaf..32b419e 100644 --- a/src/gui/image/qpixmapdata_p.h +++ b/src/gui/image/qpixmapdata_p.h @@ -116,6 +116,7 @@ private: friend class QPixmap; friend class QGLContextPrivate; friend class QX11PixmapData; + friend class QGLTextureCache; //Needs to check the reference count QAtomicInt ref; int detach_no; diff --git a/src/opengl/qgl.cpp b/src/opengl/qgl.cpp index 8bb72d5..a8d1797 100644 --- a/src/opengl/qgl.cpp +++ b/src/opengl/qgl.cpp @@ -1488,12 +1488,18 @@ void QGLTextureCache::imageCleanupHook(qint64 cacheKey) void QGLTextureCache::pixmapCleanupHook(QPixmap* pixmap) { // ### remove when the GL texture cache becomes thread-safe - if (qApp->thread() != QThread::currentThread()) - return; - const qint64 cacheKey = pixmap->cacheKey(); - QGLTexture *texture = instance()->getTexture(cacheKey); - if (texture && texture->clean) - instance()->remove(cacheKey); + if (qApp->thread() == QThread::currentThread()) { + const qint64 cacheKey = pixmap->cacheKey(); + QGLTexture *texture = instance()->getTexture(cacheKey); + if (texture && texture->clean) + instance()->remove(cacheKey); + } +#if defined(Q_WS_X11) + QPixmapData *pd = pixmap->data_ptr(); + // Only need to delete the gl surface if the pixmap is about to be deleted + if (pd->ref == 0) + QGLContextPrivate::destroyGlSurfaceForPixmap(pd); +#endif } void QGLTextureCache::deleteIfEmpty() @@ -2036,11 +2042,11 @@ QGLTexture *QGLContextPrivate::bindTexture(const QPixmap &pixmap, GLenum target, #if defined(Q_WS_X11) // Try to use texture_from_pixmap if (pd->classId() == QPixmapData::X11Class) { - QPixmap *thatPixmap = const_cast(&pixmap); - texture = bindTextureFromNativePixmap(thatPixmap, key, canInvert); + texture = bindTextureFromNativePixmap(pd, key, canInvert); if (texture) { texture->clean = clean; - boundPixmaps.insert(thatPixmap->data_ptr(), QPixmap(pixmap)); + texture->boundPixmap = pd; + boundPixmaps.insert(pd, QPixmap(pixmap)); } } #endif diff --git a/src/opengl/qgl_p.h b/src/opengl/qgl_p.h index a83cc63..f21ab93 100644 --- a/src/opengl/qgl_p.h +++ b/src/opengl/qgl_p.h @@ -241,7 +241,9 @@ public: quint32 gpm; int screen; QHash boundPixmaps; - QGLTexture *bindTextureFromNativePixmap(QPixmap *pm, const qint64 key, bool internal); + QGLTexture *bindTextureFromNativePixmap(QPixmapData*, const qint64 key, bool canInvert); + static void destroyGlSurfaceForPixmap(QPixmapData*); + static void unbindPixmapFromTexture(QPixmapData*); #endif #if defined(Q_WS_MAC) bool update; @@ -423,7 +425,8 @@ public: // is a current context - the context the pixmap was bound to a texture in. // Otherwise the release doesn't do anything and you get BadDrawable errors // when you come to delete the context. - deleteBoundPixmap(); + if (boundPixmap) + QGLContextPrivate::unbindPixmapFromTexture(boundPixmap); #endif glDeleteTextures(1, &id); if (switch_context && current) @@ -437,9 +440,9 @@ public: bool clean; bool yInverted; // NOTE: Y-Inverted textures are for internal use only! #if defined(Q_WS_X11) - Qt::HANDLE boundPixmap; - void deleteBoundPixmap(); // in qgl_x11.cpp/qgl_x11egl.cpp + QPixmapData* boundPixmap; #endif + }; class QGLTextureCache { diff --git a/src/opengl/qgl_x11.cpp b/src/opengl/qgl_x11.cpp index 6381bc2..34e9d38 100644 --- a/src/opengl/qgl_x11.cpp +++ b/src/opengl/qgl_x11.cpp @@ -1536,38 +1536,26 @@ void QGLExtensions::init() } } -#if !defined(glXBindTexImageEXT) +// Solaris defines glXBindTexImageEXT as part of the GL library +#if defined(GLX_VERSION_1_3) && !defined(Q_OS_HPUX) && !defined(glXBindTexImageEXT) typedef void (*qt_glXBindTexImageEXT)(Display*, GLXDrawable, int, const int*); -static qt_glXBindTexImageEXT glXBindTexImageEXT = 0; -#endif -#if !defined(glXReleaseTexImageEXT) typedef void (*qt_glXReleaseTexImageEXT)(Display*, GLXDrawable, int); +static qt_glXBindTexImageEXT glXBindTexImageEXT = 0; static qt_glXReleaseTexImageEXT glXReleaseTexImageEXT = 0; -#endif -static bool qt_resolved_texture_from_pixmap = false; -QGLTexture *QGLContextPrivate::bindTextureFromNativePixmap(QPixmap *pm, const qint64 key, bool canInvert) +bool qt_resolveTextureFromPixmap() { -#if !defined(Q_OS_LINUX) - return 0; -#else - Q_Q(QGLContext); - - if (pm->data_ptr()->classId() != QPixmapData::X11Class) - return 0; - QX11PixmapData *pixmapData = static_cast(pm->data_ptr()); - const QX11Info *x11Info = qt_x11Info(pm); - - - // Check to see if we have NPOT texture support - // TODO: Use GLX_TEXTURE_RECTANGLE_EXT texture target on systems without npot textures - if ( !(QGLExtensions::glExtensions & QGLExtensions::NPOTTextures) && - !(QGLFormat::openGLVersionFlags() & QGLFormat::OpenGL_Version_2_0)) - return 0; + static bool resolvedTextureFromPixmap = false; + if (!resolvedTextureFromPixmap) { + resolvedTextureFromPixmap = true; - if (!qt_resolved_texture_from_pixmap) { - qt_resolved_texture_from_pixmap = true; + // Check to see if we have NPOT texture support + if ( !(QGLExtensions::glExtensions & QGLExtensions::NPOTTextures) && + !(QGLFormat::openGLVersionFlags() & QGLFormat::OpenGL_Version_2_0)) + { + return false; // Can't use TFP without NPOT + } QString glxExt = QLatin1String(glXGetClientString(QX11Info::display(), GLX_EXTENSIONS)); if (glxExt.contains(QLatin1String("GLX_EXT_texture_from_pixmap"))) { @@ -1589,81 +1577,141 @@ QGLTexture *QGLContextPrivate::bindTextureFromNativePixmap(QPixmap *pm, const qi } } - if (!glXBindTexImageEXT) - return 0; + return glXBindTexImageEXT && glXReleaseTexImageEXT; +} +#endif //defined(GLX_VERSION_1_3) && !defined(Q_OS_HPUX) && !defined(glXBindTexImageEXT) + +QGLTexture *QGLContextPrivate::bindTextureFromNativePixmap(QPixmapData *pmd, const qint64 key, bool canInvert) +{ #if !defined(GLX_VERSION_1_3) || defined(Q_OS_HPUX) return 0; #else - GLXFBConfig *configList = 0; - GLXFBConfig glxPixmapConfig; - int configCount = 0; - bool hasAlpha = pixmapData->hasAlphaChannel(); - - int configAttribs[] = { - hasAlpha ? GLX_BIND_TO_TEXTURE_RGBA_EXT : GLX_BIND_TO_TEXTURE_RGB_EXT, True, - GLX_DRAWABLE_TYPE, GLX_PIXMAP_BIT, - GLX_BIND_TO_TEXTURE_TARGETS_EXT, GLX_TEXTURE_2D_BIT_EXT, - // QGLContext::bindTexture() can't return an inverted texture, but QPainter::drawPixmap() can: - GLX_Y_INVERTED_EXT, canInvert ? GLX_DONT_CARE : False, - XNone -// GLX_BIND_TO_MIPMAP_TEXTURE_EXT, False, -// GLX_BIND_TO_TEXTURE_TARGETS_EXT, GLX_TEXTURE_1D_BIT_EXT or GLX_TEXTURE_2D_BIT_EXT or GLX_TEXTURE_RECTANGLE_BIT_EXT - }; - configList = glXChooseFBConfig(x11Info->display(), x11Info->screen(), configAttribs, &configCount); - if (!configList) - return 0; - glxPixmapConfig = configList[0]; - XFree(configList); - - GLXPixmap glxPixmap; - int pixmapAttribs[] = { - GLX_TEXTURE_FORMAT_EXT, hasAlpha ? GLX_TEXTURE_FORMAT_RGBA_EXT : GLX_TEXTURE_FORMAT_RGB_EXT, - GLX_TEXTURE_TARGET_EXT, GLX_TEXTURE_2D_EXT, - GLX_MIPMAP_TEXTURE_EXT, False, - XNone -// GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_FORMAT_RGBA_EXT or GLX_TEXTURE_FORMAT_RGB_EXT or GLX_TEXTURE_FORMAT_NONE_EXT, -// GLX_TEXTURE_TARGET_EXT, GLX_TEXTURE_2D_EXT or GLX_TEXTURE_RECTANGLE_EXT, -// GLX_MIPMAP_TEXTURE_EXT, True or False, - }; + Q_Q(QGLContext); - // Wrap the X Pixmap into a GLXPixmap: - glxPixmap = glXCreatePixmap(x11Info->display(), glxPixmapConfig, pixmapData->handle(), pixmapAttribs); + Q_ASSERT(pmd->classId() == QPixmapData::X11Class); - if (!glxPixmap) +#if !defined(glXBindTexImageEXT) + if (!qt_resolveTextureFromPixmap()) return 0; +#endif - int yInverted; - glXGetFBConfigAttrib(x11Info->display(), glxPixmapConfig, GLX_Y_INVERTED_EXT, &yInverted); + QX11PixmapData *pixmapData = static_cast(pmd); + const QX11Info &x11Info = pixmapData->xinfo; + + // Store the configs (Can be static because configs aren't dependent on current context) + static GLXFBConfig glxRGBPixmapConfig = 0; + static bool RGBConfigInverted = false; + static GLXFBConfig glxRGBAPixmapConfig = 0; + static bool RGBAConfigInverted = false; + + bool hasAlpha = pixmapData->hasAlphaChannel(); + + // Check to see if we need a config + if ( (hasAlpha && !glxRGBAPixmapConfig) || (!hasAlpha && !glxRGBPixmapConfig) ) { + GLXFBConfig *configList = 0; + int configCount = 0; + + int configAttribs[] = { + hasAlpha ? GLX_BIND_TO_TEXTURE_RGBA_EXT : GLX_BIND_TO_TEXTURE_RGB_EXT, True, + GLX_DRAWABLE_TYPE, GLX_PIXMAP_BIT, + GLX_BIND_TO_TEXTURE_TARGETS_EXT, GLX_TEXTURE_2D_BIT_EXT, + // QGLContext::bindTexture() can't return an inverted texture, but QPainter::drawPixmap() can: + GLX_Y_INVERTED_EXT, canInvert ? GLX_DONT_CARE : False, + XNone + }; + configList = glXChooseFBConfig(x11Info.display(), x11Info.screen(), configAttribs, &configCount); + if (!configList) + return 0; + + int yInv; + glXGetFBConfigAttrib(x11Info.display(), configList[0], GLX_Y_INVERTED_EXT, &yInv); + + if (hasAlpha) { + glxRGBAPixmapConfig = configList[0]; + RGBAConfigInverted = yInv; + } + else { + glxRGBPixmapConfig = configList[0]; + RGBConfigInverted = yInv; + } + + XFree(configList); + } + + // Check to see if the surface is still valid + if (pixmapData->gl_surface && + hasAlpha != (pixmapData->flags & QX11PixmapData::GlSurfaceCreatedWithAlpha)) + { + // Surface is invalid! + destroyGlSurfaceForPixmap(pixmapData); + } + + // Check to see if we need a surface + if (!pixmapData->gl_surface) { + GLXPixmap glxPixmap; + int pixmapAttribs[] = { + GLX_TEXTURE_FORMAT_EXT, hasAlpha ? GLX_TEXTURE_FORMAT_RGBA_EXT : GLX_TEXTURE_FORMAT_RGB_EXT, + GLX_TEXTURE_TARGET_EXT, GLX_TEXTURE_2D_EXT, + GLX_MIPMAP_TEXTURE_EXT, False, // Maybe needs to be don't care + XNone + }; + + // Wrap the X Pixmap into a GLXPixmap: + glxPixmap = glXCreatePixmap(x11Info.display(), + hasAlpha ? glxRGBAPixmapConfig : glxRGBPixmapConfig, + pixmapData->handle(), pixmapAttribs); + + if (!glxPixmap) + return 0; + + pixmapData->gl_surface = (Qt::HANDLE)glxPixmap; + + // Make sure the cleanup hook gets called so we can delete the glx pixmap + pixmapData->is_cached = true; + } GLuint textureId; glGenTextures(1, &textureId); glBindTexture(GL_TEXTURE_2D, textureId); - glXBindTexImageEXT(x11Info->display(), glxPixmap, GLX_FRONT_LEFT_EXT, 0); + glXBindTexImageEXT(x11Info.display(), (GLXPixmap)pixmapData->gl_surface, GLX_FRONT_LEFT_EXT, 0); glBindTexture(GL_TEXTURE_2D, textureId); - QGLTexture *texture = new QGLTexture(q, textureId, GL_TEXTURE_2D, canInvert, yInverted); - texture->boundPixmap = glxPixmap; + QGLTexture *texture = new QGLTexture(q, textureId, GL_TEXTURE_2D, canInvert, false); + texture->yInverted = (hasAlpha && RGBAConfigInverted) || (!hasAlpha && RGBConfigInverted); + if (texture->yInverted) + pixmapData->flags |= QX11PixmapData::InvertedWhenBoundToTexture; // We assume the cost of bound pixmaps is zero QGLTextureCache::instance()->insert(q, key, texture, 0); return texture; #endif //!defined(GLX_VERSION_1_3) || defined(Q_OS_HPUX) -#endif //!defined(Q_OS_LINUX } -void QGLTexture::deleteBoundPixmap() + +void QGLContextPrivate::destroyGlSurfaceForPixmap(QPixmapData* pmd) { -#if defined(GLX_VERSION_1_3) && !defined(Q_OS_HPUX) && defined(Q_OS_LINUX) - if (boundPixmap) { - glXReleaseTexImageEXT(QX11Info::display(), boundPixmap, GLX_FRONT_LEFT_EXT); - glXDestroyPixmap(QX11Info::display(), boundPixmap); - boundPixmap = 0; +#if defined(GLX_VERSION_1_3) && !defined(Q_OS_HPUX) + Q_ASSERT(pmd->classId() == QPixmapData::X11Class); + QX11PixmapData *pixmapData = static_cast(pmd); + if (pixmapData->gl_surface) { + glXDestroyPixmap(QX11Info::display(), (GLXPixmap)pixmapData->gl_surface); + pixmapData->gl_surface = 0; } #endif } +void QGLContextPrivate::unbindPixmapFromTexture(QPixmapData* pmd) +{ +#if defined(GLX_VERSION_1_3) && !defined(Q_OS_HPUX) + Q_ASSERT(pmd->classId() == QPixmapData::X11Class); + Q_ASSERT(QGLContext::currentContext()); + QX11PixmapData *pixmapData = static_cast(pmd); + if (pixmapData->gl_surface) + glXReleaseTexImageEXT(QX11Info::display(), (GLXPixmap)pixmapData->gl_surface, GLX_FRONT_LEFT_EXT); +#endif +} QT_END_NAMESPACE diff --git a/src/opengl/qgl_x11egl.cpp b/src/opengl/qgl_x11egl.cpp index c6904fe..6b90a4f 100644 --- a/src/opengl/qgl_x11egl.cpp +++ b/src/opengl/qgl_x11egl.cpp @@ -486,13 +486,19 @@ void QGLWidgetPrivate::recreateEglSurface(bool force) } } -QGLTexture *QGLContextPrivate::bindTextureFromNativePixmap(QPixmap *pm, const qint64 key, bool canInvert) + +QGLTexture *QGLContextPrivate::bindTextureFromNativePixmap(QPixmapData*, const qint64 key, bool canInvert) { // TODO return 0; } -void QGLTexture::deleteBoundPixmap() +void QGLContextPrivate::destroyGlSurfaceForPixmap(QPixmapData*) +{ + //TODO +} + +void QGLContextPrivate::unbindPixmapFromTexture(QPixmapData*) { //TODO } -- cgit v0.12 From fd0cd53a24459e0314360d70d8499b491c06a8e4 Mon Sep 17 00:00:00 2001 From: Tom Cooksey Date: Fri, 24 Jul 2009 18:44:45 +0200 Subject: Add a getter to QEglContext for the EGL extension string Reviewed-By: Rhys Weatherley --- src/gui/egl/qegl.cpp | 11 +++++++++++ src/gui/egl/qegl_p.h | 3 +++ 2 files changed, 14 insertions(+) diff --git a/src/gui/egl/qegl.cpp b/src/gui/egl/qegl.cpp index 89d9d1b..ebdac9a 100644 --- a/src/gui/egl/qegl.cpp +++ b/src/gui/egl/qegl.cpp @@ -400,4 +400,15 @@ void QEglContext::dumpAllConfigs() delete [] configs; } +QString QEglContext::extensions() +{ + const char* exts = eglQueryString(dpy, EGL_EXTENSIONS); + return QString(QLatin1String(exts)); +} + +bool QEglContext::hasExtension(const char* extensionName) +{ + return extensions().contains(QLatin1String(extensionName)); +} + QT_END_NAMESPACE diff --git a/src/gui/egl/qegl_p.h b/src/gui/egl/qegl_p.h index ddf7d27..3ae1489 100644 --- a/src/gui/egl/qegl_p.h +++ b/src/gui/egl/qegl_p.h @@ -122,6 +122,9 @@ public: void dumpAllConfigs(); + QString extensions(); + bool hasExtension(const char* extensionName); + private: QEgl::API apiType; EGLDisplay dpy; -- cgit v0.12 From e71c1a89f4747c8f94e19113d1fcbc3c51450f3e Mon Sep 17 00:00:00 2001 From: Tom Cooksey Date: Fri, 24 Jul 2009 18:46:29 +0200 Subject: Support EGL_NOKIA_texture_from_pixmap on Harmattan Added QGLContextPrivate::bindTextureFromNativePixmap() implementation for X11/EGL. --- src/opengl/qgl_x11egl.cpp | 171 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 163 insertions(+), 8 deletions(-) diff --git a/src/opengl/qgl_x11egl.cpp b/src/opengl/qgl_x11egl.cpp index 6b90a4f..5ab3647 100644 --- a/src/opengl/qgl_x11egl.cpp +++ b/src/opengl/qgl_x11egl.cpp @@ -41,15 +41,16 @@ #include "qgl.h" #include +#include #include #include #include "qgl_egl_p.h" #include "qcolormap.h" +#include QT_BEGIN_NAMESPACE - bool QGLFormat::hasOpenGL() { return true; @@ -487,20 +488,174 @@ void QGLWidgetPrivate::recreateEglSurface(bool force) } -QGLTexture *QGLContextPrivate::bindTextureFromNativePixmap(QPixmapData*, const qint64 key, bool canInvert) +QGLTexture *QGLContextPrivate::bindTextureFromNativePixmap(QPixmapData* pd, const qint64 key, bool canInvert) { - // TODO - return 0; + Q_Q(QGLContext); + + Q_ASSERT(pd->classId() == QPixmapData::X11Class); + + static bool checkedForTFP = false; + static bool haveTFP = false; + + if (!checkedForTFP) { + // Check for texture_from_pixmap egl extension + checkedForTFP = true; + if (eglContext->hasExtension("EGL_NOKIA_texture_from_pixmap") || + eglContext->hasExtension("EGL_EXT_texture_from_pixmap")) + { + qDebug("Found texture_from_pixmap EGL extension!"); + haveTFP = true; + } + } + + if (!haveTFP) + return 0; + + QX11PixmapData *pixmapData = static_cast(pd); + + bool hasAlpha = pixmapData->hasAlphaChannel(); + + // Check to see if the surface is still valid + if (pixmapData->gl_surface && + hasAlpha != (pixmapData->flags & QX11PixmapData::GlSurfaceCreatedWithAlpha)) + { + // Surface is invalid! + destroyGlSurfaceForPixmap(pixmapData); + } + + EGLint pixmapAttribs[] = { + EGL_TEXTURE_TARGET, EGL_TEXTURE_2D, + EGL_TEXTURE_FORMAT, hasAlpha ? EGL_TEXTURE_RGBA : EGL_TEXTURE_RGB, + EGL_NONE + }; + Q_ASSERT(sizeof(Qt::HANDLE) >= sizeof(EGLSurface)); // Just to make totally sure! + if (pixmapData->gl_surface == 0) + pixmapData->gl_surface = (Qt::HANDLE)EGL_NO_SURFACE; + EGLSurface pixmapSurface = (EGLSurface)pixmapData->gl_surface; + static EGLConfig pixmapRGBConfig = 0; + static EGLConfig pixmapRGBAConfig = 0; + + // Check to see if we need to find a config + if ((hasAlpha && !pixmapRGBAConfig) || (!hasAlpha && !pixmapRGBConfig) ) { + const EGLint configAttribs[] = { + EGL_SURFACE_TYPE, EGL_PIXMAP_BIT, + EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT, + EGL_DEPTH_SIZE, 0, + hasAlpha ? EGL_BIND_TO_TEXTURE_RGBA : EGL_BIND_TO_TEXTURE_RGB, EGL_TRUE, + EGL_NONE + }; + + EGLint configCount = 0; + eglChooseConfig(eglContext->display(), configAttribs, 0, 256, &configCount); + if (configCount == 0) { + haveTFP = false; + qWarning("bindTextureFromNativePixmap() - Couldn't find a suitable config"); + return 0; + } + + EGLConfig *configList = new EGLConfig[configCount]; + eglChooseConfig(eglContext->display(), configAttribs, configList, configCount, &configCount); + Q_ASSERT(configCount); + + // Try to create a pixmap surface for each config until one works + for (int i = 0; i < configCount; ++i) { + pixmapSurface = eglCreatePixmapSurface(eglContext->display(), configList[i], + (EGLNativePixmapType) pixmapData->handle(), + pixmapAttribs); + if (pixmapSurface != EGL_NO_SURFACE) { + // Got one! + qDebug() << "Found an" << (hasAlpha ? "ARGB" : "RGB") + << "config (" << int(configList[i]) << ") to create a pixmap surface"; + if (hasAlpha) + pixmapRGBAConfig = configList[i]; + else + pixmapRGBConfig = configList[i]; + pixmapData->gl_surface = (Qt::HANDLE)pixmapSurface; + break; + } + } + delete configList; + + if ((hasAlpha && !pixmapRGBAConfig) || (!hasAlpha && !pixmapRGBConfig) ) { + qDebug("Couldn't create a pixmap surface with any of the provided configs"); + haveTFP = false; + return 0; + } + } + + if (pixmapSurface == EGL_NO_SURFACE) { + pixmapSurface = eglCreatePixmapSurface(eglContext->display(), + hasAlpha? pixmapRGBAConfig : pixmapRGBConfig, + (EGLNativePixmapType) pixmapData->handle(), + pixmapAttribs); + if (pixmapSurface == EGL_NO_SURFACE) { + qWarning("Failed to create a pixmap surface using config %d", + (int)(hasAlpha? pixmapRGBAConfig : pixmapRGBConfig)); + haveTFP = false; + return 0; + } + pixmapData->gl_surface = (Qt::HANDLE)pixmapSurface; + } + + // Make sure the cleanup hook gets called so we can delete the glx pixmap + pixmapData->is_cached = true; + Q_ASSERT(pixmapData->gl_surface); + + GLuint textureId; + glGenTextures(1, &textureId); + glEnable(GL_TEXTURE_2D); + glBindTexture(GL_TEXTURE_2D, textureId); + + // bind the egl pixmap surface to a texture + EGLBoolean success; + success = eglBindTexImage(eglContext->display(), pixmapSurface, EGL_BACK_BUFFER); + if (success == EGL_FALSE) { + qWarning() << "eglBindTexImage() failed:" << eglContext->errorString(eglGetError()); + eglDestroySurface(eglContext->display(), pixmapSurface); + pixmapData->gl_surface = (Qt::HANDLE)EGL_NO_SURFACE; + haveTFP = false; + return 0; + } + + QGLTexture *texture = new QGLTexture(q, textureId, GL_TEXTURE_2D, canInvert, true); + pixmapData->flags |= QX11PixmapData::InvertedWhenBoundToTexture; + + // We assume the cost of bound pixmaps is zero + QGLTextureCache::instance()->insert(q, key, texture, 0); + + glBindTexture(GL_TEXTURE_2D, textureId); + return texture; } -void QGLContextPrivate::destroyGlSurfaceForPixmap(QPixmapData*) +void QGLContextPrivate::destroyGlSurfaceForPixmap(QPixmapData* pmd) { - //TODO + Q_ASSERT(pmd->classId() == QPixmapData::X11Class); + QX11PixmapData *pixmapData = static_cast(pmd); + if (pixmapData->gl_surface) { + EGLBoolean success; + success = eglDestroySurface(QEglContext::defaultDisplay(0), (EGLSurface)pixmapData->gl_surface); + if (success == EGL_FALSE) { + qWarning() << "destroyGlSurfaceForPixmap() - Error deleting surface: " + << QEglContext::errorString(eglGetError()); + } + pixmapData->gl_surface = 0; + } } -void QGLContextPrivate::unbindPixmapFromTexture(QPixmapData*) +void QGLContextPrivate::unbindPixmapFromTexture(QPixmapData* pmd) { - //TODO + Q_ASSERT(pmd->classId() == QPixmapData::X11Class); + QX11PixmapData *pixmapData = static_cast(pmd); + if (pixmapData->gl_surface) { + EGLBoolean success; + success = eglReleaseTexImage(QEglContext::defaultDisplay(0), + (EGLSurface)pixmapData->gl_surface, + EGL_BACK_BUFFER); + if (success == EGL_FALSE) { + qWarning() << "unbindPixmapFromTexture() - Unable to release bound texture: " + << QEglContext::errorString(eglGetError()); + } + } } QT_END_NAMESPACE -- cgit v0.12 From 0ff4c453bf3d549e8344ab18f643f61a8b6174ef Mon Sep 17 00:00:00 2001 From: Tom Cooksey Date: Wed, 29 Jul 2009 14:50:06 +0200 Subject: Fix build on Solaris x86 with old Mesa glx headers --- src/opengl/qgl_x11.cpp | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/opengl/qgl_x11.cpp b/src/opengl/qgl_x11.cpp index 34e9d38..642c7c1 100644 --- a/src/opengl/qgl_x11.cpp +++ b/src/opengl/qgl_x11.cpp @@ -58,11 +58,16 @@ #include #endif +// We always define GLX_EXT_texture_from_pixmap ourselves because +// we can't trust system headers to do it properly +#define GLX_EXT_texture_from_pixmap 1 + #define INT8 dummy_INT8 #define INT32 dummy_INT32 #include #undef INT8 #undef INT32 + #include #include #include @@ -82,7 +87,7 @@ extern const QX11Info *qt_x11Info(const QPaintDevice *pd); #define GLX_SAMPLES_ARB 100001 #endif -#ifndef GLX_EXT_texture_from_pixmap +#ifndef GLX_TEXTURE_2D_BIT_EXT #define GLX_TEXTURE_2D_BIT_EXT 0x00000002 #define GLX_TEXTURE_RECTANGLE_BIT_EXT 0x00000004 #define GLX_BIND_TO_TEXTURE_RGB_EXT 0x20D0 @@ -1537,7 +1542,7 @@ void QGLExtensions::init() } // Solaris defines glXBindTexImageEXT as part of the GL library -#if defined(GLX_VERSION_1_3) && !defined(Q_OS_HPUX) && !defined(glXBindTexImageEXT) +#if defined(GLX_VERSION_1_3) && !defined(Q_OS_HPUX) typedef void (*qt_glXBindTexImageEXT)(Display*, GLXDrawable, int, const int*); typedef void (*qt_glXReleaseTexImageEXT)(Display*, GLXDrawable, int); static qt_glXBindTexImageEXT glXBindTexImageEXT = 0; @@ -1579,7 +1584,7 @@ bool qt_resolveTextureFromPixmap() return glXBindTexImageEXT && glXReleaseTexImageEXT; } -#endif //defined(GLX_VERSION_1_3) && !defined(Q_OS_HPUX) && !defined(glXBindTexImageEXT) +#endif //defined(GLX_VERSION_1_3) && !defined(Q_OS_HPUX) QGLTexture *QGLContextPrivate::bindTextureFromNativePixmap(QPixmapData *pmd, const qint64 key, bool canInvert) @@ -1591,10 +1596,8 @@ QGLTexture *QGLContextPrivate::bindTextureFromNativePixmap(QPixmapData *pmd, con Q_ASSERT(pmd->classId() == QPixmapData::X11Class); -#if !defined(glXBindTexImageEXT) if (!qt_resolveTextureFromPixmap()) return 0; -#endif QX11PixmapData *pixmapData = static_cast(pmd); const QX11Info &x11Info = pixmapData->xinfo; -- cgit v0.12 From d09fa4a816c6b9ccf306b7e1a887c4a4b1dc2f4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Morten=20S=C3=B8rvig?= Date: Thu, 30 Jul 2009 09:25:10 +0200 Subject: Start implementing Mac accessibility for cocoa. Rather than having this stuck in a branch somewhere I'm going to implement it incrementally in main. It's going to be a long haul before it's done. This commit implements: - accessibilityIsIgnored() - Accessibility role translation --- src/gui/accessible/accessible.pri | 3 +- src/gui/accessible/qaccessible_mac_cocoa.mm | 234 ++++++++++++++++++++++++++++ 2 files changed, 236 insertions(+), 1 deletion(-) diff --git a/src/gui/accessible/accessible.pri b/src/gui/accessible/accessible.pri index 76b6687..ad2fb4c 100644 --- a/src/gui/accessible/accessible.pri +++ b/src/gui/accessible/accessible.pri @@ -14,7 +14,8 @@ contains(QT_CONFIG, accessibility) { mac:!embedded { HEADERS += accessible/qaccessible_mac_p.h - OBJECTIVE_SOURCES += accessible/qaccessible_mac.mm + OBJECTIVE_SOURCES += accessible/qaccessible_mac.mm \ + accessible/qaccessible_mac_cocoa.mm } else:win32 { SOURCES += accessible/qaccessible_win.cpp } else { diff --git a/src/gui/accessible/qaccessible_mac_cocoa.mm b/src/gui/accessible/qaccessible_mac_cocoa.mm index e69de29..1cb2ffa 100644 --- a/src/gui/accessible/qaccessible_mac_cocoa.mm +++ b/src/gui/accessible/qaccessible_mac_cocoa.mm @@ -0,0 +1,234 @@ + +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtGui module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "qaccessible.h" +#include "qaccessible_mac_p.h" +#include "qdebug.h" +#include "qtabwidget.h" + +#include +#include +#include + + +#ifndef QT_NO_ACCESSIBILITY + +#ifdef QT_MAC_USE_COCOA + +QT_BEGIN_NAMESPACE + +//#define MAC_ACCESSIBILTY_DEVELOPER_MODE + +#ifdef MAC_ACCESSIBILTY_DEVELOPER_MODE +#define MAC_ACCESSIBILTY_DEBUG qDebug +#else +#define MAC_ACCESSIBILTY_DEBUG if (0) qDebug +#endif + +typedef QMap QMacAccessibiltyRoleMap; +Q_GLOBAL_STATIC(QMacAccessibiltyRoleMap, qMacAccessibiltyRoleMap); + +static QAInterface interfaceForView(QT_MANGLE_NAMESPACE(QCocoaView) *view) +{ + return QAInterface(QAccessible::queryAccessibleInterface([view qt_qwidget])); +} + +/* + Set up mappings from Qt accessibilty roles to Mac accessibilty roles. +*/ +static void populateRoleMap() +{ + QMacAccessibiltyRoleMap &roleMap = *qMacAccessibiltyRoleMap(); + roleMap[QAccessible::MenuItem] = NSAccessibilityMenuItemRole; + roleMap[QAccessible::MenuBar] = NSAccessibilityMenuBarRole; + roleMap[QAccessible::ScrollBar] = NSAccessibilityScrollBarRole; + roleMap[QAccessible::Grip] = NSAccessibilityGrowAreaRole; + roleMap[QAccessible::Window] = NSAccessibilityWindowRole; + roleMap[QAccessible::Dialog] = NSAccessibilityWindowRole; + roleMap[QAccessible::AlertMessage] = NSAccessibilityWindowRole; + roleMap[QAccessible::ToolTip] = NSAccessibilityWindowRole; + roleMap[QAccessible::HelpBalloon] = NSAccessibilityWindowRole; + roleMap[QAccessible::PopupMenu] = NSAccessibilityMenuRole; + roleMap[QAccessible::Application] = NSAccessibilityApplicationRole; + roleMap[QAccessible::Pane] = NSAccessibilityGroupRole; + roleMap[QAccessible::Grouping] = NSAccessibilityGroupRole; + roleMap[QAccessible::Separator] = NSAccessibilitySplitterRole; + roleMap[QAccessible::ToolBar] = NSAccessibilityToolbarRole; + roleMap[QAccessible::PageTab] = NSAccessibilityRadioButtonRole; + roleMap[QAccessible::ButtonMenu] = NSAccessibilityMenuButtonRole; + roleMap[QAccessible::ButtonDropDown] = NSAccessibilityPopUpButtonRole; + roleMap[QAccessible::SpinBox] = NSAccessibilityIncrementorRole; + roleMap[QAccessible::Slider] = NSAccessibilitySliderRole; + roleMap[QAccessible::ProgressBar] = NSAccessibilityProgressIndicatorRole; + roleMap[QAccessible::ComboBox] = NSAccessibilityPopUpButtonRole; + roleMap[QAccessible::RadioButton] = NSAccessibilityRadioButtonRole; + roleMap[QAccessible::CheckBox] = NSAccessibilityCheckBoxRole; + roleMap[QAccessible::StaticText] = NSAccessibilityStaticTextRole; + roleMap[QAccessible::Table] = NSAccessibilityTableRole; + roleMap[QAccessible::StatusBar] = NSAccessibilityStaticTextRole; + roleMap[QAccessible::Column] = NSAccessibilityColumnRole; + roleMap[QAccessible::ColumnHeader] = NSAccessibilityColumnRole; + roleMap[QAccessible::Row] = NSAccessibilityRowRole; + roleMap[QAccessible::RowHeader] = NSAccessibilityRowRole; + roleMap[QAccessible::Cell] = NSAccessibilityTextFieldRole; + roleMap[QAccessible::PushButton] = NSAccessibilityButtonRole; + roleMap[QAccessible::EditableText] = NSAccessibilityTextFieldRole; + roleMap[QAccessible::Link] = NSAccessibilityTextFieldRole; + roleMap[QAccessible::Indicator] = NSAccessibilityValueIndicatorRole; + roleMap[QAccessible::Splitter] = NSAccessibilitySplitGroupRole; + roleMap[QAccessible::List] = NSAccessibilityListRole; + roleMap[QAccessible::ListItem] = NSAccessibilityStaticTextRole; + roleMap[QAccessible::Cell] = NSAccessibilityStaticTextRole; +} + +/* + Returns a Mac accessibility role for the given interface, or + NSAccessibilityUnknownRole if no role mapping is found. +*/ +static NSString *macRoleForInterface(QAInterface interface) +{ + const QAccessible::Role qtRole = interface.role(); + QMacAccessibiltyRoleMap &roleMap = *qMacAccessibiltyRoleMap(); + + if (roleMap.isEmpty()) + populateRoleMap(); + + MAC_ACCESSIBILTY_DEBUG() << "role for" << interface.object() << "interface role" << hex << qtRole; + + if (roleMap.contains(qtRole)) { + MAC_ACCESSIBILTY_DEBUG() << "return" << roleMap[qtRole]; + return roleMap[qtRole]; + } + + MAC_ACCESSIBILTY_DEBUG() << "return NSAccessibilityUnknownRole"; + return NSAccessibilityUnknownRole; +} + +/* + Is the interface a QTabBar embedded in a QTabWidget? + (as opposed to a stand-alone tab bar) +*/ +static bool isEmbeddedTabBar(const QAInterface &interface) +{ + QObject *object = interface.object(); + if (interface.role() == QAccessible::PageTabList && object) + return (qobject_cast(object->parent())); + + return false; +} + +static bool isInterfaceIgnored(QAInterface interface) +{ + // Mac accessibility does not have an attribute that corresponds to the + // Invisible/Offscreen state. Use the ignore facility to disable them. + const QAccessible::State state = interface.state(); + if (state & QAccessible::Invisible || + state & QAccessible::Offscreen ) + return false; + + // Hide QTabBars that has a QTabWidget parent (the QTabWidget handles the accessibility) + if (isEmbeddedTabBar(interface)) + return false; + + if (QObject * const object = interface.object()) { + const QString className = QLatin1String(object->metaObject()->className()); + + // Prevent VoiceOver from focusing on tool tips by ignoring those + // interfaces. Shifting VoiceOver focus to the tool tip is confusing + // and the contents of the tool tip is avalible through the description + // attribute anyway. + if (className == QLatin1String("QTipLabel")) + return false; + } + + // Hide interfaces with an unknown role. When developing it's often useful to disable + // this check to see all interfaces in the hierarchy. +#ifndef MAC_ACCESSIBILTY_DEVELOPER_MODE + return [macRoleForInterface(interface) isEqualToString: NSAccessibilityUnknownRole]; +#else + return NO; +#endif +} + +QT_END_NAMESPACE + +@implementation QT_MANGLE_NAMESPACE(QCocoaView) (Accessibility) + +- (BOOL)accessibilityIsIgnored +{ + QAInterface interface = interfaceForView(self); + return isInterfaceIgnored(interface); +} + +- (NSArray *)accessibilityAttributeNames +{ + QAInterface interface = interfaceForView(self); + + static NSArray *attributes = nil; + if (attributes == nil) { + attributes = [super accessibilityAttributeNames]; + + } + return attributes; +} + +- (id)accessibilityAttributeValue:(NSString *)attribute +{ + MAC_ACCESSIBILTY_DEBUG() << "accessibilityAttributeValue" << self << QCFString::toQString(reinterpret_cast(attribute)); + + QAInterface interface = interfaceForView(self); + + // Switch on the attribute name and call the appropriate handler function. + // Pass the call on to the NSView class for attributes we don't handle. + if ([attribute isEqualToString:@"AXRole"]) { + return macRoleForInterface(interface); + } else { + return [super accessibilityAttributeValue:attribute]; + } +} + +@end + +#endif // QT_MAC_USE_COCOA + +#endif // QT_NO_ACCESSIBILITY + -- cgit v0.12 From 9523b27be4fe00870d19c4ff4caa2d78dcf520e6 Mon Sep 17 00:00:00 2001 From: Olivier Goffart Date: Thu, 30 Jul 2009 10:11:57 +0200 Subject: parse Q_INVOKABLE explicit constructors regression introduced in e43eae35 because the code of maybeParseFunction and parseFunction is not exactly the same. Reviewed-by: Kent Hansen --- src/tools/moc/moc.cpp | 2 +- tests/auto/moc/tst_moc.cpp | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/src/tools/moc/moc.cpp b/src/tools/moc/moc.cpp index 797595f..0ba7d53 100644 --- a/src/tools/moc/moc.cpp +++ b/src/tools/moc/moc.cpp @@ -429,7 +429,7 @@ bool Moc::parseMaybeFunction(const ClassDef *cdef, FunctionDef *def) { def->isVirtual = false; //skip modifiers and attributes - while (test(INLINE) || test(STATIC) || + while (test(EXPLICIT) || test(INLINE) || test(STATIC) || (test(VIRTUAL) && (def->isVirtual = true)) //mark as virtual || testFunctionAttribute(def)) {} bool tilde = test(TILDE); diff --git a/tests/auto/moc/tst_moc.cpp b/tests/auto/moc/tst_moc.cpp index d66791f..488f068 100644 --- a/tests/auto/moc/tst_moc.cpp +++ b/tests/auto/moc/tst_moc.cpp @@ -1157,6 +1157,13 @@ void tst_Moc::constructors() QObject *o3 = mo->newInstance(Q_ARG(QString, str)); QVERIFY(o3 != 0); QCOMPARE(qobject_cast(o3)->m_str, str); + + { + //explicit constructor + QObject *o = QObject::staticMetaObject.newInstance(); + QVERIFY(o); + delete o; + } } #include "task234909.h" -- cgit v0.12 From 776c4a5b8035b87d011b8e431c3d9e970ad98cd9 Mon Sep 17 00:00:00 2001 From: Kent Hansen Date: Thu, 30 Jul 2009 10:44:15 +0200 Subject: fix two bugs in the custom script class example 1) fromScriptValue() needs to call qvariant_cast() on the data, in order to be symmetric with toScriptValue(). 2) use the overload of newFunction() that takes a prototype object, so that the prototype.constructor and constructor.prototype relationship is set up correctly; otherwise the instanceof operator won't work. --- examples/script/customclass/bytearrayclass.cpp | 9 ++++++--- examples/script/customclass/main.cpp | 4 ++++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/examples/script/customclass/bytearrayclass.cpp b/examples/script/customclass/bytearrayclass.cpp index 81a0b8a..2044a16 100644 --- a/examples/script/customclass/bytearrayclass.cpp +++ b/examples/script/customclass/bytearrayclass.cpp @@ -100,7 +100,7 @@ ByteArrayClass::ByteArrayClass(QScriptEngine *engine) QScriptValue global = engine->globalObject(); proto.setPrototype(global.property("Object").property("prototype")); - ctor = engine->newFunction(construct); + ctor = engine->newFunction(construct, proto); ctor.setData(qScriptValueFromValue(engine, this)); } //! [0] @@ -224,7 +224,10 @@ QScriptValue ByteArrayClass::construct(QScriptContext *ctx, QScriptEngine *) ByteArrayClass *cls = qscriptvalue_cast(ctx->callee().data()); if (!cls) return QScriptValue(); - int size = ctx->argument(0).toInt32(); + QScriptValue arg = ctx->argument(0); + if (arg.instanceOf(ctx->callee())) + return cls->newInstance(qscriptvalue_cast(arg)); + int size = arg.toInt32(); return cls->newInstance(size); } //! [2] @@ -240,7 +243,7 @@ QScriptValue ByteArrayClass::toScriptValue(QScriptEngine *eng, const QByteArray void ByteArrayClass::fromScriptValue(const QScriptValue &obj, QByteArray &ba) { - ba = qscriptvalue_cast(obj.data()); + ba = qvariant_cast(obj.data().toVariant()); } diff --git a/examples/script/customclass/main.cpp b/examples/script/customclass/main.cpp index 05aefd5..3b98f5c 100644 --- a/examples/script/customclass/main.cpp +++ b/examples/script/customclass/main.cpp @@ -52,6 +52,7 @@ int main(int argc, char **argv) eng.globalObject().setProperty("ByteArray", baClass->constructor()); qDebug() << "ba = new ByteArray(4):" << eng.evaluate("ba = new ByteArray(4)").toString(); + qDebug() << "ba instanceof ByteArray:" << eng.evaluate("ba instanceof ByteArray").toBool(); qDebug() << "ba.length:" << eng.evaluate("ba.length").toNumber(); qDebug() << "ba[1] = 123; ba[1]:" << eng.evaluate("ba[1] = 123; ba[1]").toNumber(); qDebug() << "ba[7] = 224; ba.length:" << eng.evaluate("ba[7] = 224; ba.length").toNumber(); @@ -65,6 +66,9 @@ int main(int argc, char **argv) qDebug() << "ba.toBase64().toLatin1String():" << eng.evaluate("b64.toLatin1String()").toString(); qDebug() << "ba.valueOf():" << eng.evaluate("ba.valueOf()").toString(); qDebug() << "ba.chop(2); ba.length:" << eng.evaluate("ba.chop(2); ba.length").toNumber(); + qDebug() << "ba2 = new ByteArray(ba):" << eng.evaluate("ba2 = new ByteArray(ba)").toString(); + qDebug() << "ba2.equals(ba):" << eng.evaluate("ba2.equals(ba)").toBool(); + qDebug() << "ba2.equals(new ByteArray()):" << eng.evaluate("ba2.equals(new ByteArray())").toBool(); return 0; } -- cgit v0.12 From e181f8754bccb13cb59212f279e05c20cb76db62 Mon Sep 17 00:00:00 2001 From: Leonardo Sobral Cunha Date: Thu, 30 Jul 2009 12:09:16 +0200 Subject: Avoids comparing a pointer (d->layout) after deleted in qgraphicswidget Reviewed-by: ogoffart --- src/gui/graphicsview/qgraphicswidget.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/gui/graphicsview/qgraphicswidget.cpp b/src/gui/graphicsview/qgraphicswidget.cpp index 3ea80ce..cb8336d 100644 --- a/src/gui/graphicsview/qgraphicswidget.cpp +++ b/src/gui/graphicsview/qgraphicswidget.cpp @@ -258,7 +258,6 @@ QGraphicsWidget::~QGraphicsWidget() //we check if we have a layout previously if (d->layout) { - delete d->layout; foreach (QGraphicsItem * item, childItems()) { // In case of a custom layout which doesn't remove and delete items, we ensure that // the parent layout item does not point to the deleted layout. This code is here to @@ -269,6 +268,7 @@ QGraphicsWidget::~QGraphicsWidget() widget->setParentLayoutItem(0); } } + delete d->layout; } // Remove this graphics widget from widgetStyles -- cgit v0.12 From fbe103bd39fcef2b873aae31dcfee9604237a95e Mon Sep 17 00:00:00 2001 From: Leonardo Sobral Cunha Date: Thu, 30 Jul 2009 12:23:49 +0200 Subject: Revert "Avoids comparing a pointer (d->layout) after deleted in qgraphicswidget" This reverts commit e181f8754bccb13cb59212f279e05c20cb76db62. This code is used for compatibility issues for custom layouts that dont delete their children, so its a false positive from coverity. --- src/gui/graphicsview/qgraphicswidget.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/gui/graphicsview/qgraphicswidget.cpp b/src/gui/graphicsview/qgraphicswidget.cpp index cb8336d..3ea80ce 100644 --- a/src/gui/graphicsview/qgraphicswidget.cpp +++ b/src/gui/graphicsview/qgraphicswidget.cpp @@ -258,6 +258,7 @@ QGraphicsWidget::~QGraphicsWidget() //we check if we have a layout previously if (d->layout) { + delete d->layout; foreach (QGraphicsItem * item, childItems()) { // In case of a custom layout which doesn't remove and delete items, we ensure that // the parent layout item does not point to the deleted layout. This code is here to @@ -268,7 +269,6 @@ QGraphicsWidget::~QGraphicsWidget() widget->setParentLayoutItem(0); } } - delete d->layout; } // Remove this graphics widget from widgetStyles -- cgit v0.12 From 04f7834fcd8db4ecb6a4c53de42ac83f571b37c8 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Thu, 30 Jul 2009 12:58:06 +0200 Subject: Fix compilation on AIX: -I/usr/include cannot be used. The reason is that the C++ compiler needs to add -I/usr/vacpp/include before -I/usr/include, so our adding of -I/usr/include changes the order. This causes a compilation error in the C++ header xlocinfo.h. In any case, these checks done in qmake are unnecessary. If the OpenSSL headers are in one of those include paths, they will be found on their own already. Reviewed-By: Bradley T. Hughes --- config.tests/unix/openssl/openssl.pri | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/config.tests/unix/openssl/openssl.pri b/config.tests/unix/openssl/openssl.pri index bc95479..f069396 100644 --- a/config.tests/unix/openssl/openssl.pri +++ b/config.tests/unix/openssl/openssl.pri @@ -1,9 +1,3 @@ -!cross_compile { - TRY_INCLUDEPATHS = /include /usr/include /usr/local/include $$QMAKE_INCDIR $$INCLUDEPATH - # LSB doesn't allow using headers from /include or /usr/include - linux-lsb-g++:TRY_INCLUDEPATHS = $$QMAKE_INCDIR $$INCLUDEPATH - for(p, TRY_INCLUDEPATHS) { - pp = $$join(p, "", "", "/openssl") - exists($$pp):INCLUDEPATH *= $$p - } -} +# Empty file since Qt 4.6 +# I'm too lazy to find all places where this file is included + -- cgit v0.12 From 9fb11e5c2e8127e2916e1cf9b51f676effc9d31e Mon Sep 17 00:00:00 2001 From: Gunnar Sletta Date: Thu, 30 Jul 2009 13:55:17 +0200 Subject: Reviewed-by: Thomas H. Squashed commit of the following: commit fcf7e8cab339d0cf9f3f2a9756d7754c54c4d934 Author: Gunnar Sletta Date: Thu Jul 30 13:15:13 2009 +0200 note in the changes file... commit 2c9c3880215988e6609c290a8e738b228736e601 Author: Gunnar Sletta Date: Thu Jul 30 12:51:42 2009 +0200 Don't leak native window HRGN handles commit 6bb30d2075dd1d71a8a600d25f413a38af7f2f2c Author: Gunnar Sletta Date: Thu Jul 30 11:09:22 2009 +0200 Moved qregion_wince.cpp -> qregion_win.cpp, platforms are identical now commit 173fcc5baec73a198167985c6f777987e6015a71 Author: Gunnar Sletta Date: Thu Jul 30 09:42:06 2009 +0200 win32 calls on QRegion.handle() is no longer supported, use from HRGN commit d7ddcce4ba29b70ed81f85274208b388a2bb9d4d Author: Gunnar Sletta Date: Thu Jul 30 09:41:37 2009 +0200 Added convenience function to convert from HRGN to QRegion commit 2fc53ac3d59a9c42bb4154fff7557610092b7946 Author: Gunnar Sletta Date: Wed Jul 29 09:28:10 2009 +0200 Kill qregion_win.cpp and use the unix code instead --- dist/changes-4.6.0 | 67 ++--- src/gui/painting/painting.pri | 8 +- src/gui/painting/qregion.cpp | 28 +- src/gui/painting/qregion.h | 4 +- src/gui/painting/qregion_win.cpp | 514 ++++--------------------------------- src/gui/painting/qregion_wince.cpp | 119 --------- src/gui/styles/qwindowsxpstyle.cpp | 18 +- 7 files changed, 109 insertions(+), 649 deletions(-) delete mode 100644 src/gui/painting/qregion_wince.cpp diff --git a/dist/changes-4.6.0 b/dist/changes-4.6.0 index 383c6b7..7a6decf 100644 --- a/dist/changes-4.6.0 +++ b/dist/changes-4.6.0 @@ -34,9 +34,15 @@ information about a particular change. - Significant external contribution from Milan Burda for planned removal of (non-unicode) Windows 9x/ME support. + - QRegion is no longer a GDI object by default. This means it is no + longer subjuect to gui-thread only nor does it potentially impact + the 10.000 GDI object limit per process. By explicitly calling + .handle() a GDI object will be created and memory managed by + QRegion. The native handle is for reading out only. Any GDI calls + made on the HRGN handle will not affect the QRegion. **************************************************************************** -* Important Behavior Changes * +* Important Behavior Changes * **************************************************************************** - The experimental Direct3D paint engine has been removed. The reason for @@ -71,33 +77,32 @@ information about a particular change. QGraphicsItem::ItemSendsGeometryChanges (which is enabled by default by QGraphicsWidget and QGraphicsProxyWidget). -- QDesktopWidget on X11 no longer emits the resized(int) signal when screens - are added or removed. This was not done on other platforms. Use the - screenCountChanged signal instead - -- QUrl's parser is more strict when for hostnames in URLs. QUrl now - enforces STD 3 rules: - - * each individual hostname section (between dots) must be at most - 63 ASCII characters in length; - - * only letters, digits, and the hyphen character are allowed in the - ASCII range; letters outside the ASCII range follow the normal - IDN rules - - That means QUrl no longer accepts some URLs that were invalid - before, but weren't interpreted as such. - -- The Unix configure-time check for STL is stricter now in Qt - 4.6.0. This means some legacy STL implementations may fail to pass - the test and, therefore, Qt will automatically disable STL support. - - This is a binary-compatible change: existing code will continue to - work without being recompiled. However, it affects the source code, - since some STL-compatibility API will not be enabled. - - Platforms affected by this change: - * solaris-cc-* with the default (Cstd) C++ STL library - recommendation: use -library=stlport4 - See Sun Studio's documentation for the effects of this option - + - QDesktopWidget on X11 no longer emits the resized(int) signal when screens + are added or removed. This was not done on other platforms. Use the + screenCountChanged signal instead + + - QUrl's parser is more strict when for hostnames in URLs. QUrl now + enforces STD 3 rules: + + * each individual hostname section (between dots) must be at most + 63 ASCII characters in length; + + * only letters, digits, and the hyphen character are allowed in the + ASCII range; letters outside the ASCII range follow the normal + IDN rules + + That means QUrl no longer accepts some URLs that were invalid + before, but weren't interpreted as such. + + - The Unix configure-time check for STL is stricter now in Qt + 4.6.0. This means some legacy STL implementations may fail to pass + the test and, therefore, Qt will automatically disable STL support. + + This is a binary-compatible change: existing code will continue to + work without being recompiled. However, it affects the source code, + since some STL-compatibility API will not be enabled. + + Platforms affected by this change: + * solaris-cc-* with the default (Cstd) C++ STL library + recommendation: use -library=stlport4 + See Sun Studio's documentation for the effects of this option diff --git a/src/gui/painting/painting.pri b/src/gui/painting/painting.pri index 34d1779..d226be2 100644 --- a/src/gui/painting/painting.pri +++ b/src/gui/painting/painting.pri @@ -100,8 +100,8 @@ win32 { painting/qcolormap_win.cpp \ painting/qpaintdevice_win.cpp \ painting/qprintengine_win.cpp \ - painting/qprinterinfo_win.cpp \ - painting/qregion_win.cpp + painting/qprinterinfo_win.cpp + !win32-borland:!wince*:LIBS += -lmsimg32 } @@ -126,10 +126,6 @@ embedded { painting/qwindowsurface_raster.cpp \ } -wince* { - SOURCES -= painting/qregion_win.cpp -} - unix:x11 { HEADERS += \ painting/qpaintengine_x11_p.h diff --git a/src/gui/painting/qregion.cpp b/src/gui/painting/qregion.cpp index 762e9e0..d59f3ff 100644 --- a/src/gui/painting/qregion.cpp +++ b/src/gui/painting/qregion.cpp @@ -49,7 +49,7 @@ #include -#if defined(Q_OS_UNIX) || defined(Q_OS_WINCE) +#if defined(Q_OS_UNIX) || defined(Q_WS_WIN) #include "qimage.h" #include "qbitmap.h" #include @@ -545,7 +545,7 @@ QRegion& QRegion::operator|=(const QRegion &r) \sa intersected() */ -#if !defined (Q_OS_UNIX) && !defined (Q_OS_WINCE) +#if !defined (Q_OS_UNIX) && !defined (Q_WS_WIN) QRegion& QRegion::operator+=(const QRect &r) { return operator+=(QRegion(r)); @@ -561,16 +561,14 @@ QRegion& QRegion::operator+=(const QRect &r) \sa intersected() */ -#if !defined(Q_WS_WIN) || defined(Q_OS_WINCE) QRegion& QRegion::operator&=(const QRegion &r) { return *this = *this & r; } -#endif /*! \overload \since 4.4 */ -#if defined (Q_OS_UNIX) || defined (Q_OS_WINCE) +#if defined (Q_OS_UNIX) || defined (Q_WS_WIN) QRegion& QRegion::operator&=(const QRect &r) { return *this = *this & r; @@ -591,10 +589,8 @@ QRegion& QRegion::operator&=(const QRect &r) \sa subtracted() */ -#if !defined(Q_WS_WIN) || defined(Q_OS_WINCE) QRegion& QRegion::operator-=(const QRegion &r) { return *this = *this - r; } -#endif /*! Applies the xored() function to this region and \a r and @@ -731,7 +727,7 @@ bool QRegion::intersects(const QRect &rect) const return false; } -#if !defined (Q_OS_UNIX) && !defined (Q_OS_WINCE) +#if !defined (Q_OS_UNIX) && !defined (Q_WS_WIN) /*! \overload \since 4.4 @@ -1086,7 +1082,7 @@ Q_AUTOTEST_EXPORT QPainterPath qt_regionToPath(const QRegion ®ion) return result; } -#if defined(Q_OS_UNIX) || defined(Q_OS_WINCE) +#if defined(Q_OS_UNIX) || defined(Q_WS_WIN) //#define QT_REGION_DEBUG /* @@ -1627,9 +1623,9 @@ QT_END_INCLUDE_NAMESPACE QT_BEGIN_INCLUDE_NAMESPACE # include "qregion_mac.cpp" QT_END_INCLUDE_NAMESPACE -#elif defined(Q_OS_WINCE) +#elif defined(Q_WS_WIN) QT_BEGIN_INCLUDE_NAMESPACE -# include "qregion_wince.cpp" +# include "qregion_win.cpp" QT_END_INCLUDE_NAMESPACE #elif defined(Q_WS_QWS) static QRegionPrivate qrp; @@ -3829,7 +3825,7 @@ QRegion::QRegion(const QRect &r, RegionType t) #if defined(Q_WS_X11) d->rgn = 0; d->xrectangles = 0; -#elif defined(Q_OS_WINCE) +#elif defined(Q_WS_WIN) d->rgn = 0; #endif if (t == Rectangle) { @@ -3851,7 +3847,7 @@ QRegion::QRegion(const QPolygon &a, Qt::FillRule fillRule) #if defined(Q_WS_X11) d->rgn = 0; d->xrectangles = 0; -#elif defined(Q_OS_WINCE) +#elif defined(Q_WS_WIN) d->rgn = 0; #endif d->qt_rgn = PolygonRegion(a.constData(), a.size(), @@ -3881,7 +3877,7 @@ QRegion::QRegion(const QBitmap &bm) #if defined(Q_WS_X11) d->rgn = 0; d->xrectangles = 0; -#elif defined(Q_OS_WINCE) +#elif defined(Q_WS_WIN) d->rgn = 0; #endif d->qt_rgn = qt_bitmapToRegion(bm); @@ -3896,7 +3892,7 @@ void QRegion::cleanUp(QRegion::QRegionData *x) XDestroyRegion(x->rgn); if (x->xrectangles) free(x->xrectangles); -#elif defined(Q_OS_WINCE) +#elif defined(Q_WS_WIN) if (x->rgn) qt_win_dispose_rgn(x->rgn); #endif @@ -3932,7 +3928,7 @@ QRegion QRegion::copy() const #if defined(Q_WS_X11) x->rgn = 0; x->xrectangles = 0; -#elif defined(Q_OS_WINCE) +#elif defined(Q_WS_WIN) x->rgn = 0; #endif if (d->qt_rgn) diff --git a/src/gui/painting/qregion.h b/src/gui/painting/qregion.h index bfedcb1..1db07a1 100644 --- a/src/gui/painting/qregion.h +++ b/src/gui/painting/qregion.h @@ -59,7 +59,7 @@ QT_MODULE(Gui) template class QVector; class QVariant; -#if defined(Q_WS_QWS) || defined(Q_WS_X11) || defined(Q_WS_MAC) || defined(Q_OS_WINCE) +#if defined(Q_WS_QWS) || defined(Q_WS_X11) || defined(Q_WS_MAC) || defined(Q_WS_WIN) struct QRegionPrivate; #endif @@ -199,7 +199,7 @@ private: #elif defined(Q_WS_MAC) && !defined(QT_MAC_USE_COCOA) mutable RgnHandle unused; // Here for binary compatability reasons. ### Qt 5 remove. #endif -#if defined(Q_WS_QWS) || defined(Q_WS_X11) || defined(Q_WS_MAC) || defined(Q_OS_WINCE) +#if defined(Q_WS_QWS) || defined(Q_WS_X11) || defined(Q_WS_MAC) || defined(Q_WS_WIN) QRegionPrivate *qt_rgn; #endif }; diff --git a/src/gui/painting/qregion_win.cpp b/src/gui/painting/qregion_win.cpp index 249b1a6..2d5e76b 100644 --- a/src/gui/painting/qregion_win.cpp +++ b/src/gui/painting/qregion_win.cpp @@ -39,27 +39,25 @@ ** ****************************************************************************/ +#include "qatomic.h" #include "qbitmap.h" #include "qbuffer.h" #include "qimage.h" #include "qpolygon.h" #include "qregion.h" #include "qt_windows.h" +#include "qpainterpath.h" +#include "qguifunctions_wince.h" QT_BEGIN_NAMESPACE +QRegion::QRegionData QRegion::shared_empty = { Q_BASIC_ATOMIC_INITIALIZER(1), 0, 0 }; -/* - In Windows versions before Windows Vista CreateRectRgn - when called in a multi-threaded - environment - might return an invalid handle. This function works around this limitation - by verifying the handle with a quick GetRegionData() call and re-creates the region - if necessary. -*/ HRGN qt_tryCreateRegion(QRegion::RegionType type, int left, int top, int right, int bottom) { const int tries = 10; for (int i = 0; i < tries; ++i) { - HRGN region = 0; + HRGN region; switch (type) { case QRegion::Rectangle: region = CreateRectRgn(left, top, right, bottom); @@ -80,497 +78,73 @@ HRGN qt_tryCreateRegion(QRegion::RegionType type, int left, int top, int right, return 0; } -#ifndef Q_OS_WINCE -HRGN qt_tryCreatePolygonRegion(const QPolygon &a, Qt::FillRule fillRule) -{ - const int tries = 10; - for (int i = 0; i < tries; ++i) { - HRGN region = CreatePolygonRgn(reinterpret_cast(a.data()), a.size(), - fillRule == Qt::OddEvenFill ? ALTERNATE : WINDING); - if (region) { - if (GetRegionData(region, 0, 0)) - return region; - else - DeleteObject(region); - } - } - return 0; -} -#endif - -QRegion::QRegionData QRegion::shared_empty = { Q_BASIC_ATOMIC_INITIALIZER(1), 0 }; - -QRegion::QRegion() - : d(&shared_empty) -{ - d->ref.ref(); -} - -#ifndef Q_OS_WINCE //implementation for WindowsCE in qregion_wce.cpp -QRegion::QRegion(const QRect &r, RegionType t) -{ - if (r.isEmpty()) { - d = &shared_empty; - d->ref.ref(); - } else { - d = new QRegionData; - d->ref = 1; - if (t == Rectangle) - d->rgn = qt_tryCreateRegion(t, r.left(), r.top(), r.x() + r.width(), r.y() + r.height()); - else if (t == Ellipse) { - // need to add 1 to width/height for the ellipse to have correct boundingrect. - d->rgn = qt_tryCreateRegion(t, r.x(), r.y(), r.x() + r.width() + 1, r.y() + r.height() + 1); - } - } -} -#endif - -#ifndef Q_OS_WINCE //implementation for WindowsCE in qregion_wce.cpp -QRegion::QRegion(const QPolygon &a, Qt::FillRule fillRule) -{ - if (a.size() < 3) { - d = &shared_empty; - d->ref.ref(); - } else { - d = new QRegionData; - d->ref = 1; - d->rgn = qt_tryCreatePolygonRegion(a, fillRule); - } -} -#endif - -QRegion::QRegion(const QRegion &r) -{ - d = r.d; - d->ref.ref(); -} - -HRGN qt_win_bitmapToRegion(const QBitmap& bitmap) -{ - HRGN region=0; - QImage image = bitmap.toImage(); - const int MAXRECT = 256; - struct RData { - RGNDATAHEADER header; - RECT rect[MAXRECT]; - }; - RData data; - -#define FlushSpans \ - { \ - data.header.dwSize = sizeof(RGNDATAHEADER); \ - data.header.iType = RDH_RECTANGLES; \ - data.header.nCount = n; \ - data.header.nRgnSize = 0; \ - data.header.rcBound.bottom = y; \ - HRGN r = ExtCreateRegion(0, \ - sizeof(RGNDATAHEADER)+n*sizeof(RECT),(RGNDATA*)&data); \ - if (region) { \ - CombineRgn(region, region, r, RGN_OR); \ - DeleteObject(r); \ - } else { \ - region = r; \ - } \ - data.header.rcBound.top = y; \ - } - -#define AddSpan \ - { \ - data.rect[n].left=prev1; \ - data.rect[n].top=y; \ - data.rect[n].right=x-1+1; \ - data.rect[n].bottom=y+1; \ - n++; \ - if (n == MAXRECT) { \ - FlushSpans \ - n=0; \ - } \ - } - - data.header.rcBound.top = 0; - data.header.rcBound.left = 0; - data.header.rcBound.right = image.width()-1; - int n = 0; - - int zero = 0x00; - - int x, y; - for (y = 0; y < image.height(); ++y) { - uchar *line = image.scanLine(y); - int w = image.width(); - uchar all=zero; - int prev1 = -1; - for (x = 0; x < w;) { - uchar byte = line[x/8]; - if (x > w - 8 || byte != all) { - for (int b = 8; b > 0 && x < w; --b) { - if (!(byte & 0x01) == !all) { - // More of the same - } else { - // A change. - if (all != zero) { - AddSpan; - all = zero; - } else { - prev1 = x; - all = ~zero; - } - } - byte >>= 1; - ++x; - } - } else { - x += 8; - } - } - if (all != zero) { - AddSpan; - } - } - if (n) { - FlushSpans; - } - - if (!region) { - // Surely there is some better way. - region = qt_tryCreateRegion(QRegion::Rectangle, 0,0,1,1); - CombineRgn(region, region, region, RGN_XOR); - } - return region; -} - -#ifndef Q_OS_WINCE //implementation for WindowsCE in qregion_wce.cpp -QRegion::QRegion(const QBitmap &bm) -{ - if (bm.isNull()) { - d = &shared_empty; - d->ref.ref(); - } else { - d = new QRegionData; - d->ref = 1; - d->rgn = qt_win_bitmapToRegion(bm); - } -} -#endif - -void QRegion::cleanUp(QRegion::QRegionData *x) -{ - if (x->rgn) - DeleteObject(x->rgn); - delete x; -} - -QRegion::~QRegion() -{ - if (!d->ref.deref()) - cleanUp(d); -} - -QRegion &QRegion::operator=(const QRegion &r) -{ - r.d->ref.ref(); - if (!d->ref.deref()) - cleanUp(d); - d = r.d; - return *this; -} - - -QRegion QRegion::copy() const -{ - QRegion r; - QRegionData *x = new QRegionData; - x->ref = 1; - if (d->rgn) { - x->rgn = qt_tryCreateRegion(QRegion::Rectangle, 0, 0, 2, 2); - CombineRgn(x->rgn, d->rgn, 0, RGN_COPY); - } else { - x->rgn = 0; - } - if (!r.d->ref.deref()) - cleanUp(r.d); - r.d = x; - return r; -} - -bool QRegion::isEmpty() const -{ - return (d == &shared_empty || boundingRect().isEmpty()); -} - - -bool QRegion::contains(const QPoint &p) const -{ - return d->rgn ? PtInRegion(d->rgn, p.x(), p.y()) : false; -} - -bool QRegion::contains(const QRect &r) const -{ - if (!d->rgn) - return false; - RECT rect; - SetRect(&rect, r.left(), r.top(), r.right(), r.bottom()); - return RectInRegion(d->rgn, &rect); -} - - -void QRegion::translate(int dx, int dy) -{ - if (!d->rgn || (dx == 0 && dy == 0)) - return; - detach(); - OffsetRgn(d->rgn, dx, dy); -} - - -#define RGN_NOP -1 - -// Duplicates of those in qregion.cpp -#define QRGN_OR 6 -#define QRGN_AND 7 -#define QRGN_SUB 8 -#define QRGN_XOR 9 - -/* - Performs the actual OR, AND, SUB and XOR operation between regions. - Sets the resulting region handle to 0 to indicate an empty region. -*/ - -QRegion QRegion::winCombine(const QRegion &r, int op) const +QRegion qt_region_from_HRGN(HRGN rgn) { - int both=RGN_NOP, - left=RGN_NOP, - right=RGN_NOP; - switch (op) { - case QRGN_OR: - both = RGN_OR; - left = right = RGN_COPY; - break; - case QRGN_AND: - both = RGN_AND; - break; - case QRGN_SUB: - both = RGN_DIFF; - left = RGN_COPY; - break; - case QRGN_XOR: - both = RGN_XOR; - left = right = RGN_COPY; - break; - default: - qWarning("QRegion: Internal error in winCombine"); - } - - int allCombineRgnResults = NULLREGION; - QRegion result; - result.detach(); - result.d->rgn = qt_tryCreateRegion(QRegion::Rectangle, 0, 0, 0, 0); - if (d->rgn && r.d->rgn) - allCombineRgnResults = CombineRgn(result.d->rgn, d->rgn, r.d->rgn, both); - else if (d->rgn && left != RGN_NOP) - allCombineRgnResults = CombineRgn(result.d->rgn, d->rgn, d->rgn, left); - else if (r.d->rgn && right != RGN_NOP) - allCombineRgnResults = CombineRgn(result.d->rgn, r.d->rgn, r.d->rgn, right); - - if (allCombineRgnResults == NULLREGION || allCombineRgnResults == ERROR) - result = QRegion(); - - //##### do not delete this. A null pointer is different from an empty region in SelectClipRgn in qpainter_win! (M) -// if (allCombineRgnResults == NULLREGION) { -// if (result.data->rgn) -// DeleteObject(result.data->rgn); -// result.data->rgn = 0; // empty region -// } - return result; -} - -QRegion QRegion::unite(const QRegion &r) const -{ - if (!d->rgn) - return r; - if (!r.d->rgn) - return *this; - return winCombine(r, QRGN_OR); -} - -QRegion QRegion::unite(const QRect &r) const -{ - return unite(QRegion(r)); -} - -QRegion QRegion::intersect(const QRegion &r) const -{ - if (!r.d->rgn || !d->rgn) - return QRegion(); - return winCombine(r, QRGN_AND); -} - -QRegion QRegion::subtract(const QRegion &r) const -{ - if (!r.d->rgn || !d->rgn) - return *this; - return winCombine(r, QRGN_SUB); -} - -QRegion QRegion::eor(const QRegion &r) const -{ - if (!d->rgn) - return r; - if (!r.d->rgn) - return *this; - return winCombine(r, QRGN_XOR); -} - - -QRect QRegion::boundingRect() const -{ - if (!d->rgn) - return QRect(); - RECT r; - if (GetRgnBox(d->rgn, &r) == NULLREGION) - return QRect(); - else - return QRect(r.left, r.top, r.right - r.left, r.bottom - r.top); -} - -QVector QRegion::rects() const -{ - if (d->rgn == 0) - return QVector(); - - int numBytes = GetRegionData(d->rgn, 0, 0); + int numBytes = GetRegionData(rgn, 0, 0); if (numBytes == 0) - return QVector(); + return QRegion(); char *buf = new char[numBytes]; if (buf == 0) - return QVector(); + return QRegion(); RGNDATA *rd = reinterpret_cast(buf); - if (GetRegionData(d->rgn, numBytes, rd) == 0) { + if (GetRegionData(rgn, numBytes, rd) == 0) { delete [] buf; - return QVector(); + return QRegion(); } - QVector a(rd->rdh.nCount); + QRegion region; RECT *r = reinterpret_cast(rd->Buffer); - for (int i = 0; i < a.size(); ++i) { - a[i].setCoords(r->left, r->top, r->right - 1, r->bottom - 1); + for (int i = 0; i < rd->rdh.nCount; ++i) { + QRect rect; + rect.setCoords(r->left, r->top, r->right - 1, r->bottom - 1); ++r; + region |= rect; } delete [] buf; - return a; -} - -void QRegion::setRects(const QRect *rects, int num) -{ - *this = QRegion(); - if (!rects || num == 0 || (num == 1 && rects->isEmpty())) - return; - for (int i = 0; i < num; ++i) - *this |= rects[i]; -} - -int QRegion::numRects() const -{ - if (d->rgn == 0) - return 0; - - const int numBytes = GetRegionData(d->rgn, 0, 0); - if (numBytes == 0) - return 0; - - char *buf = new char[numBytes]; - if (buf == 0) - return 0; - - RGNDATA *rd = reinterpret_cast(buf); - if (GetRegionData(d->rgn, numBytes, rd) == 0) { - delete[] buf; - return 0; - } - - const int n = rd->rdh.nCount; - delete[] buf; - return n; + return region; } -bool QRegion::operator==(const QRegion &r) const +void qt_win_dispose_rgn(HRGN r) { - if (d == r.d) - return true; - if ((d->rgn == 0) ^ (r.d->rgn == 0)) // one is empty, not both - return false; - return d->rgn == 0 ? true // both empty - : EqualRgn(d->rgn, r.d->rgn); // both non-empty + if (r) + DeleteObject(r); } -QRegion& QRegion::operator+=(const QRegion &r) +static void qt_add_rect(HRGN &winRegion, QRect r) { - if (!r.d->rgn) - return *this; - - if (!d->rgn) { - *this = r; - return *this; + HRGN rgn = CreateRectRgn(r.left(), r.top(), r.x() + r.width(), r.y() + r.height()); + if (rgn) { + HRGN dest = CreateRectRgn(0,0,0,0); + int result = CombineRgn(dest, winRegion, rgn, RGN_OR); + if (result) { + DeleteObject(winRegion); + winRegion = dest; + } + DeleteObject(rgn); } - - detach(); - - int result; - result = CombineRgn(d->rgn, d->rgn, r.d->rgn, RGN_OR); - if (result == NULLREGION || result == ERROR) - *this = QRegion(); - - return *this; -} - -QRegion& QRegion::operator-=(const QRegion &r) -{ - if (!r.d->rgn || !d->rgn) - return *this; - - detach(); - - int result; - result = CombineRgn(d->rgn, d->rgn, r.d->rgn, RGN_DIFF); - if (result == NULLREGION || result == ERROR) - *this = QRegion(); - - return *this; } -QRegion& QRegion::operator&=(const QRegion &r) +void QRegion::ensureHandle() const { - if (!d->rgn) - return *this; - - if (!r.d->rgn) { - *this = QRegion(); - return *this; + if (d->rgn) + DeleteObject(d->rgn); + d->rgn = CreateRectRgn(0,0,0,0); + if (d->qt_rgn) { + if (d->qt_rgn->numRects == 1) { + QRect r = d->qt_rgn->extents; + qt_add_rect(d->rgn, r); + return; + } + for (int i = 0;i < d->qt_rgn->numRects;i++) { + QRect r = d->qt_rgn->rects.at(i); + qt_add_rect(d->rgn, r); + } } - - detach(); - - int result; - result = CombineRgn(d->rgn, d->rgn, r.d->rgn, RGN_AND); - if (result == NULLREGION || result == ERROR) - *this = QRegion(); - - return *this; -} - -bool qt_region_strictContains(const QRegion ®ion, const QRect &rect) -{ - Q_UNUSED(region); - Q_UNUSED(rect); - return false; } -void QRegion::ensureHandle() const -{ -} QT_END_NAMESPACE diff --git a/src/gui/painting/qregion_wince.cpp b/src/gui/painting/qregion_wince.cpp deleted file mode 100644 index 9c33123..0000000 --- a/src/gui/painting/qregion_wince.cpp +++ /dev/null @@ -1,119 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the QtGui module of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include "qatomic.h" -#include "qbitmap.h" -#include "qbuffer.h" -#include "qimage.h" -#include "qpolygon.h" -#include "qregion.h" -#include "qt_windows.h" -#include "qpainterpath.h" -#include "qguifunctions_wince.h" - -QT_BEGIN_NAMESPACE - -QRegion::QRegionData QRegion::shared_empty = { Q_BASIC_ATOMIC_INITIALIZER(1), 0, 0 }; - -HRGN qt_tryCreateRegion(QRegion::RegionType type, int left, int top, int right, int bottom) -{ - const int tries = 10; - for (int i = 0; i < tries; ++i) { - HRGN region; - switch (type) { - case QRegion::Rectangle: - region = CreateRectRgn(left, top, right, bottom); - break; - case QRegion::Ellipse: -#ifndef Q_OS_WINCE - region = CreateEllipticRgn(left, top, right, bottom); -#endif - break; - } - if (region) { - if (GetRegionData(region, 0, 0)) - return region; - else - DeleteObject(region); - } - } - return 0; -} - -void qt_win_dispose_rgn(HRGN r) -{ - if (r) - DeleteObject(r); -} - -static void qt_add_rect(HRGN &winRegion, QRect r) -{ - HRGN rgn = CreateRectRgn(r.left(), r.top(), r.x() + r.width(), r.y() + r.height()); - if (rgn) { - HRGN dest = CreateRectRgn(0,0,0,0); - int result = CombineRgn(dest, winRegion, rgn, RGN_OR); - if (result) { - DeleteObject(winRegion); - winRegion = dest; - } - } -} - -void QRegion::ensureHandle() const -{ - if (d->rgn) - DeleteObject(d->rgn); - d->rgn = CreateRectRgn(0,0,0,0); - if (d->qt_rgn) { - if (d->qt_rgn->numRects == 1) { - QRect r = d->qt_rgn->extents; - qt_add_rect(d->rgn, r); - return; - } - for (int i = 0;i < d->qt_rgn->numRects;i++) { - QRect r = d->qt_rgn->rects.at(i); - qt_add_rect(d->rgn, r); - } - } -} - - -QT_END_NAMESPACE diff --git a/src/gui/styles/qwindowsxpstyle.cpp b/src/gui/styles/qwindowsxpstyle.cpp index 9560c4b..ad87354 100644 --- a/src/gui/styles/qwindowsxpstyle.cpp +++ b/src/gui/styles/qwindowsxpstyle.cpp @@ -134,6 +134,7 @@ static const int windowsRightBorder = 12; // right border on windows // External function calls extern Q_GUI_EXPORT HDC qt_win_display_dc(); +extern QRegion qt_region_from_HRGN(HRGN rgn); @@ -445,6 +446,7 @@ bool QWindowsXPStylePrivate::isTransparent(XPThemeData &themeData) themeData.stateId); } + /*! \internal Returns a QRegion of the region of the part */ @@ -456,12 +458,18 @@ QRegion QWindowsXPStylePrivate::region(XPThemeData &themeData) themeData.stateId, &rect, &hRgn))) return QRegion(); - QRegion rgn = QRegion(0,0,1,1); - const bool success = CombineRgn(rgn.handle(), hRgn, 0, RGN_COPY) != ERROR; - DeleteObject(hRgn); + HRGN dest = CreateRectRgn(0, 0, 0, 0); + const bool success = CombineRgn(dest, hRgn, 0, RGN_COPY) != ERROR; + + QRegion region; + if (success) - return rgn; - return QRegion(); + region = qt_region_from_HRGN(dest); + + DeleteObject(hRgn); + DeleteObject(dest); + + return region; } /*! \internal -- cgit v0.12 From 66a3c503e8e99b8cd28c2fef2b0a869f27c7efe7 Mon Sep 17 00:00:00 2001 From: Kavindra Devi Palaraja Date: Thu, 30 Jul 2009 13:59:57 +0200 Subject: Doc - some cleanups to beautify the paragraphs Reviewed-By: TrustMe --- src/gui/kernel/qapplication.cpp | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/gui/kernel/qapplication.cpp b/src/gui/kernel/qapplication.cpp index 5181689..109ceb1 100644 --- a/src/gui/kernel/qapplication.cpp +++ b/src/gui/kernel/qapplication.cpp @@ -179,11 +179,11 @@ QApplicationPrivate::~QApplicationPrivate() QApplication contains the main event loop, where all events from the window system and other sources are processed and dispatched. It also handles the - application's initialization and finalization, and provides session - management. In addition, it handles most system-wide and application-wide - settings. + application's initialization, finalization, and provides session + management. In addition, QApplication handles most of the system-wide and + application-wide settings. - For any GUI application using Qt, there is precisely one QApplication + For any GUI application using Qt, there is precisely \bold one QApplication object, no matter whether the application has 0, 1, 2 or more windows at any given time. For non-GUI Qt applications, use QCoreApplication instead, as it does not depend on the \l QtGui library. @@ -239,9 +239,9 @@ QApplicationPrivate::~QApplicationPrivate() saveState() for details. \endlist - The QApplication object does so much initialization. Hence, it \e{must} be + Since the QApplication object does so much initialization, it \e{must} be created before any other objects related to the user interface are created. - Since QApplication also deals with common command line arguments, it is + QApplication also deals with common command line arguments. Hence, it is usually a good idea to create it \e before any interpretation or modification of \c argv is done in the application itself. -- cgit v0.12 From 26e9f4e077c49d1191835def595e4fb70ee50be2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Morten=20S=C3=B8rvig?= Date: Thu, 30 Jul 2009 14:19:50 +0200 Subject: Mac/Carbon: Fix issue causing update(QRegion) to fail on large widgets. HIViewSetNeedsDisplayInRegion fails on large regions with large coordinates, fall back on updating the entire region in this case. The task mentions coordinates outside the range of signed short, but the provided example demonstrates failures in the 10-20K range as well. --- src/gui/kernel/qwidget_mac.mm | 7 ++++++- src/gui/painting/qregion.h | 1 + src/gui/painting/qregion_mac.cpp | 38 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 1 deletion(-) diff --git a/src/gui/kernel/qwidget_mac.mm b/src/gui/kernel/qwidget_mac.mm index 70eea3a..3bbf5d4 100644 --- a/src/gui/kernel/qwidget_mac.mm +++ b/src/gui/kernel/qwidget_mac.mm @@ -3100,7 +3100,12 @@ void QWidgetPrivate::update_sys(const QRegion &rgn) return; dirtyOnWidget += rgn; #ifndef QT_MAC_USE_COCOA - HIViewSetNeedsDisplayInRegion(qt_mac_nativeview_for(q), QMacSmartQuickDrawRegion(rgn.toQDRgn()), true); + RgnHandle rgnHandle = rgn.toQDRgnForUpdate_sys(); + if (rgnHandle) + HIViewSetNeedsDisplayInRegion(qt_mac_nativeview_for(q), QMacSmartQuickDrawRegion(rgnHandle), true); + else { + HIViewSetNeedsDisplay(qt_mac_nativeview_for(q), true); // do a complete repaint on overflow. + } #else // Cocoa doesn't do regions, it seems more efficient to just update the bounding rect instead of a potential number of message passes for each rect. const QRect &boundingRect = rgn.boundingRect(); diff --git a/src/gui/painting/qregion.h b/src/gui/painting/qregion.h index bfedcb1..6dfdc83 100644 --- a/src/gui/painting/qregion.h +++ b/src/gui/painting/qregion.h @@ -148,6 +148,7 @@ public: #elif defined(Q_WS_MAC) #if defined Q_WS_MAC32 RgnHandle toQDRgn() const; + RgnHandle toQDRgnForUpdate_sys() const; static QRegion fromQDRgn(RgnHandle shape); #endif #ifdef QT_MAC_USE_COCOA diff --git a/src/gui/painting/qregion_mac.cpp b/src/gui/painting/qregion_mac.cpp index b57f234..9b0e99f 100644 --- a/src/gui/painting/qregion_mac.cpp +++ b/src/gui/painting/qregion_mac.cpp @@ -155,6 +155,44 @@ RgnHandle QRegion::toQDRgn() const } return rgnHandle; } + +/*! + \internal + Create's a RegionHandle, it's the caller's responsibility to release. + Returns 0 if the QRegion overflows. +*/ +RgnHandle QRegion::toQDRgnForUpdate_sys() const +{ + RgnHandle rgnHandle = qt_mac_get_rgn(); + if(d->qt_rgn && d->qt_rgn->numRects) { + RgnHandle tmp_rgn = qt_mac_get_rgn(); + int n = d->qt_rgn->numRects; + const QRect *qt_r = (n == 1) ? &d->qt_rgn->extents : d->qt_rgn->rects.constData(); + while (n--) { + + // detect overflow. Tested for use with HIViewSetNeedsDisplayInRegion + // in QWidgetPrivate::update_sys(). + enum { HIViewSetNeedsDisplayInRegionOverflow = 10000 }; // empirically determined conservative value + qDebug() << qt_r->x() << qt_r->y() << qt_r->right() << qt_r->bottom(); + if (qt_r->right() > HIViewSetNeedsDisplayInRegionOverflow || qt_r->bottom() > HIViewSetNeedsDisplayInRegionOverflow) { + qt_mac_dispose_rgn(tmp_rgn); + qt_mac_dispose_rgn(rgnHandle); + return 0; + } + + SetRectRgn(tmp_rgn, + qMax(SHRT_MIN, qt_r->x()), + qMax(SHRT_MIN, qt_r->y()), + qMin(SHRT_MAX, qt_r->right() + 1), + qMin(SHRT_MAX, qt_r->bottom() + 1)); + UnionRgn(rgnHandle, tmp_rgn, rgnHandle); + ++qt_r; + } + qt_mac_dispose_rgn(tmp_rgn); + } + return rgnHandle; +} + #endif #if (MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_5) -- cgit v0.12 From 9939ce88427b4d33f50b45a0da85266f9ee37927 Mon Sep 17 00:00:00 2001 From: Eskil Abrahamsen Blomfeldt Date: Fri, 5 Jun 2009 16:59:17 +0200 Subject: Don't do two hash lookups in loadGlyphs() loadGlyphs() has a big impact on text rendering speed on X11. Removing the uneeded hash lookup makes this function go twice as fast, as it in the common case (where the glyphs are already cached) the hash lookups are 100% of the running time of the function. Reviewed-by: Trond --- src/gui/text/qfontengine_ft.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/gui/text/qfontengine_ft.cpp b/src/gui/text/qfontengine_ft.cpp index a0b6f0c..d210cb4 100644 --- a/src/gui/text/qfontengine_ft.cpp +++ b/src/gui/text/qfontengine_ft.cpp @@ -1378,8 +1378,8 @@ bool QFontEngineFT::loadGlyphs(QGlyphSet *gs, glyph_t *glyphs, int num_glyphs, G FT_Face face = 0; for (int i = 0; i < num_glyphs; ++i) { - if (!gs->glyph_data.contains(glyphs[i]) - || gs->glyph_data.value(glyphs[i])->format != format) { + Glyph *glyph = gs->glyph_data.value(glyphs[i]); + if (glyph == 0 || glyph->format != format) { if (!face) { face = lockFace(); FT_Matrix m = matrix; -- cgit v0.12 From aec91cf6fbfa6abd4a3548690fd22ebeb6237cf6 Mon Sep 17 00:00:00 2001 From: Gunnar Sletta Date: Wed, 29 Jul 2009 12:15:57 +0200 Subject: updates... --- .../data/qps/linear_gradients_perspectives_qps.png | Bin 78017 -> 77944 bytes tests/arthur/data/qps/linear_gradients_qps.png | Bin 82119 -> 162643 bytes tests/arthur/data/qps/lineconsistency_qps.png | Bin 12500 -> 12388 bytes tests/arthur/data/qps/linedashes2_aa_qps.png | Bin 28956 -> 28418 bytes tests/arthur/data/qps/paths_aa_qps.png | Bin 92711 -> 92147 bytes tests/arthur/data/qps/paths_qps.png | Bin 20637 -> 20392 bytes .../data/qps/radial_gradients_perspectives_qps.png | Bin 133150 -> 131744 bytes tests/arthur/data/qps/radial_gradients_qps.png | Bin 156036 -> 161009 bytes tests/arthur/data/qps/rasterops.qps | 167 +++++++++++---------- tests/arthur/data/qps/rasterops_qps.png | Bin 20400 -> 11059 bytes tests/arthur/data/qps/text_perspectives_qps.png | Bin 112750 -> 116847 bytes tests/arthur/data/qps/text_qps.png | Bin 72027 -> 32991 bytes tests/arthur/lance/interactivewidget.cpp | 2 +- tests/arthur/lance/lance.pro | 2 +- tests/arthur/lance/main.cpp | 16 +- tests/arthur/lance/widgets.h | 151 ++++++++++++++++++- 16 files changed, 234 insertions(+), 104 deletions(-) diff --git a/tests/arthur/data/qps/linear_gradients_perspectives_qps.png b/tests/arthur/data/qps/linear_gradients_perspectives_qps.png index 42ba872..3315ebe 100644 Binary files a/tests/arthur/data/qps/linear_gradients_perspectives_qps.png and b/tests/arthur/data/qps/linear_gradients_perspectives_qps.png differ diff --git a/tests/arthur/data/qps/linear_gradients_qps.png b/tests/arthur/data/qps/linear_gradients_qps.png index dc5223b..a4cdc43 100644 Binary files a/tests/arthur/data/qps/linear_gradients_qps.png and b/tests/arthur/data/qps/linear_gradients_qps.png differ diff --git a/tests/arthur/data/qps/lineconsistency_qps.png b/tests/arthur/data/qps/lineconsistency_qps.png index 48768ef..9d19a5d 100644 Binary files a/tests/arthur/data/qps/lineconsistency_qps.png and b/tests/arthur/data/qps/lineconsistency_qps.png differ diff --git a/tests/arthur/data/qps/linedashes2_aa_qps.png b/tests/arthur/data/qps/linedashes2_aa_qps.png index 0cb5b40..54c84b3 100644 Binary files a/tests/arthur/data/qps/linedashes2_aa_qps.png and b/tests/arthur/data/qps/linedashes2_aa_qps.png differ diff --git a/tests/arthur/data/qps/paths_aa_qps.png b/tests/arthur/data/qps/paths_aa_qps.png index 45b4b74..e51a4ac 100644 Binary files a/tests/arthur/data/qps/paths_aa_qps.png and b/tests/arthur/data/qps/paths_aa_qps.png differ diff --git a/tests/arthur/data/qps/paths_qps.png b/tests/arthur/data/qps/paths_qps.png index a9a8743..094a84f 100644 Binary files a/tests/arthur/data/qps/paths_qps.png and b/tests/arthur/data/qps/paths_qps.png differ diff --git a/tests/arthur/data/qps/radial_gradients_perspectives_qps.png b/tests/arthur/data/qps/radial_gradients_perspectives_qps.png index 0e28aae..d833250 100644 Binary files a/tests/arthur/data/qps/radial_gradients_perspectives_qps.png and b/tests/arthur/data/qps/radial_gradients_perspectives_qps.png differ diff --git a/tests/arthur/data/qps/radial_gradients_qps.png b/tests/arthur/data/qps/radial_gradients_qps.png index 66fcfc4..11043e8 100644 Binary files a/tests/arthur/data/qps/radial_gradients_qps.png and b/tests/arthur/data/qps/radial_gradients_qps.png differ diff --git a/tests/arthur/data/qps/rasterops.qps b/tests/arthur/data/qps/rasterops.qps index b79ec0d..ee3deca 100644 --- a/tests/arthur/data/qps/rasterops.qps +++ b/tests/arthur/data/qps/rasterops.qps @@ -1,83 +1,84 @@ -setPen NoPen - -setBrush black -drawRect 10 10 1200 140 - -setCompositionMode SourceOrDestination -translate 20 20 -begin_block drawShape -setBrush 0xffff0000 -drawEllipse 10 10 80 80 -setBrush 0xff00ff00 -drawRect 0 0 50 50 -setBrush 0xff0000ff -drawRect 50 50 50 50 -end_block - -begin_block loop -setCompositionMode SourceAndDestination -translate 120 0 -repeat_block drawShape - -setCompositionMode SourceXorDestination -translate 120 0 -repeat_block drawShape - -setCompositionMode NotSourceAndNotDestination -translate 120 0 -repeat_block drawShape - -setCompositionMode NotSourceOrNotDestination -translate 120 0 -repeat_block drawShape - -setCompositionMode NotSourceXorDestination -translate 120 0 -repeat_block drawShape - -setCompositionMode NotSource -translate 120 0 -repeat_block drawShape - -setCompositionMode NotSourceAndDestination -translate 120 0 -repeat_block drawShape - -setCompositionMode SourceAndNotDestination -translate 120 0 -repeat_block drawShape -end_block - -resetMatrix -setCompositionMode Source -setBrush white -drawRect 10 160 1200 140 -translate 20 170 -repeat_block loop - -resetMatrix -setCompositionMode Source -translate 20 320 -repeat_block loop - -resetMatrix -setPen black -setCompositionMode SourceOver -translate 20 470 -drawText 20 0 "Or ROP" -translate 120 0 -drawText 20 0 "And ROP" -translate 120 0 -drawText 20 0 "Xor ROP" -translate 120 0 -drawText 20 0 "Nor ROP" -translate 120 0 -drawText 20 0 "Nand ROP" -translate 120 0 -drawText 0 0 "NSrcXorDst ROP" -translate 120 0 -drawText 20 0 "NSrc ROP" -translate 120 0 -drawText 0 0 "NSrcAndDst ROP" -translate 120 0 -drawText 0 0 "SrcAndNDst ROP" +setPen NoPen + +setBrush black +drawRect 10 10 60 500 + +setCompositionMode SourceOrDestination +translate 20 20 + +begin_block drawShape + setBrush 0xffff0000 + drawEllipse 5 5 30 30 + setBrush 0xff00ff00 + drawRect 0 0 20 20 + setBrush 0xff0000ff + drawRect 20 20 20 20 +end_block + +begin_block loop + setCompositionMode SourceAndDestination + translate 0 50 +repeat_block drawShape + +setCompositionMode SourceXorDestination +translate 0 50 +repeat_block drawShape + +setCompositionMode NotSourceAndNotDestination +translate 0 50 +repeat_block drawShape + +setCompositionMode NotSourceOrNotDestination +translate 0 50 +repeat_block drawShape + +setCompositionMode NotSourceXorDestination +translate 0 50 +repeat_block drawShape + +setCompositionMode NotSource +translate 0 50 +repeat_block drawShape + +setCompositionMode NotSourceAndDestination +translate 0 50 +repeat_block drawShape + +setCompositionMode SourceAndNotDestination +translate 0 50 +repeat_block drawShape +end_block + +resetMatrix +setCompositionMode Source +setBrush white +drawRect 100 10 60 500 +translate 110 20 +repeat_block loop + +resetMatrix +setCompositionMode Source +translate 190 20 +repeat_block loop + +resetMatrix +setPen black +setCompositionMode SourceOver +translate 250 45 +drawText 20 0 "Or ROP" +translate 0 50 +drawText 20 0 "And ROP" +translate 0 50 +drawText 20 0 "Xor ROP" +translate 0 50 +drawText 20 0 "Nor ROP" +translate 0 50 +drawText 20 0 "Nand ROP" +translate 0 50 +drawText 0 0 "NSrcXorDst ROP" +translate 0 50 +drawText 20 0 "NSrc ROP" +translate 0 50 +drawText 0 0 "NSrcAndDst ROP" +translate 0 50 +drawText 0 0 "SrcAndNDst ROP" diff --git a/tests/arthur/data/qps/rasterops_qps.png b/tests/arthur/data/qps/rasterops_qps.png index 80ca8ae..7b93001 100644 Binary files a/tests/arthur/data/qps/rasterops_qps.png and b/tests/arthur/data/qps/rasterops_qps.png differ diff --git a/tests/arthur/data/qps/text_perspectives_qps.png b/tests/arthur/data/qps/text_perspectives_qps.png index 483ccc0..183ad6f 100644 Binary files a/tests/arthur/data/qps/text_perspectives_qps.png and b/tests/arthur/data/qps/text_perspectives_qps.png differ diff --git a/tests/arthur/data/qps/text_qps.png b/tests/arthur/data/qps/text_qps.png index 2c2ebf2..9a95493 100644 Binary files a/tests/arthur/data/qps/text_qps.png and b/tests/arthur/data/qps/text_qps.png differ diff --git a/tests/arthur/lance/interactivewidget.cpp b/tests/arthur/lance/interactivewidget.cpp index 0febbed..0c2c7a6 100644 --- a/tests/arthur/lance/interactivewidget.cpp +++ b/tests/arthur/lance/interactivewidget.cpp @@ -43,7 +43,7 @@ InteractiveWidget::InteractiveWidget() { - m_onScreenWidget = new OnScreenWidget(); + m_onScreenWidget = new OnScreenWidget(""); m_onScreenWidget->setMinimumSize(320, 240); setCentralWidget(m_onScreenWidget); diff --git a/tests/arthur/lance/lance.pro b/tests/arthur/lance/lance.pro index 193dbd2..ee9e08b 100644 --- a/tests/arthur/lance/lance.pro +++ b/tests/arthur/lance/lance.pro @@ -6,7 +6,7 @@ INCLUDEPATH += . # Input HEADERS += widgets.h interactivewidget.h -SOURCES += interactivewidget.cpp main.cpp +SOURCES += interactivewidget.cpp main.cpp RESOURCES += icons.qrc contains(QT_CONFIG, opengl)|contains(QT_CONFIG, opengles1)|contains(QT_CONFIG, opengles2):QT += opengl diff --git a/tests/arthur/lance/main.cpp b/tests/arthur/lance/main.cpp index 07e5180..f95b426 100644 --- a/tests/arthur/lance/main.cpp +++ b/tests/arthur/lance/main.cpp @@ -66,7 +66,7 @@ extern bool qt_show_painter_debug_output = false; //#define CONSOLE_APPLICATION -static const struct { +static const struct { const char *name; QImage::Format format; } imageFormats[] = { @@ -282,7 +282,7 @@ int main(int argc, char **argv) if (imageFormat == QImage::Format_Invalid) { printf("Invalid image format. Available formats are:\n"); - for (int ff = 0; ff < formatCount; ++ff) + for (int ff = 0; ff < formatCount; ++ff) printf("\t%s\n", imageFormats[ff].name); return -1; } @@ -403,12 +403,10 @@ int main(int argc, char **argv) case WidgetType: { OnScreenWidget *qWidget = - new OnScreenWidget; + new OnScreenWidget(files.at(j)); qWidget->setVerboseMode(verboseMode); qWidget->setType(type); qWidget->setCheckersBackground(checkers_background); - qWidget->m_filename = files.at(j); - qWidget->setWindowTitle(fileinfo.filePath()); qWidget->m_commands = content; qWidget->resize(width, height); qWidget->show(); @@ -418,12 +416,10 @@ int main(int argc, char **argv) case ImageWidgetType: { - OnScreenWidget *qWidget = new OnScreenWidget; + OnScreenWidget *qWidget = new OnScreenWidget(files.at(j)); qWidget->setVerboseMode(verboseMode); qWidget->setType(type); qWidget->setCheckersBackground(checkers_background); - qWidget->m_filename = files.at(j); - qWidget->setWindowTitle(fileinfo.filePath()); qWidget->m_commands = content; qWidget->resize(width, height); qWidget->show(); @@ -452,12 +448,10 @@ int main(int argc, char **argv) } case OpenGLType: { - OnScreenWidget *qGLWidget = new OnScreenWidget; + OnScreenWidget *qGLWidget = new OnScreenWidget(files.at(j)); qGLWidget->setVerboseMode(verboseMode); qGLWidget->setType(type); qGLWidget->setCheckersBackground(checkers_background); - qGLWidget->m_filename = files.at(j); - qGLWidget->setWindowTitle(fileinfo.filePath()); qGLWidget->m_commands = content; qGLWidget->resize(width, height); qGLWidget->show(); diff --git a/tests/arthur/lance/widgets.h b/tests/arthur/lance/widgets.h index 271c18a..7247608 100644 --- a/tests/arthur/lance/widgets.h +++ b/tests/arthur/lance/widgets.h @@ -57,15 +57,47 @@ #include #include +#include + #include const int CP_RADIUS = 10; +class StupidWorkaround : public QObject +{ + Q_OBJECT +public: + StupidWorkaround(QWidget *widget, int *value) + : QObject(widget), w(widget), mode(value) + { + } + +public slots: + void setViewMode(int m) { + *mode = m; + w->update(); + } + +private: + QWidget *w; + int *mode; +}; + template class OnScreenWidget : public T { public: - OnScreenWidget(QWidget *parent = 0) : T(parent) + + enum ViewMode { + RenderView, + BaselineView, + DifferenceView + }; + + OnScreenWidget(const QString &file, QWidget *parent = 0) + : T(parent), + m_view_mode(RenderView), + m_filename(file) { QSettings settings("Trolltech", "lance"); for (int i=0; i<10; ++i) { @@ -78,11 +110,47 @@ public: m_deviceType = WidgetType; m_checkersBackground = true; m_verboseMode = false; - } - void setVerboseMode(bool v) { m_verboseMode = v; } - void setCheckersBackground(bool b) { m_checkersBackground = b; } - void setType(DeviceType t) { m_deviceType = t; } + m_baseline_name = QString(m_filename).replace(".qps", "_qps") + ".png"; + if (QFileInfo(m_baseline_name).exists()) { + m_baseline = QPixmap(m_baseline_name); + } + + if (m_baseline.isNull()) { + setWindowTitle("Rendering: '" + file + "'. No baseline available"); + } else { + setWindowTitle("Rendering: '" + file + "'. Shortcuts: 1=render, 2=baseline, 3=difference"); + + StupidWorkaround *workaround = new StupidWorkaround(this, &m_view_mode); + + QSignalMapper *mapper = new QSignalMapper(this); + connect(mapper, SIGNAL(mapped(int)), workaround, SLOT(setViewMode(int))); + connect(mapper, SIGNAL(mapped(QString)), this, SLOT(setWindowTitle(QString))); + + QAction *renderViewAction = new QAction("Render View", this); + renderViewAction->setShortcut(Qt::Key_1); + connect(renderViewAction, SIGNAL(triggered()), mapper, SLOT(map())); + mapper->setMapping(renderViewAction, RenderView); + mapper->setMapping(renderViewAction, "Render View: " + file); + addAction(renderViewAction); + + QAction *baselineAction = new QAction("Baseline", this); + baselineAction->setShortcut(Qt::Key_2); + connect(baselineAction, SIGNAL(triggered()), mapper, SLOT(map())); + mapper->setMapping(baselineAction, BaselineView); + mapper->setMapping(baselineAction, "Baseline View: " + file); + addAction(baselineAction); + + QAction *differenceAction = new QAction("Differenfe View", this); + differenceAction->setShortcut(Qt::Key_3); + connect(differenceAction, SIGNAL(triggered()), mapper, SLOT(map())); + mapper->setMapping(differenceAction, DifferenceView); + mapper->setMapping(differenceAction, "Difference View" + file); + addAction(differenceAction); + + } + + } ~OnScreenWidget() { @@ -93,12 +161,24 @@ public: settings.sync(); } + void setVerboseMode(bool v) { m_verboseMode = v; } + void setCheckersBackground(bool b) { m_checkersBackground = b; } + void setType(DeviceType t) { m_deviceType = t; } + void resizeEvent(QResizeEvent *e) { m_image = QImage(); T::resizeEvent(e); } - void paintEvent(QPaintEvent *) + void paintEvent(QPaintEvent *) { + switch (m_view_mode) { + case RenderView: paintRenderView(); break; + case BaselineView: paintBaselineView(); break; + case DifferenceView: paintDifferenceView(); break; + } + } + + void OnScreenWidget::paintRenderView() { QPainter pt; QPaintDevice *dev = this; @@ -152,6 +232,57 @@ public: } } + if (m_render_view.isNull()) { + m_render_view = window()->windowSurface()->grabWidget(this); + m_render_view.save("renderView.png"); + } + } + + void paintBaselineView() { + QPainter p(this); + + if (m_baseline.isNull()) { + p.drawText(rect(), Qt::AlignCenter, + "No baseline found\n" + "file '" + m_baseline_name + "' does not exist..."); + return; + } + + p.drawPixmap(0, 0, m_baseline); + + p.setPen(QColor::fromRgb(0, 0, 0, 0.1)); + p.setFont(QFont("Arial", 128)); + p.rotate(45); + p.drawText(100, 0, "BASELINE"); + } + + QPixmap generateDifference() + { + QImage img(size(), QImage::Format_RGB32); + img.fill(0); + + QPainter p(&img); + p.drawPixmap(0, 0, m_render_view); + + p.setCompositionMode(QPainter::RasterOp_SourceXorDestination); + p.drawPixmap(0, 0, m_baseline); + + p.end(); + + return QPixmap::fromImage(img); + } + + void paintDifferenceView() { + QPainter p(this); + if (m_baseline.isNull()) { + p.drawText(rect(), Qt::AlignCenter, + "No baseline found\n" + "file '" + m_baseline_name + "' does not exist..."); + return; + } + + p.fillRect(rect(), Qt::black); + p.drawPixmap(0, 0, generateDifference()); } @@ -190,8 +321,6 @@ public: T::update(); } - - QSize sizeHint() const { return QSize(800, 800); } QVector m_controlPoints; @@ -200,12 +329,18 @@ public: QStringList m_commands; QString m_filename; + QString m_baseline_name; bool m_verboseMode; bool m_checkersBackground; DeviceType m_deviceType; + int m_view_mode; + QImage m_image; + + QPixmap m_baseline; + QPixmap m_render_view; }; #endif -- cgit v0.12 From eb8c2574848da1a418dbcec6f43699b2a2bc7edc Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Thu, 30 Jul 2009 14:47:14 +0200 Subject: Doc: Move class and function documentation into a dedicated directory. --- doc/src/classes/phonon-api.qdoc | 5023 +++++++++++++++++++++++++++++++++ doc/src/classes/q3asciicache.qdoc | 465 +++ doc/src/classes/q3asciidict.qdoc | 416 +++ doc/src/classes/q3cache.qdoc | 461 +++ doc/src/classes/q3dict.qdoc | 446 +++ doc/src/classes/q3intcache.qdoc | 446 +++ doc/src/classes/q3intdict.qdoc | 390 +++ doc/src/classes/q3memarray.qdoc | 523 ++++ doc/src/classes/q3popupmenu.qdoc | 76 + doc/src/classes/q3ptrdict.qdoc | 388 +++ doc/src/classes/q3ptrlist.qdoc | 1157 ++++++++ doc/src/classes/q3ptrqueue.qdoc | 230 ++ doc/src/classes/q3ptrstack.qdoc | 217 ++ doc/src/classes/q3ptrvector.qdoc | 427 +++ doc/src/classes/q3sqlfieldinfo.qdoc | 234 ++ doc/src/classes/q3sqlrecordinfo.qdoc | 89 + doc/src/classes/q3valuelist.qdoc | 569 ++++ doc/src/classes/q3valuestack.qdoc | 149 + doc/src/classes/q3valuevector.qdoc | 274 ++ doc/src/classes/qalgorithms.qdoc | 651 +++++ doc/src/classes/qcache.qdoc | 244 ++ doc/src/classes/qcolormap.qdoc | 152 + doc/src/classes/qdesktopwidget.qdoc | 266 ++ doc/src/classes/qiterator.qdoc | 1431 ++++++++++ doc/src/classes/qmacstyle.qdoc | 261 ++ doc/src/classes/qpagesetupdialog.qdoc | 84 + doc/src/classes/qpaintdevice.qdoc | 289 ++ doc/src/classes/qpair.qdoc | 229 ++ doc/src/classes/qpatternistdummy.cpp | 1010 +++++++ doc/src/classes/qplugin.qdoc | 135 + doc/src/classes/qprintdialog.qdoc | 72 + doc/src/classes/qprinterinfo.qdoc | 137 + doc/src/classes/qset.qdoc | 953 +++++++ doc/src/classes/qsignalspy.qdoc | 98 + doc/src/classes/qsizepolicy.qdoc | 522 ++++ doc/src/classes/qtdesigner-api.qdoc | 1413 ++++++++++ doc/src/classes/qtendian.qdoc | 168 ++ doc/src/classes/qtestevent.qdoc | 191 ++ doc/src/classes/qvarlengtharray.qdoc | 274 ++ doc/src/classes/qwaitcondition.qdoc | 188 ++ doc/src/phonon-api.qdoc | 5023 --------------------------------- doc/src/q3asciicache.qdoc | 465 --- doc/src/q3asciidict.qdoc | 416 --- doc/src/q3cache.qdoc | 461 --- doc/src/q3dict.qdoc | 446 --- doc/src/q3intcache.qdoc | 446 --- doc/src/q3intdict.qdoc | 390 --- doc/src/q3memarray.qdoc | 523 ---- doc/src/q3popupmenu.qdoc | 76 - doc/src/q3ptrdict.qdoc | 388 --- doc/src/q3ptrlist.qdoc | 1157 -------- doc/src/q3ptrqueue.qdoc | 230 -- doc/src/q3ptrstack.qdoc | 217 -- doc/src/q3ptrvector.qdoc | 427 --- doc/src/q3sqlfieldinfo.qdoc | 234 -- doc/src/q3sqlrecordinfo.qdoc | 89 - doc/src/q3valuelist.qdoc | 569 ---- doc/src/q3valuestack.qdoc | 149 - doc/src/q3valuevector.qdoc | 274 -- doc/src/qalgorithms.qdoc | 651 ----- doc/src/qcache.qdoc | 244 -- doc/src/qcolormap.qdoc | 152 - doc/src/qdesktopwidget.qdoc | 266 -- doc/src/qiterator.qdoc | 1431 ---------- doc/src/qpagesetupdialog.qdoc | 84 - doc/src/qpaintdevice.qdoc | 289 -- doc/src/qpair.qdoc | 229 -- doc/src/qpatternistdummy.cpp | 1010 ------- doc/src/qplugin.qdoc | 135 - doc/src/qprintdialog.qdoc | 72 - doc/src/qprinterinfo.qdoc | 137 - doc/src/qset.qdoc | 953 ------- doc/src/qsignalspy.qdoc | 98 - doc/src/qsizepolicy.qdoc | 522 ---- doc/src/qstyles.qdoc | 261 -- doc/src/qtdesigner.qdoc | 1373 --------- doc/src/qtendian.qdoc | 168 -- doc/src/qtestevent.qdoc | 191 -- doc/src/qvarlengtharray.qdoc | 274 -- doc/src/qwaitcondition.qdoc | 188 -- 80 files changed, 20748 insertions(+), 20708 deletions(-) create mode 100644 doc/src/classes/phonon-api.qdoc create mode 100644 doc/src/classes/q3asciicache.qdoc create mode 100644 doc/src/classes/q3asciidict.qdoc create mode 100644 doc/src/classes/q3cache.qdoc create mode 100644 doc/src/classes/q3dict.qdoc create mode 100644 doc/src/classes/q3intcache.qdoc create mode 100644 doc/src/classes/q3intdict.qdoc create mode 100644 doc/src/classes/q3memarray.qdoc create mode 100644 doc/src/classes/q3popupmenu.qdoc create mode 100644 doc/src/classes/q3ptrdict.qdoc create mode 100644 doc/src/classes/q3ptrlist.qdoc create mode 100644 doc/src/classes/q3ptrqueue.qdoc create mode 100644 doc/src/classes/q3ptrstack.qdoc create mode 100644 doc/src/classes/q3ptrvector.qdoc create mode 100644 doc/src/classes/q3sqlfieldinfo.qdoc create mode 100644 doc/src/classes/q3sqlrecordinfo.qdoc create mode 100644 doc/src/classes/q3valuelist.qdoc create mode 100644 doc/src/classes/q3valuestack.qdoc create mode 100644 doc/src/classes/q3valuevector.qdoc create mode 100644 doc/src/classes/qalgorithms.qdoc create mode 100644 doc/src/classes/qcache.qdoc create mode 100644 doc/src/classes/qcolormap.qdoc create mode 100644 doc/src/classes/qdesktopwidget.qdoc create mode 100644 doc/src/classes/qiterator.qdoc create mode 100644 doc/src/classes/qmacstyle.qdoc create mode 100644 doc/src/classes/qpagesetupdialog.qdoc create mode 100644 doc/src/classes/qpaintdevice.qdoc create mode 100644 doc/src/classes/qpair.qdoc create mode 100644 doc/src/classes/qpatternistdummy.cpp create mode 100644 doc/src/classes/qplugin.qdoc create mode 100644 doc/src/classes/qprintdialog.qdoc create mode 100644 doc/src/classes/qprinterinfo.qdoc create mode 100644 doc/src/classes/qset.qdoc create mode 100644 doc/src/classes/qsignalspy.qdoc create mode 100644 doc/src/classes/qsizepolicy.qdoc create mode 100644 doc/src/classes/qtdesigner-api.qdoc create mode 100644 doc/src/classes/qtendian.qdoc create mode 100644 doc/src/classes/qtestevent.qdoc create mode 100644 doc/src/classes/qvarlengtharray.qdoc create mode 100644 doc/src/classes/qwaitcondition.qdoc delete mode 100644 doc/src/phonon-api.qdoc delete mode 100644 doc/src/q3asciicache.qdoc delete mode 100644 doc/src/q3asciidict.qdoc delete mode 100644 doc/src/q3cache.qdoc delete mode 100644 doc/src/q3dict.qdoc delete mode 100644 doc/src/q3intcache.qdoc delete mode 100644 doc/src/q3intdict.qdoc delete mode 100644 doc/src/q3memarray.qdoc delete mode 100644 doc/src/q3popupmenu.qdoc delete mode 100644 doc/src/q3ptrdict.qdoc delete mode 100644 doc/src/q3ptrlist.qdoc delete mode 100644 doc/src/q3ptrqueue.qdoc delete mode 100644 doc/src/q3ptrstack.qdoc delete mode 100644 doc/src/q3ptrvector.qdoc delete mode 100644 doc/src/q3sqlfieldinfo.qdoc delete mode 100644 doc/src/q3sqlrecordinfo.qdoc delete mode 100644 doc/src/q3valuelist.qdoc delete mode 100644 doc/src/q3valuestack.qdoc delete mode 100644 doc/src/q3valuevector.qdoc delete mode 100644 doc/src/qalgorithms.qdoc delete mode 100644 doc/src/qcache.qdoc delete mode 100644 doc/src/qcolormap.qdoc delete mode 100644 doc/src/qdesktopwidget.qdoc delete mode 100644 doc/src/qiterator.qdoc delete mode 100644 doc/src/qpagesetupdialog.qdoc delete mode 100644 doc/src/qpaintdevice.qdoc delete mode 100644 doc/src/qpair.qdoc delete mode 100644 doc/src/qpatternistdummy.cpp delete mode 100644 doc/src/qplugin.qdoc delete mode 100644 doc/src/qprintdialog.qdoc delete mode 100644 doc/src/qprinterinfo.qdoc delete mode 100644 doc/src/qset.qdoc delete mode 100644 doc/src/qsignalspy.qdoc delete mode 100644 doc/src/qsizepolicy.qdoc delete mode 100644 doc/src/qstyles.qdoc delete mode 100644 doc/src/qtendian.qdoc delete mode 100644 doc/src/qtestevent.qdoc delete mode 100644 doc/src/qvarlengtharray.qdoc delete mode 100644 doc/src/qwaitcondition.qdoc diff --git a/doc/src/classes/phonon-api.qdoc b/doc/src/classes/phonon-api.qdoc new file mode 100644 index 0000000..09274bf --- /dev/null +++ b/doc/src/classes/phonon-api.qdoc @@ -0,0 +1,5023 @@ +/* + This file is part of the KDE project + Copyright (C) 2005-2007 Matthias Kretz + Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). + Contact: Nokia Corporation (qt-info@nokia.com) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License version 2 as published by the Free Software Foundation. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + + +/*! + \enum Phonon::DiscType + Enum to identify the media discs supported by MediaObject. + + \value NoDisc + No disc was selected. This is only useful as a return value from + MediaSource::diskType(). + \value Cd Identifies Audio CDs. + \value Dvd Identifies DVDs (not arbitrary data DVDs, only movie DVDs). + \value Vcd Identifies Video CDs. + + \sa MediaSource, MediaObject +*/ + +/*! + \enum Phonon::MetaData + + Provided as keys for Phonon::MediaObject::metaData(). The enum + values matches strings defined in the Ogg Vorbis specification + + \value ArtistMetaData + \value AlbumMetaData + \value TitleMetaData + \value DateMetaData + \value GenreMetaData + \value TracknumberMetaData + \value DescriptionMetaData + \value MusicBrainzDiscIdMetaData +*/ + +/*! + \enum Phonon::State + \since 4.4 + + The state enum describes the different states a media object can + take. Several functions of \l{Phonon::}{MediaObject} are + asynchronous, so even if a you have requested a state change + through a function call, e.g., through + \l{Phonon::MediaObject::}{play()}, you cannot be sure that the + change has taken place before you receive the + \l{Phonon::MediaObject::}{stateChanged()} signal. + + A media object can at any time change into any state, regardless + of the state it previously had. \omit In the + \l{Phonon::}{MediaObject} class description explains the typical + state changes in the life of a media object. \endomit + + \value LoadingState + After construction it might take a while before the media object + is ready to \l{Phonon::MediaObject::}{play()}. This state is + commonly used by backends to initialize the \l{Phonon + Overview}{media graph} and loading the source. When + the object leaves the loading state, it will enter the + StoppedState unless an error occurred or another state is + requested through a function call, e.g., + \l{Phonon::}{MediaObject::play()}. + + \value StoppedState + In the stopped state, the media object is ready to play its + current media source. The current + \l{MediaObject::seek()}{position} in the media stream is then 0. + + \value PlayingState + The media object is playing back its media source. + + \value BufferingState + The Player is waiting for data to be able to start or continue + playing. This state is commonly used to wait for media data over a + network connection. + + \value PausedState + The media player has currently paused its playback, i.e., it + stops playing but keeps the current playback position in the + stream. + + \value ErrorState + When a media object enters the error state a problem with the + playback has occurred. The possible errors are grouped into + two categories by Phonon::ErrorType, and the type can be + queried through \l{Phonon::MediaObject::}{errorType()}. A + \l{Phonon::}{FatalError} implies that the playback + cannot continue, but one can still try with a new media + source. With a \l{Phonon::}{NormalError} it might + be possible to continue playback, and a media object may + therefore change state from the ErrorState. + + \sa MediaObject +*/ + +/*! + \enum Phonon::Category + + Sets the category your program should be listed in in the mixer. + + \value NoCategory + Will make use of the default device. + \value NotificationCategory + If the sounds produced are notifications (ping, beep and such) you + should use this category. + \value MusicCategory + If your application is a music player (like a jukebox or media player + playing an audio file). + \value VideoCategory + If the sound is the audio channel of a video. + \value CommunicationCategory + If your applications produces sounds from communication with somebody + else (VoIP, voice chat). + \value GameCategory + Sound produced by a computer game should go into this category. + \value AccessibilityCategory + Sounds produced for accessibility (e.g., Text-To-Speech) + \omitvalue LastCategory + Holds the largest value of categories. + \omitvalue AccessibilityCategory + + A Jukebox will set this to Music, a VoIP program to Communication, a + DVD player to video, and so on. + + \note These categories can also become useful for an application that + controls the volumes automatically, like turning down the music when a call + comes in, or turning down the notifications when the media player knows + it's playing classical music. +*/ + +/*! + \enum Phonon::ErrorType + + This enum describes the severity when an error has occurred during + playback. + + After a media object has entered the \l{Phonon::}{ErrorState}, one + can query the type of error from + \l{Phonon::}{MediaObject::errorType()}. Note that you should query + the error when receiving the + \l{Phonon::}{MediaObject::stateChanged()} signal, because the + error type will be lost if the media object leaves the error + state. + + \value NoError No error. MediaObject::errorType() returns this if + MediaObject::state() != Phonon::ErrorState. + + \value NormalError An error has occurred with the playback of the current + source. It might be possible to continue playback, for instance, if only the + audio stream in a video cannot be played back. The media object will then + leave the error state again. + + \value FatalError. Something important does not work. Your program cannot continue + the playback of the current source, but it might be possible to try another. + + \sa MediaObject::errorType() +*/ + +/*! + \fn QString Phonon::categoryToString(Category c) + + Returns a (translated) string to show to the user identifying the given + Category (\a c). +*/ + +/*! + \enum Phonon::ObjectDescriptionType + \relates Phonon::ObjectDescription + + This enum defines the type of information that is contained in a + \l{Phonon::}{ObjectDescription} object. + + \value AudioOutputDeviceType An audio output device (\l{Phonon::}{AudioOutputDevice}). + This can be soundcards (with different drivers), + sound servers, or other virtual outputs like playback on a different + computer on the network. + + \value EffectType An audio effect (\l{Phonon::}{EffectDescription}). + \omitvalue SubtitleType + \omitvalue AudioCaptureDeviceType + \omitvalue AudioChannelType +*/ + +/*! + \typedef Phonon::AudioOutputDevice + \relates Phonon::ObjectDescription + + This typedef of \l{Phonon::}{ObjectDescription} describes an audio output + device, such as soundcards (with different drivers), sound servers, or other + virtual outputs like playback on a different computer on the network. + + \omit + For Hardware devices the backend should use libkaudiodevicelist + (AudioDevice and AudioDeviceEnumerator) which will list removable + devices even when they are unplugged and provide a unique identifier + that can make backends use the same identifiers. + \endomit + + A list of available devices is given by the backend with + Backendcapabilities::availableAudioOutputDevices() + + \snippet doc/src/snippets/phononobjectdescription.cpp 1 + +*/ + +/*! + \fn Phonon::phononVersion() + \inmodule Phonon + \since 4.5 + + Returns the Phonon version. +*/ + +/*! + \class Phonon::ObjectDescription + \inmodule Phonon + \inheaderfile Phonon/ObjectDescription + \since 4.4 + \brief The ObjectDescription class provides information about Phonon objects. + + Phonon currently uses this class to describe audio effects and + audio output devices - using the typedefs AudioOutputDevice and + EffectDescription. The type of an ObjectDescription is also + described through the \l{Phonon::}{ObjectDescriptionType} enum. + Objects of the same \l{Phonon::ObjectDescriptionType}{type} are + uniquely identified by an index(). + + The class gives a description() and a name() of the object, both + of which are strings appropriate for end users of a Phonon + application. You can also check whether the device or effect + described is \l{isValid()}{valid}. This does not guarantee that + the device or effect functions as expected, but that the + ObjectDescription describes an existing device or effect. + + Audio output devices and effect descriptions are used to select + the audio output device to be used for playback and to create + effects; we show examples of this in the snippet below. The + available descriptions can be fetched with + \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()} + and \l{Phonon::BackendCapabilities::}{availableAudioEffects()} + static functions in the Phonon::BackendCapabilities namespace + + \snippet doc/src/snippets/phononobjectdescription.cpp 0 + + Other types of ObjectDescriptions might be possible in the future, + e.g., descriptions of audio capture devices, such as microphones. + + \omit Not implemented yet. + Need a new paragraph on that some descriptions 'belong + together', such as chained audio effects. + + Some parts give the end user choices, e.g. what source to capture + audio from. These choices are described by the name and + description methods of this class and identified with the id + method. Subclasses then define additional information like which + audio and video choices belong together. \endomit + + \sa Phonon::AudioOutputDevice, Phonon::EffectDescription, {Capabilities Example}, {Phonon Module} +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription() + \brief constructs a new object description. + \internal +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription (int index, const QHash & properties) + \internal +*/ + +/*! + \fn Phonon::ObjectDescription::ObjectDescription(const QExplicitlySharedDataPointer &dd) + \internal +*/ + +/*! + \fn static inline ObjectDescription Phonon::ObjectDescription::fromIndex(int index) + \internal + + \omit Currently indices are not unique for all ObjectDescription types, making + the behavior of this function undefined. \endomit + + Returns a new description object that describes the + device/effect/codec/... with the given \a index. +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::operator==(const ObjectDescription &otherDescription) const + + Returns \c true if this ObjectDescription describes the same + object as \a otherDescription; otherwise, returns \c false. +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::operator!=(const ObjectDescription &otherDescription) const + Returns \c false if this ObjectDescription describes the same + as \a otherDescription; otherwise, returns \c true. +*/ + +/*! + \fn inline QString Phonon::ObjectDescription::name() const + + Returns a string appropriate for a user to select between + object descriptions, e.g., from a QComboBox. + + \sa description() +*/ + +/*! + \fn inline QString Phonon::ObjectDescription::description() const + + Returns a more extensive description than the name() function. + + For example, in the case of \l{Phonon::}{AudioOutputDevice}s, this + text should make clear which sound source is described; this is + sometimes hard to describe or understand from just the name. + + The text is appropriate to present to an end user in for example + tool tips of items, with the name()'s as text, in a QComboBox. + +*/ + +/*! + \fn inline QVariant Phonon::ObjectDescription::property(const char *name) const + + Returns the property named \a name. A property can be used for + extended information, such as the manufacturer of a sound card. The + information will usually be given as text. + + If the property is not set an invalid QVariant is returned. + + Qt's backends do not use properties at the time of this writing. + + \sa propertyNames() +*/ + +/*! + \fn inline QList Phonon::ObjectDescription::propertyNames() const + + Properties can be used for extended information about a + ObjectDescription, e.g., a manufacturer of a sound card. The + information will usually be given text. + + This function returns all names that return valid data when + property() is called. + + Currently, Qt backends do not use properties for their object + descriptions. + + \sa property() +*/ + +/*! + \fn inline bool Phonon::ObjectDescription::isValid() const + + Returns true if the device or effect described exists. + + An ObjectDescription that is invalid, will also have an + index() of -1. + + \sa index() +*/ + +/*! + \fn inline int Phonon::ObjectDescription::index() const + + Returns a unique identifier for this ObjectDescription. Used + internally to distinguish between the descriptions. + + Notice that the identifiers are only unique to the type of + description, e.g., \l{Phonon::}{AudioOutputDevice} or + \l{Phonon::}{EffectDescription}. +*/ + +/*! + \class Phonon::ObjectDescriptionPrivate + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::StreamInterface + \inmodule Phonon + \since 4.4 + \brief Backend interface to handle media streams (AbstractMediaStream). + \internal +*/ + +/*! + \fn virtual Phonon::StreamInterface::~StreamInterface() +*/ + +/*! + \fn virtual void Phonon::StreamInterface::writeData(const QByteArray &data) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::endOfData() = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::setStreamSize(qint64 newSize) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::StreamInterface::setStreamSeekable(bool s) = 0 + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::connectToSource(const MediaSource &mediaSource) + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::needData() + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::enoughData() + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::seekStream(qint64) + \internal +*/ + +/*! + \fn void Phonon::StreamInterface::reset() + \internal +*/ + +/*! + \fn Phonon::StreamInterface::StreamInterface() + \internal + \omit + For subclasses. + \endomit +*/ + +/*! + \class StreamInterfacePrivate + \inmodule Phonon + \internal +*/ + +/*! + \class Phonon::AbstractVideoOutput + \inmodule Phonon + \internal + \since 4.4 + \brief The AbstractVideoOutput class is the common base class for all video output classes. + + \sa VideoWidget +*/ + +/*! + \namespace Phonon::Experimental + \internal +*/ + +/*! + \fn Phonon::AbstractVideoOutput::AbstractVideoOutput(AbstractVideoOutputPrivate &d) + \internal + + Constructor that is called from derived classes. + + \param parent Standard QObject parent. +*/ + +/*! + \class Phonon::AbstractVideoOutputPrivate + \inmodule Phonon + \internal + \since 4.4 +*/ + +/*! + \class Phonon::VolumeFaderEffect + \inmodule Phonon + \internal + \since 4.4 + + This effect differs from gradually changing the output volume in that + a dedicated effect can change the volume in the smallest possible + steps while every other volume control will make more or less + noticeable steps. + + \sa AudioOutput::volume() +*/ + +/*! + \property Phonon::VolumeFaderEffect::volume + + This is the current volume of the output as voltage factor. + Setting this property changes the volume immediately. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% + + \sa volumeDecibel +*/ + +/*! + \property Phonon::VolumeFaderEffect::volumeDecibel + + This is the current volume of the output in decibel. + Setting this property changes the volume immediately. + + 0 dB means no change in volume, -6dB means an attenuation of the + voltage to 50% and an attenuation of the power to 25%, -inf dB means + silence. + + \sa volume +*/ + +/*! + \property Phonon::VolumeFaderEffect::fadeCurve + + This property holds the fade curve to be used for the fadeIn(), fadeOut() + and fadeTo() slots. + + Defaults to Fade3Decibel. + + \sa FadeCurve +*/ + +/*! + \enum Phonon::VolumeFaderEffect::FadeCurve + Determines the curve of the volume change. + + \value Fade3Decibel Crossfade curve/fast fade out. + This is the default fade curve. + \value Fade6Decibel Linear fade out. + \value Fade9Decibel Slow fade out. + \value Fade12Decibel A more extreme version of the -9dB fade. + + \bold{Notes:} + + \c Fade3Decibel is often the best fade for a crossfade, as after half + of the time the volume reached -3dB. This means that half the + possible power (which is proportional to the square of the + voltage) is reached. Summed, the maximum power of two audio + signals fading with a -3dB curve will always be equal. + + For fading in or out the -3dB curve is too abrupt in the end. + + With a -6dB fade curve, a volume of -6dB is reached after half of + the fading time. -6dB is equal to half of the voltage meaning + that the voltage multiplier changes linearly from the start + of the fade to the end. + + With the \c Fade9Decibel fade, a volume of -9dB is reached after + half of the fade time, so the fade is fast in the beginning and + slow at the end. This is a good fade for ending music. +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeIn(int fadeTime) + + Tells the Fader to change the volume from the current volume to 100% + in \a fadeTime milliseconds. + + Short for \c fadeTo(1.0, fadeTime). + + \param fadeTime the fade duration in milliseconds + + \sa fadeTo(), volume +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeOut(int fadeTime) + + Tells the Fader to change the volume from the current volume to 0% + in \a fadeTime milliseconds. + Short for \c fadeTo(0.0, fadeTime). + + \param fadeTime the fade duration in milliseconds + + \sa fadeTo +*/ + +/*! + \fn void Phonon::VolumeFaderEffect::fadeTo(float volume, int fadeTime) + + Tells the Fader to change the volume from the current value to + \a volume in \a fadeTime milliseconds. + + \sa fadeIn(), fadeOut() +*/ + +/*! + \class Phonon::VolumeFaderEffectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::VolumeFaderInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual Phonon::VolumeFaderInterface::~VolumeFaderInterface() + \internal +*/ + +/*! + \fn virtual float Phonon::VolumeFaderInterface::volume() const + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::setVolume(float) + \internal +*/ + +/*! + \fn virtual Phonon::VolumeFaderEffect::FadeCurve Phonon::VolumeFaderInterface::fadeCurve() const + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::setFadeCurve(Phonon::VolumeFaderEffect::FadeCurve) + \internal +*/ + +/*! + \fn virtual void Phonon::VolumeFaderInterface::fadeTo(float, int) + \internal +*/ + +/*! + \class Phonon::AbstractMediaStream + \inmodule Phonon + \internal + \since 4.4 + \brief The AbstractMediaStream class is the base class for custom media data streams. + \inheaderfile Phonon/AbstractMediaStream + + This class is subclassed to provide custom data streams for + \l{Phonon::}{MediaSource}s. + + The \l{Phonon::}{MediaSource} knows how to handle the most common + media sources, such as files and CD. If you need to fetch + multimedia from other sources, you can reimplement this class, + which can be used by a \l{Phonon::}{MediaSource}. + + When a backend needs more data from the stream, needData() will be + called. You must then use writeData() to write the data to the + backend. You can either write one time and wait for a new + needData() call, or continue to write data until you receive an + enoughData() call. When the stream is at its end, call endOfData() + instead of writeData(). + + Before the custom stream is passed to a \l{Phonon::}{MediaSource}, + setStreamSize() needs to be called, and also setStreamSeekable() + (if the stream is seekable). A good place to do this work is in + the constructor. A seekable stream must also reimplement + seekStream(). + + We show two examples. The first writes data repeatedly until it + receives the enoughData() call, while the second only writes once + and waits for a new needData() call. + + Example where data is written repeatedly. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 0 + + Example where data is written once: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 1 + + \sa Phonon::MediaSource, Phonon::MediaObject + +*/ + +/*! + \fn Phonon::AbstractMediaStream::AbstractMediaStream(QObject *parent = 0) + \internal + + Constructs an AbstractMediaStream object with the given \a parent. + +*/ + +/*! + \fn qint64 Phonon::AbstractMediaStream::streamSize() const + + Returns the stream size that was set with setStreamSize(). + + A negative value means that the length of the stream cannot be known. + + Defaults to 0. + + \sa setStreamSize() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::setStreamSize(qint64 size) + + Sets the \a size of the stream in number of bytes. + + A negative value means that the length of the stream cannot be known. + + Defaults to 0. + + This function has to be called. A backend will not call needData() + until the stream size is set. + + \sa streamSize() + +*/ + +/*! + \fn bool Phonon::AbstractMediaStream::streamSeekable() const + + Returns whether your data stream is set as seekable. + + Defaults to \c false. + + \sa setStreamSeekable() + +*/ + +/*! + \fn void Phonon::AbstractMediaStream::setStreamSeekable(bool s) + + Sets whether your data stream is seekable. \a s should be true if + the stream is seekable; otherwise false. + + Defaults to \c false. + + If you set this to \c true you have to implement the seekStream() + function. + + \sa streamSeekable() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::writeData(const QByteArray &data) + + Sends the media \a data to the backend for decoding. + + Use this function to send data to the backend after needData() has + been called. + + If your stream is a push stream, data should be written until the + enoughData() function is called. For a pull stream, write data + once before the call to needData() function returns. + + If the data is depleted, call endOfData() instead of writeData(). + + \warning Don't call this function before the first needData() is emitted. + + \sa needData(), endOfData() + +*/ + +/*! + \fn void Phonon::AbstractMediaStream::endOfData() + + Tells the backend that the media data stream is at its end. + + \warning Don't call this function before the first needData() is emitted. + + \sa writeData(), needData() +*/ + +/*! + \fn void Phonon::AbstractMediaStream::error(Phonon::ErrorType errorType, const QString &errorString) + + If an I/O error occurs you should call this function to make + MediaObject go into ErrorState. \c errorType classifies the error, + while \a errorString is a textual description of the error suitable + for users of Phonon applications. + + \sa MediaObject::errorType(), MediaObject::errorString() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::reset() = 0 + + Reimplement this function to reset the stream. Subsequent calls to writeData should start + from the first position of the data unless a seek is requested. + + The function is necessary for the case where a non-seekable MediaStream is + played more than once. For a seekable stream the implementation can simply call + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 2 + + \sa writeData(), needData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::needData() = 0 + + Reimplement this function to be notified when the backend needs data. + + When this function is called you should write data to the backend + (See writeData()). + + \sa writeData(), endOfData(), enoughData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::enoughData() + + If your stream is a push stream, reimplement this function to be + notified when the backend has enough data and your stream object + may take a break. + + This method is important for pushing data to the backend in order + to not fill the backend buffer unnecessarily. + + \sa needData() +*/ + +/*! + \fn virtual void Phonon::AbstractMediaStream::seekStream(qint64 offset) + + Reimplement this function if your stream is seekable. + + When this function is called the next call to writeData has to be at the + requested \a offset. + + \warning Do not call the parent implementation. + + \sa setStreamSeekable(), streamSeekable(), needData() +*/ + +/*! + \class Phonon::BackendInterface + \inmodule Phonon + \since 4.4 + \brief Main Backend class interface + \internal + + This interface defines the main factory of the backend. The createObject() function creates all the + objects needed by the frontend. + + The objectDescriptionIndexes and objectDescriptionProperties functions return information about + available devices, effects and codecs. + + An implementation could look like this: + \snippet snippets/phonon/samplebackend/main.cpp snippet + +*/ + +/*! + \fn virtual Phonon::BackendInterface::~BackendInterface() + \internal + + Silence gcc's warning. +*/ + +/*! + \enum Phonon::BackendInterface::Class + \internal + + Classes that the createObject() function has to handle. + + \value MediaObjectClass Request to return a \c MediaObject object. + \value VolumeFaderEffectClass Request to return a \c VolumeFaderEffect + object. + \value AudioOutputClass Request to return an \c AudioOutput object. + \value AudioDataOutputClass Request to return an \c AudioDataOutput object. + \value VisualizationClass Request to return a \c Visualization object. + \value VideoDataOutputClass Request to return a \c VideoDataOutput object. + \value EffectClass Request to return a \c Effect object. + Takes an additional int that specifies the effect ID. + \value VideoWidgetClass Request to return a \c VideoWidget object. +*/ + +/*! + \fn virtual QObject *Phonon::BackendInterface::createObject(Class c, QObject *parent, const QList &args = QList()) = 0 + \internal + + Returns a new instance of the requested class. + + \param c The requested class. + \param parent The parent object. + \param args Additional arguments (documented in Class). +*/ + + +/*! + \fn virtual QList Phonon::BackendInterface::objectDescriptionIndexes(ObjectDescriptionType type) const = 0 + \internal + + Returns the unique identifiers for the devices/effects/codecs of the given \a type. + + \param type see ObjectDescriptionType +*/ + +/*! + \fn virtual QHash Phonon::BackendInterface::objectDescriptionProperties(ObjectDescriptionType type, int index) const = 0 + \internal + + Given a unique identifier that was returned from objectDescriptionIndexes this function + returns a hash mapping property names to values. + + The property "name" must always be present. All other properties are optional. + + \table + \header \o Property \o Description + \row \o name \o The name of the device/effect/codec/... + \row \o description \o A text explaining what this device/effect/codec/... is/can do + \row \o icon \o An icon name (using the freedesktop naming scheme) or a QIcon for this + device/effect/codec/... + \row \o available \o A bool telling whether the device is present or unplugged. + \endtable + + \param type see ObjectDescriptionType + \param index The unique identifier that is returned from objectDescriptionIndexes +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::startConnectionChange(QSet) = 0; + \internal + + When this function is called the nodes given in the parameter list should + not lose any signal data when connections are changed. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::connectNodes(QObject *, QObject *) = 0 + \internal + + Defines a signal connection between the two given nodes. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::disconnectNodes(QObject *, QObject *) = 0 + \internal + + Cuts a signal connection between the two given nodes. +*/ + +/*! + \fn virtual bool Phonon::BackendInterface::endConnectionChange(QSet) = 0 + \internal + + When this function is called the nodes given in the parameter list may lose + signal data when a port is not connected. +*/ + +/*! + \fn virtual QStringList Phonon::BackendInterface::availableMimeTypes() const = 0 + \internal + + Returns all available MIME types. +*/ + +/*! + \class Phonon::MediaSource + \inmodule Phonon + \inheaderfile Phonon/MediaSource + \since 4.4 + \brief The MediaSource class provides multimedia data for media objects. + + The MediaSource class manages a source of multimedia content, such + as a music or video file, of which data is given to a + \l{Phonon::}{MediaObject}. + + The media source knows how fetch its data from several sources, + e.g., from files, a QIODevice, or a CD. The possible source types + are described by the \l{MediaSource::}{Type} enum. The type of the + source is set by the media source itself, and is dependent on the + constructor used to create it. Note that it is possible to provide + data from any source by implementing a QIODevice. + + The class has several functions to acquire information about the + source it manages, e.g., fileName() and url(). The return from + these functions are dependent on the type() of the media source. + + Normally, a programmer does not need to be concerned with media + sources. It's constructors are implicit, so one can, for instance, + send an URL or filename directly to the constructors of the + \l{Phonon::}{MediaObject}. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 3 + + A MediaSource object cannot be reused for another multimedia + source. It is possible to play the same source again, and also + stop and start a non-seekable media source, such as a radio + stream, with the same MediaSource object. + + \section1 Qt Backends + + Currently, Qt's backends support files in local and remote + locations. Support for other sources, such as CD/DVD, are planned + for the future. + + \sa MediaObject, {Phonon Module} +*/ + +/*! + \enum Phonon::MediaSource::Type + + Identifies the type of media described by the MediaSource object. + + \value Invalid The MediaSource object does not describe any valid source. + \value LocalFile The MediaSource object describes a local file. + \value Url The MediaSource object describes an URL, which can be either a + local file or a file on the network. + \value Disc The MediaSource object describes a disc, e.g., a CD. + \value Stream The MediaSource object describes a data stream. + This is the type used for \l{QIODevice}s. Note + that a stream opened with a QUrl, will still be of the Url type. + \value Empty The media source doesn't have a source. + + \sa MediaSource::type() +*/ + +/*! + \fn Phonon::MediaSource::MediaSource() + \internal + + Creates an invalid MediaSource object. + + \sa Invalid +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const QString &fileName) + + Creates a MediaSource object for the file specified by \a + fileName. You can also use this constructor with \l{The Qt + Resource System}{Qt resources} + + \omit + \param fileName file name of a local media file or a Qt resource that was compiled in. + \endomit +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const QUrl &url) + + Creates a MediaSource object for a the URL specified by \a url. + + If the multimedia content you would like to play back is on a + remote network location, you should use this constructor; though, + it also possible to specify an URL to a local file. + + \sa QUrl +*/ + + +/*! + \fn Phonon::MediaSource::MediaSource(Phonon::DiscType discType, const QString &deviceName = QString()) + + Creates a MediaSource object for the type of disc specified by \a discType in the named + device referred to by \a deviceName. + + \note \a deviceName is a platform dependent device name. It can be useful to specify this + if the computer has more than one CD drive. On KDE, it is recommended to use the Solid + hardware discovery framework to retrieve the device name in a portable way. +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(AbstractMediaStream *stream) + \internal + Creates a MediaSource object for a data stream. + + Your application can provide the media data by subclassing AbstractMediaStream and + passing a pointer to that object. Phonon will never delete the \a stream. + + \param stream The AbstractMediaStream subclass to provide the media data. + + \sa setAutoDelete +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(QIODevice *ioDevice) + + Creates a MediaSource object for the QIODevice specified by \a ioDevice. + + This constructor can be very handy in the combination of + QByteArray and QBuffer. + + If you need to fetch multimedia data from a source that is not + supported by MediaSource, you should subclass QIODevice and use + this MediaSource constructor. It is important that you reimplement + QIODevice::isSequential(), as it is used by MediaSource to + determine if the media source is seekable. + + \a ioDevice is an arbitrary readable QIODevice subclass. If the device is not opened + MediaSource will open it as QIODevice::ReadOnly. + + \note Sequential devices can also be used, but MediaObject::isSeekable() will + return false as a result. + + \warning On Windows, we only support \l{QIODevice}s containing the + \c avi, \c mp3, or \c mpg formats. Use the constructor that takes + a file name to open files (the Qt backend does not use a QFile + internally). + + \sa setAutoDelete() +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(MediaSourcePrivate &) + \internal +*/ + +/*! + \fn Phonon::MediaSource::~MediaSource() + + Destroys the MediaSource object. You should never delete a + MediaSource yourself, the MediaObject will handle this. + +*/ + +/*! + \fn Phonon::MediaSource::MediaSource(const MediaSource &other) + + Constructs a copy of the \a other media source. + + This constructor is fast thanks to explicit sharing. +*/ + +/*! + \fn MediaSource &Phonon::MediaSource::operator=(const MediaSource &other) + + Assigns the \a other media source to this media source and returns a + reference to it. + + This operation is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::MediaSource::operator==(const MediaSource &other) const + + Returns true if this media source is equal to the \a other media source; + otherwise returns false. +*/ + +/*! + \fn void Phonon::MediaSource::setAutoDelete(bool enable) + + If \a enable is true, the media source will take ownership of the + object passed in the \l{Phonon::}{MediaSource}'s constructor + object that was passed in the constructor; otherwise, the + programmer is responsible for deletion of this object. + + This setting is false by default. If you enable it, you should + only access the stream or device as long as you keep the media + source object around. As long as you keep the media source + wrapping the stream or device, the object will not get deleted. + + \sa autoDelete() +*/ + +/*! + \fn bool Phonon::MediaSource::autoDelete() const + + Returns the setting of the auto-delete option. The default is + false. + + \sa setAutoDelete() +*/ + +/*! + \fn Type Phonon::MediaSource::type() const + + Returns the type of the MediaSource (depends on the constructor + that was used). + + \sa Type +*/ + +/*! + \fn QString Phonon::MediaSource::fileName() const + + Returns the file name of the MediaSource if type() == + LocalFile; otherwise, returns QString(). + + \sa type() +*/ + +/*! + \fn QUrl Phonon::MediaSource::url() const + Returns the URL of the MediaSource if type() == URL or type() == LocalFile; + otherwise returns QUrl(). + + \sa type() +*/ + +/*! + \fn Phonon::DiscType Phonon::MediaSource::discType() const + Returns the disc type of the MediaSource if type() == Disc; otherwise + returns NoDisc. + + \sa type() +*/ + +/*! + \fn QString Phonon::MediaSource::deviceName() const + + Returns the device name of the MediaSource if type() == Disc; otherwise + returns QString(). + + \sa type() +*/ + +/*! + \fn AbstractMediaStream *Phonon::MediaSource::stream() const + \internal + Returns the media stream of the MediaSource if type() == Stream; otherwise + returns 0. + QIODevices are handled as streams, too. +*/ + +/*! + \class Phonon::MediaSourcePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::SeekSlider + \inmodule Phonon + \inheaderfile Phonon/SeekSlider + \since 4.4 + \brief The SeekSlider class provides a slider for seeking to positions in media streams. + + The SeekSlider connects to a \l{Phonon::}{MediaObject}, and + controls the seek position in the object's media stream. + + The slider will connect to the necessary signals to keep track of + the sliders maximum, minimum, and current values. It will also + disable itself for non-seekable streams, and update the media + object when the current value of the slider changes. + + Here follows a typical example of SeekSlider usage: + + \snippet doc/src/snippets/seekslider.cpp 0 + + \sa Phonon::VolumeSlider, Phonon::VideoWidget, {Music Player Example}, {Phonon Module} + +*/ + +/*! + \property Phonon::SeekSlider::iconVisible + \brief whether the icon next to the slider is visible + + By default the icon is visible if the platform provides an icon; else + it's hidden. + +*/ + +/*! + \property Phonon::SeekSlider::tracking + \brief whether slider tracking is enabled + + If tracking is enabled (the default), the media seeks + while the slider is being dragged. If tracking is + disabled, the media seeks only when the user + releases the slider. +*/ + +/*! + \property Phonon::SeekSlider::pageStep + \brief the page step interval + + The larger of two natural steps that a slider provides and + typically corresponds to the user pressing PageUp or PageDown. + + Defaults to 5 seconds. +*/ + +/*! + \property Phonon::SeekSlider::singleStep + \brief the single step interval + + The smaller of two natural steps that a slider provides and + typically corresponds to the user pressing an arrow key. + + Defaults to 0.5 seconds. +*/ + +/*! + \property Phonon::SeekSlider::orientation + \brief the orientation of the slider + + The orientation must be Qt::Vertical or Qt::Horizontal (the default). +*/ + +/*! + \property Phonon::SeekSlider::iconSize + \brief the icon size used for the mute button/icon. + + The default size is defined by the GUI style. +*/ + +/*! + \fn explicit Phonon::SeekSlider::SeekSlider(QWidget *parent = 0) + + Constructs a seek slider widget with the given \a parent. +*/ + +/*! + \fn explicit Phonon::SeekSlider::SeekSlider(MediaObject *media, QWidget *parent = 0) + + Constructs a seek slider widget for the specified \a media with the + given \a parent. +*/ + +/*! + \fn Phonon::SeekSlider::~SeekSlider() + Destroys the seek slider. +*/ + +/*! + \fn Phonon::MediaObject *Phonon::SeekSlider::mediaObject() const + + Return the media object this SeekSlider controls. +*/ + +/*! + \class Phonon::SeekSliderPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn void Phonon::SeekSlider::setMediaObject(MediaObject *media) + + Sets the media object to be controlled by this slider to the \a media specified. +*/ + +/*! + \class Phonon::VideoPlayer + \inmodule Phonon + \inheaderfile Phonon/VideoPlayer + \since 4.4 + \brief The VideoPlayer widget is used to perform playback of video. + + With VideoPlayer you can get results quickly and easily. You can + do the standard playback tasks like play(), pause(), and stop(), + but also set a playback volume and seek - if the media and backend + supports seeking. + + VideoPlayer is provided for convenience and removes the need to + create a media graph with a \l{Phonon::}{MediaObject}, + \l{Phonon::}{AudioOutput}, and \l{Phonon::}{VideoWidget}. If + you need functionality not supported by the player, you can build + this \l{Building Graphs}{graph} yourself. + + Keep in mind that when the VideoPlayer instance is deleted the + playback will stop. + + Note also that most of the functions in this class are + asynchronous. For instance, a media source may not play + immediately after you call the play() function. + + A play and forget code example: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 4 + + \sa {Phonon Module}, MediaObject +*/ + +/*! + \fn Phonon::VideoPlayer::VideoPlayer(QWidget *parent = 0) + + Constructs a new video widget with a \a parent using + Phonon::VideoCategory as its category. + + \param parent The QObject parent. +*/ + +/*! + \fn Phonon::VideoPlayer::VideoPlayer(Phonon::Category category, QWidget *parent = 0) + + Constructs a new VideoPlayer instance with the specified \a + parent. + + \a category is the category used for the audio output device. +*/ + +/*! + \fn Phonon::VideoPlayer::~VideoPlayer() + + On destruction the playback is stopped, also the audio output is + removed so that the desktop mixer will not show the application + anymore. If you need a persistent audio output don't use + VideoPlayer but MediaObject, VideoPath and VideoOutput. +*/ + +/*! + \fn qint64 Phonon::VideoPlayer::totalTime() const + + Get the total time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn qint64 Phonon::VideoPlayer::currentTime() const + + Get the current time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn float Phonon::VideoPlayer::volume() const + + This is the current volume of the output as voltage factor. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% +*/ + +/*! + \fn bool Phonon::VideoPlayer::isPlaying() const + + Returns true if it is currently playing; otherwise returns false if it + is currently stopped or paused +*/ + +/*! + \fn bool Phonon::VideoPlayer::isPaused() const + + Returns true if it is currently paused; otherwise returns false if it + is currently playing or stopped. +*/ + +/*! + \fn void Phonon::VideoPlayer::load(const Phonon::MediaSource &source) + + Starts pre-loading the media data from the specified \a source and + filling audio buffers in the backend. + + When there's already a media playing (or paused) it will be stopped + (the finished signal will not be emitted). + + \sa MediaObject::setCurrentSource() +*/ + +/*! + \fn void Phonon::VideoPlayer::play(const Phonon::MediaSource &source) + + Plays the media from the given \a source. Starts playback as fast as + possible. + This can take a considerable time depending on the URL and the + backend. + + If you need low latency between calling play() and the sound actually + starting to play on your output device you need to use MediaObject + and be able to set the URL before calling play(). Note that + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 5 + doesn't make a difference: the application should be idle between the + load and play calls so that the backend can start preloading the + media and fill audio buffers. +*/ + +/*! + \fn void Phonon::VideoPlayer::play() + + Continues playback of paused media. Restarts playback of a stopped + (or newly loaded) media. + + \sa MediaObject::play(), play() +*/ + +/*! + \fn void Phonon::VideoPlayer::pause() + + Pauses the playback. + + \sa MediaObject::pause() +*/ + +/*! + \fn void Phonon::VideoPlayer::stop() + + Stops the playback. + + \sa MediaObject::stop() +*/ + +/*! + \fn void Phonon::VideoPlayer::seek(qint64 ms) + + Seeks to the requested time. Note that the backend is free to + ignore the seek request if the media source isn't seekable; you + can check this by asking the media object of the VideoPlayer. + + \snippet doc/src/snippets/videomedia.cpp 0 + + The \a ms parameter is the time in milliseconds from the start of + the media. + + The call is asynchronous, so currentTime() can still be the old + value right after this method was called. If all you need is a + slider that shows the current position and allows the user to + seek, use the class SeekSlider. + + \sa MediaObject::seek(), MediaObject::isSeekable(), mediaObject() +*/ + +/*! + \fn void Phonon::VideoPlayer::setVolume(float volume) + + Sets the \a volume of the output as voltage factor. + + 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% +*/ + +/*! + \fn MediaObject *Phonon::VideoPlayer::mediaObject() const + + Returns the media object being used by the player. + + The media object can be accessed directly instead of using the + \l{VideoPlayer}s convenience functions, e.g., play() and stop(). + It is also possible to give the object to other Phonon widgets, + e.g., a \l{Phonon::}{SeekSlider} or a \l{Phonon::}{VolumeSlider}. + + \sa Phonon::SeekSlider, Phonon::MediaObject +*/ + +/*! + \fn AudioOutput *Phonon::VideoPlayer::audioOutput() const + + Returns the audio output object being used by the player. + +*/ + +/*! + \fn VideoWidget *Phonon::VideoPlayer::videoWidget() const + + Returns the video widget being used by the player. +*/ + +/*! + \fn void Phonon::VideoPlayer::finished() + + This signal is emitted when the playback finished. + +*/ + +/*! + \class Phonon::VideoWidgetPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaObject + \inmodule Phonon + \inheaderfile Phonon/MediaObject + \since 4.4 + \brief The MediaObject class provides an interface for media playback. + + + The media object manages a \l{Phonon::}{MediaSource}, which + supplies the media object with multimedia content, e.g., from a + file. A playback in Phonon is always started by calling the + \l{Phonon::MediaObject::}{play()} function. + + The state of play (play, pause, stop, seek) is controlled by the + media object, and you can also query the current + \l{Phonon::MediaObject::}{state()}. It keeps track of the playback + position in the media stream, and emits the + \l{Phonon::MediaObject::}{tick()} signal when the current position + in the stream changes. + + Notice that most functions of this class are asynchronous, so you + cannot rely on that a state is entered after a function call + before you receive the \l{Phonon::MediaObject::}{stateChanged()} + signal. The description of the \l{Phonon::}{State} enum gives a + description of the different states. + + Before play() is called, the media object should be connected to + \l{Sinks}{output nodes}, which outputs the media to the + underlying hardware. The output nodes required are dependent on + the contents of the multimedia file that is played back. Phonon + has currently two output nodes: the \l{Phonon::}{AudioOutput} for + audio content and \l{Phonon::}{VideoWidget} for video content. If + a \l{Phonon::}{MediaSource} contains both audio and video, both + nodes need to be connected to the media object. + + \snippet snippets/phonon.cpp 4 + \snippet snippets/phonon.cpp 5 + + The media object can queue sources for playback. When it has + finished to play one source, it will start playing the next in the + queue; the new source is then removed from the queue. The + queue can be altered at any time. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 7 + + You can also make use of the + \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is + guaranteed to be emitted in time for altering the queue. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 8 + + When playback is finishing, i.e., when a media source has been + played to the end and the queue is empty, several signals are + emitted. First, the media object will emit aboutToFinish() - + shortly before the playback has finished - and then finished(). + The stateChanged() signal will also be emitted with + \l{Phonon::}{PausedState}, which is the state the media object + takes when the playback is finished. If you wish to enter another + state, you can connect a slot to finished() and set a new state + there. + + The media object resolves the meta information, such as title, + artist, and album. The meta data is not resolved immediately after + a new source is provided, but will be resolved before the object + leaves the \l{Phonon::}{LoadingState}. The data is queried by + string keys - which should follow the Ogg Vorbis specification + \l http://xiph.org/vorbis/doc/v-comment.html - or by using the + \l{Phonon::}{MetaData} enum. The data available will depend on the + type and content of the individual media files. metaDataChanged() + will be emitted when the media object has resolved new meta data. + + Errors encountered during playback and loading of media sources + are reported by emitting a state changed signal with + \l{Phonon::}{ErrorState}. The severity of the error can be queried + by the \l{Phonon::}{ErrorType}. With a \l{Phonon::}{NormalError}, + it might be possible to continue the playback, for instance, if + only audio playback fails for a media source which also has video. + A \l{Phonon::}{FatalError} indicates that Phonon cannot continue + playback of the current source, but it is possible to try with a + different one. A user readable error message is given by + errorString(). + + \sa Phonon::MediaSource, Phonon::AudioOutput, VideoWidget, + {Music Player Example}, {Phonon Overview}, Phonon::VideoPlayer, + Phonon::createPlayer(), {Phonon Module} + +*/ + +/*! + \property Phonon::MediaObject::transitionTime + \brief Defines the time between playback of two media sources + in the media queue. + + A positive transition time defines a gap of silence between queued + media sources. + + A transition time of 0 ms requests gapless playback (i.e., the + next source in the media queue starts immediately after the + playback of the current source finishes). + + A negative transition time defines a crossfade between the queued + media sources. + + Defaults to 0 (gapless playback). + + \warning This feature might not work reliably with every + backend. +*/ + +/*! + \property Phonon::MediaObject::prefinishMark + \brief the time when the prefinishMarkReached signal is emitted before playback ends. + + This property specifies the time in milliseconds the + prefinishMarkReached() signal is emitted before the playback + finishes. A value of \c 0 disables the signal. The signal is only + emitted for the last source in the \l{queue()}{media queue}. + + Defaults to \c 0 (disabled). + + \warning For some media data the total time cannot be determined + accurately, therefore the accuracy of the prefinishMarkReached signal + can be bad sometimes. Still, it is better to use this method than to + look at totalTime() and currentTime() to emulate the behavior + because the backend might have more information available than your + application does through totalTime() and currentTime(). + + \sa prefinishMarkReached() +*/ + +/*! + \property Phonon::MediaObject::tickInterval + \brief The time interval in milliseconds between two ticks. + + The tick() signal is emitted continuously during playback. + The tick interval is the time that elapses between the emission of two tick signals. + If you set the interval to \c 0 the tick signal gets disabled. + + The tick() signal can, for instance, be used to update widgets + that show the current position in the playback of a media source. + + Defaults to \c 0 (disabled). + + \warning The back-end is free to choose a different tick interval close + to what you asked for. This means that the following code \c may fail: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 9 + On the other hand the following is guaranteed: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 10 + + \sa tick() +*/ + +/*! + \fn Phonon::MediaObject::~MediaObject() + + Destroys the MediaObject. +*/ + +/*! + \fn State Phonon::MediaObject::state() const + + Returns the current Phonon::State of the object. + + \sa Phonon::State, stateChanged() +*/ + +/*! + \fn bool Phonon::MediaObject::hasVideo() const + + Check whether the current media source includes a video stream. + + \warning This information is not resolved immediately after a + media object gets a new source. Listen to the hasVideoChanged() + signal instead. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 11 + + Returns \c true if the media contains video data; otherwise, + returns \c false. + + \sa hasVideoChanged() +*/ + +/*! + \fn bool Phonon::MediaObject::isSeekable() const + + Check whether it is possible to seek, i.e., change the + playback position in the media stream. + + \warning This information is not solved immediately after the + media object gets a new media source. The hasVideoChanged() signal + is emitted after this information is available. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 12 + + Returns \c true if the current media may be seeked; otherwise, + returns \c false. + + \sa seekableChanged() +*/ + +/*! + \fn QStringList Phonon::MediaObject::metaData(const QString &key) const + + Returns the strings associated with the given \a key. + + Backends should use the keys specified in the Ogg Vorbis + documentation: \l http://xiph.org/vorbis/doc/v-comment.html + + Therefore the following should work with every backend: + + Note that meta data is not resolved before the \c + metaDataChanged() signal is emitted. + + A typical usage looks like this: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 13 +*/ + +/*! + \fn QStringList Phonon::MediaObject::metaData(Phonon::MetaData key) const + + Returns the strings associated with the given \a key. + + Same as above except that the keys are defined in the + Phonon::MetaData enum. + + \sa metaDataChanged() +*/ + +/*! + \fn QMultiMap Phonon::MediaObject::metaData() const + + Returns all meta data in a multi map. + + \sa metaDataChanged() +*/ + +/*! + \fn QString Phonon::MediaObject::errorString() const + + Returns a human-readable description of the last error that occurred. + The strings given may vary between backends. + + The error description can be used to give a message to the user - + and the developer - when the stateChanged() signal is emitted with + \l{Phonon::}{ErrorState}. + + \section1 Qt Backends + + On Windows, Qt fetches its error messages from the DirectShow + backend. This usually includes an error number, which can be + looked up in the DirectShow documentation: + \l{http://msdn.microsoft.com/archive/default.asp?url=/archive/en-us/dx81_c/directx_cpp/htm/errorandsuccesscodes.asp}. + + On Linux and Mac, the error strings are not fetched directly from + the backend, but are created in the backend. + + \sa Phonon::ErrorState, stateChanged() +*/ + +/*! + \fn ErrorType Phonon::MediaObject::errorType() const + + Tells your program what to do about the last error that occurred. + Use this function after receiving a stateChanged() signal with + \l{Phonon::}{ErrorState}. + + \sa Phonon::ErrorType, Phonon::ErrorState, stateChanged() +*/ + +/*! + \fn MediaSource Phonon::MediaObject::currentSource() const + + Returns the current media source, i.e., the media source that is + being played back. The current source is either set with + setCurrentSource() or taken from the media queue() when a media + source has finished playing. + + \sa setCurrentSource() +*/ + +/*! + \fn void Phonon::MediaObject::setCurrentSource(const MediaSource &source) + + Set the media source the MediaObject should use. + + After the media object receives a new source, it will enter the + \l{Phonon::}{LoadingState}. When it is ready to play, it + enters the \l{Phonon::}{StoppedState} unless another state + has been requested, e.g., by calling play(). + + \a source is the MediaSource object to the media data. You can + just as well use a QUrl or QString (for a local file) here. + + We show an example: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 14 + + \sa currentSource(), MediaSource +*/ + +/*! + \fn QList Phonon::MediaObject::queue() const + + Returns the queued media sources. + + This does list does not include the current source, + returned by currentSource(). + + \sa enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::setQueue(const QList &sources) + + Set the \a sources to play when the current source has finished. + + This function will overwrite the current queue. + + \sa clearQueue(), enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::setQueue(const QList &urls) + + Set the \a urls to play when the current media has finished. + + This function overwrites the current queue. + + \sa clearQueue(), enqueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const MediaSource &source) + + Appends \a source to the queue. + + You can use this function to provide the next source after the + aboutToFinish() signal has been emitted. + + \sa aboutToFinish(), setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const QList &sources) + + Appends multiple \a sources to the queue. + + \sa setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::enqueue(const QList &urls) + + Appends the URLs in \a urls to the media source queue. + + The function will create \l{MediaSource}s from the \l{QUrl}s, and + append these to the queue. + + \sa setQueue(), clearQueue() +*/ + +/*! + \fn void Phonon::MediaObject::clearQueue() + + Clears the queue of media sources. + + \sa queue(), enqueue() +*/ + +/*! + \fn qint64 Phonon::MediaObject::currentTime() const + + Returns the current time (in milliseconds), i.e., position in the + media stream, of the file currently being played. + + \sa tick(), totalTime(), remainingTime() +*/ + +/*! + \fn qint64 Phonon::MediaObject::totalTime() const + + Get the total time (in milliseconds) of the file currently being played. + + Returns the total time in milliseconds. + + \warning The total time is not defined before the media object + enters the \l{Phonon::}{LoadingState}. + + \sa totalTimeChanged() +*/ + +/*! + \fn qint64 Phonon::MediaObject::remainingTime() const + + Get the remaining time (in milliseconds) of the file currently being played. + + Returns the remaining time in milliseconds. + + \sa totalTime(), currentTime(), totalTimeChanged() +*/ + +/*! + \fn void Phonon::MediaObject::play() + + Requests playback of the media data to start. + + Playback starts when the stateChanged() signal is emitted with + \l{Phonon::}{PlayingState}. + + If the media object is already in a + \l{Phonon::}{PlayingState}, nothing happens. + + \sa stop(), pause(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::pause() + + Requests playback to pause, and the media object to enter the + \l{Phonon::}{PausedState}. If it was paused already, nothing + changes. + + This function is asynchronous and the media might not be paused + immediately. + + \sa play(), stop(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::stop() + + Requests playback to stop, and the media object to enter the + \l{Phonon::}{StoppedState}. If it was stopped before + nothing changes. + + This function is asynchronous and the media might not be + stopped immediately. + + \sa play(), pause(), stateChanged() +*/ + +/*! + \fn void Phonon::MediaObject::seek(qint64 time) + + Requests a seek to the \a time indicated, specified in milliseconds. + + You can only seek if state() is PlayingState, BufferingState or PausedState. + + The call is asynchronous, so currentTime can still be the old + value right after this method was called. If all you need is a + slider that shows the current position and allows the user to + seek, use the class SeekSlider. + + If the current source of the media object is not seekable, calls + to this functions do nothing. + + \sa SeekSlider, tick() +*/ + +/*! + \fn void Phonon::MediaObject::clear() + + Stops and removes all playing and enqueued media sources. + + \sa setCurrentSource() +*/ + + +/*! + \fn void Phonon::MediaObject::stateChanged(Phonon::State newstate, Phonon::State oldstate) + + This signal is emitted when the state of the MediaObject has changed. + The \a oldstate and \a newstate parameters indicate the previous + state and current state of the media object. + + If you are only interested in the new state of the media object, you can + connect this signal to a slot that accepts only one State argument. +*/ + +/*! + \fn void Phonon::MediaObject::tick(qint64 time) + + This signal is emitted in intervals defined by the + \l{tickInterval} property. The current position of the media + object in the stream is given by the \a time parameter. The \a + time is specified in milliseconds. + + \sa tickInterval +*/ + +/*! + \fn void Phonon::MediaObject::metaDataChanged() + + This signal is emitted when the media object has resolved new meta + data. This will happen before the media object leaves the + \l{Phonon::}{LoadingState} after a new source has been set. + + This signal is not emitted when the media object removes the + current data, i.e., when a new source is set or an error has + occurred. If you need to know this, you can listen for the + \l{Phonon::}{ErrorState}, and connect to the + \l{Phonon::MediaObject::}{currentSourceChanged()} signal. + + You can get the new meta data with the metaData methods. + + \sa metaData(), currentSourceChanged(), stateChanged(), Phonon::State +*/ + +/*! + \fn void Phonon::MediaObject::seekableChanged(bool isSeekable) + + This signal is emitted when the media object's ability to seek in + the media stream changes. \a isSeekable is true if it is possible + to seek(); otherwise, it is false. + + Change in the ability to seek in the stream usually happens when + the current source changes or when an error occurs. + + \omit Emitted whenever the return value of isSeekable() + changes. \endomit + + Normally you'll check isSeekable() after setting a new media + source, and then let this signal tell you when seeking is + possible. That way you don't have to poll isSeekable(). +*/ + +/*! + \fn void Phonon::MediaObject::hasVideoChanged(bool hasVideo) + + Emitted whenever the return value of hasVideo() changes, i.e., + the media source being played back contains video. + + Normally you'll check hasVideo() first and then let this signal + tell you whether video is available now or not. That way you + don't have to poll hasVideo(). + + \a hasVideo is true when the stream contains video and adding a + VideoWidget will show a video, and false if there is no video data + in the stream and adding a VideoWidget will show an empty (black) + VideoWidget. +*/ + +/*! + \fn void Phonon::MediaObject::bufferStatus(int percentFilled) + + Provides information about the status of the buffer. + + When a MediaObject is in the \l{Phonon::}{BufferingState}, it will + send this signal regularly. \a percentFilled is a number between 0 + and 100 telling you how much the buffer is filled. + + You can use this signal to show a progress bar to the user when + in BufferingState: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 15 + + Note that the \l{Phonon::}{BufferingState} is commonly used when + waiting for data over a network connection, but this might not be + true for all backends. +*/ + +/*! + \fn void Phonon::MediaObject::finished() + + Emitted when the object has finished playback. It is not emitted + if you call stop(), pause() or load(). It is emitted only when the + current media source has finished playing and the media queue() is + empty, or when a \l{Phonon::FatalError}{fatal error} occurs. + + \warning This signal is not emitted when the current source has + finished and there's another source in the queue. It is only + emitted when the queue is empty. + + \sa currentSourceChanged(), aboutToFinish(), prefinishMarkReached() +*/ + +/*! + \fn void Phonon::MediaObject::currentSourceChanged(const Phonon::MediaSource &newSource) + + Emitted when the MediaObject fetches a new MediaSource from the + queue() and before it enters the \l{Phonon::}{LoadingState} for + the new source. The media object will take a new source from the + queue() when it has finished the playback of the + \l{currentSource()}{current source}. + + \a newSource is the source that starts to play at the time the + signal is emitted. +*/ + +/*! + \fn void Phonon::MediaObject::aboutToFinish() + + Emitted before the playback of the whole queue ends. When this + signal is emitted you still have time to enqueue() a new + MediaSource, so that playback continues. + + If you need a signal to be emitted at a specific time before + playback is finished, you should use the prefinishMarkReached() + signal instead. + + \sa enqueue(), prefinishMark, prefinishMarkReached() +*/ + +/*! + \fn void Phonon::MediaObject::prefinishMarkReached(qint32 msecToEnd) + + Emitted when there are only \a msecToEnd milliseconds left + of playback. + + \warning This signal is not emitted when there is another source + in the queue. It is only emitted when the queue is empty. + + \sa setPrefinishMark(), prefinishMark(), aboutToFinish(), finished() +*/ + +/*! + \fn void Phonon::MediaObject::totalTimeChanged(qint64 newTotalTime) + + This signal is emitted as soon as the total time of the media file is + known or has changed. For most non-local media data the total + time of the media can only be known after some time. At that time the + totalTime function can not return useful information. You have + to wait for this signal to know the real total time. + + \a newTotalTime is the length of the media file in milliseconds. + + \sa totalTime() +*/ + +/*! + \fn MediaObject *Phonon::createPlayer(Phonon::Category category, const MediaSource &source = MediaSource()) + + Convenience function to create a MediaObject and AudioOutput + connected by a path. The \l{Phonon::}{MediaObject} return will + have \a source set as its current source and the specified \a + category. + +*/ + +/*! + \class Phonon::MediaObjectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \namespace Phonon::BackendCapabilities + \inmodule Phonon + \since 4.4 + \brief The BackendCapabilities namespace contains functions to describe the capabilities of the multimedia backend. + +*/ + +/*! + \class Phonon::BackendCapabilitiesPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::BackendCapabilities::Notifier + \since 4.4 + \inmodule Phonon + \inheaderfile Phonon/BackendCapabilities + + Notifications about backend capabilities. +*/ + +/*! + \fn void Phonon::BackendCapabilities::Notifier::capabilitiesChanged() + + This signal is emitted if the capabilities have changed. This can + happen if the user has requested a backend change. +*/ + +/*! + \fn void Phonon::BackendCapabilities::Notifier::availableAudioOutputDevicesChanged() + + This signal is emitted when audio output devices were plugged or + unplugged. + + Check BackendCapabilities::availableAudioOutputDevices to get the + current list of available devices. +*/ + +/*! + \fn Notifier *Phonon::BackendCapabilities::notifier() + + Use this function to get a QObject pointer to connect to the capabilitiesChanged signal. + + \return a pointer to a QObject. + + The capabilitiesChanged signal is emitted if the capabilities have changed. This can + happen if the user has requested a backend change. + + To connect to this signal do the following: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 16 + + \sa Notifier::capabilitiesChanged() +*/ + +/*! + \fn QStringList Phonon::BackendCapabilities::availableMimeTypes() + + Returns a list of mime types that the Backend can decode. + + \sa isMimeTypeAvailable() +*/ + +/*! + \fn bool Phonon::BackendCapabilities::isMimeTypeAvailable(const QString &mimeType) + + Often all you want to know is whether one given MIME type can be + decoded by the backend. Use this method in favor of + availableMimeTypes() as it can give you a negative answer without + having a backend loaded. + + Returns true if the given \a mimeType is supported by the backend; + otherwise, returns false. + + \sa availableMimeTypes() +*/ + +/*! + \fn QList Phonon::BackendCapabilities::availableAudioOutputDevices() + + Returns the audio output devices the backend supports. + + \return A list of AudioOutputDevice objects that give a name and + description for every supported audio output device. +*/ + +/*! + \fn QList Phonon::BackendCapabilities::availableAudioEffects() + + Returns descriptions for the audio effects the backend supports. + + \return A list of AudioEffectDescription objects that give a name and + description for every supported audio effect. +*/ + +/*! + \internal + \class ObjectDescriptionModelData + \internal + \inmodule Phonon + \brief Data class for models for ObjectDescription objects. +*/ + +/*! + \typedef Phonon::EffectDescription + \relates Phonon::ObjectDescription + + EffectDescription gives a description of an \l{Processors}{audio + effect}. It is a typedef of the \l{Phonon::}{ObjectDescription} + class. Please see its class description for details. + + EffectDescription is used to create audio \l{Phonon::}{Effect}s, + which can be inserted into a media graph, altering an audio + stream. + + \sa Phonon::ObjectDescription, {Capabilities Example}, {Media + Player} + +*/ + +/*! + \class Phonon::ObjectDescriptionModel + \inmodule Phonon + \internal + \since 4.4 + \brief The ObjectDescriptionModel class provides a model from + a list of ObjectDescription objects. + + ObjectDescriptionModel is a read only model that supplies a list + using ObjectDescription::name() for the text and + ObjectDescription::description() for the tooltip. If set the properties + "icon" and "available" are used to set the decoration and disable the + item (disabled only visually, you can still select and drag it). + + It also provides the methods moveUp() and moveDown() to order the list. + Additionally drag and drop is possible so that + QAbstractItemView::InternalMove can be used. + The resulting order of the ObjectDescription::index() values can then be + retrieved using tupleIndexOrder(). + + An example use case would be to give the user a QComboBox to select + the output device: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 17 + + And to retrieve the selected AudioOutputDevice: + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 18 + +*/ + +/*! + \fn inline int Phonon::ObjectDescriptionModel::rowCount(const QModelIndex &parent = QModelIndex()) const + + Returns the number of rows in the model. This value corresponds + to the size of the list passed through setModelData. + + \param parent The optional \a parent argument is used in most models to specify + the parent of the rows to be counted. Because this is a list if a + valid parent is specified the result will always be 0. + + Reimplemented from QAbstractItemModel. + + \sa QAbstractItemModel::rowCount() +*/ + +/*! + \fn inline QVariant Phonon::ObjectDescriptionModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const + + Returns data from the item with the given \a index for the specified + \a role. + If the view requests an invalid index, an invalid variant is + returned. + + Reimplemented from QAbstractItemModel. + + \sa QAbstractItemModel::data(), Qt::ItemDataRole +*/ + +/*! + \fn inline Qt::ItemFlags Phonon::ObjectDescriptionModel::flags(const QModelIndex &index) const + \internal + + Reimplemented to show unavailable devices as disabled (but still + selectable). The \a index of the model index for which to return + flags. + +*/ + +/*! + \fn inline QList Phonon::ObjectDescriptionModel::tupleIndexOrder() const + + Returns a list of indexes in the same order as they are in the + model. The indexes come from the ObjectDescription::index + method. + + This is useful to let the user define a list of preference. +*/ + +/*! + \fn inline int Phonon::ObjectDescriptionModel::tupleIndexAtPositionIndex(int positionIndex) const + + Returns the ObjectDescription::index for the tuple + at the given position \a positionIndex. For example a + QComboBox will give you the currentIndex as the + position in the list. But to select the according + AudioOutputDevice using AudioOutputDevice::fromIndex + you can use this method. + + \param positionIndex The position in the list. +*/ + +/*! + \class Phonon::ObjectDescriptionModelDataPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn inline QMimeData *Phonon::ObjectDescriptionModel::mimeData(const QModelIndexList &indexes) const + \internal + + Returns the MIME data that dropMimeData() can use to create new + items. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::moveUp(const QModelIndex &index) + + Moves the item at the given \a index up. In the resulting list + the items at index.row() and index.row() - 1 are swapped. + + Connected views are updated automatically. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::moveDown(const QModelIndex &index) + + Moves the item at the given \a index down. In the resulting list + the items at index.row() and index.row() + 1 are swapped. + + Connected views are updated automatically. +*/ + +/*! + \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(QObject *parent = 0) + + Constructs a ObjectDescription model with the + given \a parent. +*/ + +/*! + \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(const QList > &data, QObject *parent = 0) + + Constructs a ObjectDescription model with the + given \a parent and the given \a data. +*/ + +/*! + \fn inline void Phonon::ObjectDescriptionModel::setModelData(const QList > &data) + + Sets the model data using the list provided by \a data. + + All previous model data is cleared. +*/ + +/*! + \fn inline QList > Phonon::ObjectDescriptionModel::modelData() const + + Returns the model data. + + As the order of the list might have changed this can be different + to what was set using setModelData(). +*/ + +/*! + \fn inline ObjectDescription Phonon::ObjectDescriptionModel::modelData(const QModelIndex &index) const + + Returns one ObjectDescription of the model data for the given \a index. +*/ + +/*! + \fn inline Qt::DropActions Phonon::ObjectDescriptionModel::supportedDropActions() const + + This model supports drag and drop to copy or move + items. +*/ + +/*! + \fn inline bool Phonon::ObjectDescriptionModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) + + Accept drops from other models of the same ObjectDescriptionType. + + The \a data is dropped at the given \a row and \a column; you + also receive the \a parent model index. + + If a valid \a parent is given the dropped items will be inserted + above that item. +*/ + +/*! + \fn inline bool Phonon::ObjectDescriptionModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex()) + + Removes count rows starting with the given row. + + If a valid \a parent is given no rows are removed since this is a + list model. + + Returns true if the rows were successfully removed; otherwise returns false. +*/ + +/*! + \fn inline QStringList Phonon::ObjectDescriptionModel::mimeTypes() const + + Returns a list of supported drag and drop MIME types. Currently + it only supports one type used internally. +*/ + +/*! + \class Phonon::EffectInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::Effect + \inmodule Phonon + \inheaderfile Phonon/Effect + \since 4.4 + \brief The Effect class is used to transform audio streams. + + An effect is a media node which is inserted into a path between a + \l{Phonon::}{MediaObject} and an audio output node, for instance, + an \l{Phonon::}{AudioOutput}. The Effect transforms the media + stream on that path. + + Examples may include simple modifiers, such as fading or pitch + shifting, and more complex mathematical transformations. You can + query the backend for available effects with + BackendCapabilities::availableAudioEffects(). Note that the + effects available is dependent on the underlying system + (DirectDraw, GStreamer, or QuickTime). + + In order to use an effect, insert it into the path as follows: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 19 + + The effect will immediately begin applying it's transformations on + the path. To stop it, remove the Effect from the path. + + To create an effect, you use the \l{Phonon::}{EffectDescription} + class, which you get from + \l{BackendCapabilities::}{availableAudioEffects()}. We give a code + example below. + + \snippet doc/src/snippets/audioeffects.cpp 0 + + An effect can have one or more parameters, which let you alter how + the effect works, for instance, by specifying the depth of a + reverb effect. See the EffectParameter class description for + details. + + Phonon also provides EffectWidget, which lets the user modify the + parameters of an effect an the fly; e.g., with combo boxes. + + \sa {Phonon Module}, EffectWidget +*/ + +/*! + \fn explicit Phonon::Effect::Effect(const EffectDescription &description, QObject *parent = 0) + + Constructs a new effect object with the given \a description and \a parent object. + + The EffectDescription object determines the type of the effect. + + \sa {Phonon::BackendCapabilities::availableAudioEffects()} +*/ + +/*! + \fn Phonon::Effect::Effect(EffectPrivate &dd, QObject *parent) + \internal +*/ + +/*! + \fn Phonon::Effect::~Effect() + \internal +*/ + +/*! + \fn QVariant Phonon::Effect::parameterValue(const EffectParameter ¶meter) const + + Returns the value of the given effect \a parameter. You can fetch + the available parameters for an effect with parameters(). + + \sa setParameterValue(), EffectParameter +*/ + +/*! + \fn void Phonon::Effect::setParameterValue(const EffectParameter ¶meter, const QVariant &value) + + Sets the given effect \a parameter to the specified \a value. + + Parameters for an effect are returned by parameters(). You can + check which QVariant::Type an EffectParameter takes with the + EffectParameter::type() function. + + \sa parameterValue(), EffectParameter +*/ + +/*! + \fn EffectDescription Phonon::Effect::description() const; + + Returns the description of this effect. This is the same + description that was passed to the constructor. +*/ + +/*! + \fn QList Phonon::Effect::parameters() const; + + Returns a list of parameters that this effect provides to control + its behavior. + + \sa EffectParameter, EffectWidget +*/ + +/*! + \class Phonon::EffectPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::AudioOutput + \inmodule Phonon + \inheaderfile Phonon/AudioOutput + \since 4.4 + \brief The AudioOutput class is used to send data to audio output devices. + + The AudioOutput class plays sound over a sound device. The audio + output needs to be connected to a \l{Phonon::}{MediaObject} using + \l{Phonon::}{createPath()}. To start playback, you call + \l{Phonon::MediaObject::}{play()} on the media object. + + \snippet snippets/phonon.cpp 2 + + The class supports changing the volume(). It is also possible to + mute the sound. + + To find out what \l{Phonon::}{AudioOutputDevice}s are available + for AudioOutput, you can call + BackendCapabilities::availableAudioOutputDevices(). A default device is + selected by the backend, but it is possible to set the device to + be used with setOutputDevice(). The outputDeviceChanged() signal + will be emitted if the device changes. + + If an error occurs with the playback, for instance, if no valid + output device is found, the media object will receive a + stateChanged() signal with the \l{Phonon::}{ErrorState}. + + Note that the default values of properties are dependent on the + backend. + + \sa Phonon::VolumeSlider, {Music Player Example}, BackendCapabilities, {Phonon Module} +*/ + +/*! + \property Phonon::AudioOutput::name + + This is the name that appears in Mixer applications that control + the volume of this output. + +*/ + +/*! + \property Phonon::AudioOutput::volume + + This is the current loudness of the output. \omit The volume is a + real value between 0.0 (minimum) and 1.0 (maximum). The volume + follows the sound device used, with 1.0 being the maximum volume + the device can produce. \endomit + + (it is using Stevens' law + to calculate the change in voltage internally). + + \sa volumeDecibel +*/ + +/*! + \property Phonon::AudioOutput::volumeDecibel + + This is the current volume of the output in decibel. + + 0 dB means no change in volume, -6dB means an attenuation of the + voltage to 50% and an attenuation of the power to 25%, -inf dB means + silence. + + \sa volume +*/ + +/*! + \property Phonon::AudioOutput::outputDevice + This property holds the (hardware) destination for the output. + + The default device is determined by the \l{Phonon::}{Category} and the global + configuration for that category. Normally you don't need + to override this setting - letting the user change the global + configuration is the right choice. You can still override the + device though, if you have good reasons to do so. + + \sa outputDeviceChanged() +*/ + +/*! + \property Phonon::AudioOutput::muted + This property tells whether the output is muted. + + Muting the output has the same effect as calling setVolume(0.0). +*/ + +/*! + \fn explicit Phonon::AudioOutput::AudioOutput(Phonon::Category category, QObject *parent = 0) + + Creates a new AudioOutput with the given \a parent that defines + output to a physical device. + + The \a category can be used by mixer applications to group volume + controls of applications into categories. That makes it easier for + the user to identify the programs. + The category is also used for the default output device that is + configured centrally. As an example: often users want to have the + audio signal of a VoIP application go to their USB headset while + all other sounds should go to the internal soundcard. + + \sa Phonon::categoryToString(), outputDevice +*/ + +/*! + \fn explicit Phonon::AudioOutput::AudioOutput(QObject *parent = 0) + + Creates a new AudioOutput that defines output to the system + default device with the \{Phonon::Category::}{NoCategory} category + + \sa Phonon::categoryToString(), outputDevice +*/ + +/*! + \fn Phonon::Category Phonon::AudioOutput::category() const + + Returns the category of this output. + + \sa Phonon::AudioOutput::AudioOutput() +*/ + +/*! + \fn void Phonon::AudioOutput::volumeChanged(qreal newVolume) + + This signal is emitted whenever the volume has changed. As the + volume can change without a call to setVolume (calls over dbus) + this is important to keep a widget showing the current volume up + to date. + + \a newVolume is the new volume level. + + \sa setVolume(), volume() +*/ + +/*! + \fn void Phonon::AudioOutput::mutedChanged(bool muted) + + This signal is emitted when the muted property has changed. The \a muted + value passed by the signal indicates the state of the muted property. + As this property can change by IPC (DBus) calls a UI element showing + the muted property should listen to this signal. +*/ + +/*! + \fn void Phonon::AudioOutput::outputDeviceChanged(const Phonon::AudioOutputDevice &newAudioOutputDevice) + + This signal is emitted when the (hardware) device for the output + has changed. \a newAudioOutputDevice is the new device. + + The change can happen either through setOutputDevice or if the + global configuration for the used category has changed. + + \sa outputDevice +*/ + +/*! + \class Phonon::AudioOutputPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectParameter + \inmodule Phonon + \inheaderfile Phonon/EffectParameter + \since 4.4 + \brief The EffectParameter class describes one parameter of an effect. + + You fetch the parameters of an \l{Phonon::}{Effect} with + \l{Phonon::}{Effect::parameters()}. + + \snippet doc/src/snippets/phononeffectparameter.cpp 0 + + To describe itself, an effect parameter gives a name() and + possibly description() (depending on the backend used). These are + suited to present the effect parameter to the user of a Phonon + application. + + Note that effects are created by the backend, and that + their name and descriptions may vary. + + The value of an effect parameter is stored in a \l{QVariant}, + of which type() is usually \c int or \c double. + + The value is retrieved with \l{Phonon::}{Effect::parameterValue()} + and set with \l{Phonon::Effect::}{setParameterValue()} - both of + which takes the EffectParameter as argument. Note that not all + effect parameters support setting of their value. + + You get the values a parameter can take with possibleValues(); an + empty list is returned if the values are continuous. + + A parameter may also specify default(), minimum(), and maximum() + values. Values are returned as \l{QVariant}s. If the parameter + does not have the requested value, an \l{QVariant::Invalid} + invalid QVariant is returned from these functions. + + The \l{Phonon::}{EffectWidget} provides a widget with which one + can control the parameters of an \l{Phonon::}{Effect}. + + \snippet doc/src/snippets/phononeffectparameter.cpp 1 + + \sa Effect, EffectWidget, {Capabilities Example}, {Phonon Module} +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter() + \internal + + Creates an invalid effect parameter. +*/ + +/*! + \fn Phonon::EffectParameter::~EffectParameter() + + Destroys the effect parameter. +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter(const EffectParameter &other) + + Constructs a copy of the \a other effect parameter. +*/ + +/*! + \fn const QString &Phonon::EffectParameter::name() const + + The name of the parameter. Can be used as the label. + + \return A label for the parameter. +*/ + +/*! + \fn const QString &Phonon::EffectParameter::description() const + + The parameter may come with a description (LADSPA doesn't have a + field for this, so don't expect many effects to provide a + description). + + The description can be used for a tooltip or WhatsThis help. + + \return A text describing the parameter. +*/ + +/*! + \fn QVariant::Type Phonon::EffectParameter::type() const + + Returns the parameter type. + + Common types are QVariant::Int, QVariant::Double, QVariant::Bool and QVariant::String. When + QVariant::String is returned you get the possible values from possibleValues. +*/ + +/*! + \fn bool Phonon::EffectParameter::isLogarithmicControl() const + + Returns whether the parameter should be + displayed using a logarithmic scale. This is particularly useful for + frequencies and gains. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::minimumValue() const + + The minimum value to be used for the control to edit the parameter. + + If the returned QVariant is invalid the value is not bounded from + below. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::maximumValue() const + + The maximum value to be used for the control to edit the parameter. + + If the returned QVariant is invalid the value is not bounded from + above. +*/ + +/*! + \fn QVariant Phonon::EffectParameter::defaultValue() const + + The default value. +*/ + +/*! + \fn QVariantList Phonon::EffectParameter::possibleValues() const + + The possible values to be used for the control to edit the parameter. + + if the value of this parameter is to be picked from predefined values + this returns the list (otherwise it returns an empty QVariantList). +*/ + +/*! + \fn bool Phonon::EffectParameter::operator<(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn bool Phonon::EffectParameter::operator>(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn bool Phonon::EffectParameter::operator==(const EffectParameter &rhs) const + + \internal + compares the ids of the parameters +*/ + +/*! + \fn Phonon::EffectParameter &Phonon::EffectParameter::operator=(const EffectParameter &other) + + Assigns the \a other effect parameter to this parameter and returns + a reference to this parameter. +*/ + +/*! + \enum Phonon::EffectParameter::Hint + + Only for backend developers: + + Flags to set the return values of isToggleControl(), + isLogarithmicControl(), isIntegerControl(), isBoundedBelow() and + isBoundedAbove(). The values of the flags correspond to the values + used for LADSPA effects. + + \value ToggledHint + If this hint is set it means that + the control has only two states: zero and non-zero + (see isToggleControl()). + + \value LogarithmicHint + LADSPA's SAMPLE_RATE hint needs to be translated by the backend + to normal bounds, as the backend knows the sample rate - and the + frontend doesn't (see isLogarithmicControl()). + + \value IntegerHint See isIntegerControl(). +*/ + +/*! + \fn Phonon::EffectParameter::EffectParameter(int parameterId, + const QString &name, EffectParameter::Hints hints, + const QVariant &defaultValue, const QVariant &min = QVariant(), + const QVariant &max = QVariant(), const QVariantList &values = QVariantList(), + const QString &description = QString()) + + Only to be used by backend implementations: + + Creates a new effect parameter. + + \a parameterId This is a number to uniquely identify the + parameter. The id is used for value() and setValue(). + + \a name is the name/label for this parameter. + + \a hints sets the hints for the type of parameter. + + \a defaultValue The value that should be used as a default. + + \a min is the minimum value allowed for this parameter. You only + need to set this if the BoundedBelowHint is set. + + \a max is the maximum value allowed for this parameter. You only + need to set this if the BoundedAboveHint is set. + + The \a values parameter is the values that the effect parameter + can take (only applies if non-continuous) + + \a description is a descriptive text for the parameter + (explaining what it controls) to be used as a tooltip or + WhatsThis help. +*/ + +/*! + \fn int Phonon::EffectParameter::id() const + + \internal + + Returns the parameter's identifier. +*/ + +/*! + \typedef Phonon::AudioOutputInterface + \inmodule Phonon + \internal +*/ + +/*! + \class Phonon::AudioOutputInterface40 + \inmodule Phonon + \since 4.4 + \internal + \brief Interface for AudioOutput objects + +*/ + +/*! + \fn virtual Phonon::AudioOutputInterface40::~AudioOutputInterface40() + \internal +*/ + +/*! + \fn virtual qreal Phonon::AudioOutputInterface40::volume() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::AudioOutputInterface40::setVolume(qreal) = 0 + \internal +*/ + +/*! + \fn virtual int Phonon::AudioOutputInterface40::outputDevice() const = 0 + \internal +*/ + +/*! + \fn virtual bool Phonon::AudioOutputInterface40::setOutputDevice(int) = 0 + \internal +*/ + +/*! + \class Phonon::Path + \inmodule Phonon + \inheaderfile Phonon/Path + \since 4.4 + \brief The Path class describes connections between media nodes. + + In a \l{Building Graphs}{media graph}, \l{Phonon::}{MediaNode}s + are connected by Paths. The multimedia travels in streams over + these paths. + + You create a path between two media nodes using the static + Phonon::createPath() function, which takes two nodes as arguments. + The first argument will send the media stream to the second. + Please refer to the class description of the individual media + nodes and the Phonon \l{Phonon Overview}{overview} to see which + nodes can be connected to each other. + + Paths are also used to insert audio \l{Phonon::}{Effect}s between + two media nodes. The effect will then alter the stream on the + path. Notice that \l{Phonon::}{Effect}s also are media nodes, but + that insertEffect() - instead of Phonon::createPath() - is used to + insert them into the media graph. + + The following code example shows how to create a path between two + media nodes and insert an effect on that path. + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 20 + + \sa Phonon::MediaNode, Phonon::MediaObject, Phonon::AudioOutput, + Phonon::VideoWidget, {Phonon Module} +*/ + +/*! + \fn Phonon::Path::~Path(); + + Destroys this reference to the Path. If the path was valid the connection is not broken + as both the source and the sink MediaNodes still keep a reference to the Path. + + \sa disconnect() +*/ + +/*! + \fn Phonon::Path::Path(); + + Creates an invalid path. + + You can still make it a valid path by calling reconnect. It is + recommended to use the Phonon::createPath() function to create + paths. + + \sa Phonon::createPath(), isValid() +*/ + +/*! + \fn Phonon::Path::Path(const Path &path); + + Constructs a copy of the other \a path specified. + + This constructor is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::Path::isValid() const; + + A path is considered valid if it is connected to two media nodes, + in which case this function returns true. If it is connected to + one or no media nodes, it is consider invalid, and this function + will then return false. +*/ + +/*! + \fn Effect *Phonon::Path::insertEffect(const EffectDescription &desc, Effect *insertBefore = 0); + + Creates and inserts an effect into the path. + + You may insert effects of the same class as often as you like, + but if you insert the same object, the call will fail. + + \a desc is the EffectDescription object for the effect to be inserted. + + If you already inserted an effect you can + tell with \a insertBefore in which order the data gets + processed. If this is \c 0 the effect is appended at the end of + the processing list. If the effect has not been inserted before + the method will do nothing and return \c false. + + Returns a pointer to the effect object if it could be inserted + at the specified position. If \c 0 is returned, the effect was not + inserted. + + Below is a code example for inserting an effect into a path: + + \snippet doc/src/snippets/audioeffects.cpp 0 + + \sa removeEffect(), effects() +*/ + +/*! + \fn bool Phonon::Path::insertEffect(Effect *effect, Effect *insertBefore = 0); + + Inserts the given \a effect into the path before the effect specified by \a insertBefore + and returns true if successful; otherwise returns false. + + If \a insertBefore is zero, the effect is appended to the processing list. + + You may insert effects of the same class as often as you like, but if you insert + the same object, the call will fail. + + \a effect will be inserted right before \a insertBefore. If + \a insertBefore is \c 0, the effect is appended at the end of the + processing list. If the effect has not been inserted before the + method will do nothing and return \c false. + + Returns whether the effect could be inserted at the specified + position. If \c false is returned the effect was not inserted. + + \sa removeEffect(), effects() +*/ + +/*! + \fn bool Phonon::Path::removeEffect(Effect *effect); + + Removes the given \a effect from the path and returns true; otherwise returns false. + + Removes an \a effect from the path. + + If the effect is deleted while it is still connected, the effect will be removed + automatically. + + \omit + \param effect The effect to be removed. + + \return Returns whether the call was successful. If it returns + \c false the effect could not be found in the path, meaning it + has not been inserted before. + \endomit + + \sa insertEffect(), effects() +*/ + +/*! + \fn QList Phonon::Path::effects() const; + + Returns a list of Effect objects that are currently + used as effects. The order in the list determines the order the + signal is sent through the effects. + + \return A list with all current effects. + + \sa insertEffect(), removeEffect() +*/ + +/*! + \fn bool Phonon::Path::reconnect(MediaNode *source, MediaNode *sink); + + Changes the media nodes the path is connected to by connecting the path + to the \a source and \a sink nodes specified. Returns true if successful; + otherwise returns false. + + If unsuccessful, the path remains connected to the same nodes as before. + + \sa Phonon::createPath(), {Phonon Overview} +*/ + +/*! + \fn bool Phonon::Path::disconnect(); + + Tries to disconnect the path from the MediaNodes it is connected to, returning + true if successful or false if unsuccessful. + + If successful, the path is invalidated: isValid() will returns false. +*/ + +/*! + \fn Path &Phonon::Path::operator=(const Path &p); + + Assigns \a p to this Path and returns a reference to this Path. + + This operation is fast thanks to explicit sharing. +*/ + +/*! + \fn bool Phonon::Path::operator==(const Path &p) const; + + Returns true if this Path is equal to \a p; otherwise returns false; +*/ + +/*! + \fn bool Phonon::Path::operator!=(const Path &p) const; + + Returns true if this Path is not equal to \a p; otherwise returns false. +*/ + +/*! + \fn MediaNode *Phonon::Path::source() const; + + Returns the source MediaNode used by the path. +*/ + +/*! + \fn MediaNode *Phonon::Path::sink() const; + + Returns the sink MediaNode used by the path. +*/ + +/*! + \fn Path Phonon::createPath(MediaNode *source, MediaNode *sink); + + \relates Phonon::Path + Creates a new Path connecting the two MediaNodes \a source and \a sink. + + The implementation will automatically select the right format and media type. E.g. connecting a + MediaObject and AudioOutput will create a Path object connecting the audio. This might be + represented as PCM or perhaps even AC3 depending on the AudioOutput object. + + \param source The MediaNode to connect an output from + \param sink The MediaNode to connect to. +*/ + +/*! + \class Phonon::PathPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaObjectInterface + \inmodule Phonon + \since 4.4 + \internal + \brief Backend interface for media sources. + + The backend implementation has to provide two signals, that are not defined + in this interface: + \list + \o \target phonon_MediaObjectInterface_stateChanged + void stateChanged(Phonon::State newstate, Phonon::State oldstate) + + Emitted when the state of the MediaObject has changed. + In case you're not interested in the old state you can also + connect to a slot that only has one State argument. + + \param newstate The state the Player is in now. + \param oldstate The state the Player was in before. + + \o \target phonon_MediaObjectInterface_tick + void tick(qint64 time) + + This signal gets emitted every tickInterval milliseconds. + + \param time The position of the media file in milliseconds. + + \sa setTickInterval() + \sa tickInterval() + \endlist + + \sa MediaObject +*/ + +/*! + \fn virtual Phonon::MediaObjectInterface::~MediaObjectInterface() + \internal +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::remainingTime() const + \internal +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::prefinishMark() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setPrefinishMark(qint32) = 0 + \internal +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::transitionTime() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setTransitionTime(qint32) = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::play() = 0 + \internal + + Requests the playback to start. + + This method is only called if the state transition to PlayingState is possible. + + The backend should react immediately + by either going into PlayingState or BufferingState if the + former is not possible. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::pause() = 0 + \internal + + Requests the playback to pause. + + This method is only called if the state transition to PausedState is possible. + + The backend should react as fast as possible. Go to PausedState + as soon as playback is paused. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::stop() = 0 + \internal + + Requests the playback to be stopped. + + This method is only called if the state transition to StoppedState is possible. + + The backend should react as fast as possible. Go to StoppedState + as soon as playback is stopped. + + A subsequent call to play() will start playback at the beginning of + the media. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::seek(qint64 milliseconds) = 0 + \internal + + Requests the playback to be seeked to the given time. + + The backend does not have to finish seeking while in this function + (i.e. the backend does not need to block the thread until the seek is + finished; even worse it might lead to deadlocks when using a + ByteStream which gets its data from the thread this function would + block). + + As soon as the seek is done the currentTime() function and + the tick() signal will report it. + + \param milliseconds The time where playback should seek to in + milliseconds. +*/ + +/*! + \fn virtual qint32 Phonon::MediaObjectInterface::tickInterval() const = 0 + \internal + + Return the time interval in milliseconds between two ticks. + + Returns the tick interval that it was set to (might not + be the same as you asked for). +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setTickInterval(qint32 interval) = 0 + \internal + + Change the interval the tick signal is emitted. Set \a interval to 0 to + disable the signal. + + \a interval tick interval in milliseconds + + Returns the tick interval that it was set to (might not be the same as you + asked for). + +*/ + +/*! + \fn virtual bool Phonon::MediaObjectInterface::hasVideo() const = 0 + \internal + + Check whether the media data includes a video stream. + + Returns true if the media contains video data. +*/ + +/*! + \fn virtual bool Phonon::MediaObjectInterface::isSeekable() const = 0 + \internal + + If the current media may be seeked this function returns true; + otherwise, false. + + Returns whether the current media may be seeked. +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::currentTime() const = 0 + \internal + + Get the current time (in milliseconds) of the file currently being played. +*/ + +/*! + \fn virtual Phonon::State Phonon::MediaObjectInterface::state() const = 0 + \internal + + Get the current state. +*/ + +/*! + \fn virtual QString Phonon::MediaObjectInterface::errorString() const = 0 + \internal + + A translated string describing the error. +*/ + +/*! + \fn virtual Phonon::ErrorType Phonon::MediaObjectInterface::errorType() const = 0 + \internal + + Tells your program what to do about the error. + + \sa Phonon::ErrorType +*/ + +/*! + \fn virtual qint64 Phonon::MediaObjectInterface::totalTime() const = 0 + \internal + + Returns the total time of the media in milliseconds. + + If the total time is not know return -1. Do not block until it is + known, instead emit the totalTimeChanged signal as soon as the total + time is known or changes. +*/ + +/*! + \fn virtual MediaSource Phonon::MediaObjectInterface::source() const = 0 + \internal + + Returns the current source. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setSource(const MediaSource &) = 0 + \internal + + Sets the current source. When this function is called the MediaObject is + expected to stop all current activity and start loading the new + source (i.e. go into LoadingState). + + It is expected that the + backend now starts preloading the media data, filling the audio + and video buffers and making all media meta data available. It + will also trigger the totalTimeChanged signal. + + If the backend does not know how to handle the source it needs to + change state to Phonon::ErrorState. Don't bother about handling KIO + URLs. It is enough to handle AbstractMediaStream sources correctly. + + \warning Keep the MediaSource object around as long as the backend + uses the AbstractMediaStream returned by the MediaSource. In case + that no other reference to the MediaSource exists and it is set to + MediaSource::autoDelete, the AbstractMediaStream is deleted when the + last MediaSource ref is deleted. +*/ + +/*! + \fn virtual void Phonon::MediaObjectInterface::setNextSource(const MediaSource &source) = 0 + \internal + + Sets the next source to be used for transitions. When a next source + is set playback should continue with the new source. In that case + finished and prefinishMarkReached are not emitted. + + \param source The source to transition to (crossfade/gapless/gap). If + \a source is an invalid MediaSource object then the queue is empty + and the playback should stop normally. + + \warning Keep the MediaSource object around as long as the backend + uses the AbstractMediaStream returned by the MediaSource. In case + that no other reference to the MediaSource exists and it is set to + MediaSource::autoDelete, the AbstractMediaStream is deleted when the + last MediaSource ref is deleted. +*/ + +/*! + \class Phonon::EffectWidget effectwidget.h Phonon/EffectWidget + \inmodule Phonon + \inheaderfile Phonon/EffectWidget + \since 4.4 + \brief The EffectWidget class provides a widget to control the parameters of an Effect. + + The EffectWidget class provides a widget, with which an effects + parameters can be controlled. The widget does not have an API, + and is constructed with the \l{Phonon::}{Effect}, of which + parameters should be controlled. + + \snippet doc/src/snippets/audioeffects.cpp 1 + + The following image shows an example of an effect widget. + + \image effectwidget.png + + Note that some audio effects do not have parameters, and the + widget will then not \l{QWidget::}{show()} at all. + + \sa Effect, BackendCapabilities, EffectDescription, {Phonon Module} +*/ + +/*! + \class Phonon::AbstractAudioOutput + \inmodule Phonon + \internal + \brief Provides a common base class for all audio outputs. + + \sa AudioOutput +*/ + +/*! + \fn Phonon::AbstractAudioOutput::~AbstractAudioOutput() + \internal +*/ + +/*! + \class Phonon::AbstractAudioOutputPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class AudioOutputAdaptor + \inmodule Phonon + \brief Provides an adaptor class for interface org.kde.Phonon.AudioOutput + \internal +*/ + +/*! + \class Phonon::VolumeSlider + \inmodule Phonon + \inheaderfile Phonon/VolumeSlider + \since 4.4 + \brief The VolumeSlider widget provides a slider that is used to control the volume of an audio output device. + + The slider also displays an icon indicating if the volume of the + \l{Phonon::}{AudioOutput} it is connected to is muted. The icon + can be removed with setMuteVisible(). + + It is possible to set the \l{maximumVolume}{maximum} value of the + slider. By default, the minimum and maximum values of the slider + are 0.0 (no sound) to 1.0 (the maximum volume the audio output can + produce). + + Here follows a code example: + + \snippet doc/src/snippets/volumeslider.cpp 0 + + \omit mention how to change the style of the slider. \endomit + + \sa {Phonon Module} +*/ + +/*! + \property Phonon::VolumeSlider::maximumVolume + + This property holds the maximum volume that can be set with this slider. + + By default the maximum value is 1.0 (100%). +*/ + +/*! + \property Phonon::VolumeSlider::orientation + This property holds the orientation of the slider. + + The orientation must be Qt::Vertical (the default) or Qt::Horizontal. +*/ + +/*! + \property Phonon::VolumeSlider::tracking + This property holds whether slider tracking is enabled. + + If tracking is enabled (the default), the volume changes + while the slider is being dragged. If tracking is + disabled, the volume changes only when the user + releases the slider. +*/ + +/*! + \property Phonon::VolumeSlider::pageStep + This property holds the page step. + + The larger of two natural steps that a slider provides and + typically corresponds to the user pressing PageUp or PageDown. + + Defaults to 5 (5% of the voltage). +*/ + +/*! + \property Phonon::VolumeSlider::singleStep + This property holds the single step. + + The smaller of two natural steps that a slider provides and + typically corresponds to the user pressing an arrow key. + + Defaults to 1 (1% of the voltage). +*/ + +/*! + \property Phonon::VolumeSlider::muteVisible + This property holds whether the mute button/icon next to the slider is visible. + + By default the mute button/icon is visible. +*/ + +/*! + \property Phonon::VolumeSlider::iconSize + \brief the icon size used for the mute button/icon. + + The default size is defined by the GUI style. +*/ + +/*! + \fn explicit Phonon::VolumeSlider::VolumeSlider(QWidget *parent = 0) + Constructs a new volume slider with the given \a parent. +*/ + +/*! + \fn explicit Phonon::VolumeSlider::VolumeSlider(AudioOutput *output, QWidget *parent = 0) + Constructs a new volume slider with the given \a output object and \a parent. +*/ + +/*! + \fn Phonon::VolumeSlider::~VolumeSlider() +*/ + +/*! + \fn AudioOutput *Phonon::VolumeSlider::audioOutput() const +*/ + +/*! + \fn void Phonon::VolumeSlider::setAudioOutput(Phonon::AudioOutput *output) + + Sets the audio output object to be controlled by this slider to the specified + \a output object. +*/ + +/*! + \class Phonon::VolumeSliderPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::MediaController + \inmodule Phonon + \inheaderfile Phonon/MediaController + \since 4.4 + \brief The MediaController class controls optional features of a media file/device. + + Some media sources have content that the \l{Phonon::}{MediaObject} + does not provide control over, for instance, chapters in a DVD + file. The functionality the media controller offers is + dependent on the type of media source that is played back. + Commonly, the media controller allows you to: + + \list + \o Navigate between \bold chapters. + \o Navigate between \bold titles. + \o Select between \bold angles. + \endlist + + The \l{Phonon::MediaController::}{Feature} enum explains these + terms in more detail, and their context in playback of CD and DVD. + + The media controller keeps a \l{Phonon::}{MediaObject}, of which + \l{Phonon::MediaObject::currentSource()}{media source} is played + back. You can still call the media object's functions, e.g., + \l{Phonon::MediaObject::}{stop()}; this is all handled correctly + by the media controller. You have the option of letting the media + controller play all titles of a source in sequence by setting the + \l{autoplayTitles()}{autoplay titles} option. + + To start a playback using a media object, you call + \l{Phonon::MediaObject::}{play()} on the media object. To play a + specific title, use setCurrentTitle() and then call + \l{Phonon::MediaObject::}{play()}. + + \warning The Phonon::MediaController class is not yet supported by + Qt backends. + + \sa {Phonon Module} +*/ + +/*! + \fn int Phonon::MediaController::availableAudioChannels() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::availableAudioChannelsChanged() + \internal +*/ + +/*! + \fn QList Phonon::MediaController::availableSubtitles() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::availableSubtitlesChanged() + \internal +*/ + +/*! + \fn AudioChannelDescription Phonon::MediaController::currentAudioChannel() const + \internal +*/ + +/*! + \fn SubtitleDescription Phonon::MediaController::currentSubtitle() const + \internal +*/ + +/*! + \fn void Phonon::MediaController::setCurrentAudioChannel(const Phonon::AudioChannelDescription &stream) + \internal +*/ + +/*! + \fn void Phonon::MediaController::setCurrentSubtitle(const Phonon::SubtitleDescription &stream) + \internal +*/ + +/*! + \fn Phonon::BackendCapabilities::availableAudioCaptureDevices() + \internal +*/ + +/*! + \fn Phonon::BackendCapabilities::Notifier::availableAudioCaptureDevicesChanged() + \internal +*/ + +/*! + \enum Phonon::MediaController::Feature + + The values of this enum are interpreted differently depending on + the type of media source, e.g., DVD or CD. We give examples for + these sources. + + \value Angles In the VOB (DVD) format, it is possible to to give + several video streams of the same scene, each of which displays + the scene from a different angle. The DVD viewer can then change + between these angles. + + \value Chapters In the VOB format, chapters are points in a + single video stream that can be played and seeked to + separately. + + \value Titles On a CD, a title is a separate sound track. On DVD, + a title is a separate VOB file. + +*/ + +/*! + \fn Phonon::MediaController::MediaController(MediaObject *parent) + + Constructs a new MediaController with the media object (\a parent) + to be used by the media controller. + + \sa MediaObject, Feature +*/ + +/*! + \fn Phonon::MediaController::~MediaController() +*/ + +/*! + \fn Features Phonon::MediaController::supportedFeatures() const +*/ + +/*! + \fn int Phonon::MediaController::availableAngles() const + + Returns the available angles that is available for the current + media source. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentAngle() const + + Returns the angle that is currently used. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::availableChapters() const + + Returns the number of chapters the current media source + contains. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentChapter() const + + Returns the chapter that is currently being played back. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::availableTitles() const + + Returns the number of titles that the current media source + contains. + + \sa Feature +*/ + +/*! + \fn int Phonon::MediaController::currentTitle() const + + Returns the title that is currently played back. + + The current title is 0 (the first) by default. + + \sa Feature +*/ + +/*! + \fn bool Phonon::MediaController::autoplayTitles() const + + Returns true if titles will automatically be played when the media + is played; otherwise returns false. + + The media controller will play the titles of the media source in + sequence when the media object's \l{Phonon::MediaObject::}{play()} + function is called. If the autoplay option is disabled, the media + object will play the + \l{Phonon::}{MediaController::currentTitle()}{current title} and then + finish the playback. + + \sa setAutoplayTitles(), currentTitle() +*/ + +/*! + \fn void Phonon::MediaController::setAutoplayTitles(bool enable) + + Sets the titles to play automatically when the media is played if + \a enable is true; otherwise disables this option. + + The media controller will play the titles of the media source in + sequence when the media object's \l{Phonon::MediaObject::}{play()} + function is called. If the autoplay option is disabled, the media + object will play the + \l{Phonon::}{MediaController::currentTitle()}{current title} and then + finish the playback. + + \sa autoplayTitles(), currentTitle() +*/ + +/*! + \fn void Phonon::MediaController::setCurrentAngle(int angleNumber) + + Sets the current angle to the given \a angleNumber if the media + file or device supports navigation by angle number. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::setCurrentChapter(int chapterNumber) + + Sets the current chapter to the given \a chapterNumber if the media + file or device supports navigation by chapter number. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::setCurrentTitle(int titleNumber) + + Skips to the given title \a titleNumber. + + If it was playing before the title change it will start playback on the new title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::nextTitle() + + Skips to the next title. + + If it was playing before the title change it will start playback on the next title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::previousTitle() + + Skips to the previous title. + + If it was playing before the title change it will start playback on the previous title if + autoplayTitles is enabled. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableAnglesChanged(int availableAngles) + + This signal is emitted whenever the number of available angles changes. + The new number of available angles is given by \a availableAngles. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::angleChanged(int angleNumber) + + This signal is emitted whenever the current angle changes. + The new angle number is given by \a angleNumber. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableChaptersChanged(int availableChapters) + + This signal is emitted whenever the number of available chapters changes. + The new number of available chapters is given by \a availableChapters. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::chapterChanged(int chapterNumber) + + This signal is emitted whenever the current chapter changes. + The new chapter number is given by \a chapterNumber. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::availableTitlesChanged(int availableTitles) + + This signal is emitted whenever the number of available titles changes. + The new number of available titles is given by \a availableTitles. + + \sa Feature +*/ + +/*! + \fn void Phonon::MediaController::titleChanged(int titleNumber) + + This signal is emitted whenever the current title changes. + The new title number is given by \a titleNumber. + + \sa Feature +*/ + +/*! + \class Phonon::VideoWidget + \inmodule Phonon + \inheaderfile Phonon/VideoWidget + \since 4.4 + \ingroup advanced + \ingroup multimedia + \brief The VideoWidget class provides a widget that is used to display video. + + The VideoWidget class renders the video of a media stream on a + QWidget. It is connected to the \l{Phonon::}{MediaObject}, of + which video stream it should render. You connect the two objects + using the Phonon::createPath() function. + + The widget has some possibilities to manipulate the video + stream. You can change the brightness(), hue(), saturation(), + and contrast(). + + Resizing of the video is handled automatically, but you can affect + the way the video is resized with the aspectRatio and scaleMode + properties. By default, the widget will use the aspect ratio of + the video stream itself. + + The video widget takes the size of the video when it receives a new video + stream (i.e., when a new MediaSource is set on the MediaObject to which it is + connected). If you need to know the size of the video, you can call + \l{QWidget::}{sizeHint()} after the video has been loaded (i.e., after the + MediaObject leaves the \l{Phonon::}{LoadingState}). + + It is also possible to go to \l{fullScreen}{full screen} mode. + + A typical example of usage follows below: + + \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 21 + + \sa {Phonon Module} +*/ + +/*! + \fn Phonon::VideoWidget::VideoWidget(QWidget *parent = 0) + + Constructs a new video widget with the specified \a parent. +*/ + +/*! + \fn Phonon::VideoWidget::VideoWidget(VideoWidgetPrivate &d, QWidget *parent) + \internal + + Constructs a new video widget with the specified \a parent. +*/ + +/*! + \fn bool Phonon::VideoWidget::event(QEvent *) + \reimp +*/ + +/*! + \fn void Phonon::VideoWidget::mouseMoveEvent(QMouseEvent *) + \reimp +*/ + +/*! + \enum Phonon::VideoWidget::ScaleMode + + The ScaleMode enum describes how to treat aspect ratio during + resizing of video. + + \value FitInView The video will be fitted to fill the view + keeping aspect ratio. + \value ScaleAndCrop The video is scaled +*/ + +/*! + \property Phonon::VideoWidget::fullScreen + This property holds whether the video is shown using the complete + screen. + + The property differs from QWidget::fullScreen in that it is + writeable. + + By default the widget is not shown in fullScreen. + + \warning When switching to full screen mode using setFullScreen(), + the widget onto which the video is rendered is shown as a + top-level window. Key event forwarding is handled by VideoWidget, + but if you need to handle other events, e.g., mouse events, you + should handle fullscreen mode yourself. +*/ + +/*! + \property Phonon::VideoWidget::aspectRatio + Defaults to AspectRatioAuto. + + \sa AspectRatio +*/ + +/*! + \property Phonon::VideoWidget::scaleMode + + If the size of the widget and the size of the video are not equal. + The video will be zoomed to fit the widget. The smaller zoom + (AddBarsScaleMode) adds black bars at the left/right or top/bottom to + make all of the image visible (default). The bigger zoom (ExpandMode) + fills the widget completely, keeping all information in one direction + and leaving parts of the image outside of the widget in the other + direction. +*/ + +/*! + \property Phonon::VideoWidget::brightness + + This property holds brightness of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::contrast + + This property holds the contrast of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::hue + + This property holds the hue of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \property Phonon::VideoWidget::saturation + + This property holds saturation of the video. + + Default is 0. Acceptable values are in range of -1, 1. +*/ + +/*! + \enum Phonon::VideoWidget::AspectRatio + + Defines the width:height to be used for the video. + + \value AspectRatioAuto + Let the decoder find the aspect ratio automatically from the + media file (this is the default). + + \value AspectRatioWidget + Fits the video into the widget making the aspect ratio depend + solely on the size of the widget. This way the aspect ratio + is freely resizeable by the user. + + \value AspectRatio4_3 + Make width/height == 4/3, which is the old TV size and + monitor size (1024/768 == 4/3). (4:3) + + \value AspectRatio16_9 + Make width/height == 16/9, which is the size of most current + media. (16:9) +*/ + +/*! + \fn void Phonon::VideoWidget::exitFullScreen() + + Convenience slot, calling setFullScreen(false) +*/ + + +/*! + \fn void Phonon::VideoWidget::enterFullScreen() + + Convenience slot, calling setFullScreen(true) +*/ + +/*! + \class Phonon::VideoWidgetInterface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual Phonon::VideoWidgetInterface::~VideoWidgetInterface() +*/ + +/*! + \fn virtual Phonon::VideoWidget::AspectRatio Phonon::VideoWidgetInterface::aspectRatio() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setAspectRatio(Phonon::VideoWidget::AspectRatio ratio) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::brightness() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setBrightness(qreal) = 0 + \internal +*/ + +/*! + \fn virtual Phonon::VideoWidget::ScaleMode Phonon::VideoWidgetInterface::scaleMode() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setScaleMode(Phonon::VideoWidget::ScaleMode mode) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::contrast() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setContrast(qreal) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::hue() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setHue(qreal) = 0 + \internal +*/ + +/*! + \fn virtual qreal Phonon::VideoWidgetInterface::saturation() const = 0 + \internal +*/ + +/*! + \fn virtual void Phonon::VideoWidgetInterface::setSaturation(qreal) = 0 + \internal +*/ + +/*! + \fn virtual QWidget *Phonon::VideoWidgetInterface::widget() = 0 + \internal +*/ + +/*! + \class Phonon::PlatformPlugin + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn virtual AbstractMediaStream *Phonon::PlatformPlugin::createMediaStream(const QUrl &url, QObject *parent) = 0 + + Creates a AbstractMediaStream object with the given \a parent that provides the data + for the given URL specified by \a url. + \omit + On KDE this uses KIO. + \endomit +*/ + +/*! + \fn virtual QIcon Phonon::PlatformPlugin::icon(const QString &name) const = 0 + + Returns the icon for the given icon name. +*/ + +/*! + \fn virtual void Phonon::PlatformPlugin::notification(const char *notificationName, const QString &text, + const QStringList &actions, QObject *receiver, const char *actionSlot) const = 0 + + Shows a notification pop-up with the given \a notificationName and \a text. + Each action in the associated list of \a actions is connected to the \a actionSlot + of the specified \a receiver object, which is expected to act on the actions as + they are triggered by the user. +*/ + +/*! + \fn virtual QString Phonon::PlatformPlugin::applicationName() const = 0 + + Returns the name of the application. For most Qt application this is + QCoreApplication::applicationName(), but for KDE this is overridden by KAboutData. +*/ + + +/*! + \fn virtual QObject *Phonon::PlatformPlugin::createBackend() = 0 + + Creates a backend object. This way the platform can decide the backend preference. +*/ + +/*! + \fn virtual QObject *Phonon::PlatformPlugin::createBackend(const QString &library, const QString &version) = 0 + + Using the library loader of the platform, loads a given backend provided the + specified \a library and \a version. +*/ + +/*! + \fn virtual bool Phonon::PlatformPlugin::isMimeTypeAvailable(const QString &mimeType) const = 0 + + Tries to check whether the default backend supports the MIME type specified by \a mimeType + without loading the actual backend library. + \omit + On KDE this reads the MIME type list from the .desktop file of + the backend. + \endomit +*/ + +/*! + \fn virtual void Phonon::PlatformPlugin::saveVolume(const QString &outputName, qreal volume) = 0 + + Saves the volume for the given output. +*/ + +/*! + \fn virtual qreal Phonon::PlatformPlugin::loadVolume(const QString &outputName) const = 0 + + Loads the volume for the given output. +*/ + +/*! + \class Phonon::MediaNode + \inmodule Phonon + \inheaderfile Phonon/MediaNode + \since 4.4 + \brief The MediaNode class is the base class for all nodes in a media graph. + + In all phonon applications, one builds a media graph consisting of + MediaNodes. The graph will take multimedia content, e.g., from a + file, as input. After its nodes have processed the multimedia, the + graph will output the media again, e.g., to a sound card. + + The multimedia content is streamed over \l{Phonon::}{Path}s + between the nodes in the graph. You can query the paths that are + connected to a media node with inputPaths() and outputPaths(). + + You can check whether the node is implemented by the current + backend by calling isValid(). This does not guarantee that an + instance of the class works as expected, but that the backend has + implemented functionality for the class. + + Currently, Phonon has four media nodes: \l{Phonon::}{MediaObject}, + \l{Phonon::}{AudioOutput}, \l{Phonon::}{VideoWidget}, and \l{Phonon::}{Effect}. + Please refer to their class descriptions for details about their usage, and to + find out which nodes can be connected to each other. See also \l{Building + Graphs} in Phonon's \l{Phonon Overview}{overview} document. + + Two nodes are connected to each other using the + Phonon::createPath() or \l{Phonon::}{Path::insertEffect()} + functions (only \l{Phonon::Effect}s use + \l{Phonon::Path::}{insertEffect()}). We show a code example below, + in which we build a media graph for video playback and then query + its media nodes for their \l{Phonon::}{Path}s: + + \snippet doc/src/snippets/medianodesnippet.cpp 0 + + When you create a Phonon application, you will likely build the + graph yourself. This makes isValid() the most useful function of + this class. The other two functions help navigate the graph, which + you do not need to do as you created the nodes yourself. + + \sa {Phonon Overview}, Phonon::MediaObject, + Phonon::AudioOutput, Phonon::VideoWidget, {Phonon Module} +*/ + +/*! + \fn virtual Phonon::MediaNode::~MediaNode() + + Destroys the media node and any paths connecting it to other + nodes. Any \l{Phonon::}{Effect}s connected to these paths will + also be deleted. +*/ + +/*! + \fn bool Phonon::MediaNode::isValid() const + + Returns true if the backend provides an implementation of this + class; otherwise returns false. + + This does not guarantee that instances of the class works as + expected, but that the backend has implemented the functionality + for this class. For instance, Qt's GStreamer backend will return + true for instances of the \l{Phonon::}{AudioOutput} class, even if + there is a problem with GStreamer and it could not play sound. + +*/ + +/*! + \fn QList Phonon::MediaNode::inputPaths() const + + Returns the paths that inputs multimedia to this media node. + + \sa outputPaths() +*/ + +/*! + \fn QList Phonon::MediaNode::outputPaths() const + + Returns the paths to which this media node outputs media. + + \sa inputPaths() +*/ + +/*! + \fn Phonon::MediaNode::MediaNode(MediaNodePrivate &dd) + \internal +*/ + +/*! + \class Phonon::GlobalConfig + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn Phonon::GlobalConfig::GlobalConfig() + \internal +*/ + +/*! + \fn Phonon::GlobalConfig::~GlobalConfig() + \internal +*/ + +/*! + \fn QList Phonon::GlobalConfig::audioOutputDeviceListFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const + \internal +*/ + +/*! + \fn int Phonon::GlobalConfig::audioOutputDeviceFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const + \internal +*/ + +/*! + \class Phonon::ObjectDescriptionData + \inmodule Phonon + \since 4.4 + \internal + \brief Data class for objects describing devices or features of the backend. + + \sa Phonon::BackendCapabilities +*/ + +/*! + \fn bool Phonon::ObjectDescriptionData::operator==(const ObjectDescriptionData &otherDescription) const + + Returns \c true if this ObjectDescription describes the same + as \a otherDescription; otherwise returns \c false. +*/ + +/*! + \fn QString Phonon::ObjectDescriptionData::name() const + + Returns the name of the capture source. + + \return A string that should be presented to the user to + choose the capture source. +*/ + +/*! + \fn QString Phonon::ObjectDescriptionData::description() const + + Returns a description of the capture source. This text should + make clear what sound source this is, which is sometimes hard + to describe or understand from just the name. + + \return A string describing the capture source. +*/ + +/*! + \fn QVariant Phonon::ObjectDescriptionData::property(const char *name) const + + Returns a named property. + + If the property is not set an invalid value is returned. + + \sa propertyNames() +*/ + +/*! + \fn QList Phonon::ObjectDescriptionData::propertyNames() const + + Returns all names that return valid data when property() is called. + + \sa property() +*/ + +/*! + \fn bool Phonon::ObjectDescriptionData::isValid() const + + Returns true if the Tuple is valid (index != -1); otherwise returns + false. +*/ + +/*! + \fn int Phonon::ObjectDescriptionData::index() const + + A unique identifier for this device/. Used internally + to distinguish between the devices/. + + \return An integer that uniquely identifies every device. +*/ + +/*! + \fn static ObjectDescriptionData *Phonon::ObjectDescriptionData::fromIndex(ObjectDescriptionType type, int index) + \internal +*/ + +/*! + \fn Phonon::ObjectDescriptionData::~ObjectDescriptionData() + \internal +*/ + +/*! + \fn Phonon::ObjectDescriptionData::ObjectDescriptionData(ObjectDescriptionPrivate * = 0) + \internal +*/ + +/*! + \class Phonon::AddonInterface + \inmodule Phonon + \since 4.4 + \internal + \brief Interface for Menu, Chapter, Angle and Title/Track control. +*/ + +/*! + \fn virtual Phonon::AddonInterface::~AddonInterface() + \internal +*/ + +/*! + \enum Phonon::AddonInterface::Interface + + This enum describes the type of interface represented by an AddonInterface object. + + \value NavigationInterface + \value ChapterInterface + \value AngleInterface + \value TitleInterface +*/ + +/*! + \enum Phonon::AddonInterface::NavigationCommand + \internal + \value Menu1Button +*/ + +/*! + \enum Phonon::AddonInterface::ChapterCommand + \internal + \value availableChapters + \value chapter + \value setChapter +*/ + +/*! + \enum Phonon::AddonInterface::AngleCommand + \internal + \value availableAngles + \value angle + \value setAngle +*/ + +/*! + \enum Phonon::AddonInterface::TitleCommand + \internal + \value availableTitles + \value title + \value setTitle + \value autoplayTitles + \value setAutoplayTitles +*/ + +/*! + \fn virtual bool Phonon::AddonInterface::hasInterface(Interface iface) const = 0 + \internal +*/ + +/*! + \fn virtual QVariant Phonon::AddonInterface::interfaceCall(Interface iface, int command, + const QList &arguments) = 0 + \internal +*/ + +/*! + \class Phonon::MediaNodePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \namespace Phonon::Factory + \inmodule Phonon + \internal +*/ + +/*! + \fn Sender *Phonon::Factory::sender() + + Returns a pointer to the object emitting the signals. + + \sa Sender::backendChanged() +*/ + +/*! + \fn QObject *Phonon::Factory::createMediaObject(QObject *parent = 0) + + Create a new backend object for a MediaObject. + + \return a pointer to the MediaObject the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createEffect(int effectId, QObject *parent = 0) + + Create a new backend object for a Effect. + + \return a pointer to the Effect the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createVolumeFaderEffect(QObject *parent = 0) + + Create a new backend object for a VolumeFaderEffect. + + \return a pointer to the VolumeFaderEffect the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createAudioOutput(QObject *parent = 0) + + Create a new backend object for a AudioOutput. + + \return a pointer to the AudioOutput the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::createVideoWidget(QObject *parent = 0) + + Create a new backend object for a VideoWidget. + + \return a pointer to the VideoWidget the backend provides. +*/ + +/*! + \fn QObject *Phonon::Factory::backend(bool createWhenNull = true) + + \return a pointer to the backend interface. +*/ + +/*! + \fn QString Phonon::Factory::identifier() + + Unique identifier for the Backend. Can be used in configuration files + for example. +*/ + + +/*! + \fn QString Phonon::Factory::backendName() + + Get the name of the Backend. + \omit + It's the name from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendComment() + + Get the comment of the Backend. + \omit + It's the comment from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendVersion() + + Get the version of the Backend. + \omit + It's the version from the .desktop file. + \endomit + + The version is especially interesting if there are several versions + available for binary incompatible versions of the backend's media + framework. +*/ + +/*! + \fn QString Phonon::Factory::backendIcon() + + Get the icon (name) of the Backend. + \omit + It's the icon from the .desktop file. + \endomit +*/ + +/*! + \fn QString Phonon::Factory::backendWebsite() + + Get the website of the Backend. + \omit + It's the website from the .desktop file. + \endomit +*/ + +/*! + \fn QObject *Phonon::Factory::registerQObject(QObject *object) + + Registers the given backend \a object with the factory. +*/ + +/*! + \fn bool Phonon::Factory::isMimeTypeAvailable(const QString &mimeType) +*/ + +/*! + \fn void Phonon::Factory::registerFrontendObject(MediaNodePrivate *) + \internal +*/ + +/*! + \fn void Phonon::Factory::deregisterFrontendObject(MediaNodePrivate *) + \internal +*/ + +/*! + \fn void Phonon::Factory::setBackend(QObject *) +*/ + +/*! + \fn PlatformPlugin *Phonon::Factory::platformPlugin() +*/ + +/*! +/*! + \class Phonon::AbstractMediaStreamPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::FrontendInterfacePrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectWidgetPrivate + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::IODeviceStream + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \fn explicit Phonon::IODeviceStream::IODeviceStream(QIODevice *ioDevice, QObject *parent = 0) + \internal + + Creates a new IODeviceStream with the given \a ioDevice and \a + parent. + +*/ + +/*! + \fn Phonon::IODeviceStream::~IODeviceStream() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::reset() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::needData() + \internal +*/ + +/*! + \fn void Phonon::IODeviceStream::seekStream(qint64) + \internal +*/ + +/*! + \namespace Phonon::Platform + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::EffectDescriptionModel + \inmodule Phonon + \brief provides a item view model containing available audio effects. + +*/ + +/*! + \typedef Phonon::SubtitleDescription + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::SubtitleDescriptionModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioChannelDescription + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioChannelDescriptionModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioCaptureDevice + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::AudioCaptureDeviceModel + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::CleanUpFunction + \inmodule Phonon + \internal +*/ + +/*! + \typedef Phonon::QObjectPair + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \typedef Phonon::AudioOutputDeviceModel + \inmodule Phonon + \brief provides an item view model containing available audio output devices. + +*/ + +/*! + \fn uint Phonon::qHash(const Phonon::EffectParameter ¶m) + \internal + +*/ + +/*! + \fn Phonon::CleanUpGlobalStatic::~CleanUpGlobalStatic() + \internal +*/ + +/*! + \class Phonon::ConstIface + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::CleanUpGlobalStatic + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class Phonon::EffectParameterPrivate + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::QSettingsGroup + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \class Phonon::MediaNodeDestructionHandler + \inmodule Phonon + \since 4.4 + \internal + +*/ + +/*! + \fn Phonon::MediaNodeDestructionHandler::~MediaNodeDestructionHandler() + \internal + Called from Base::~Base if this object was registered + using BasePrivate::addDestructionHandler(). +*/ + +/*! + \fn Phonon::MediaNodeDestructionHandler::phononObjectDestroyed(MediaNodePrivate *) + \internal +*/ + +/*! + \fn explicit Phonon::EffectWidget::EffectWidget(Effect *effect, QWidget *parent = 0) + \internal + + Constructs a new EffectWidget for the specified \a effect and with + the specified \a parent. +*/ + +/*! + \fn Phonon::EffectWidget::~EffectWidget() + \internal +*/ + +/*! + \fn QDebug Phonon::operator<<(QDebug s, const ObjectDescription &o) + \internal +*/ + +/*! + \class Phonon::ListModelHelper + \inmodule Phonon + \since 4.4 + \internal +*/ + +/*! + \class AudioOutputInterface42 + \inmodule Phonon + \since 4.4 + \internal +*/ + diff --git a/doc/src/classes/q3asciicache.qdoc b/doc/src/classes/q3asciicache.qdoc new file mode 100644 index 0000000..43537cc --- /dev/null +++ b/doc/src/classes/q3asciicache.qdoc @@ -0,0 +1,465 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3AsciiCache + \brief The Q3AsciiCache class is a template class that provides a cache based on char* keys. + \compat + + Q3AsciiCache is implemented as a template class. Define a template + instance Q3AsciiCache\ to create a cache that operates on + pointers to X (X*). + + A cache is a least recently used (LRU) list of cache items. The + cache items are accessed via \c char* keys. For Unicode keys use + the Q3Cache template instead, which uses QString keys. A Q3Cache + has the same performace as a Q3AsciiCache. + + Each cache item has a cost. The sum of item costs, totalCost(), + will not exceed the maximum cache cost, maxCost(). If inserting a + new item would cause the total cost to exceed the maximum cost, + the least recently used items in the cache are removed. + + Apart from insert(), by far the most important function is find() + (which also exists as operator[]()). This function looks up an + item, returns it, and by default marks it as being the most + recently used item. + + There are also methods to remove() or take() an object from the + cache. Calling \link Q3PtrCollection::setAutoDelete() + setAutoDelete(TRUE)\endlink tells the cache to delete items that + are removed. The default is to not delete items when then are + removed (i.e., remove() and take() are equivalent). + + When inserting an item into the cache, only the pointer is copied, + not the item itself. This is called a shallow copy. It is possible + to make the cache copy all of the item's data (known as a deep + copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a cache and reimplement newItem() if you want deep copies. + + When removing a cache item the virtual function + Q3PtrCollection::deleteItem() is called. Its default implementation + in Q3AsciiCache is to delete the item if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + There is a Q3AsciiCacheIterator which may be used to traverse the + items in the cache in arbitrary order. + + \sa Q3AsciiCacheIterator, Q3Cache, Q3IntCache +*/ + +/*! + \fn Q3AsciiCache::Q3AsciiCache( const Q3AsciiCache &c ) + + \internal + + Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. +*/ + + +/*! + \fn Q3AsciiCache::Q3AsciiCache( int maxCost, int size, bool caseSensitive, bool copyKeys ) + + Constructs a cache whose contents will never have a total cost + greater than \a maxCost and which is expected to contain less than + \a size items. + + \a size is actually the size of an internal hash array; it's + usually best to make it prime and at least 50% bigger than the + largest expected number of items in the cache. + + Each inserted item has an associated cost. When inserting a new + item, if the total cost of all items in the cache will exceed \a + maxCost, the cache will start throwing out the older (least + recently used) items until there is enough room for the new item + to be inserted. + + If \a caseSensitive is TRUE (the default), the cache keys are case + sensitive; if it is FALSE, they are case-insensitive. + Case-insensitive comparison only affects the 26 letters in + US-ASCII. If \a copyKeys is TRUE (the default), Q3AsciiCache makes + a copy of the cache keys, otherwise it copies just the const char + * pointer - slightly faster if you can guarantee that the keys + will never change, but very risky. +*/ + +/*! + \fn Q3AsciiCache::~Q3AsciiCache() + + Removes all items from the cache and destroys it. + All iterators that access this cache will be reset. +*/ + +/*! + \fn Q3AsciiCache& Q3AsciiCache::operator=( const Q3AsciiCache &c ) + + \internal + + Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn int Q3AsciiCache::maxCost() const + + Returns the maximum allowed total cost of the cache. + + \sa setMaxCost() totalCost() +*/ + +/*! + \fn int Q3AsciiCache::totalCost() const + + Returns the total cost of the items in the cache. This is an + integer in the range 0 to maxCost(). + + \sa setMaxCost() +*/ + +/*! + \fn void Q3AsciiCache::setMaxCost( int m ) + + Sets the maximum allowed total cost of the cache to \a m. If the + current total cost is greater than \a m, some items are removed + immediately. + + \sa maxCost() totalCost() +*/ + +/*! + \fn uint Q3AsciiCache::count() const + + Returns the number of items in the cache. + + \sa totalCost() size() +*/ + +/*! + \fn uint Q3AsciiCache::size() const + + Returns the size of the hash array used to implement the cache. + This should be a bit bigger than count() is likely to be. +*/ + +/*! + \fn bool Q3AsciiCache::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. +*/ + +/*! + \fn bool Q3AsciiCache::insert( const char *k, const type *d, int c, int p ) + + Inserts the item \a d into the cache using key \a k, and with an + associated cost of \a c. Returns TRUE if the item is successfully + inserted. Returns FALSE if the item is not inserted, for example, + if the cost of the item exceeds maxCost(). + + The cache's size is limited, and if the total cost is too high, + Q3AsciiCache will remove old, least recently used items until there + is room for this new item. + + Items with duplicate keys can be inserted. + + The parameter \a p is internal and should be left at the default + value (0). + + \warning If this function returns FALSE, you must delete \a d + yourself. Additionally, be very careful about using \a d after + calling this function, because any other insertions into the + cache, from anywhere in the application or within Qt itself, could + cause the object to be discarded from the cache and the pointer to + become invalid. +*/ + +/*! + \fn bool Q3AsciiCache::remove( const char *k ) + + Removes the item with key \a k and returns TRUE if the item was + present in the cache; otherwise returns FALSE. + + The item is deleted if auto-deletion has been enabled, i.e., if + you have called \link Q3PtrCollection::setAutoDelete() + setAutoDelete(TRUE)\endlink. + + If there are two or more items with equal keys, the one that was + inserted last is removed. + + All iterators that refer to the removed item are set to point to + the next item in the cache's traversal order. + + \sa take(), clear() +*/ + +/*! + \fn type *Q3AsciiCache::take( const char *k ) + + Takes the item associated with \a k out of the cache without + deleting it and returns a pointer to the item taken out, or 0 + if the key does not exist in the cache. + + If there are two or more items with equal keys, the one that was + inserted last is taken. + + All iterators that refer to the taken item are set to point to the + next item in the cache's traversal order. + + \sa remove(), clear() +*/ + +/*! + \fn void Q3AsciiCache::clear() + + Removes all items from the cache, and deletes them if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink has been + enabled. + + All cache iterators that operate on this cache are reset. + + \sa remove() take() +*/ + +/*! + \fn type *Q3AsciiCache::find( const char *k, bool ref ) const + + Returns the item with key \a k, or 0 if the key does not exist + in the cache. If \a ref is TRUE (the default), the item is moved + to the front of the least recently used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. +*/ + +/*! + \fn type *Q3AsciiCache::operator[]( const char *k ) const + + Returns the item with key \a k, or 0 if \a k does not exist in + the cache, and moves the item to the front of the least recently + used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. + + This is the same as find( k, TRUE ). + + \sa find() +*/ + +/*! + \fn void Q3AsciiCache::statistics() const + + A debug-only utility function. Prints out cache usage, hit/miss, + and distribution information using qDebug(). This function does + nothing in the release library. +*/ + +/*! + \class Q3AsciiCacheIterator + \brief The Q3AsciiCacheIterator class provides an iterator for Q3AsciiCache collections. + \compat + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. If new objects are inserted into the cache + while the iterator is active, the iterator may or may not see + them. + + Multiple iterators are completely independent, even when they + operate on the same Q3AsciiCache. Q3AsciiCache updates all iterators + that refer an item when that item is removed. + + Q3AsciiCacheIterator provides an operator++() and an operator+=() + to traverse the cache; current() and currentKey() to access the + current cache item and its key. It also provides atFirst() and + atLast(), which return TRUE if the iterator points to the first or + last item in the cache respectively. The isEmpty() function + returns TRUE if the cache is empty; and count() returns the number + of items in the cache. + + Note that atFirst() and atLast() refer to the iterator's arbitrary + ordering, not to the cache's internal least recently used list. + + \sa Q3AsciiCache +*/ + +/*! + \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator( const Q3AsciiCache &cache ) + + Constructs an iterator for \a cache. The current iterator item is + set to point to the first item in the \a cache. +*/ + +/*! + \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator (const Q3AsciiCacheIterator & ci) + + Constructs an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current() but moves + independently from there on. +*/ + +/*! + \fn Q3AsciiCacheIterator& Q3AsciiCacheIterator::operator=( const Q3AsciiCacheIterator &ci ) + + Makes this an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently thereafter. +*/ + +/*! + \fn uint Q3AsciiCacheIterator::count() const + + Returns the number of items in the cache over which this iterator + operates. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3AsciiCacheIterator::isEmpty() const + + Returns TRUE if the cache is empty, i.e. count() == 0; otherwise + returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3AsciiCacheIterator::atFirst() const + + Returns TRUE if the iterator points to the first item in the + cache; otherwise returns FALSE. Note that this refers to the + iterator's arbitrary ordering, not to the cache's internal least + recently used list. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3AsciiCacheIterator::atLast() const + + Returns TRUE if the iterator points to the last item in the cache; + otherwise returns FALSE. Note that this refers to the iterator's + arbitrary ordering, not to the cache's internal least recently + used list. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3AsciiCacheIterator::toFirst() + + Sets the iterator to point to the first item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toLast() isEmpty() +*/ + +/*! + \fn type *Q3AsciiCacheIterator::toLast() + + Sets the iterator to point to the last item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toFirst() isEmpty() +*/ + +/*! + \fn Q3AsciiCacheIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3AsciiCacheIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn const char *Q3AsciiCacheIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the cache or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator+=( uint jump ) + + Returns the item \a jump positions after the current item, or 0 + if it is beyond the last item. Makes this the current item. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item, or 0 + if it is before the first item. Makes this the current item. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator++() + + Prefix ++ makes the iterator point to the item just after + current(), and makes that the new current item for the iterator. If + current() was the last item, operator++() returns 0. +*/ + +/*! + \fn type *Q3AsciiCacheIterator::operator--() + + Prefix -- makes the iterator point to the item just before + current(), and makes that the new current item for the iterator. If + current() was the first item, operator--() returns 0. +*/ + diff --git a/doc/src/classes/q3asciidict.qdoc b/doc/src/classes/q3asciidict.qdoc new file mode 100644 index 0000000..9a51db1 --- /dev/null +++ b/doc/src/classes/q3asciidict.qdoc @@ -0,0 +1,416 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3AsciiDict + \brief The Q3AsciiDict class is a template class that provides a dictionary based on char* keys. + \compat + + Q3AsciiDict is implemented as a template class. Define a template + instance Q3AsciiDict\ to create a dictionary that operates on + pointers to X (X*). + + A dictionary is a collection of key-value pairs. The key is a + char* used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + Q3AsciiDict cannot handle Unicode keys; use the Q3Dict template + instead, which uses QString keys. A Q3Dict has the same + performace as a Q3AsciiDict. + + Example: + \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 0 + In this example we use a dictionary to keep track of the line + edits we're using. We insert each line edit into the dictionary + with a unique name and then access the line edits via the + dictionary. See Q3PtrDict, Q3IntDict and Q3Dict. + + See Q3Dict for full details, including the choice of dictionary + size, and how deletions are handled. + + \sa Q3AsciiDictIterator, Q3Dict, Q3IntDict, Q3PtrDict +*/ + + +/*! + \fn Q3AsciiDict::Q3AsciiDict( int size, bool caseSensitive, bool copyKeys ) + + Constructs a dictionary optimized for less than \a size entries. + + We recommend setting \a size to a suitably large prime number (a + bit larger than the expected number of entries). This makes the + hash distribution better and will improve lookup performance. + + When \a caseSensitive is TRUE (the default) Q3AsciiDict treats + "abc" and "Abc" as different keys; when it is FALSE "abc" and + "Abc" are the same. Case-insensitive comparison only considers the + 26 letters in US-ASCII. + + If \a copyKeys is TRUE (the default), the dictionary copies keys + using strcpy(); if it is FALSE, the dictionary just copies the + pointers. +*/ + +/*! + \fn Q3AsciiDict::Q3AsciiDict( const Q3AsciiDict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3AsciiDict::~Q3AsciiDict() + + Removes all items from the dictionary and destroys it. + + The items are deleted if auto-delete is enabled. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3AsciiDict &Q3AsciiDict::operator=(const Q3AsciiDict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared and then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy) unless newItem() has been reimplemented(). +*/ + +/*! + \fn uint Q3AsciiDict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3AsciiDict::size() const + + Returns the size of the internal hash array (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3AsciiDict::resize( uint newsize ) + + Changes the size of the hashtable to \a newsize. The contents of + the dictionary are preserved but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3AsciiDict::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0; + otherwise it returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3AsciiDict::insert( const char *key, const type *item ) + + Inserts the \a key with the \a item into the dictionary. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3AsciiDict::replace( const char *key, const type *item ) + + Replaces an item that has a key equal to \a key with \a item. + + If the item does not already exist, it will be inserted. + + \a item may not be 0. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 1 + + If there are two or more items with equal keys, then the most + recently inserted item will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3AsciiDict::remove( const char *key ) + + Removes the item associated with \a key from the dictionary. + Returns TRUE if successful, i.e. if the key existed in the + dictionary; otherwise returns FALSE. + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary traversal order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3AsciiDict::take( const char *key ) + + Takes the item associated with \a key out of the dictionary + without deleting it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the most + recently inserted item will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3AsciiDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that operate on dictionary are reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3AsciiDict::find( const char *key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + This function uses an internal hashing algorithm to optimize + lookup. + + If there are two or more items with equal keys, then the item that + was most recently inserted will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *Q3AsciiDict::operator[]( const char *key ) const + + Returns the item associated with \a key, or 0 if the key does + not exist in the dictionary. + + This function uses an internal hashing algorithm to optimize + lookup. + + If there are two or more items with equal keys, then the item that + was most recently inserted will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3AsciiDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3AsciiDict::read( QDataStream &s, + Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3AsciiDict::write(QDataStream &s, Q3PtrCollection::Item item) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3AsciiDictIterator + \brief The Q3AsciiDictIterator class provides an iterator for Q3AsciiDict collections. + \compat + + Q3AsciiDictIterator is implemented as a template class. Define a + template instance Q3AsciiDictIterator\ to create a dictionary + iterator that operates on Q3AsciiDict\ (dictionary of X*). + + Example: + \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 2 + In the example we insert some line edits into a dictionary, then + iterate over the dictionary printing the strings associated with + those line edits. + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. + + Multiple iterators may independently traverse the same dictionary. + A Q3AsciiDict knows about all the iterators that are operating on + the dictionary. When an item is removed from the dictionary, + Q3AsciiDict updates all the iterators that are referring to the + removed item to point to the next item in the (arbitrary) + traversal order. + + \sa Q3AsciiDict +*/ + +/*! + \fn Q3AsciiDictIterator::Q3AsciiDictIterator( const Q3AsciiDict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point on the first item in the \a dict. +*/ + +/*! + \fn Q3AsciiDictIterator::~Q3AsciiDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3AsciiDictIterator::count() const + + Returns the number of items in the dictionary this iterator + operates over. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3AsciiDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0, + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3AsciiDictIterator::toFirst() + + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. If the dictionary is + empty it sets the current item to 0 and returns 0. +*/ + +/*! + \fn Q3AsciiDictIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3AsciiDictIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn const char *Q3AsciiDictIterator::currentKey() const + + Returns a pointer to the key for the current iterator item. +*/ + +/*! + \fn type *Q3AsciiDictIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3AsciiDictIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3AsciiDictIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item, and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/classes/q3cache.qdoc b/doc/src/classes/q3cache.qdoc new file mode 100644 index 0000000..d8799b6 --- /dev/null +++ b/doc/src/classes/q3cache.qdoc @@ -0,0 +1,461 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3Cache + \brief The Q3Cache class is a template class that provides a cache based on QString keys. + \compat + + A cache is a least recently used (LRU) list of cache items. Each + cache item has a key and a certain cost. The sum of item costs, + totalCost(), never exceeds the maximum cache cost, maxCost(). If + inserting a new item would cause the total cost to exceed the + maximum cost, the least recently used items in the cache are + removed. + + Q3Cache is a template class. Q3Cache\ defines a cache that + operates on pointers to X, or X*. + + Apart from insert(), by far the most important function is find() + (which also exists as operator[]()). This function looks up an + item, returns it, and by default marks it as being the most + recently used item. + + There are also methods to remove() or take() an object from the + cache. Calling setAutoDelete(TRUE) for a cache tells it to delete + items that are removed. The default is to not delete items when + they are removed (i.e., remove() and take() are equivalent). + + When inserting an item into the cache, only the pointer is copied, + not the item itself. This is called a shallow copy. It is possible + to make the cache copy all of the item's data (known as a deep + copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a cache and reimplement newItem() if you want deep copies. + + When removing a cache item, the virtual function + Q3PtrCollection::deleteItem() is called. The default + implementation deletes the item if auto-deletion is enabled, and + does nothing otherwise. + + There is a Q3CacheIterator that can be used to traverse the items + in the cache in arbitrary order. + + In Q3Cache, the cache items are accessed via QString keys, which + are Unicode strings. If you want to use non-Unicode, plain 8-bit + \c char* keys, use the Q3AsciiCache template. A Q3Cache has the + same performance as a Q3AsciiCache. + + \sa Q3CacheIterator, Q3AsciiCache, Q3IntCache +*/ + +/*! + \fn Q3Cache::Q3Cache( const Q3Cache &c ) + + \internal + + Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. +*/ + + +/*! + \fn Q3Cache::Q3Cache( int maxCost, int size, bool caseSensitive ) + + Constructs a cache whose contents will never have a total cost + greater than \a maxCost and which is expected to contain less than + \a size items. + + \a size is actually the size of an internal hash array; it's + usually best to make it a prime number and at least 50% bigger + than the largest expected number of items in the cache. + + Each inserted item has an associated cost. When inserting a new + item, if the total cost of all items in the cache will exceed \a + maxCost, the cache will start throwing out the older (least + recently used) items until there is enough room for the new item + to be inserted. + + If \a caseSensitive is TRUE (the default), the cache keys are case + sensitive; if it is FALSE, they are case-insensitive. + Case-insensitive comparison considers all Unicode letters. +*/ + +/*! + \fn Q3Cache::~Q3Cache() + + Removes all items from the cache and destroys it. All iterators + that access this cache will be reset. +*/ + +/*! + \fn Q3Cache& Q3Cache::operator=( const Q3Cache &c ) + + \internal + + Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn int Q3Cache::maxCost() const + + Returns the maximum allowed total cost of the cache. + + \sa setMaxCost() totalCost() +*/ + +/*! + \fn int Q3Cache::totalCost() const + + Returns the total cost of the items in the cache. This is an + integer in the range 0 to maxCost(). + + \sa setMaxCost() +*/ + +/*! + \fn void Q3Cache::setMaxCost( int m ) + + Sets the maximum allowed total cost of the cache to \a m. If the + current total cost is greater than \a m, some items are deleted + immediately. + + \sa maxCost() totalCost() +*/ + +/*! + \fn uint Q3Cache::count() const + + Returns the number of items in the cache. + + \sa totalCost() +*/ + +/*! + \fn uint Q3Cache::size() const + + Returns the size of the hash array used to implement the cache. + This should be a bit bigger than count() is likely to be. +*/ + +/*! + \fn bool Q3Cache::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. +*/ + +/*! + \fn bool Q3Cache::insert( const QString &k, const type *d, int c, int p ) + + Inserts the item \a d into the cache with key \a k and associated + cost, \a c. Returns TRUE if it is successfully inserted; otherwise + returns FALSE. + + The cache's size is limited, and if the total cost is too high, + Q3Cache will remove old, least recently used items until there is + room for this new item. + + The parameter \a p is internal and should be left at the default + value (0). + + \warning If this function returns FALSE (which could happen, e.g. + if the cost of this item alone exceeds maxCost()) you must delete + \a d yourself. Additionally, be very careful about using \a d + after calling this function because any other insertions into the + cache, from anywhere in the application or within Qt itself, could + cause the object to be discarded from the cache and the pointer to + become invalid. +*/ + +/*! + \fn bool Q3Cache::remove( const QString &k ) + + Removes the item associated with \a k, and returns TRUE if the + item was present in the cache; otherwise returns FALSE. + + The item is deleted if auto-deletion has been enabled, i.e., if + you have called setAutoDelete(TRUE). + + If there are two or more items with equal keys, the one that was + inserted last is removed. + + All iterators that refer to the removed item are set to point to + the next item in the cache's traversal order. + + \sa take(), clear() +*/ + +/*! + \fn type *Q3Cache::take( const QString &k ) + + Takes the item associated with \a k out of the cache without + deleting it, and returns a pointer to the item taken out, or 0 + if the key does not exist in the cache. + + If there are two or more items with equal keys, the one that was + inserted last is taken. + + All iterators that refer to the taken item are set to point to the + next item in the cache's traversal order. + + \sa remove(), clear() +*/ + +/*! + \fn void Q3Cache::clear() + + Removes all items from the cache and deletes them if auto-deletion + has been enabled. + + All cache iterators that operate this on cache are reset. + + \sa remove() take() +*/ + +/*! + \fn type *Q3Cache::find( const QString &k, bool ref ) const + + Returns the item associated with key \a k, or 0 if the key does + not exist in the cache. If \a ref is TRUE (the default), the item + is moved to the front of the least recently used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. +*/ + +/*! + \fn type *Q3Cache::operator[]( const QString &k ) const + + Returns the item associated with key \a k, or 0 if \a k does not + exist in the cache, and moves the item to the front of the least + recently used list. + + If there are two or more items with equal keys, the one that was + inserted last is returned. + + This is the same as find( k, TRUE ). + + \sa find() +*/ + +/*! + \fn void Q3Cache::statistics() const + + A debug-only utility function. Prints out cache usage, hit/miss, + and distribution information using qDebug(). This function does + nothing in the release library. +*/ + +/***************************************************************************** + Q3CacheIterator documentation + *****************************************************************************/ + +/*! + \class Q3CacheIterator qcache.h + \brief The Q3CacheIterator class provides an iterator for Q3Cache collections. + \compat + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. If new objects are inserted into the cache + while the iterator is active, the iterator may or may not see + them. + + Multiple iterators are completely independent, even when they + operate on the same Q3Cache. Q3Cache updates all iterators that + refer an item when that item is removed. + + Q3CacheIterator provides an operator++(), and an operator+=() to + traverse the cache. The current() and currentKey() functions are + used to access the current cache item and its key. The atFirst() + and atLast() return TRUE if the iterator points to the first or + last item in the cache respectively. The isEmpty() function + returns TRUE if the cache is empty, and count() returns the number + of items in the cache. + + Note that atFirst() and atLast() refer to the iterator's arbitrary + ordering, not to the cache's internal least recently used list. + + \sa Q3Cache +*/ + +/*! + \fn Q3CacheIterator::Q3CacheIterator( const Q3Cache &cache ) + + Constructs an iterator for \a cache. The current iterator item is + set to point to the first item in the \a cache. +*/ + +/*! + \fn Q3CacheIterator::Q3CacheIterator (const Q3CacheIterator & ci) + + Constructs an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently from there on. +*/ + +/*! + \fn Q3CacheIterator& Q3CacheIterator::operator=( const Q3CacheIterator &ci ) + + Makes this an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently thereafter. +*/ + +/*! + \fn uint Q3CacheIterator::count() const + + Returns the number of items in the cache on which this iterator + operates. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3CacheIterator::isEmpty() const + + Returns TRUE if the cache is empty, i.e. count() == 0; otherwise + it returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3CacheIterator::atFirst() const + + Returns TRUE if the iterator points to the first item in the + cache; otherwise returns FALSE. Note that this refers to the + iterator's arbitrary ordering, not to the cache's internal least + recently used list. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3CacheIterator::atLast() const + + Returns TRUE if the iterator points to the last item in the cache; + otherwise returns FALSE. Note that this refers to the iterator's + arbitrary ordering, not to the cache's internal least recently + used list. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3CacheIterator::toFirst() + + Sets the iterator to point to the first item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toLast() isEmpty() +*/ + +/*! + \fn type *Q3CacheIterator::toLast() + + Sets the iterator to point to the last item in the cache and + returns a pointer to the item. + + Sets the iterator to 0 and returns 0 if the cache is empty. + + \sa toFirst() isEmpty() +*/ + +/*! + \fn Q3CacheIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3CacheIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn QString Q3CacheIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3CacheIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the cache or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3CacheIterator::operator+=( uint jump ) + + Returns the item \a jump positions after the current item, or 0 if + it is beyond the last item. Makes this the current item. +*/ + +/*! + \fn type *Q3CacheIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item, or 0 + if it is before the first item. Makes this the current item. +*/ + +/*! + \fn type *Q3CacheIterator::operator++() + + Prefix++ makes the iterator point to the item just after current() + and makes that the new current item for the iterator. If current() + was the last item, operator++() returns 0. +*/ + +/*! + \fn type *Q3CacheIterator::operator--() + + Prefix-- makes the iterator point to the item just before + current() and makes that the new current item for the iterator. If + current() was the first item, operator--() returns 0. +*/ + diff --git a/doc/src/classes/q3dict.qdoc b/doc/src/classes/q3dict.qdoc new file mode 100644 index 0000000..0e6d51d --- /dev/null +++ b/doc/src/classes/q3dict.qdoc @@ -0,0 +1,446 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3Dict + \brief The Q3Dict class is a template class that provides a + dictionary based on QString keys. + \compat + + Q3Dict is implemented as a template class. Define a template + instance Q3Dict\ to create a dictionary that operates on + pointers to X (X *). + + A dictionary is a collection of key-value pairs. The key is a + QString used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + If you want to use non-Unicode, plain 8-bit \c char* keys, use the + Q3AsciiDict template. A Q3Dict has the same performance as a + Q3AsciiDict. If you want to have a dictionary that maps QStrings to + QStrings use QMap. + + The size() of the dictionary is very important. In order to get + good performance, you should use a suitably large prime number. + Suitable means equal to or larger than the maximum expected number + of dictionary items. Size is set in the constructor but may be + changed with resize(). + + Items are inserted with insert(); 0 pointers cannot be inserted. + Items are removed with remove(). All the items in a dictionary can + be removed with clear(). The number of items in the dictionary is + returned by count(). If the dictionary contains no items isEmpty() + returns TRUE. You can change an item's value with replace(). Items + are looked up with operator[](), or with find() which return a + pointer to the value or 0 if the given key does not exist. You can + take an item out of the dictionary with take(). + + Calling setAutoDelete(TRUE) for a dictionary tells it to delete + items that are removed. The default behavior is not to delete + items when they are removed. + + When an item is inserted, the key is converted (hashed) to an + integer index into an internal hash array. This makes lookup very + fast. + + Items with equal keys are allowed. When inserting two items with + the same key, only the last inserted item will be accessible (last + in, first out) until it is removed. + + The Q3DictIterator class can traverse the dictionary, but only in + an arbitrary order. Multiple iterators may independently traverse + the same dictionary. + + When inserting an item into a dictionary, only the pointer is + copied, not the item itself, i.e. a shallow copy is made. It is + possible to make the dictionary copy all of the item's data (a + deep copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement newItem() if you want deep + copies. + + When removing a dictionary item, the virtual function + Q3PtrCollection::deleteItem() is called. Q3Dict's default + implementation is to delete the item if auto-deletion is enabled. + + \sa Q3DictIterator, Q3AsciiDict, Q3IntDict, Q3PtrDict +*/ + + +/*! + \fn Q3Dict::Q3Dict( int size, bool caseSensitive ) + + Constructs a dictionary optimized for less than \a size entries. + + We recommend setting \a size to a suitably large prime number + (e.g. a prime that's slightly larger than the expected number of + entries). This makes the hash distribution better which will lead + to faster lookup. + + If \a caseSensitive is TRUE (the default), keys which differ only + by case are considered different. +*/ + +/*! + \fn Q3Dict::Q3Dict( const Q3Dict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3Dict::~Q3Dict() + + Removes all items from the dictionary and destroys it. If + setAutoDelete() is TRUE, each value is deleted. All iterators that + access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3Dict &Q3Dict::operator=(const Q3Dict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared, then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented. +*/ + +/*! + \fn uint Q3Dict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3Dict::size() const + + Returns the size of the internal hash array (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3Dict::resize( uint newsize ) + + Changes the size of the hash table to \a newsize. The contents of + the dictionary are preserved, but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3Dict::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0; + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3Dict::insert( const QString &key, const type *item ) + + Inserts the key \a key with value \a item into the dictionary. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3Dict::replace( const QString &key, const type *item ) + + Replaces the value of the key, \a key with \a item. + + If the item does not already exist, it will be inserted. + + \a item may not be 0. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 0 + + If there are two or more items with equal keys, then the last item + that was inserted will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3Dict::remove( const QString &key ) + + Removes the item with \a key from the dictionary. Returns TRUE if + successful, i.e. if the item is in the dictionary; otherwise + returns FALSE. + + If there are two or more items with equal keys, then the last item + that was inserted will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary's traversal order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3Dict::take( const QString &key ) + + Takes the item with \a key out of the dictionary without deleting + it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the last item + that was inserted will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3Dict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that operate on the dictionary are reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3Dict::find( const QString &key ) const + + Returns the item with key \a key, or 0 if the key does not exist + in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *Q3Dict::operator[]( const QString &key ) const + + Returns the item with key \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3Dict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3Dict::read( QDataStream &s, Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3Dict::write( QDataStream &s, Q3PtrCollection::Item item ) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3DictIterator + \brief The Q3DictIterator class provides an iterator for Q3Dict collections. + \compat + + Q3DictIterator is implemented as a template class. Define a + template instance Q3DictIterator\ to create a dictionary + iterator that operates on Q3Dict\ (dictionary of X*). + + The traversal order is arbitrary; when we speak of the "first", + "last" and "next" item we are talking in terms of this arbitrary + order. + + Multiple iterators may independently traverse the same dictionary. + A Q3Dict knows about all the iterators that are operating on the + dictionary. When an item is removed from the dictionary, Q3Dict + updates all iterators that are referring to the removed item to + point to the next item in the (arbitrary) traversal order. + + Example: + \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 1 + In the example we insert some pointers to line edits into a + dictionary, then iterate over the dictionary printing the strings + associated with the line edits. + + \sa Q3Dict +*/ + +/*! + \fn Q3DictIterator::Q3DictIterator( const Q3Dict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point to the first item in the dictionary, \a dict. First + in this context means first in the arbitrary traversal order. +*/ + +/*! + \fn Q3DictIterator::~Q3DictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3DictIterator::count() const + + Returns the number of items in the dictionary over which the + iterator is operating. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3DictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0; + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3DictIterator::toFirst() + + Resets the iterator, making the first item the first current item. + First in this context means first in the arbitrary traversal + order. Returns a pointer to this item. + + If the dictionary is empty it sets the current item to 0 and + returns 0. +*/ + +/*! + \fn type *Q3DictIterator::operator*() + \internal +*/ + +/*! + \fn Q3DictIterator::operator type*() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + + +/*! + \fn type *Q3DictIterator::current() const + + Returns a pointer to the current iterator item's value. +*/ + +/*! + \fn QString Q3DictIterator::currentKey() const + + Returns the current iterator item's key. +*/ + +/*! + \fn type *Q3DictIterator::operator()() + + Makes the next item current and returns the original current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3DictIterator::operator++() + + Prefix ++ makes the next item current and returns the new current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3DictIterator::operator+=( uint jump ) + \internal + Sets the current item to the item \a jump positions after the current item, + and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is empty, + it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/classes/q3intcache.qdoc b/doc/src/classes/q3intcache.qdoc new file mode 100644 index 0000000..dfff679 --- /dev/null +++ b/doc/src/classes/q3intcache.qdoc @@ -0,0 +1,446 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3IntCache + \brief The Q3IntCache class is a template class that provides a cache based on long keys. + \compat + + Q3IntCache is implemented as a template class. Define a template + instance Q3IntCache\ to create a cache that operates on + pointers to X, or X*. + + A cache is a least recently used (LRU) list of cache items, + accessed via \c long keys. Each cache item has a cost. The sum + of item costs, totalCost(), will not exceed the maximum cache + cost, maxCost(). If inserting a new item would cause the total + cost to exceed the maximum cost, the least recently used items in + the cache are removed. + + Apart from insert(), by far the most important function is find() + (which also exists as operator[]). This function looks up an + item, returns it, and by default marks it as being the most + recently used item. + + There are also methods to remove() or take() an object from the + cache. Calling setAutoDelete(TRUE) for a cache tells it to delete + items that are removed. The default is to not delete items when + they are removed (i.e. remove() and take() are equivalent). + + When inserting an item into the cache, only the pointer is copied, + not the item itself. This is called a shallow copy. It is possible + to make the cache copy all of the item's data (known as a deep + copy) when an item is inserted. insert() calls the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement newItem() if you want deep + copies. + + When removing a cache item, the item will be automatically + deleted if auto-deletion is enabled. + + There is a Q3IntCacheIterator which may be used to traverse the + items in the cache in arbitrary order. + + \sa Q3IntCacheIterator, Q3Cache, Q3AsciiCache +*/ + +/*! + \fn Q3IntCache::Q3IntCache( const Q3IntCache &c ) + + \internal + + Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn Q3IntCache::Q3IntCache( int maxCost, int size ) + + Constructs a cache whose contents will never have a total cost + greater than \a maxCost and which is expected to contain less than + \a size items. + + \a size is actually the size of an internal hash array; it's + usually best to make it prime and at least 50% bigger than the + largest expected number of items in the cache. + + Each inserted item is associated with a cost. When inserting a new + item, if the total cost of all items in the cache will exceed \a + maxCost, the cache will start throwing out the older (least + recently used) items until there is enough room for the new item + to be inserted. +*/ + +/*! + \fn Q3IntCache::~Q3IntCache() + + Removes all items from the cache and then destroys the int cache. + If auto-deletion is enabled the cache's items are deleted. All + iterators that access this cache will be reset. +*/ + +/*! + \fn Q3IntCache& Q3IntCache::operator=( const Q3IntCache &c ) + + \internal + + Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. +*/ + +/*! + \fn int Q3IntCache::maxCost() const + + Returns the maximum allowed total cost of the cache. + + \sa setMaxCost() totalCost() +*/ + +/*! + \fn int Q3IntCache::totalCost() const + + Returns the total cost of the items in the cache. This is an + integer in the range 0 to maxCost(). + + \sa setMaxCost() +*/ + +/*! + \fn void Q3IntCache::setMaxCost( int m ) + + Sets the maximum allowed total cost of the cache to \a m. If the + current total cost is greater than \a m, some items are removed + immediately. + + \sa maxCost() totalCost() +*/ + +/*! + \fn uint Q3IntCache::count() const + + Returns the number of items in the cache. + + \sa totalCost() +*/ + +/*! + \fn uint Q3IntCache::size() const + + Returns the size of the hash array used to implement the cache. + This should be a bit larger than count() is likely to be. +*/ + +/*! + \fn bool Q3IntCache::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. +*/ + +/*! + \fn bool Q3IntCache::insert( long k, const type *d, int c, int p ) + + Inserts the item \a d into the cache with key \a k and assigns it + a cost of \a c (default 1). Returns TRUE if it succeeds; otherwise + returns FALSE. + + The cache's size is limited, and if the total cost is too high, + Q3IntCache will remove old, least-used items until there is room + for this new item. + + The parameter \a p is internal and should be left at the default + value (0). + + \warning If this function returns FALSE (for example, the cost \c, + exceeds maxCost()), you must delete \a d yourself. Additionally, + be very careful about using \a d after calling this function. Any + other insertions into the cache, from anywhere in the application + or within Qt itself, could cause the object to be discarded from + the cache and the pointer to become invalid. +*/ + +/*! + \fn bool Q3IntCache::remove( long k ) + + Removes the item associated with \a k, and returns TRUE if the + item was present in the cache; otherwise returns FALSE. + + The item is deleted if auto-deletion has been enabled, i.e. if you + have called setAutoDelete(TRUE). + + If there are two or more items with equal keys, the one that was + inserted most recently is removed. + + All iterators that refer to the removed item are set to point to + the next item in the cache's traversal order. + + \sa take(), clear() +*/ + +/*! + \fn type * Q3IntCache::take( long k ) + + Takes the item associated with \a k out of the cache without + deleting it, and returns a pointer to the item taken out or 0 if + the key does not exist in the cache. + + If there are two or more items with equal keys, the one that was + inserted most recently is taken. + + All iterators that refer to the taken item are set to point to the + next item in the cache's traversal order. + + \sa remove(), clear() +*/ + +/*! + \fn void Q3IntCache::clear() + + Removes all items from the cache, and deletes them if + auto-deletion has been enabled. + + All cache iterators that operate this on cache are reset. + + \sa remove() take() +*/ + +/*! + \fn type * Q3IntCache::find( long k, bool ref ) const + + Returns the item associated with \a k, or 0 if the key does not + exist in the cache. If \a ref is TRUE (the default), the item is + moved to the front of the least recently used list. + + If there are two or more items with equal keys, the one that was + inserted most recently is returned. +*/ + +/*! + \fn type * Q3IntCache::operator[]( long k ) const + + Returns the item associated with \a k, or 0 if \a k does not exist + in the cache, and moves the item to the front of the least + recently used list. + + If there are two or more items with equal keys, the one that was + inserted most recently is returned. + + This is the same as find( k, TRUE ). + + \sa find() +*/ + +/*! + \fn void Q3IntCache::statistics() const + + A debug-only utility function. Prints out cache usage, hit/miss, + and distribution information using qDebug(). This function does + nothing in the release library. +*/ + +/*! + \class Q3IntCacheIterator + \brief The Q3IntCacheIterator class provides an iterator for Q3IntCache collections. + \compat + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. If new objects are inserted into the cache + while the iterator is active, the iterator may or may not see + them. + + Multiple iterators are completely independent, even when they + operate on the same Q3IntCache. Q3IntCache updates all iterators + that refer an item when that item is removed. + + Q3IntCacheIterator provides an operator++(), and an operator+=() to + traverse the cache; current() and currentKey() to access the + current cache item and its key; atFirst() atLast(), which return + TRUE if the iterator points to the first/last item in the cache; + isEmpty(), which returns TRUE if the cache is empty; and count(), + which returns the number of items in the cache. + + Note that atFirst() and atLast() refer to the iterator's arbitrary + ordering, not to the cache's internal least recently used list. + + \sa Q3IntCache +*/ + +/*! + \fn Q3IntCacheIterator::Q3IntCacheIterator( const Q3IntCache &cache ) + + Constructs an iterator for \a cache. The current iterator item is + set to point to the first item in the \a cache (or rather, the + first item is defined to be the item at which this constructor + sets the iterator to point). +*/ + +/*! + \fn Q3IntCacheIterator::Q3IntCacheIterator (const Q3IntCacheIterator & ci) + + Constructs an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently from there on. +*/ + +/*! + \fn Q3IntCacheIterator& Q3IntCacheIterator::operator=( const Q3IntCacheIterator &ci ) + + Makes this an iterator for the same cache as \a ci. The new + iterator starts at the same item as ci.current(), but moves + independently thereafter. +*/ + +/*! + \fn uint Q3IntCacheIterator::count() const + + Returns the number of items in the cache on which this iterator + operates. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3IntCacheIterator::isEmpty() const + + Returns TRUE if the cache is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3IntCacheIterator::atFirst() const + + Returns TRUE if the iterator points to the first item in the + cache; otherwise returns FALSE. Note that this refers to the + iterator's arbitrary ordering, not to the cache's internal least + recently used list. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3IntCacheIterator::atLast() const + + Returns TRUE if the iterator points to the last item in the cache; + otherwise returns FALSE. Note that this refers to the iterator's + arbitrary ordering, not to the cache's internal least recently + used list. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3IntCacheIterator::toFirst() + + Sets the iterator to point to the first item in the cache and + returns a pointer to the item. + + Sets the iterator to 0, and returns 0, if the cache is empty. + + \sa toLast() isEmpty() +*/ + +/*! + \fn type *Q3IntCacheIterator::toLast() + + Sets the iterator to point to the last item in the cache and + returns a pointer to the item. + + Sets the iterator to 0, and returns 0, if the cache is empty. + + \sa toFirst() isEmpty() +*/ + +/*! + \fn Q3IntCacheIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3IntCacheIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn long Q3IntCacheIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the cache or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator+=( uint jump ) + + Returns the item \a jump positions after the current item, or 0 if + it is beyond the last item. Makes this the current item. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item, or 0 + if it is beyond the first item. Makes this the current item. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator++() + + Prefix ++ makes the iterator point to the item just after + current(), and makes it the new current item for the iterator. If + current() was the last item, operator--() returns 0. +*/ + +/*! + \fn type *Q3IntCacheIterator::operator--() + + Prefix -- makes the iterator point to the item just before + current(), and makes it the new current item for the iterator. If + current() was the first item, operator--() returns 0. +*/ diff --git a/doc/src/classes/q3intdict.qdoc b/doc/src/classes/q3intdict.qdoc new file mode 100644 index 0000000..cef2e79 --- /dev/null +++ b/doc/src/classes/q3intdict.qdoc @@ -0,0 +1,390 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3IntDict + \brief The Q3IntDict class is a template class that provides a dictionary based on long keys.\ + \compat + + Q3IntDict is implemented as a template class. Define a template + instance Q3IntDict\ to create a dictionary that operates on + pointers to X (X*). + + A dictionary is a collection of key-value pairs. The key is an \c + long used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + Example: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 0 + + See Q3Dict for full details, including the choice of dictionary + size, and how deletions are handled. + + \sa Q3IntDictIterator, Q3Dict, Q3AsciiDict, Q3PtrDict +*/ + + +/*! + \fn Q3IntDict::Q3IntDict( int size ) + + Constructs a dictionary using an internal hash array of size \a + size. + + Setting \a size to a suitably large prime number (equal to or + greater than the expected number of entries) makes the hash + distribution better which leads to faster lookup. +*/ + +/*! + \fn Q3IntDict::Q3IntDict( const Q3IntDict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3IntDict::~Q3IntDict() + + Removes all items from the dictionary and destroys it. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3IntDict &Q3IntDict::operator=(const Q3IntDict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared and then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented. +*/ + +/*! + \fn uint Q3IntDict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3IntDict::size() const + + Returns the size of the internal hash array (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3IntDict::resize( uint newsize ) + + Changes the size of the hashtable to \a newsize. The contents of + the dictionary are preserved, but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3IntDict::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3IntDict::insert( long key, const type *item ) + + Insert item \a item into the dictionary using key \a key. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3IntDict::replace( long key, const type *item ) + + If the dictionary has key \a key, this key's item is replaced with + \a item. If the dictionary doesn't contain key \a key, \a item is + inserted into the dictionary using key \a key. + + \a item may not be 0. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 1 + + If there are two or more items with equal keys, then the most + recently inserted item will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3IntDict::remove( long key ) + + Removes the item associated with \a key from the dictionary. + Returns TRUE if successful, i.e. if the \a key is in the + dictionary; otherwise returns FALSE. + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary's traversal + order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3IntDict::take( long key ) + + Takes the item associated with \a key out of the dictionary + without deleting it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the most + recently inserted item will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary's traversing order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3IntDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that access this dictionary will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3IntDict::find( long key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to operator[]. + + \sa operator[]() +*/ + +/*! + \fn type *Q3IntDict::operator[]( long key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3IntDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3IntDict::read( QDataStream &s, Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3IntDict::write( QDataStream &s, Q3PtrCollection::Item item ) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3IntDictIterator + \brief The Q3IntDictIterator class provides an iterator for Q3IntDict collections. + \compat + + Q3IntDictIterator is implemented as a template class. Define a + template instance Q3IntDictIterator\ to create a dictionary + iterator that operates on Q3IntDict\ (dictionary of X*). + + Example: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 2 + + Note that the traversal order is arbitrary; you are not guaranteed the + order shown above. + + Multiple iterators may independently traverse the same dictionary. + A Q3IntDict knows about all the iterators that are operating on the + dictionary. When an item is removed from the dictionary, Q3IntDict + updates all iterators that refer the removed item to point to the + next item in the traversal order. + + \sa Q3IntDict +*/ + +/*! + \fn Q3IntDictIterator::Q3IntDictIterator( const Q3IntDict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point to the 'first' item in the \a dict. The first item + refers to the first item in the dictionary's arbitrary internal + ordering. +*/ + +/*! + \fn Q3IntDictIterator::~Q3IntDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3IntDictIterator::count() const + + Returns the number of items in the dictionary this iterator + operates over. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3IntDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise eturns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3IntDictIterator::toFirst() + + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. The first item + refers to the first item in the dictionary's arbitrary internal + ordering. If the dictionary is empty it sets the current item to + 0 and returns 0. +*/ + +/*! + \fn Q3IntDictIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3IntDictIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn long Q3IntDictIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3IntDictIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3IntDictIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3IntDictIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item, and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/classes/q3memarray.qdoc b/doc/src/classes/q3memarray.qdoc new file mode 100644 index 0000000..b9c1f73 --- /dev/null +++ b/doc/src/classes/q3memarray.qdoc @@ -0,0 +1,523 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3MemArray + \brief The Q3MemArray class is a template class that provides arrays of simple types. + \compat + + Q3MemArray is implemented as a template class. Define a template + instance Q3MemArray\ to create an array that contains X items. + + Q3MemArray stores the array elements directly in the array. It can + only deal with simple types (i.e. C++ types, structs, and classes + that have no constructors, destructors, or virtual functions). + Q3MemArray uses bitwise operations to copy and compare array + elements. + + The Q3PtrVector collection class is also a kind of array. Like most + old Qt collection classes, it uses pointers to the contained items. + + Q3MemArray uses explicit sharing with a + reference count. If more than one array shares common data and one + of the arrays is modified, all the arrays are modified. + + The benefit of sharing is that a program does not need to duplicate + data when it is not required, which results in lower memory use + and less copying of data. + + Example: + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 0 + + Program output: + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 1 + + Note concerning the use of Q3MemArray for manipulating structs or + classes: Compilers will often pad the size of structs of odd sizes + up to the nearest word boundary. This will then be the size + Q3MemArray will use for its bitwise element comparisons. Because + the remaining bytes will typically be uninitialized, this can + cause find() etc. to fail to find the element. Example: + + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 2 + + To work around this, make sure that you use a struct where + sizeof() returns the same as the sum of the sizes of the members + either by changing the types of the struct members or by adding + dummy members. + + Q3MemArray data can be traversed by iterators (see begin() and + end()). The number of items is returned by count(). The array can + be resized with resize() and filled using fill(). + + You can make a shallow copy of the array with assign() (or + operator=()) and a deep copy with duplicate(). + + Search for values in the array with find() and contains(). For + sorted arrays (see sort()) you can search using bsearch(). + + You can set the data directly using setRawData() and + resetRawData(), although this requires care. +*/ + +/*! \fn Q3MemArray::operator QVector() const + + Automatically converts the Q3MemArray into a QVector. +*/ + +/*! \typedef Q3MemArray::Iterator + A Q3MemArray iterator. + \sa begin() end() +*/ +/*! \typedef Q3MemArray::ConstIterator + A const Q3MemArray iterator. + \sa begin() end() +*/ +/*! \typedef Q3MemArray::ValueType + \internal +*/ + +/*! + \fn Q3MemArray::Q3MemArray() + + Constructs a null array. + + \sa isNull() +*/ + +/*! + \fn Q3MemArray::Q3MemArray( int size ) + + Constructs an array with room for \a size elements. Makes a null + array if \a size == 0. + + The elements are left uninitialized. + + \sa resize(), isNull() +*/ + +/*! + \fn Q3MemArray::Q3MemArray( const Q3MemArray &a ) + + Constructs a shallow copy of \a a. + + \sa assign() +*/ + +/*! + \fn Q3MemArray::Q3MemArray(const QVector &vector) + + Constructs a copy of \a vector. +*/ + +/*! + \fn Q3MemArray::Q3MemArray(int arg1, int arg2) + + Constructs an array \e{without allocating} array space. The + arguments \a arg1 and \a arg2 should be zero. Use at your own + risk. +*/ + +/*! + \fn Q3MemArray::~Q3MemArray() + + Dereferences the array data and deletes it if this was the last + reference. +*/ + +/*! + \fn Q3MemArray &Q3MemArray::operator=( const Q3MemArray &a ) + + Assigns a shallow copy of \a a to this array and returns a + reference to this array. + + Equivalent to assign( a ). +*/ + +/*! + \fn type *Q3MemArray::data() const + + Returns a pointer to the actual array data. + + The array is a null array if data() == 0 (null pointer). + + \sa isNull() +*/ + +/*! + \fn uint Q3MemArray::nrefs() const + + Returns the reference count for the shared array data. This + reference count is always greater than zero. +*/ + +/*! + \fn uint Q3MemArray::size() const + + Returns the size of the array (maximum number of elements). + + The array is a null array if size() == 0. + + \sa isNull(), resize() +*/ + +/*! + \fn uint Q3MemArray::count() const + + Returns the same as size(). + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::isEmpty() const + + Returns TRUE if the array is empty; otherwise returns FALSE. + + isEmpty() is equivalent to isNull() for Q3MemArray (unlike + QString). +*/ + +/*! + \fn bool Q3MemArray::isNull() const + + Returns TRUE if the array is null; otherwise returns FALSE. + + A null array has size() == 0 and data() == 0. +*/ + +/*! + \fn bool Q3MemArray::resize( uint size, Optimization optim ) + + Resizes (expands or shrinks) the array to \a size elements. The + array becomes a null array if \a size == 0. + + Returns TRUE if successful, or FALSE if the memory cannot be + allocated. + + New elements are not initialized. + + \a optim is either Q3GArray::MemOptim (the default) or + Q3GArray::SpeedOptim. When optimizing for speed rather than memory + consumption, the array uses a smart grow and shrink algorithm that + might allocate more memory than is actually needed for \a size + elements. This speeds up subsequent resize operations, for example + when appending many elements to an array, since the space has + already been allocated. + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::resize( uint size ) + + \overload + + Resizes (expands or shrinks) the array to \a size elements. The + array becomes a null array if \a size == 0. + + Returns TRUE if successful, i.e. if the memory can be allocated; + otherwise returns FALSE. + + New elements are not initialized. + + \sa size() +*/ + +/*! + \fn bool Q3MemArray::truncate( uint pos ) + + Truncates the array at position \a pos. + + Returns TRUE if successful, i.e. if the memory can be allocated; + otherwise returns FALSE. + + Equivalent to resize(\a pos). + + \sa resize() +*/ + +/*! + \fn bool Q3MemArray::fill( const type &v, int size ) + + Fills the array with the value \a v. If \a size is specified as + different from -1, then the array will be resized before being + filled. + + Returns TRUE if successful, i.e. if \a size is -1, or \a size is + != -1 and the memory can be allocated; otherwise returns FALSE. + + \sa resize() +*/ + +/*! + \fn void Q3MemArray::detach() + + Detaches this array from shared array data; i.e. it makes a + private, deep copy of the data. + + Copying will be performed only if the \link nrefs() reference + count\endlink is greater than one. + + \sa copy() +*/ + +/*! + \fn Q3MemArray Q3MemArray::copy() const + + Returns a deep copy of this array. + + \sa detach(), duplicate() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::assign( const Q3MemArray &a ) + + Shallow copy. Dereferences the current array and references the + data contained in \a a instead. Returns a reference to this array. + + \sa operator=() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::assign( const type *data, uint size ) + + \overload + + Shallow copy. Dereferences the current array and references the + array data \a data, which contains \a size elements. Returns a + reference to this array. + + Do not delete \a data later; Q3MemArray will call free() on it + at the right time. +*/ + +/*! + \fn Q3MemArray &Q3MemArray::duplicate( const Q3MemArray &a ) + + Deep copy. Dereferences the current array and obtains a copy of + the data contained in \a a instead. Returns a reference to this + array. + + \sa copy() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::duplicate( const type *data, uint size ) + + \overload + + Deep copy. Dereferences the current array and obtains a copy of + the array data \a data instead. Returns a reference to this array. + The size of the array is given by \a size. + + \sa copy() +*/ + +/*! + \fn Q3MemArray &Q3MemArray::setRawData( const type *data, uint size ) + + Sets raw data and returns a reference to the array. + + Dereferences the current array and sets the new array data to \a + data and the new array size to \a size. Do not attempt to resize + or re-assign the array data when raw data has been set. Call + resetRawData(\a data, \a size) to reset the array. + + Setting raw data is useful because it sets Q3MemArray data without + allocating memory or copying data. + + Example I (intended use): + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 3 + + Example II (you don't want to do this): + \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 4 + + \warning If you do not call resetRawData(), Q3MemArray will attempt + to deallocate or reallocate the raw data, which might not be too + good. Be careful. + + \sa resetRawData() +*/ + +/*! + \fn void Q3MemArray::resetRawData( const type *data, uint size ) + + Removes internal references to the raw data that was set using + setRawData(). This means that Q3MemArray no longer has access to + the \a data, so you are free to manipulate \a data as you wish. + You can now use the Q3MemArray without affecting the original \a + data, for example by calling setRawData() with a pointer to some + other data. + + The arguments must be the \a data and length, \a size, that were + passed to setRawData(). This is for consistency checking. + + \sa setRawData() +*/ + +/*! + \fn int Q3MemArray::find( const type &v, uint index ) const + + Finds the first occurrence of \a v, starting at position \a index. + + Returns the position of \a v, or -1 if \a v could not be found. + + \sa contains() +*/ + +/*! + \fn int Q3MemArray::contains( const type &v ) const + + Returns the number of times \a v occurs in the array. + + \sa find() +*/ + +/*! + \fn void Q3MemArray::sort() + + Sorts the array elements in ascending order, using bitwise + comparison (memcmp()). + + \sa bsearch() +*/ + +/*! + \fn int Q3MemArray::bsearch( const type &v ) const + + In a sorted array (as sorted by sort()), finds the first + occurrence of \a v by using a binary search. For a sorted + array this is generally much faster than find(), which does + a linear search. + + Returns the position of \a v, or -1 if \a v could not be found. + + \sa sort(), find() +*/ + +/*! + \fn type &Q3MemArray::operator[]( int index ) const + + Returns a reference to the element at position \a index in the + array. + + This can be used to both read and set an element. Equivalent to + at(). + + \sa at() +*/ + +/*! + \fn type &Q3MemArray::at( uint index ) const + + Returns a reference to the element at position \a index in the array. + + This can be used to both read and set an element. + + \sa operator[]() +*/ + +/*! + \fn Q3MemArray::operator const type *() const + + Cast operator. Returns a pointer to the array. + + \sa data() +*/ + +/*! + \fn bool Q3MemArray::operator==( const Q3MemArray &a ) const + + Returns TRUE if this array is equal to \a a; otherwise returns + FALSE. + + The two arrays are compared bitwise. + + \sa operator!=() +*/ + +/*! + \fn bool Q3MemArray::operator!=( const Q3MemArray &a ) const + + Returns TRUE if this array is different from \a a; otherwise + returns FALSE. + + The two arrays are compared bitwise. + + \sa operator==() +*/ + +/*! + \fn Iterator Q3MemArray::begin() + + Returns an iterator pointing at the beginning of this array. This + iterator can be used in the same way as the iterators of + Q3ValueList and QMap, for example. +*/ + +/*! + \fn Iterator Q3MemArray::end() + + Returns an iterator pointing behind the last element of this + array. This iterator can be used in the same way as the iterators + of Q3ValueList and QMap, for example. +*/ + +/*! + \fn ConstIterator Q3MemArray::begin() const + + \overload + + Returns a const iterator pointing at the beginning of this array. + This iterator can be used in the same way as the iterators of + Q3ValueList and QMap, for example. +*/ + +/*! + \fn ConstIterator Q3MemArray::end() const + + \overload + + Returns a const iterator pointing behind the last element of this + array. This iterator can be used in the same way as the iterators + of Q3ValueList and QMap, for example. +*/ diff --git a/doc/src/classes/q3popupmenu.qdoc b/doc/src/classes/q3popupmenu.qdoc new file mode 100644 index 0000000..a2cfe08 --- /dev/null +++ b/doc/src/classes/q3popupmenu.qdoc @@ -0,0 +1,76 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PopupMenu + \brief The Q3PopupMenu class is a thin compatibility wrapper around QMenu. + \compat + + Use QMenu in new applications. Note that the menu's actions must + be \l {Q3Action}s. +*/ + +/*! + \fn Q3PopupMenu::Q3PopupMenu(QWidget *parent, const char *name) + + Constructs a menu with the given \a parent and \a name. +*/ + +/*! + \fn int Q3PopupMenu::exec() + + Pops up the menu and returns the ID of the action that was + selected. + + \sa QMenu::exec() +*/ + +/*! + \fn int Q3PopupMenu::exec(const QPoint & pos, int indexAtPoint) + + Pops up the menu at coordinate \a pos and returns the ID of the + action that was selected. + + If \a indexAtPoint is specified, the menu will pop up with the + item at index \a indexAtPoint under the mouse cursor. + + \sa QMenu::exec() +*/ diff --git a/doc/src/classes/q3ptrdict.qdoc b/doc/src/classes/q3ptrdict.qdoc new file mode 100644 index 0000000..38ca0bb --- /dev/null +++ b/doc/src/classes/q3ptrdict.qdoc @@ -0,0 +1,388 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrDict + \brief The Q3PtrDict class is a template class that provides a dictionary based on void* keys. + \compat + + Q3PtrDict is implemented as a template class. Define a template + instance Q3PtrDict\ to create a dictionary that operates on + pointers to X (X*). + + A dictionary is a collection of key-value pairs. The key is a + void* used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + Example: + \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 0 + In this example we use a dictionary to add an extra property (a + char*) to the line edits we're using. + + See Q3Dict for full details, including the choice of dictionary + size, and how deletions are handled. + + \sa Q3PtrDictIterator, Q3Dict, Q3AsciiDict, Q3IntDict +*/ + + +/*! + \fn Q3PtrDict::Q3PtrDict( int size ) + + Constructs a dictionary using an internal hash array with the size + \a size. + + Setting \a size to a suitably large prime number (equal to or + greater than the expected number of entries) makes the hash + distribution better and improves lookup performance. +*/ + +/*! + \fn Q3PtrDict::Q3PtrDict( const Q3PtrDict &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3PtrDict::~Q3PtrDict() + + Removes all items from the dictionary and destroys it. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3PtrDict &Q3PtrDict::operator=(const Q3PtrDict &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared and then each item in \a dict is + inserted into the dictionary. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented. +*/ + +/*! + \fn uint Q3PtrDict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3PtrDict::size() const + + Returns the size of the internal hash table (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3PtrDict::resize( uint newsize ) + + Changes the size of the hash table to \a newsize. The contents of + the dictionary are preserved, but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3PtrDict::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3PtrDict::insert( void *key, const type *item ) + + Inserts the \a key with the \a item into the dictionary. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3PtrDict::replace( void *key, const type *item ) + + If the dictionary has key \a key, this key's item is replaced with + \a item. If the dictionary doesn't contain key \a key, \a item is + inserted into the dictionary using key \a key. + + \a item may not be 0. + + Equivalent to + \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 1 + + If there are two or more items with equal keys, then the most + recently inserted item will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3PtrDict::remove( void *key ) + + Removes the item associated with \a key from the dictionary. + Returns TRUE if successful, i.e. if \a key is in the dictionary; + otherwise returns FALSE. + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary traversal order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3PtrDict::take( void *key ) + + Takes the item associated with \a key out of the dictionary + without deleting it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3PtrDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that access this dictionary will be + reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3PtrDict::find( void *key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to operator[]. + + \sa operator[]() +*/ + +/*! + \fn type *Q3PtrDict::operator[]( void *key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3PtrDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3PtrDict::read( QDataStream &s, Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrDict::write( QDataStream &s, Q3PtrCollection::Item item) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3PtrDictIterator + \brief The Q3PtrDictIterator class provides an iterator for Q3PtrDict collections. + \compat + + Q3PtrDictIterator is implemented as a template class. Define a + template instance Q3PtrDictIterator\ to create a dictionary + iterator that operates on Q3PtrDict\ (dictionary of X*). + + Example: + \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 2 + In the example we insert some line edits into a dictionary, + associating a string with each. We then iterate over the + dictionary printing the associated strings. + + Multiple iterators may independently traverse the same dictionary. + A Q3PtrDict knows about all the iterators that are operating on the + dictionary. When an item is removed from the dictionary, Q3PtrDict + updates all iterators that refer the removed item to point to the + next item in the traversing order. + + \sa Q3PtrDict +*/ + +/*! + \fn Q3PtrDictIterator::Q3PtrDictIterator( const Q3PtrDict &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point on the first item in the \a dict. +*/ + +/*! + \fn Q3PtrDictIterator::~Q3PtrDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3PtrDictIterator::count() const + + Returns the number of items in the dictionary this iterator + operates on. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3PtrDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3PtrDictIterator::toFirst() + + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. If the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ + +/*! + \fn Q3PtrDictIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3PtrDictIterator::current() const + + Returns a pointer to the current iterator item's value. +*/ + +/*! + \fn void *Q3PtrDictIterator::currentKey() const + + Returns the current iterator item's key. +*/ + +/*! + \fn type *Q3PtrDictIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrDictIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrDictIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ diff --git a/doc/src/classes/q3ptrlist.qdoc b/doc/src/classes/q3ptrlist.qdoc new file mode 100644 index 0000000..3000940 --- /dev/null +++ b/doc/src/classes/q3ptrlist.qdoc @@ -0,0 +1,1157 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrList + \brief The Q3PtrList class is a template class that provides a list. + \compat + + Q3ValueList is an STL-compatible alternative to this class. + + Define a template instance Q3PtrList\ to create a list that + operates on pointers to X (X*). + + The list class is indexable and has a \link at() current + index\endlink and a \link current() current item\endlink. The + first item corresponds to index position 0. The current index is + -1 if the current item is 0. + + Items are inserted with prepend(), insert() or append(). Items are + removed with remove(), removeRef(), removeFirst() and + removeLast(). You can search for an item using find(), findNext(), + findRef() or findNextRef(). The list can be sorted with sort(). + You can count the number of occurrences of an item with contains() + or containsRef(). You can get a pointer to the current item with + current(), to an item at a particular index position in the list + with at() or to the first or last item with getFirst() and + getLast(). You can also iterate over the list with first(), + last(), next() and prev() (which all update current()). The list's + deletion property is set with setAutoDelete(). + + \target example + Example: + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 0 + + The output is + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 1 + + Q3PtrList has several member functions for traversing the list, but + using a Q3PtrListIterator can be more practical. Multiple list + iterators may traverse the same list, independently of each other + and of the current list item. + + In the example above we make the call setAutoDelete(true). + Enabling auto-deletion tells the list to delete items that are + removed. The default is to not delete items when they are removed + but this would cause a memory leak in the example because there + are no other references to the list items. + + When inserting an item into a list only the pointer is copied, not + the item itself, i.e. a shallow copy. It is possible to make the + list copy all of the item's data (deep copy) when an item is + inserted. insert(), inSort() and append() call the virtual + function Q3PtrCollection::newItem() for the item to be inserted. + Inherit a list and reimplement newItem() to have deep copies. + + When removing an item from a list, the virtual function + Q3PtrCollection::deleteItem() is called. Q3PtrList's default + implementation is to delete the item if auto-deletion is enabled. + + The virtual function compareItems() can be reimplemented to + compare two list items. This function is called from all list + functions that need to compare list items, for instance + remove(const type*). If you only want to deal with pointers, there + are functions that compare pointers instead, for instance + removeRef(const type*). These functions are somewhat faster than + those that call compareItems(). + + List items are stored as \c void* in an internal Q3LNode, which + also holds pointers to the next and previous list items. The + functions currentNode(), removeNode(), and takeNode() operate + directly on the Q3LNode, but they should be used with care. The + data component of the node is available through Q3LNode::getData(). + + The Q3StrList class is a list of \c char*. + It reimplements newItem(), deleteItem() and compareItems(). (But + see QStringList for a list of Unicode QStrings.) + + \sa Q3PtrListIterator +*/ + + +/*! + \fn Q3PtrList::Q3PtrList() + + Constructs an empty list. +*/ + +/*! + \fn Q3PtrList::Q3PtrList( const Q3PtrList &list ) + + Constructs a copy of \a list. + + Each item in \a list is \link append() appended\endlink to this + list. Only the pointers are copied (shallow copy). +*/ + +/*! + \fn Q3PtrList::~Q3PtrList() + + Removes all items from the list and destroys the list. + + All list iterators that access this list will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3PtrList &Q3PtrList::operator=(const Q3PtrList &list) + + Assigns \a list to this list and returns a reference to this list. + + This list is first cleared and then each item in \a list is \link + append() appended\endlink to this list. Only the pointers are + copied (shallow copy) unless newItem() has been reimplemented. +*/ + +/*! + \fn bool Q3PtrList::operator==(const Q3PtrList &list ) const + + Compares this list with \a list. Returns TRUE if the lists contain + the same data; otherwise returns FALSE. +*/ + +/*! + \fn uint Q3PtrList::count() const + + Returns the number of items in the list. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3PtrList::operator!=(const Q3PtrList &list ) const + + Compares this list with \a list. Returns TRUE if the lists contain + different data; otherwise returns FALSE. +*/ + + +/*! + \fn void Q3PtrList::sort() + + Sorts the list by the result of the virtual compareItems() + function. + + The heap sort algorithm is used for sorting. It sorts n items with + O(n*log n) comparisons. This is the asymptotic optimal solution of + the sorting problem. + + If the items in your list support operator<() and operator==(), + you might be better off with Q3SortedList because it implements the + compareItems() function for you using these two operators. + + \sa inSort() +*/ + +/*! + \fn bool Q3PtrList::isEmpty() const + + Returns TRUE if the list is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3PtrList::insert( uint index, const type *item ) + + Inserts the \a item at position \a index in the list. + + Returns TRUE if successful, i.e. if \a index is in range; + otherwise returns FALSE. The valid range is 0 to count() + (inclusively). The item is appended if \a index == count(). + + The inserted item becomes the current list item. + + \a item must not be 0. + + \sa append(), current(), replace() +*/ + +/*! + \fn bool Q3PtrList::replace( uint index, const type *item ) + + Replaces the item at position \a index with the new \a item. + + Returns TRUE if successful, i.e. \a index is in the range 0 to + count()-1. + + \sa append(), current(), insert() +*/ + +/*! + \fn void Q3PtrList::inSort( const type *item ) + + Inserts the \a item at its sorted position in the list. + + The sort order depends on the virtual compareItems() function. All + items must be inserted with inSort() to maintain the sorting + order. + + The inserted item becomes the current list item. + + \a item must not be 0. + + \warning Using inSort() is slow. An alternative, especially if you + have lots of items, is to simply append() or insert() them and + then use sort(). inSort() takes up to O(n) compares. That means + inserting n items in your list will need O(n^2) compares whereas + sort() only needs O(n*log n) for the same task. So use inSort() + only if you already have a presorted list and want to insert just + a few additional items. + + \sa insert(), compareItems(), current(), sort() +*/ + +/*! + \fn void Q3PtrList::append( const type *item ) + + Inserts the \a item at the end of the list. + + The inserted item becomes the current list item. This is + equivalent to \c{insert( count(), item )}. + + \a item must not be 0. + + \sa insert(), current(), prepend() +*/ + +/*! + \fn void Q3PtrList::prepend( const type *item ) + + Inserts the \a item at the start of the list. + + The inserted item becomes the current list item. This is + equivalent to \c{insert( 0, item )}. + + \a item must not be 0. + + \sa append(), insert(), current() +*/ + +/*! + \fn bool Q3PtrList::remove( uint index ) + + Removes the item at position \a index in the list. + + Returns TRUE if successful, i.e. if \a index is in range; + otherwise returns FALSE. The valid range is \c{0..(count() - 1)} + inclusive. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa take(), clear(), setAutoDelete(), current() removeRef() +*/ + +/*! + \fn bool Q3PtrList::remove() + + \overload + + Removes the current list item. + + Returns TRUE if successful, i.e. if the current item isn't 0; + otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa take(), clear(), setAutoDelete(), current() removeRef() +*/ + +/*! + \fn bool Q3PtrList::remove( const type *item ) + + \overload + + Removes the first occurrence of \a item from the list. + + Returns TRUE if successful, i.e. if \a item is in the list; + otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call removeRef(). + + If \a item is NULL then the current item is removed from the list. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa removeRef(), take(), clear(), setAutoDelete(), compareItems(), + current() +*/ + +/*! + \fn bool Q3PtrList::removeRef( const type *item ) + + Removes the first occurrence of \a item from the list. + + Returns TRUE if successful, i.e. if \a item is in the list; + otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 2 + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa remove(), clear(), setAutoDelete(), current() +*/ + +/*! + \fn void Q3PtrList::removeNode( Q3LNode *node ) + + Removes the \a node from the list. + + This node must exist in the list, otherwise the program may crash. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The first item in the list will become the new current list item. + The current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the item succeeding this item or to the preceding item if + the removed item was the last item. + + \warning Do not call this function unless you are an expert. + + \sa takeNode(), currentNode() remove() removeRef() +*/ + +/*! + \fn bool Q3PtrList::removeFirst() + + Removes the first item from the list. Returns TRUE if successful, + i.e. if the list isn't empty; otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The first item in the list becomes the new current list item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa removeLast(), setAutoDelete(), current() remove() +*/ + +/*! + \fn bool Q3PtrList::removeLast() + + Removes the last item from the list. Returns TRUE if successful, + i.e. if the list isn't empty; otherwise returns FALSE. + + The removed item is deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + The last item in the list becomes the new current list item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the removed item will be set to + point to the new current item. + + \sa removeFirst(), setAutoDelete(), current() +*/ + +/*! + \fn type *Q3PtrList::take( uint index ) + + Takes the item at position \a index out of the list without + deleting it (even if \link setAutoDelete() auto-deletion\endlink + is enabled). + + Returns a pointer to the item taken out of the list, or 0 if the + index is out of range. The valid range is \c{0..(count() - 1)} + inclusive. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the taken item will be set to + point to the new current item. + + \sa remove(), clear(), current() +*/ + +/*! + \fn type *Q3PtrList::take() + + \overload + + Takes the current item out of the list without deleting it (even + if \link setAutoDelete() auto-deletion\endlink is enabled). + + Returns a pointer to the item taken out of the list, or 0 if + the current item is 0. + + The item after the removed item becomes the new current list item + if the removed item is not the last item in the list. If the last + item is removed, the new last item becomes the current item. The + current item is set to 0 if the list becomes empty. + + All list iterators that refer to the taken item will be set to + point to the new current item. + + \sa remove(), clear(), current() +*/ + +/*! + \fn type *Q3PtrList::takeNode( Q3LNode *node ) + + Takes the \a node out of the list without deleting its item (even + if \link setAutoDelete() auto-deletion\endlink is enabled). + Returns a pointer to the item taken out of the list. + + This node must exist in the list, otherwise the program may crash. + + The first item in the list becomes the new current list item. + + All list iterators that refer to the taken item will be set to + point to the item succeeding this item or to the preceding item if + the taken item was the last item. + + \warning Do not call this function unless you are an expert. + + \sa removeNode(), currentNode() +*/ + +/*! + \fn void Q3PtrList::clear() + + Removes all items from the list. + + The removed items are deleted if \link setAutoDelete() + auto-deletion\endlink is enabled. + + All list iterators that access this list will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn int Q3PtrList::find( const type *item ) + + Finds the first occurrence of \a item in the list. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call findRef(). + + \sa findNext(), findRef(), compareItems(), current() +*/ + +/*! + \fn int Q3PtrList::findNext( const type *item ) + + Finds the next occurrence of \a item in the list, starting from + the current list item. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + The compareItems() function is called when searching for the item + in the list. If compareItems() is not reimplemented, it is more + efficient to call findNextRef(). + + \sa find(), findNextRef(), compareItems(), current() +*/ + +/*! + \fn int Q3PtrList::findRef( const type *item ) + + Finds the first occurrence of \a item in the list. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + Calling this function is much faster than find() because find() + compares \a item with each list item using compareItems(), whereas + this function only compares the pointers. + + \sa findNextRef(), find(), current() +*/ + +/*! + \fn int Q3PtrList::findNextRef( const type *item ) + + Finds the next occurrence of \a item in the list, starting from + the current list item. + + If the item is found, the list sets the current item to point to + the found item and returns the index of this item. If the item is + not found, the list sets the current item to 0, the current + index to -1, and returns -1. + + Calling this function is much faster than findNext() because + findNext() compares \a item with each list item using + compareItems(), whereas this function only compares the pointers. + + \sa findRef(), findNext(), current() +*/ + +/*! + \fn uint Q3PtrList::contains( const type *item ) const + + Returns the number of occurrences of \a item in the list. + + The compareItems() function is called when looking for the \a item + in the list. If compareItems() is not reimplemented, it is more + efficient to call containsRef(). + + This function does not affect the current list item. + + \sa containsRef(), compareItems() +*/ + +/*! + \fn uint Q3PtrList::containsRef( const type *item ) const + + Returns the number of occurrences of \a item in the list. + + Calling this function is much faster than contains() because + contains() compares \a item with each list item using + compareItems(), whereas his function only compares the pointers. + + This function does not affect the current list item. + + \sa contains() +*/ + +/*! + \fn type *Q3PtrList::at( uint index ) + + Returns a pointer to the item at position \a index in the list, or + 0 if the index is out of range. + + Sets the current list item to this item if \a index is valid. The + valid range is \c{0..(count() - 1)} inclusive. + + This function is very efficient. It starts scanning from the first + item, last item, or current item, whichever is closest to \a + index. + + \sa current() +*/ + +/*! + \fn int Q3PtrList::at() const + + \overload + + Returns the index of the current list item. The returned value is + -1 if the current item is 0. + + \sa current() +*/ + +/*! + \fn type *Q3PtrList::current() const + + Returns a pointer to the current list item. The current item may + be 0 (implies that the current index is -1). + + \sa at() +*/ + +/*! + \fn Q3LNode *Q3PtrList::currentNode() const + + Returns a pointer to the current list node. + + The node can be kept and removed later using removeNode(). The + advantage is that the item can be removed directly without + searching the list. + + \warning Do not call this function unless you are an expert. + + \sa removeNode(), takeNode(), current() +*/ + +/*! + \fn type *Q3PtrList::getFirst() const + + Returns a pointer to the first item in the list, or 0 if the list + is empty. + + This function does not affect the current list item. + + \sa first(), getLast() +*/ + +/*! + \fn type *Q3PtrList::getLast() const + + Returns a pointer to the last item in the list, or 0 if the list + is empty. + + This function does not affect the current list item. + + \sa last(), getFirst() +*/ + +/*! + \fn type *Q3PtrList::first() + + Returns a pointer to the first item in the list and makes this the + current list item; returns 0 if the list is empty. + + \sa getFirst(), last(), next(), prev(), current() +*/ + +/*! + \fn type *Q3PtrList::last() + + Returns a pointer to the last item in the list and makes this the + current list item; returns 0 if the list is empty. + + \sa getLast(), first(), next(), prev(), current() +*/ + +/*! + \fn type *Q3PtrList::next() + + Returns a pointer to the item succeeding the current item. Returns + 0 if the current item is 0 or equal to the last item. + + Makes the succeeding item current. If the current item before this + function call was the last item, the current item will be set to + 0. If the current item was 0, this function does nothing. + + \sa first(), last(), prev(), current() +*/ + +/*! + \fn type *Q3PtrList::prev() + + Returns a pointer to the item preceding the current item. Returns + 0 if the current item is 0 or equal to the first item. + + Makes the preceding item current. If the current item before this + function call was the first item, the current item will be set to + 0. If the current item was 0, this function does nothing. + + \sa first(), last(), next(), current() +*/ + +/*! + \fn void Q3PtrList::toVector( Q3GVector *vec ) const + + Stores all list items in the vector \a vec. + + The vector must be of the same item type, otherwise the result + will be undefined. +*/ + +/*! + \typedef Q3PtrList::iterator + + \internal +*/ + +/*! + \typedef Q3PtrList::Iterator + + \internal +*/ + +/*! + \typedef Q3PtrList::ConstIterator + + \internal +*/ + +/*! + \typedef Q3PtrList::const_iterator + + \internal +*/ + +/*! + \fn Q3PtrList::constBegin() const + + \internal +*/ + +/*! + \fn Q3PtrList::constEnd() const + + \internal +*/ + +/*! + \fn Q3PtrList::erase(Iterator) + + \internal +*/ + + +/***************************************************************************** + Q3PtrListIterator documentation + *****************************************************************************/ + +/*! + \class Q3PtrListIterator + \brief The Q3PtrListIterator class provides an iterator for + Q3PtrList collections. + \compat + + Define a template instance Q3PtrListIterator\ to create a list + iterator that operates on Q3PtrList\ (list of X*). + + The following example is similar to the + example in the Q3PtrList class documentation, + but it uses Q3PtrListIterator. The class Employee is + defined there. + + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 3 + + The output is + \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 4 + + Using a list iterator is a more robust way of traversing the list + than using the Q3PtrList member functions \link Q3PtrList::first() + first\endlink(), \link Q3PtrList::next() next\endlink(), \link + Q3PtrList::current() current\endlink(), etc., as many iterators can + traverse the same list independently. + + An iterator has its own current list item and can get the next and + previous list items. It doesn't modify the list in any way. + + When an item is removed from the list, all iterators that point to + that item are updated to point to Q3PtrList::current() instead to + avoid dangling references. + + \sa Q3PtrList +*/ + +/*! + \fn Q3PtrListIterator::Q3PtrListIterator( const Q3PtrList &list ) + + Constructs an iterator for \a list. The current iterator item is + set to point on the first item in the \a list. +*/ + +/*! + \fn Q3PtrListIterator::~Q3PtrListIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3PtrListIterator::count() const + + Returns the number of items in the list this iterator operates on. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3PtrListIterator::isEmpty() const + + Returns TRUE if the list is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn bool Q3PtrListIterator::atFirst() const + + Returns TRUE if the current iterator item is the first list item; + otherwise returns FALSE. + + \sa toFirst(), atLast() +*/ + +/*! + \fn bool Q3PtrListIterator::atLast() const + + Returns TRUE if the current iterator item is the last list item; + otherwise returns FALSE. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3PtrListIterator::toFirst() + + Sets the current iterator item to point to the first list item and + returns a pointer to the item. Sets the current item to 0 and + returns 0 if the list is empty. + + \sa toLast(), atFirst() +*/ + +/*! + \fn type *Q3PtrListIterator::toLast() + + Sets the current iterator item to point to the last list item and + returns a pointer to the item. Sets the current item to 0 and + returns 0 if the list is empty. + + \sa toFirst(), atLast() +*/ + +/*! + \fn Q3PtrListIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3PtrListIterator::operator*() + + Asterisk operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3PtrListIterator::current() const + + Returns a pointer to the current iterator item. If the iterator is + positioned before the first item in the list or after the last + item in the list, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the list or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the list or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item and returns a pointer to that item. + + If that item is beyond the last item or if the list is empty, it + sets the current item to 0 and returns 0 +*/ + +/*! + \fn type *Q3PtrListIterator::operator--() + + Prefix - makes the preceding item current and returns the new + current item. + + If the current iterator item was the first item in the list or if + it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3PtrListIterator::operator-=( uint jump ) + + Returns the item \a jump positions before the current item or 0 + if it is beyond the first item. Makes this the current item. +*/ + +/*! + \fn Q3PtrListIterator& Q3PtrListIterator::operator=( const Q3PtrListIterator &it ) + + Assignment. Makes a copy of the iterator \a it and returns a + reference to this iterator. +*/ + +/*! + \class Q3StrList + \brief The Q3StrList class provides a doubly-linked list of char*. + \compat + + If you want a string list of \l{QString}s use QStringList. + + This class is a Q3PtrList\ instance (a list of char*). + + Q3StrList can make deep or shallow copies of the strings that are + inserted. + + A deep copy means that memory is allocated for the string and then + the string data is copied into that memory. A shallow copy is just + a copy of the pointer value and not of the string data itself. + + The disadvantage of shallow copies is that because a pointer can + be deleted only once, the program must put all strings in a + central place and know when it is safe to delete them (i.e. when + the strings are no longer referenced by other parts of the + program). This can make the program more complex. The advantage of + shallow copies is that they consume far less memory than deep + copies. It is also much faster to copy a pointer (typically 4 or 8 + bytes) than to copy string data. + + A Q3StrList that operates on deep copies will, by default, turn on + auto-deletion (see setAutoDelete()). Thus, by default Q3StrList + will deallocate any string copies it allocates. + + The virtual compareItems() function is reimplemented and does a + case-sensitive string comparison. The inSort() function will + insert strings in sorted order. In general it is fastest to insert + the strings as they come and sort() at the end; inSort() is useful + when you just have to add a few extra strings to an already sorted + list. + + The Q3StrListIterator class is an iterator for Q3StrList. +*/ + +/*! + \fn Q3StrList::operator QList() const + + Automatically converts a Q3StrList into a QList. +*/ + +/*! + \fn Q3StrList::Q3StrList( bool deepCopies ) + + Constructs an empty list of strings. Will make deep copies of all + inserted strings if \a deepCopies is TRUE, or use shallow copies + if \a deepCopies is FALSE. +*/ + +/*! + \fn Q3StrList::Q3StrList(const Q3StrList &list) + \fn Q3StrList::Q3StrList(const QList &list) + + Constructs a copy of \a list. +*/ + +/*! + \fn Q3StrList::~Q3StrList() + + Destroys the list. All strings are removed. +*/ + +/*! + \fn Q3StrList& Q3StrList::operator=(const Q3StrList& list) + \fn Q3StrList &Q3StrList::operator=(const QList &list) + + Assigns \a list to this list and returns a reference to this list. +*/ + +/*! + \class Q3StrIList + \brief The Q3StrIList class provides a doubly-linked list of char* + with case-insensitive comparison. + \compat + + This class is a Q3PtrList\ instance (a list of char*). + + Q3StrIList is identical to Q3StrList except that the virtual + compareItems() function is reimplemented to compare strings + case-insensitively. The inSort() function inserts strings in a + sorted order. In general it is fastest to insert the strings as + they come and sort() at the end; inSort() is useful when you just + have to add a few extra strings to an already sorted list. + + The Q3StrListIterator class works for Q3StrIList. + + \sa QStringList +*/ + +/*! + \fn Q3StrIList::Q3StrIList( bool deepCopies ) + + Constructs a list of strings. Will make deep copies of all + inserted strings if \a deepCopies is TRUE, or use shallow copies + if \a deepCopies is FALSE. +*/ + +/*! + \fn Q3StrIList::~Q3StrIList() + + Destroys the list. All strings are removed. +*/ + +/*! + \fn int Q3PtrList::compareItems( Q3PtrCollection::Item item1, + Q3PtrCollection::Item item2 ) + + This virtual function compares two list items. + + Returns: + \list + \i zero if \a item1 == \a item2 + \i nonzero if \a item1 != \a item2 + \endlist + + This function returns \e int rather than \e bool so that + reimplementations can return three values and use it to sort by: + + \list + \i 0 if \a item1 == \a item2 + \i \> 0 (positive integer) if \a item1 \> \a item2 + \i \< 0 (negative integer) if \a item1 \< \a item2 + \endlist + + inSort() requires that compareItems() is implemented as described + here. + + This function should not modify the list because some const + functions call compareItems(). + + The default implementation compares the pointers. +*/ + +/*! + \fn QDataStream& Q3PtrList::read( QDataStream& s, + Q3PtrCollection::Item& item ) + + Reads a list item from the stream \a s and returns a reference to + the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrList::write( QDataStream& s, + Q3PtrCollection::Item item ) const + + Writes a list item, \a item to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ + +/*! \fn iterator Q3PtrList::begin() +\internal +*/ +/*! \fn const_iterator Q3PtrList::begin() const +\internal +*/ +/*! \fn iterator Q3PtrList::end() +\internal +*/ +/*! \fn const_iterator Q3PtrList::end() const +\internal +*/ + +/*! + \class Q3StrListIterator + \brief The Q3StrListIterator class is an iterator for the Q3StrList + and Q3StrIList classes. + \compat + + This class is a Q3PtrListIterator\ instance. It can traverse + the strings in the Q3StrList and Q3StrIList classes. +*/ + + +/* + \class Q3PtrListAutoDelete + \brief The Q3PtrListAutoDelete class is a template class that provides a list that auto-deletes its data. + \compat + + A Q3PtrListAutoDelete is identical to a Q3PtrList with + setAutoDelete(TRUE). +*/ diff --git a/doc/src/classes/q3ptrqueue.qdoc b/doc/src/classes/q3ptrqueue.qdoc new file mode 100644 index 0000000..b3af5f6 --- /dev/null +++ b/doc/src/classes/q3ptrqueue.qdoc @@ -0,0 +1,230 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrQueue + \brief The Q3PtrQueue class is a template class that provides a queue. + \compat + + Q3ValueVector can be used as an STL-compatible alternative to this + class. + + A template instance Q3PtrQueue\ is a queue that operates on + pointers to X (X*). + + A queue is a first in, first out structure. Items are added to the + tail of the queue with enqueue() and retrieved from the head with + dequeue(). You can peek at the head item without dequeing it using + head(). + + You can control the queue's deletion policy with setAutoDelete(). + + For compatibility with the Q3PtrCollection classes, current() and + remove() are provided; both operate on the head(). + + \sa Q3PtrList Q3PtrStack +*/ + +/*! + \fn Q3PtrQueue::Q3PtrQueue () + + Creates an empty queue with autoDelete() set to FALSE. +*/ + +/*! + \fn Q3PtrQueue::Q3PtrQueue( const Q3PtrQueue& queue ) + + Creates a queue from \a queue. + + Only the pointers are copied; the items are not. The autoDelete() + flag is set to FALSE. +*/ + +/*! + \fn Q3PtrQueue::~Q3PtrQueue() + + Destroys the queue. Items in the queue are deleted if autoDelete() + is TRUE. +*/ + +/*! + \fn Q3PtrQueue& Q3PtrQueue::operator= (const Q3PtrQueue& queue) + + Assigns \a queue to this queue and returns a reference to this + queue. + + This queue is first cleared and then each item in \a queue is + enqueued to this queue. Only the pointers are copied. + + \warning The autoDelete() flag is not modified. If it is TRUE for + both \a queue and this queue, deleting the two lists will cause \e + double-deletion of the items. +*/ + +/*! + \fn bool Q3PtrQueue::isEmpty() const + + Returns TRUE if the queue is empty; otherwise returns FALSE. + + \sa count() dequeue() head() +*/ + +/*! + \fn void Q3PtrQueue::enqueue (const type* d) + + Adds item \a d to the tail of the queue. + + \sa count() dequeue() +*/ + +/*! + \fn type* Q3PtrQueue::dequeue () + + Takes the head item from the queue and returns a pointer to it. + Returns 0 if the queue is empty. + + \sa enqueue() count() +*/ + +/*! + \fn bool Q3PtrQueue::remove() + + Removes the head item from the queue, and returns TRUE if there + was an item, i.e. the queue wasn't empty; otherwise returns FALSE. + + The item is deleted if autoDelete() is TRUE. + + \sa head() isEmpty() dequeue() +*/ + +/*! + \fn void Q3PtrQueue::clear() + + Removes all items from the queue, and deletes them if autoDelete() + is TRUE. + + \sa remove() +*/ + +/*! + \fn uint Q3PtrQueue::count() const + + Returns the number of items in the queue. + + \sa isEmpty() +*/ + +/*! + \fn type* Q3PtrQueue::head() const + + Returns a pointer to the head item in the queue. The queue is not + changed. Returns 0 if the queue is empty. + + \sa dequeue() isEmpty() +*/ + +/*! + \fn Q3PtrQueue::operator type*() const + + Returns a pointer to the head item in the queue. The queue is not + changed. Returns 0 if the queue is empty. + + \sa dequeue() isEmpty() +*/ + +/*! + \fn type* Q3PtrQueue::current() const + + Returns a pointer to the head item in the queue. The queue is not + changed. Returns 0 if the queue is empty. + + \sa dequeue() isEmpty() +*/ + +/*! + \fn bool Q3PtrQueue::autoDelete() const + + Returns the setting of the auto-delete option. The default is + FALSE. + + \sa setAutoDelete() +*/ + +/*! + \fn void Q3PtrQueue::setAutoDelete( bool enable ) + + Sets the queue to auto-delete its contents if \a enable is TRUE + and not to delete them if \a enable is FALSE. + + If auto-deleting is turned on, all the items in a queue are + deleted when the queue itself is deleted. This can be quite + convenient if the queue has the only pointer to the items. + + The default setting is FALSE, for safety. If you turn it on, be + careful about copying the queue: you might find yourself with two + queues deleting the same items. + + \sa autoDelete() +*/ + +/*! + \fn QDataStream& Q3PtrQueue::read( QDataStream& s, + Q3PtrCollection::Item& item ) + + Reads a queue item, \a item, from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrQueue::write( QDataStream& s, + Q3PtrCollection::Item item ) const + + Writes a queue item, \a item, to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ diff --git a/doc/src/classes/q3ptrstack.qdoc b/doc/src/classes/q3ptrstack.qdoc new file mode 100644 index 0000000..1650d69 --- /dev/null +++ b/doc/src/classes/q3ptrstack.qdoc @@ -0,0 +1,217 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrStack + \brief The Q3PtrStack class is a template class that provides a stack. + \compat + + Q3ValueStack is an STL-compatible alternative to this class. + + Define a template instance Q3PtrStack\ to create a stack that + operates on pointers to X, (X*). + + A stack is a last in, first out (LIFO) structure. Items are added + to the top of the stack with push() and retrieved from the top + with pop(). Use top() to get a reference to the top element + without changing the stack. + + You can control the stack's deletion policy with setAutoDelete(). + + For compatibility with the Q3PtrCollection classes current() and + remove() are provided; they both operate on the top(). + + \sa Q3PtrList Q3PtrQueue +*/ + +/*! + \fn Q3PtrStack::Q3PtrStack () + + Creates an empty stack. +*/ + +/*! + \fn Q3PtrStack::Q3PtrStack (const Q3PtrStack& s) + + Creates a stack by making a shallow copy of another stack \a s. +*/ + +/*! + \fn Q3PtrStack::~Q3PtrStack () + + Destroys the stack. All items will be deleted if autoDelete() is + true. +*/ + +/*! + \fn Q3PtrStack& Q3PtrStack::operator= (const Q3PtrStack& s) + + Sets the contents of this stack by making a shallow copy of + another stack \a s. Elements currently in this stack will be + deleted if autoDelete() is true. +*/ + +/*! + \fn bool Q3PtrStack::isEmpty () const + + Returns true if the stack contains no elements; otherwise returns + false. +*/ + +/*! + \fn void Q3PtrStack::push (const type* d) + + Adds an element \a d to the top of the stack. Last in, first out. +*/ + +/*! + \fn type* Q3PtrStack::pop () + + Removes the top item from the stack and returns it. The stack must + not be empty. +*/ + +/*! + \fn bool Q3PtrStack::remove () + + Removes the top item from the stack and deletes it if autoDelete() + is true. Returns true if there was an item to pop; otherwise + returns false. + + \sa clear() +*/ + +/*! + \fn void Q3PtrStack::clear() + + Removes all items from the stack, deleting them if autoDelete() is + true. + + \sa remove() +*/ + +/*! + \fn uint Q3PtrStack::count() const + + Returns the number of items in the stack. + + \sa isEmpty() +*/ + +/*! + \fn type* Q3PtrStack::top () const + + Returns a pointer to the top item on the stack (most recently + pushed). The stack is not changed. Returns 0 if the stack is + empty. +*/ + +/*! + \fn Q3PtrStack::operator type* ()const + + Returns a pointer to the top item on the stack (most recently + pushed). The stack is not changed. Returns 0 if the stack is + empty. +*/ + +/*! + \fn type* Q3PtrStack::current () const + + Returns a pointer to the top item on the stack (most recently + pushed). The stack is not changed. Returns 0 if the stack is + empty. +*/ + +/*! + \fn bool Q3PtrStack::autoDelete() const + + The same as Q3PtrCollection::autoDelete(). Returns true if + the auto-delete option is set. If the option is set, the + stack auto-deletes its contents. + + \sa setAutoDelete() +*/ + +/*! + \fn void Q3PtrStack::setAutoDelete(bool enable) + + Defines whether this stack auto-deletes its contents. The same as + Q3PtrCollection::setAutoDelete(). If \a enable is true, auto-delete + is turned on. + + If auto-deleting is turned on, all the items in the stack are + deleted when the stack itself is deleted. This is convenient if + the stack has the only pointers to the items. + + The default setting is false, for safety. If you turn it on, be + careful about copying the stack, or you might find yourself with + two stacks deleting the same items. + + Note that the auto-delete setting may also affect other functions in + subclasses. For example, a subclass that has a remove() function + will remove the item from its data structure, and if auto-delete is + enabled, will also delete the item. + + \sa autoDelete() +*/ + +/*! + \fn QDataStream& Q3PtrStack::read(QDataStream& s, Q3PtrCollection::Item& item) + + Reads a stack item, \a item, from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrStack::write(QDataStream& s, + Q3PtrCollection::Item item) const + + Writes a stack item, \a item, to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ diff --git a/doc/src/classes/q3ptrvector.qdoc b/doc/src/classes/q3ptrvector.qdoc new file mode 100644 index 0000000..fa78de5 --- /dev/null +++ b/doc/src/classes/q3ptrvector.qdoc @@ -0,0 +1,427 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3PtrVector + \brief The Q3PtrVector class is a template collection class that + provides a vector (array). + \compat + + Q3ValueVector is an STL-compatible alternative to this class. + + Q3PtrVector is implemented as a template class. Defines a template + instance Q3PtrVector\ to create a vector that contains pointers + to X (X*). + + A vector is the same as an array. The main difference between + Q3PtrVector and Q3MemArray is that Q3PtrVector stores pointers to the + elements, whereas Q3MemArray stores the elements themselves (i.e. + Q3MemArray is value-based and Q3PtrVector is pointer-based). + + Items are added to the vector using insert() or fill(). Items are + removed with remove(). You can get a pointer to an item at a + particular index position using at(). + + Unless otherwise stated, all functions that remove items from the + vector will also delete the element pointed to if \link + setAutoDelete() auto-deletion\endlink is enabled. By default, + auto-deletion is disabled; see setAutoDelete(). This behavior can + be changed in a subclass by reimplementing the virtual function + deleteItem(). + + Functions that compare items (find() and sort() for example) will + do so using the virtual function compareItems(). The default + implementation of this function only compares the pointer values. + Reimplement compareItems() in a subclass to get searching and + sorting based on the item contents. You can perform a linear + search for a pointer in the vector using findRef(), or a binary + search (of a sorted vector) using bsearch(). You can count the + number of times an item appears in the vector with contains() or + containsRef(). + + \sa Q3MemArray +*/ + +/*! + \fn Q3PtrVector::Q3PtrVector() + + Constructs a null vector. + + \sa isNull() +*/ + +/*! + \fn Q3PtrVector::Q3PtrVector(uint size) + + Constructs an vector with room for \a size items. Makes a null + vector if \a size == 0. + + All \a size positions in the vector are initialized to 0. + + \sa size(), resize(), isNull() +*/ + +/*! + \fn Q3PtrVector::Q3PtrVector(const Q3PtrVector &v) + + Constructs a copy of \a v. Only the pointers are copied (i.e. + shallow copy). +*/ + +/*! + \fn Q3PtrVector::~Q3PtrVector() + + Removes all items from the vector, and destroys the vector itself. + + \sa clear() +*/ + +/*! + \fn Q3PtrVector &Q3PtrVector::operator=(const Q3PtrVector &v) + + Assigns \a v to this vector and returns a reference to this + vector. + + This vector is first cleared and then all the items from \a v are + copied into the vector. Only the pointers are copied (i.e. shallow + copy). + + \sa clear() +*/ + +/*! + \fn type **Q3PtrVector::data() const + + Returns a pointer to the actual vector data, which is an array of + type*. + + The vector is a null vector if data() == 0 (null pointer). + + \sa isNull() +*/ + +/*! + \fn uint Q3PtrVector::size() const + + Returns the size of the vector, i.e. the number of vector + positions. This is also the maximum number of items the vector can + hold. + + The vector is a null vector if size() == 0. + + \sa isNull(), resize(), count() +*/ + +/*! + \fn uint Q3PtrVector::count() const + + Returns the number of items in the vector. The vector is empty if + count() == 0. + + \sa isEmpty(), size(), isNull() +*/ + +/*! + \fn bool Q3PtrVector::isEmpty() const + + Returns true if the vector is empty; otherwise returns false. + + \sa count() +*/ + +/*! + \fn bool Q3PtrVector::isNull() const + + Returns true if the vector is null; otherwise returns false. + + A null vector has size() == 0 and data() == 0. + + \sa size() +*/ + +/*! + \fn bool Q3PtrVector::resize(uint size) + + Resizes (expands or shrinks) the vector to \a size elements. The + vector becomes a null vector if \a size == 0. + + Any items at position \a size or beyond in the vector are removed. + New positions are initialized to 0. + + Returns true if successful, i.e. if the memory was successfully + allocated; otherwise returns false. + + \sa size(), isNull() +*/ + +/*! + \fn bool Q3PtrVector::insert(uint i, const type *d) + + Sets position \a i in the vector to contain the item \a d. \a i + must be less than size(). Any previous element in position \a i is + removed. + + Returns true if \a i is within range; otherwise returns false. + + \sa at() +*/ + +/*! + \fn bool Q3PtrVector::remove(uint i) + + Removes the item at position \a i in the vector, if there is one. + \a i must be less than size(). + + Returns true if \a i is within range; otherwise returns false. + + \sa take(), at() +*/ + +/*! + \fn type* Q3PtrVector::take(uint i) + + Returns the item at position \a i in the vector, and removes that + item from the vector. \a i must be less than size(). If there is + no item at position \a i, 0 is returned. + + Unlike remove(), this function does \e not call deleteItem() for + the removed item. + + \sa remove(), at() +*/ + +/*! + \fn void Q3PtrVector::clear() + + Removes all items from the vector, and destroys the vector itself. + + The vector becomes a null vector. + + \sa isNull() +*/ + +/*! + \fn bool Q3PtrVector::fill(const type *d, int size) + + Inserts item \a d in all positions in the vector. Any existing + items are removed. If \a d is 0, the vector becomes empty. + + If \a size >= 0, the vector is first resized to \a size. By + default, \a size is -1. + + Returns true if successful, i.e. \a size is the same as the + current size, or \a size is larger and the memory has successfully + been allocated; otherwise returns false. + + \sa resize(), insert(), isEmpty() +*/ + +/*! + \fn void Q3PtrVector::sort() + + Sorts the items in ascending order. Any empty positions will be + put last. + + Compares items using the virtual function compareItems(). + + \sa bsearch() +*/ + +/*! + \fn int Q3PtrVector::bsearch(const type* d) const + + In a sorted array, finds the first occurrence of \a d using a + binary search. For a sorted array, this is generally much faster + than find(), which performs a linear search. + + Returns the position of \a d, or -1 if \a d could not be found. \a + d must not be 0. + + Compares items using the virtual function compareItems(). + + \sa sort(), find() +*/ + + +/*! + \fn int Q3PtrVector::findRef(const type *d, uint i) const + + Finds the first occurrence of the item pointer \a d in the vector + using a linear search. The search starts at position \a i, which + must be less than size(). \a i is by default 0; i.e. the search + starts at the start of the vector. + + Returns the position of \a d, or -1 if \a d could not be found. + + This function does \e not use compareItems() to compare items. + + Use the much faster bsearch() to search a sorted vector. + + \sa find(), bsearch() +*/ + +/*! + \fn int Q3PtrVector::find(const type *d, uint i) const + + Finds the first occurrence of item \a d in the vector using a + linear search. The search starts at position \a i, which must be + less than size(). \a i is by default 0; i.e. the search starts at + the start of the vector. + + Returns the position of \a d, or -1 if \a d could not be found. + + Compares items using the virtual function compareItems(). + + Use the much faster bsearch() to search a sorted vector. + + \sa findRef(), bsearch() +*/ + + +/*! + \fn uint Q3PtrVector::containsRef(const type *d) const + + Returns the number of occurrences of the item pointer \a d in the + vector. + + This function does \e not use compareItems() to compare items. + + \sa findRef() +*/ + +/*! + \fn uint Q3PtrVector::contains(const type *d) const + + Returns the number of occurrences of item \a d in the vector. + + Compares items using the virtual function compareItems(). + + \sa containsRef() +*/ + +/*! + \fn type *Q3PtrVector::operator[](int i) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). + + Equivalent to at(\a i). + + \sa at() +*/ + +/*! + \fn type *Q3PtrVector::at(uint i) const + + Returns the item at position \a i, or 0 if there is no item at + that position. \a i must be less than size(). +*/ + + +/*! + \fn void Q3PtrVector::toList(Q3GList *list) const + + \internal + + Copies all items in this vector to the list \a list. \a list is + first cleared and then all items are appended to \a list. + + \sa Q3PtrList, Q3PtrStack, Q3PtrQueue +*/ + +/*! + \fn int Q3PtrVector::compareItems(Q3PtrCollection::Item d1, + Q3PtrCollection::Item d2) + + This virtual function compares two list items. + + Returns: + \list + \i zero if \a d1 == \a d2 + \i nonzero if \a d1 != \a d2 + \endlist + + This function returns \e int rather than \e bool so that + reimplementations can return one of three values and use it to + sort by: + \list + \i 0 if \a d1 == \a d2 + \i \> 0 (positive integer) if \a d1 \> \a d2 + \i \< 0 (negative integer) if \a d1 \< \a d2 + \endlist + + The sort() and bsearch() functions require compareItems() to be + implemented as described here. + + This function should not modify the vector because some const + functions call compareItems(). +*/ + +/*! + \fn QDataStream& Q3PtrVector::read(QDataStream &s, + Q3PtrCollection::Item &item) + + Reads a vector item, \a item, from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3PtrVector::write(QDataStream &s, + Q3PtrCollection::Item item) const + + Writes a vector item, \a item, to the stream \a s and returns a + reference to the stream. + + The default implementation does nothing. + + \sa read() +*/ + +/*! + \fn bool Q3PtrVector::operator==(const Q3PtrVector &v) const + + Returns true if this vector and \a v are equal; otherwise returns + false. +*/ diff --git a/doc/src/classes/q3sqlfieldinfo.qdoc b/doc/src/classes/q3sqlfieldinfo.qdoc new file mode 100644 index 0000000..ba064f3 --- /dev/null +++ b/doc/src/classes/q3sqlfieldinfo.qdoc @@ -0,0 +1,234 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3SqlFieldInfo + \brief The Q3SqlFieldInfo class stores meta data associated with a SQL field. + + \compat + + Q3SqlFieldInfo objects only store meta data; field values are + stored in QSqlField objects. + + All values must be set in the constructor, and may be retrieved + using isRequired(), type(), length(), precision(), defaultValue(), + name(), isGenerated() and typeID(). + + \sa Q3SqlRecordInfo +*/ + +/*! + \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QString& name, + QVariant::Type typ, + int required, + int len, + int prec, + const QVariant& defValue, + int typeID, + bool generated, + bool trim, + bool calculated) + + Constructs a Q3SqlFieldInfo with the following parameters: + \table + \row \i \a name \i the name of the field. + \row \i \a typ \i the field's type in a QVariant. + \row \i \a required \i greater than 0 if the field is required, 0 + if its value can be NULL and less than 0 if it cannot be + determined whether the field is required or not. + \row \i \a len \i the length of the field. Note that for + non-character types some databases return either the length in + bytes or the number of digits. -1 signifies that the length cannot + be determined. + \row \i \a prec \i the precision of the field, or -1 if the field + has no precision or it cannot be determined. + \row \i \a defValue \i the default value that is inserted into + the table if none is specified by the user. QVariant() if there is + no default value or it cannot be determined. + \row \i \a typeID \i the internal typeID of the database system + (only useful for low-level programming). 0 if unknown. + \row \i \a generated \i TRUE indicates that this field should be + included in auto-generated SQL statments, e.g. in Q3SqlCursor. + \row \i \a trim \i TRUE indicates that widgets should remove + trailing whitespace from character fields. This does not affect + the field value but only its representation inside widgets. + \row \i \a calculated \i TRUE indicates that the value of this + field is calculated. The value of calculated fields can by + modified by subclassing Q3SqlCursor and overriding + Q3SqlCursor::calculateField(). + \endtable +*/ + +/*! + \fn Q3SqlFieldInfo::~Q3SqlFieldInfo() + + Destroys the object and frees any allocated resources. +*/ + +/*! + \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QSqlField & other) + + Creates a Q3SqlFieldInfo object with the type and the name of the + QSqlField \a other. +*/ + +/*! + \fn bool Q3SqlFieldInfo::operator==(const Q3SqlFieldInfo& other) const + + Assigns \a other to this field info and returns a reference to it. +*/ + +/*! + \fn QSqlField Q3SqlFieldInfo::toField() const + + Returns an empty QSqlField based on the information in this + Q3SqlFieldInfo. +*/ + +/*! + \fn int Q3SqlFieldInfo::isRequired() const + + Returns a value greater than 0 if the field is required (NULL + values are not allowed), 0 if it isn't required (NULL values are + allowed) or less than 0 if it cannot be determined whether the + field is required or not. +*/ + +/*! + \fn QVariant::Type Q3SqlFieldInfo::type() const + + Returns the field's type or QVariant::Invalid if the type is + unknown. +*/ + +/*! + \fn int Q3SqlFieldInfo::length() const + + Returns the field's length. For fields storing text the return + value is the maximum number of characters the field can hold. For + non-character fields some database systems return the number of + bytes needed or the number of digits allowed. If the length cannot + be determined -1 is returned. +*/ + +/*! + \fn int Q3SqlFieldInfo::precision() const + + Returns the field's precision or -1 if the field has no precision + or it cannot be determined. +*/ + +/*! + \fn QVariant Q3SqlFieldInfo::defaultValue() const + + Returns the field's default value or an empty QVariant if the + field has no default value or the value couldn't be determined. + The default value is the value inserted in the database when it + is not explicitly specified by the user. +*/ + +/*! + \fn QString Q3SqlFieldInfo::name() const + + Returns the name of the field in the SQL table. +*/ + +/*! + \fn int Q3SqlFieldInfo::typeID() const + + Returns the internal type identifier as returned from the database + system. The return value is 0 if the type is unknown. +*/ + +/*! + \fn bool Q3SqlFieldInfo::isGenerated() const + + Returns TRUE if the field should be included in auto-generated + SQL statments, e.g. in Q3SqlCursor; otherwise returns FALSE. + + \sa setGenerated() +*/ + +/*! + \fn bool Q3SqlFieldInfo::isTrim() const + + Returns TRUE if trailing whitespace should be removed from + character fields; otherwise returns FALSE. + + \sa setTrim() +*/ + +/*! + \fn bool Q3SqlFieldInfo::isCalculated() const + + Returns TRUE if the field is calculated; otherwise returns FALSE. + + \sa setCalculated() +*/ + +/*! + \fn void Q3SqlFieldInfo::setTrim(bool trim) + + If \a trim is TRUE widgets should remove trailing whitespace from + character fields. This does not affect the field value but only + its representation inside widgets. + + \sa isTrim() +*/ + +/*! + \fn void Q3SqlFieldInfo::setGenerated(bool generated) + + \a generated set to FALSE indicates that this field should not appear + in auto-generated SQL statements (for example in Q3SqlCursor). + + \sa isGenerated() +*/ + +/*! + \fn void Q3SqlFieldInfo::setCalculated(bool calculated) + + \a calculated set to TRUE indicates that this field is a calculated + field. The value of calculated fields can by modified by subclassing + Q3SqlCursor and overriding Q3SqlCursor::calculateField(). + + \sa isCalculated() +*/ diff --git a/doc/src/classes/q3sqlrecordinfo.qdoc b/doc/src/classes/q3sqlrecordinfo.qdoc new file mode 100644 index 0000000..64236d2 --- /dev/null +++ b/doc/src/classes/q3sqlrecordinfo.qdoc @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3SqlRecordInfo + \brief The Q3SqlRecordInfo class encapsulates a set of database field meta data. + + \compat + + This class is a list that holds a set of database field meta + data. Use contains() to see if a given field name exists in the + record, and use find() to get a QSqlFieldInfo record for a named + field. + + \sa Q3SqlFieldInfo +*/ + +/*! + \fn Q3SqlRecordInfo::Q3SqlRecordInfo() + + Constructs an empty record info object. +*/ + +/*! + \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const Q3SqlFieldInfoList& other) + \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const QSqlRecord& other) + + Constructs a copy of \a other. +*/ + +/*! + \fn size_type Q3SqlRecordInfo::contains(const QString& fieldName) const + + Returns the number of times a field called \a fieldName occurs in + the record. Returns 0 if no field by that name could be found. +*/ + +/*! + \fn Q3SqlFieldInfo Q3SqlRecordInfo::find(const QString& fieldName) const + + Returns a QSqlFieldInfo object for the first field in the record + which has the field name \a fieldName. If no matching field is + found then an empty QSqlFieldInfo object is returned. +*/ + +/*! + \fn QSqlRecord Q3SqlRecordInfo::toRecord() const + + Returns an empty QSqlRecord based on the field information + in this Q3SqlRecordInfo. +*/ diff --git a/doc/src/classes/q3valuelist.qdoc b/doc/src/classes/q3valuelist.qdoc new file mode 100644 index 0000000..fd73763 --- /dev/null +++ b/doc/src/classes/q3valuelist.qdoc @@ -0,0 +1,569 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3ValueList + \brief The Q3ValueList class is a value-based template class that + provides lists. + \compat + + Q3ValueList is a Qt implementation of an STL-like list container. + It can be used in your application if the standard \c list is not + available for your target platforms. + + Q3ValueList\ defines a template instance to create a list of + values that all have the class T. Note that Q3ValueList does not + store pointers to the members of the list; it holds a copy of + every member. This is why these kinds of classes are called "value + based"; Q3PtrList and Q3Dict are "pointer based". + + Q3ValueList contains and manages a collection of objects of type T + and provides iterators that allow the contained objects to be + addressed. Q3ValueList owns the contained items. For more relaxed + ownership semantics, see Q3PtrCollection and friends which are + pointer-based containers. + + Some classes cannot be used within a Q3ValueList, for example, all + classes derived from QObject and thus all classes that implement + widgets. Only values can be used in a Q3ValueList. To qualify as a + value the class must provide: + \list + \i a copy constructor; + \i an assignment operator; + \i a default constructor, i.e. a constructor that does not take any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases this is sufficient. + + In addition, some compilers (e.g. Sun CC) might require that the + class provides an equality operator (operator==()). + + Q3ValueList's function naming is consistent with the other Qt + classes (e.g. count(), isEmpty()). Q3ValueList also provides extra + functions for compatibility with STL algorithms, such as size() + and empty(). Programmers already familiar with the STL \c list may + prefer to use the STL-compatible functions. + + Example: + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 0 + + + Notice that the latest changes to Mary's salary did not affect the + value in the list because the list created a copy of Mary's entry. + + There are several ways to find items in the list. The begin() and + end() functions return iterators to the beginning and end of the + list. The advantage of getting an iterator is that you can move + forward or backward from this position by + incrementing/decrementing the iterator. The iterator returned by + end() points to the item which is one \e past the last item in the + container. The past-the-end iterator is still associated with the + list it belongs to, however it is \e not dereferenceable; + operator*() will not return a well-defined value. If the list is + empty(), the iterator returned by begin() will equal the iterator + returned by end(). + + It is safe to have multiple iterators a the list at the same + time. If some member of the list is removed, only iterators + pointing to the removed member become invalid. Inserting into the + list does not invalidate any iterator. For convenience, the + function last() returns a reference to the last item in the list, + and first() returns a reference to the first item. If the + list is empty(), both last() and first() have undefined behavior + (your application will crash or do unpredictable things). Use + last() and first() with caution, for example: + + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 1 + + Because Q3ValueList is value-based there is no need to be careful + about deleting items in the list. The list holds its own copies + and will free them if the corresponding member or the list itself + is deleted. You can force the list to free all of its items with + clear(). + + Q3ValueList is shared implicitly, which means it can be copied in + constant time, i.e. O(1). If multiple Q3ValueList instances share + the same data and one needs to modify its contents, this modifying + instance makes a copy and modifies its private copy; therefore it + does not affect the other instances; this takes O(n) time. This is + often called "copy on write". If a Q3ValueList is being used in a + multi-threaded program, you must protect all access to the list. + See \l QMutex. + + There are several ways to insert items into the list. The + prepend() and append() functions insert items at the beginning and + the end of the list respectively. The insert() function comes in + several flavors and can be used to add one or more items at + specific positions within the list. + + Items can also be removed from the list in several ways. There + are several variants of the remove() function, which removes a + specific item from the list. The remove() function will find and + remove items according to a specific item value. + + \sa Q3ValueListIterator +*/ + +/*! \typedef Q3ValueList::iterator + The list's iterator type, Q3ValueListIterator. */ +/*! \typedef Q3ValueList::const_iterator + The list's const iterator type, Q3ValueListConstIterator. */ +/*! \typedef Q3ValueList::value_type + The type of the object stored in the list, T. */ +/*! \typedef Q3ValueList::pointer + The pointer to T type. */ +/*! \typedef Q3ValueList::const_pointer + The const pointer to T type. */ +/*! \typedef Q3ValueList::reference + The reference to T type. */ +/*! \typedef Q3ValueList::const_reference + The const reference to T type. */ +/*! \typedef Q3ValueList::size_type + An unsigned integral type, used to represent various sizes. */ +/*! \typedef Q3ValueList::difference_type + \internal +*/ +/*! + \fn Q3ValueList::Q3ValueList() + + Constructs an empty list. +*/ + +/*! + \fn Q3ValueList::Q3ValueList( const Q3ValueList& l ) + \fn Q3ValueList::Q3ValueList( const QList& l ) + \fn Q3ValueList::Q3ValueList( const QLinkedList& l ) + + Constructs a copy of \a l. +*/ + +/*! + \fn Q3ValueList::Q3ValueList( const std::list& l ) + + Contructs a copy of \a l. + + This constructor is provided for compatibility with STL + containers. +*/ + +/*! + \fn Q3ValueList::~Q3ValueList() + + Destroys the list. References to the values in the list and all + iterators of this list become invalidated. Note that it is + impossible for an iterator to check whether or not it is valid: + Q3ValueList is highly tuned for performance, not for error + checking. +*/ + +/*! + \fn bool Q3ValueList::operator== ( const Q3ValueList& l ) const + + Compares both lists. + + Returns TRUE if this list and \a l are equal; otherwise returns + FALSE. +*/ + +/*! + \fn bool Q3ValueList::operator== ( const std::list& l ) const + + \overload + + Returns TRUE if this list and \a l are equal; otherwise returns + FALSE. + + This operator is provided for compatibility with STL containers. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator= ( const Q3ValueList& l ) + + Assigns \a l to this list and returns a reference to this list. + + All iterators of the current list become invalidated by this + operation. The cost of such an assignment is O(1) since Q3ValueList + is implicitly shared. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator= ( const QList& l ) + + Assigns \a l to this list and returns a reference to this list. + + All iterators of the current list become invalidated by this + operation. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator= ( const std::list& l ) + + \overload + + Assigns the contents of \a l to the list. + + All iterators of the current list become invalidated by this + operation. +*/ + +/*! + \fn bool Q3ValueList::operator!= ( const Q3ValueList& l ) const + + Compares both lists. + + Returns TRUE if this list and \a l are unequal; otherwise returns + FALSE. +*/ + +/*! + \fn iterator Q3ValueList::insert( typename Q3ValueList::Iterator it, const T& x ) + + Inserts the value \a x in front of the item pointed to by the + iterator, \a it. + + Returns an iterator pointing at the inserted item. + + \sa append(), prepend() +*/ + +/*! + \fn uint Q3ValueList::remove( const T& x ) + + \overload + + Removes all items that have value \a x and returns the number of + removed items. +*/ + +/*! + \fn QDataStream& operator>>( QDataStream& s, Q3ValueList& l ) + + \relates Q3ValueList + + Reads a list, \a l, from the stream \a s. The type T stored in the + list must implement the streaming operator. +*/ + +/*! + \fn QDataStream& operator<<( QDataStream& s, const Q3ValueList& l ) + + \overload + \relates Q3ValueList + + Writes a list, \a l, to the stream \a s. The type T stored in the + list must implement the streaming operator. +*/ + +/*! + \fn void Q3ValueList::insert( typename Q3ValueList::Iterator pos, + typename Q3ValueList::size_type n, const T& x ) + + \overload + + Inserts \a n copies of \a x before position \a pos. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator<< ( const T& x ) + + Adds the value \a x to the end of the list. + + Returns a reference to the list. +*/ + +/*! + \fn const T& Q3ValueList::operator[] ( typename Q3ValueList::size_type i ) const + + Returns a const reference to the item with index \a i in the list. + It is up to you to check whether this item really exists. You can + do that easily with the count() function. However this operator + does not check whether \a i is in range and will deliver undefined + results if it does not exist. + + \warning This function uses a linear search and can be extremely + slow for large lists. Q3ValueList is not optimized for random item + access. If you need random access use a different container, such + as Q3ValueVector. +*/ + +/*! + \fn T& Q3ValueList::operator[] ( typename Q3ValueList::size_type i ) + + \overload + + Returns a non-const reference to the item with index \a i. +*/ + +/*! + \fn const_iterator Q3ValueList::at( typename Q3ValueList::size_type i ) const + + Returns an iterator pointing to the item at position \a i in the + list, or an undefined value if the index is out of range. + + \warning This function uses a linear search and can be extremely + slow for large lists. Q3ValueList is not optimized for random item + access. If you need random access use a different container, such + as Q3ValueVector. +*/ + +/*! + \fn iterator Q3ValueList::at( typename Q3ValueList::size_type i ) + + \overload + + Returns an iterator pointing to the item at position \a i in the + list, or an undefined value if the index is out of range. + +*/ + +/*! + \fn iterator Q3ValueList::fromLast() + + \overload + + Returns an iterator to the last item in the list, or end() if + there is no last item. + + Use the end() function instead. For example: + + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 2 + +*/ + +/*! + \fn const_iterator Q3ValueList::fromLast() const + + Returns an iterator to the last item in the list, or end() if + there is no last item. + + Use the end() function instead. For example: + + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 3 + +*/ + +/*! + \fn Q3ValueList Q3ValueList::operator+( const Q3ValueList& l ) const + + Creates a new list and fills it with the items of this list. Then + the items of \a l are appended. Returns the new list. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator+= ( const Q3ValueList& l ) + + Appends the items of \a l to this list. Returns a reference to + this list. +*/ + +/*! + \fn Q3ValueList& Q3ValueList::operator+= ( const T& x ) + + \overload + + Appends the value \a x to the list. Returns a reference to the + list. +*/ + +/*! + \fn iterator Q3ValueList::append( const T& x ) + + Inserts \a x at the end of the list. + + \sa insert(), prepend() +*/ + +/*! + \fn iterator Q3ValueList::prepend( const T& x ) + + Inserts \a x at the beginning of the list. + + \sa insert(), append() +*/ + +/*! + \fn iterator Q3ValueList::remove( typename Q3ValueList::Iterator it ) + + Removes the item pointed to by \a it from the list. No iterators + other than \a it or other iterators pointing at the same item as + \a it are invalidated. Returns an iterator to the next item after + \a it, or end() if there is no such item. + + \sa clear() +*/ + +/*! + \fn uint Q3ValueList::contains( const T& x ) const + + Returns the number of occurrences of the value \a x in the list. +*/ + +/*! + \class Q3ValueListIterator + \brief The Q3ValueListIterator class provides an iterator for Q3ValueList. + \compat + + An iterator is a class for accessing the items of a container + class: a generalization of the index in an array. A pointer + into a "const char *" and an index into an "int[]" are both + iterators, and the general idea is to provide that functionality + for any data structure. + + The Q3ValueListIterator class is an iterator for Q3ValueList + instantiations. You can create the appropriate iterator type by + using the \c iterator typedef provided by Q3ValueList. + + The only way to access the items in a Q3ValueList is to use an + iterator. + + Example (see Q3ValueList for the complete code): + \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 4 + + Q3ValueList is highly optimized for performance and memory usage. + This means that you must be careful: Q3ValueList does not know + about all its iterators and the iterators don't know to which list + they belong. This makes things very fast, but if you're not + careful, you can get spectacular bugs. Always make sure iterators + are valid before dereferencing them or using them as parameters to + generic algorithms in the STL. + + Using an invalid iterator is undefined (your application will + probably crash). Many Qt functions return const value lists; to + iterate over these you should make a copy and iterate over the + copy. + + For every Iterator there is a ConstIterator. When accessing a + Q3ValueList in a const environment or if the reference or pointer + to the list is itself const, then you must use the ConstIterator. + Its semantics are the same as the Iterator, but it only returns + const references. + + \sa Q3ValueList, Q3ValueListConstIterator +*/ + +/*! + \fn Q3ValueListIterator::Q3ValueListIterator() + + Constructs an unitialized iterator. +*/ + +/*! + \fn Q3ValueListIterator::Q3ValueListIterator(const Q3ValueListIterator &o) + \fn Q3ValueListIterator::Q3ValueListIterator(const typename QLinkedList::iterator &o) + + Constucts a copy of iterator \a o. +*/ + +/*! + \class Q3ValueListConstIterator + \brief The Q3ValueListConstIterator class provides a const iterator + for Q3ValueList. + \compat + + In contrast to Q3ValueListIterator, this class is used to iterate + over a const list. It does not allow modification of the values of + the list since that would break const semantics. + + You can create the appropriate const iterator type by using the \c + const_iterator typedef provided by Q3ValueList. + + For more information on Q3ValueList iterators, see + Q3ValueListIterator. + + \sa Q3ValueListIterator, Q3ValueList +*/ + +/*! + \fn Q3ValueListConstIterator::Q3ValueListConstIterator() + + Constructs an unitialized iterator. +*/ + +/*! + \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const Q3ValueListConstIterator &o) + \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList::const_iterator &o) + \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList::iterator &o) + + Constructs a copy of iterator \a o. +*/ + +/*! + \typedef Q3ValueList::Iterator + + This iterator is an instantiation of Q3ValueListIterator for the + same type as this Q3ValueList. In other words, if you instantiate + Q3ValueList, Iterator is a Q3ValueListIterator. Several + member function use it, such as Q3ValueList::begin(), which returns + an iterator pointing to the first item in the list. + + Functionally, this is almost the same as ConstIterator. The only + difference is that you cannot use ConstIterator for non-const + operations, and that the compiler can often generate better code + if you use ConstIterator. + + \sa Q3ValueListIterator ConstIterator +*/ + +/*! + \typedef Q3ValueList::ConstIterator + + This iterator is an instantiation of Q3ValueListConstIterator for + the same type as this Q3ValueList. In other words, if you + instantiate Q3ValueList, ConstIterator is a + Q3ValueListConstIterator. Several member function use it, such + as Q3ValueList::begin(), which returns an iterator pointing to the + first item in the list. + + Functionally, this is almost the same as Iterator. The only + difference is you cannot use ConstIterator for non-const + operations, and that the compiler can often generate better code + if you use ConstIterator. + + \sa Q3ValueListIterator Iterator +*/ + +/*! + \fn Q3ValueList::operator QList() const + + Automatically converts a Q3ValueList into a QList. +*/ diff --git a/doc/src/classes/q3valuestack.qdoc b/doc/src/classes/q3valuestack.qdoc new file mode 100644 index 0000000..e3ae677 --- /dev/null +++ b/doc/src/classes/q3valuestack.qdoc @@ -0,0 +1,149 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3ValueStack + \brief The Q3ValueStack class is a value-based template class that provides a stack. + \compat + + Define a template instance Q3ValueStack\ to create a stack of + values that all have the class X. + + Note that Q3ValueStack does not store pointers to the members of + the stack; it holds a copy of every member. That is why these + kinds of classes are called "value based"; Q3PtrStack, Q3PtrList, + Q3Dict, etc., are "pointer based". + + A stack is a last in, first out (LIFO) structure. Items are added + to the top of the stack with push() and retrieved from the top + with pop(). The top() function provides access to the topmost item + without removing it. + + Example: + \snippet doc/src/snippets/code/doc_src_q3valuestack.qdoc 0 + + Q3ValueStack is a specialized Q3ValueList provided for convenience. + All of Q3ValueList's functionality also applies to Q3PtrStack, for + example the facility to iterate over all elements using + Q3ValueStack::Iterator. See Q3ValueListIterator for further + details. + + Some classes cannot be used within a Q3ValueStack, for example + everything derived from QObject and thus all classes that + implement widgets. Only values can be used in a Q3ValueStack. To + qualify as a value, the class must provide + \list + \i a copy constructor; + \i an assignment operator; + \i a default constructor, i.e. a constructor that does not take any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases this is sufficient. +*/ + + +/*! + \fn Q3ValueStack::Q3ValueStack() + + Constructs an empty stack. +*/ + +/*! + \fn Q3ValueStack::~Q3ValueStack() + + Destroys the stack. References to the values in the stack and all + iterators of this stack become invalidated. Because Q3ValueStack is + highly tuned for performance, you won't see warnings if you use + invalid iterators because it is impossible for an iterator to + check whether or not it is valid. +*/ + + +/*! + \fn void Q3ValueStack::push( const T& d ) + + Adds element, \a d, to the top of the stack. Last in, first out. + + This function is equivalent to append(). + + \sa pop(), top() +*/ + +/*! + \fn T& Q3ValueStack::top() + + Returns a reference to the top item of the stack or the item + referenced by end() if no such item exists. Note that you must not + change the value the end() iterator points to. + + This function is equivalent to last(). + + \sa pop(), push(), Q3ValueList::fromLast() +*/ + + +/*! + \fn const T& Q3ValueStack::top() const + + \overload + + Returns a reference to the top item of the stack or the item + referenced by end() if no such item exists. + + This function is equivalent to last(). + + \sa pop(), push(), Q3ValueList::fromLast() +*/ + +/*! + \fn T Q3ValueStack::pop() + + Removes the top item from the stack and returns it. + + \sa top() push() +*/ + + + + + diff --git a/doc/src/classes/q3valuevector.qdoc b/doc/src/classes/q3valuevector.qdoc new file mode 100644 index 0000000..353b7fa --- /dev/null +++ b/doc/src/classes/q3valuevector.qdoc @@ -0,0 +1,274 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3ValueVector + \brief The Q3ValueVector class is a value-based template class that provides a dynamic array. + \compat + + Q3ValueVector is a Qt implementation of an STL-like vector + container. It can be used in your application if the standard \c + vector is not available for your target platforms. + + Q3ValueVector\ defines a template instance to create a vector + of values that all have the class T. Q3ValueVector does not store + pointers to the members of the vector; it holds a copy of every + member. Q3ValueVector is said to be value based; in contrast, + Q3PtrList and Q3Dict are pointer based. + + Q3ValueVector contains and manages a collection of objects of type + T and provides random access iterators that allow the contained + objects to be addressed. Q3ValueVector owns the contained + elements. For more relaxed ownership semantics, see Q3PtrCollection + and friends, which are pointer-based containers. + + Q3ValueVector provides good performance if you append or remove + elements from the end of the vector. If you insert or remove + elements from anywhere but the end, performance is very bad. The + reason for this is that elements must to be copied into new + positions. + + Some classes cannot be used within a Q3ValueVector: for example, + all classes derived from QObject and thus all classes that + implement widgets. Only values can be used in a Q3ValueVector. To + qualify as a value the class must provide: + \list + \i a copy constructor; + \i an assignment operator; + \i a default constructor, i.e., a constructor that does not take any arguments. + \endlist + + Note that C++ defaults to field-by-field assignment operators and + copy constructors if no explicit version is supplied. In many + cases this is sufficient. + + Q3ValueVector uses an STL-like syntax to manipulate and address the + objects it contains. + + Example: + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 0 + + Program output: + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 1 + + As you can see, the most recent change to Joe's salary did not + affect the value in the vector because the vector created a copy + of Joe's entry. + + Many Qt functions return const value vectors; to iterate over + these you should make a copy and iterate over the copy. + + There are several ways to find items in the vector. The begin() + and end() functions return iterators to the beginning and end of + the vector. The advantage of getting an iterator is that you can + move forward or backward from this position by + incrementing/decrementing the iterator. The iterator returned by + end() points to the element which is one past the last element in + the container. The past-the-end iterator is still associated with + the vector it belongs to, however it is \e not dereferenceable; + operator*() will not return a well-defined value. If the vector is + empty(), the iterator returned by begin() will equal the iterator + returned by end(). + + The fastest way to access an element of a vector is by using + operator[]. This function provides random access and will return + a reference to the element located at the specified index. Thus, + you can access every element directly, in constant time, providing + you know the location of the element. It is undefined to access + an element that does not exist (your application will probably + crash). For example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 2 + + Whenever inserting, removing or referencing elements in a vector, + always make sure you are referring to valid positions. For + example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 3 + + The iterators provided by vector are random access iterators, + therefore you can use them with many generic algorithms, for + example, algorithms provided by the STL. + + It is safe to have multiple iterators on the vector at the same + time. Since Q3ValueVector manages memory dynamically, all iterators + can become invalid if a memory reallocation occurs. For example, + if some member of the vector is removed, iterators that point to + the removed element and to all following elements become + invalidated. Inserting into the middle of the vector will + invalidate all iterators. For convenience, the function back() + returns a reference to the last element in the vector, and front() + returns a reference to the first element. If the vector is + empty(), both back() and front() have undefined behavior (your + application will crash or do unpredictable things). Use back() and + front() with caution, for example: + + \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 4 + + Because Q3ValueVector manages memory dynamically, it is recommended + that you contruct a vector with an initial size. Inserting and + removing elements happens fastest when: + \list + \i Inserting or removing elements happens at the end() of the + vector; + \i The vector does not need to allocate additional memory. + \endlist + + By creating a Q3ValueVector with a sufficiently large initial size, + there will be less memory allocations. Do not use an initial size + that is too big, since it will still take time to construct all + the empty entries, and the extra space will be wasted if it is + never used. + + Because Q3ValueVector is value-based there is no need to be careful + about deleting elements in the vector. The vector holds its own + copies and will free them if the corresponding member or the + vector itself is deleted. You can force the vector to free all of + its items with clear(). + + Q3ValueVector is shared implicitly, which means it can be copied in + constant time. If multiple Q3ValueVector instances share the same + data and one needs to modify its contents, this modifying instance + makes a copy and modifies its private copy; it thus does not + affect the other instances. This is often called "copy on write". + If a Q3ValueVector is being used in a multi-threaded program, you + must protect all access to the vector. See QMutex. + + There are several ways to insert elements into the vector. The + push_back() function insert elements into the end of the vector, + and is usually fastest. The insert() function can be used to add + elements at specific positions within the vector. + + Items can be also be removed from the vector in several ways. + There are several variants of the erase() function which removes a + specific element, or range of elements, from the vector. + + Q3ValueVector stores its elements in contiguous memory. This means + that you can use a Q3ValueVector in any situation that requires an + array. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector() + + Constructs an empty vector without any elements. To create a + vector which reserves an initial amount of space for elements, use + \c Q3ValueVector(size_type n). +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( const Q3ValueVector& v ) + + Constructs a copy of \a v. + + This operation costs O(1) time because Q3ValueVector is implicitly + shared. + + The first modification to the vector does takes O(n) time, because + the elements must be copied. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( const std::vector& v ) + + This operation costs O(n) time because \a v is copied. +*/ + +/*! + \fn Q3ValueVector::Q3ValueVector( QVector::size_type n, const T& val ) + + Constructs a vector with an initial size of \a n elements. Each + element is initialized with the value of \a val. +*/ + +/*! + \fn Q3ValueVector& Q3ValueVector::operator=( const Q3ValueVector& v ) + + Assigns \a v to this vector and returns a reference to this vector. + + All iterators of the current vector become invalidated by this + operation. The cost of such an assignment is O(1) since + Q3ValueVector is implicitly shared. +*/ + +/*! + \fn Q3ValueVector& Q3ValueVector::operator=( const std::vector& v ) + + \overload + + Assigns \a v to this vector and returns a reference to this vector. + + All iterators of the current vector become invalidated by this + operation. The cost of this assignment is O(n) since \a v is + copied. +*/ + +/*! + \fn T &Q3ValueVector::at( int i , bool* ok ) + + Returns a reference to the element with index \a i. If \a ok is + non-null, and the index \a i is out of range, *\a ok is set to + FALSE and the returned reference is undefined. If the index \a i + is within the range of the vector, and \a ok is non-null, *\a ok + is set to TRUE and the returned reference is well defined. +*/ + +/*! + \fn const T &Q3ValueVector::at( int i , bool* ok ) const + + \overload + + Returns a const reference to the element with index \a i. If \a ok + is non-null, and the index \a i is out of range, *\a ok is set to + FALSE and the returned reference is undefined. If the index \a i + is within the range of the vector, and \a ok is non-null, *\a ok + is set to TRUE and the returned reference is well defined. +*/ + +/*! + \fn void Q3ValueVector::resize( int n, const T& val = T() ) + + Changes the size of the vector to \a n. If \a n is greater than + the current size(), elements are added to the end and initialized + with the value of \a val. If \a n is less than size(), elements + are removed from the end. If \a n is equal to size() nothing + happens. +*/ diff --git a/doc/src/classes/qalgorithms.qdoc b/doc/src/classes/qalgorithms.qdoc new file mode 100644 index 0000000..7634322 --- /dev/null +++ b/doc/src/classes/qalgorithms.qdoc @@ -0,0 +1,651 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \headerfile + \title Generic Algorithms + \ingroup architecture + + \brief The header provides generic template-based algorithms. + + Qt provides a number of global template functions in \c + that work on containers and perform well-know + algorithms. You can use these algorithms with any \l {container + class} that provides STL-style iterators, including Qt's QList, + QLinkedList, QVector, QMap, and QHash classes. + + These functions have taken their inspiration from similar + functions available in the STL \c header. Most of them + have a direct STL equivalent; for example, qCopyBackward() is the + same as STL's copy_backward() algorithm. + + If STL is available on all your target platforms, you can use the + STL algorithms instead of their Qt counterparts. One reason why + you might want to use the STL algorithms is that STL provides + dozens and dozens of algorithms, whereas Qt only provides the most + important ones, making no attempt to duplicate functionality that + is already provided by the C++ standard. + + Most algorithms take \l {STL-style iterators} as parameters. The + algorithms are generic in the sense that they aren't bound to a + specific iterator class; you can use them with any iterators that + meet a certain set of requirements. + + Let's take the qFill() algorithm as an example. Unlike QVector, + QList has no fill() function that can be used to fill a list with + a particular value. If you need that functionality, you can use + qFill(): + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 0 + + qFill() takes a begin iterator, an end iterator, and a value. + In the example above, we pass \c list.begin() and \c list.end() + as the begin and end iterators, but this doesn't have to be + the case: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 1 + + Different algorithms can have different requirements for the + iterators they accept. For example, qFill() accepts two + \l {forward iterators}. The iterator types required are specified + for each algorithm. If an iterator of the wrong type is passed (for + example, if QList::ConstIterator is passed as an \l {output + iterator}), you will always get a compiler error, although not + necessarily a very informative one. + + Some algorithms have special requirements on the value type + stored in the containers. For example, qEqual() requires that the + value type supports operator==(), which it uses to compare items. + Similarly, qDeleteAll() requires that the value type is a + non-const pointer type (for example, QWidget *). The value type + requirements are specified for each algorithm, and the compiler + will produce an error if a requirement isn't met. + + \target binaryFind example + + The generic algorithms can be used on other container classes + than those provided by Qt and STL. The syntax of STL-style + iterators is modeled after C++ pointers, so it's possible to use + plain arrays as containers and plain pointers as iterators. A + common idiom is to use qBinaryFind() together with two static + arrays: one that contains a list of keys, and another that + contains a list of associated values. For example, the following + code will look up an HTML entity (e.g., \c &) in the \c + name_table array and return the corresponding Unicode value from + the \c value_table if the entity is recognized: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 2 + + This kind of code is for advanced users only; for most + applications, a QMap- or QHash-based approach would work just as + well: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 3 + + \section1 Types of Iterators + + The algorithms have certain requirements on the iterator types + they accept, and these are specified individually for each + function. The compiler will produce an error if a requirement + isn't met. + + \section2 Input Iterators + + An \e{input iterator} is an iterator that can be used for reading + data sequentially from a container. It must provide the following + operators: \c{==} and \c{!=} for comparing two iterators, unary + \c{*} for retrieving the value stored in the item, and prefix + \c{++} for advancing to the next item. + + The Qt containers' iterator types (const and non-const) are all + input iterators. + + \section2 Output Iterators + + An \e{output iterator} is an iterator that can be used for + writing data sequentially to a container or to some output + stream. It must provide the following operators: unary \c{*} for + writing a value (i.e., \c{*it = val}) and prefix \c{++} for + advancing to the next item. + + The Qt containers' non-const iterator types are all output + iterators. + + \section2 Forward Iterators + + A \e{forward iterator} is an iterator that meets the requirements + of both input iterators and output iterators. + + The Qt containers' non-const iterator types are all forward + iterators. + + \section2 Bidirectional Iterators + + A \e{bidirectional iterator} is an iterator that meets the + requirements of forward iterators but that in addition supports + prefix \c{--} for iterating backward. + + The Qt containers' non-const iterator types are all bidirectional + iterators. + + \section2 Random Access Iterators + + The last category, \e{random access iterators}, is the most + powerful type of iterator. It supports all the requirements of a + bidirectional iterator, and supports the following operations: + + \table + \row \i \c{i += n} \i advances iterator \c i by \c n positions + \row \i \c{i -= n} \i moves iterator \c i back by \c n positions + \row \i \c{i + n} or \c{n + i} \i returns the iterator for the item \c + n positions ahead of iterator \c i + \row \i \c{i - n} \i returns the iterator for the item \c n positions behind of iterator \c i + \row \i \c{i - j} \i returns the number of items between iterators \c i and \c j + \row \i \c{i[n]} \i same as \c{*(i + n)} + \row \i \c{i < j} \i returns true if iterator \c j comes after iterator \c i + \endtable + + QList and QVector's non-const iterator types are random access iterators. + + \sa {container classes}, +*/ + +/*! \fn OutputIterator qCopy(InputIterator begin1, InputIterator end1, OutputIterator begin2) + \relates + + Copies the items from range [\a begin1, \a end1) to range [\a + begin2, ...), in the order in which they appear. + + The item at position \a begin1 is assigned to that at position \a + begin2; the item at position \a begin1 + 1 is assigned to that at + position \a begin2 + 1; and so on. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 4 + + \sa qCopyBackward(), {input iterators}, {output iterators} +*/ + +/*! \fn BiIterator2 qCopyBackward(BiIterator1 begin1, BiIterator1 end1, BiIterator2 end2) + \relates + + Copies the items from range [\a begin1, \a end1) to range [..., + \a end2). + + The item at position \a end1 - 1 is assigned to that at position + \a end2 - 1; the item at position \a end1 - 2 is assigned to that + at position \a end2 - 2; and so on. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 5 + + \sa qCopy(), {bidirectional iterators} +*/ + +/*! \fn bool qEqual(InputIterator1 begin1, InputIterator1 end1, InputIterator2 begin2) + \relates + + Compares the items in the range [\a begin1, \a end1) with the + items in the range [\a begin2, ...). Returns true if all the + items compare equal; otherwise returns false. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 6 + + This function requires the item type (in the example above, + QString) to implement \c operator==(). + + \sa {input iterators} +*/ + +/*! \fn void qFill(ForwardIterator begin, ForwardIterator end, const T &value) + \relates + + Fills the range [\a begin, \a end) with \a value. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 7 + + \sa qCopy(), {forward iterators} +*/ + +/*! \fn void qFill(Container &container, const T &value) + \relates + + \overload + + This is the same as qFill(\a{container}.begin(), \a{container}.end(), \a value); +*/ + +/*! \fn InputIterator qFind(InputIterator begin, InputIterator end, const T &value) + \relates + + Returns an iterator to the first occurrence of \a value in a + container in the range [\a begin, \a end). Returns \a end if \a + value isn't found. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 8 + + This function requires the item type (in the example above, + QString) to implement \c operator==(). + + If the items in the range are in ascending order, you can get + faster results by using qLowerBound() or qBinaryFind() instead of + qFind(). + + \sa qBinaryFind(), {input iterators} +*/ + +/*! \fn void qFind(const Container &container, const T &value) + \relates + + \overload + + This is the same as qFind(\a{container}.begin(), \a{container}.end(), value); +*/ + +/*! \fn void qCount(InputIterator begin, InputIterator end, const T &value, Size &n) + \relates + + Returns the number of occurrences of \a value in the range [\a begin, \a end), + which is returned in \a n. \a n is never initialized, the count is added to \a n. + It is the caller's responsibility to initialize \a n. + + Example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 9 + + This function requires the item type (in the example above, + \c int) to implement \c operator==(). + + \sa {input iterators} +*/ + +/*! \fn void qCount(const Container &container, const T &value, Size &n) +\relates + +\overload + +Instead of operating on iterators, as in the other overload, this function +operates on the specified \a container to obtain the number of instances +of \a value in the variable passed as a reference in argument \a n. +*/ + +/*! \fn void qSwap(T &var1, T &var2) + \relates + + Exchanges the values of variables \a var1 and \a var2. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 10 +*/ + +/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end) + \relates + + Sorts the items in range [\a begin, \a end) in ascending order + using the quicksort algorithm. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 11 + + The sort algorithm is efficient on large data sets. It operates + in \l {linear-logarithmic time}, O(\e{n} log \e{n}). + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + If neither of the two items is "less than" the other, the items are + taken to be equal. It is then undefined which one of the two + items will appear before the other after the sort. + + \sa qStableSort(), {random access iterators} +*/ + +/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + For example, here's how to sort the strings in a QStringList + in case-insensitive alphabetical order: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 12 + + To sort values in reverse order, pass + \l{qGreater()}{qGreater()} as the \a lessThan parameter. For + example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 13 + + If neither of the two items is "less than" the other, the items are + taken to be equal. It is then undefined which one of the two + items will appear before the other after the sort. + + An alternative to using qSort() is to put the items to sort in a + QMap, using the sort key as the QMap key. This is often more + convenient than defining a \a lessThan function. For example, the + following code shows how to sort a list of strings case + insensitively using QMap: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 14 + + \sa QMap +*/ + +/*! \fn void qSort(Container &container) + \relates + + \overload + + This is the same as qSort(\a{container}.begin(), \a{container}.end()); +*/ + +/*! + \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end) + \relates + + Sorts the items in range [\a begin, \a end) in ascending order + using a stable sorting algorithm. + + If neither of the two items is "less than" the other, the items are + taken to be equal. The item that appeared before the other in the + original container will still appear first after the sort. This + property is often useful when sorting user-visible data. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 15 + + The sort algorithm is efficient on large data sets. It operates + in \l {linear-logarithmic time}, O(\e{n} log \e{n}). + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + \sa qSort(), {random access iterators} +*/ + +/*! + \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + For example, here's how to sort the strings in a QStringList + in case-insensitive alphabetical order: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 16 + + Note that earlier versions of Qt allowed using a lessThan function that took its + arguments by non-const reference. From 4.3 and on this is no longer possible, + the arguments has to be passed by const reference or value. + + To sort values in reverse order, pass + \l{qGreater()}{qGreater()} as the \a lessThan parameter. For + example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 17 + + If neither of the two items is "less than" the other, the items are + taken to be equal. The item that appeared before the other in the + original container will still appear first after the sort. This + property is often useful when sorting user-visible data. +*/ + +/*! + \fn void qStableSort(Container &container) + \relates + + \overload + + This is the same as qStableSort(\a{container}.begin(), \a{container}.end()); +*/ + +/*! \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) + \relates + + Performs a binary search of the range [\a begin, \a end) and + returns the position of the first ocurrence of \a value. If no + such item is found, returns the position where it should be + inserted. + + The items in the range [\a begin, \e end) must be sorted in + ascending order; see qSort(). + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 18 + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + qLowerBound() can be used in conjunction with qUpperBound() to + iterate over all occurrences of the same value: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 19 + + \sa qUpperBound(), qBinaryFind() +*/ + +/*! + \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + Note that the items in the range must be sorted according to the order + specified by the \a lessThan object. +*/ + +/*! + \fn void qLowerBound(const Container &container, const T &value) + \relates + + \overload + + For read-only iteration over containers, this function is broadly equivalent to + qLowerBound(\a{container}.begin(), \a{container}.end(), value). However, since it + returns a const iterator, you cannot use it to modify the container; for example, + to insert items. +*/ + +/*! \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) + \relates + + Performs a binary search of the range [\a begin, \a end) and + returns the position of the one-past-the-last occurrence of \a + value. If no such item is found, returns the position where the + item should be inserted. + + The items in the range [\a begin, \e end) must be sorted in + ascending order; see qSort(). + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 20 + + This function requires the item type (in the example above, + \c{int}) to implement \c operator<(). + + qUpperBound() can be used in conjunction with qLowerBound() to + iterate over all occurrences of the same value: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 21 + + \sa qLowerBound(), qBinaryFind() +*/ + +/*! + \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + Note that the items in the range must be sorted according to the order + specified by the \a lessThan object. +*/ + +/*! + \fn void qUpperBound(const Container &container, const T &value) + \relates + + \overload + + This is the same as qUpperBound(\a{container}.begin(), \a{container}.end(), value); +*/ + + +/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value) + \relates + + Performs a binary search of the range [\a begin, \a end) and + returns the position of an occurrence of \a value. If there are + no occurrences of \a value, returns \a end. + + The items in the range [\a begin, \a end) must be sorted in + ascending order; see qSort(). + + If there are many occurrences of the same value, any one of them + could be returned. Use qLowerBound() or qUpperBound() if you need + finer control. + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 22 + + This function requires the item type (in the example above, + QString) to implement \c operator<(). + + See the \l{#binaryFind example}{detailed + description} for an example usage. + + \sa qLowerBound(), qUpperBound(), {random access iterators} +*/ + +/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) + \relates + + \overload + + Uses the \a lessThan function instead of \c operator<() to + compare the items. + + Note that the items in the range must be sorted according to the order + specified by the \a lessThan object. +*/ + +/*! + \fn void qBinaryFind(const Container &container, const T &value) + \relates + + \overload + + This is the same as qBinaryFind(\a{container}.begin(), \a{container}.end(), value); +*/ + + +/*! + \fn void qDeleteAll(ForwardIterator begin, ForwardIterator end) + \relates + + Deletes all the items in the range [\a begin, \a end) using the + C++ \c delete operator. The item type must be a pointer type (for + example, \c{QWidget *}). + + Example: + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 23 + + Notice that qDeleteAll() doesn't remove the items from the + container; it merely calls \c delete on them. In the example + above, we call clear() on the container to remove the items. + + This function can also be used to delete items stored in + associative containers, such as QMap and QHash. Only the objects + stored in each container will be deleted by this function; objects + used as keys will not be deleted. + + \sa {forward iterators} +*/ + +/*! + \fn void qDeleteAll(const Container &c) + \relates + + \overload + + This is the same as qDeleteAll(\a{c}.begin(), \a{c}.end()). +*/ + +/*! \fn LessThan qLess() + \relates + + Returns a functional object, or functor, that can be passed to qSort() + or qStableSort(). + + Example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 24 + + \sa {qGreater()}{qGreater()} +*/ + +/*! \fn LessThan qGreater() + \relates + + Returns a functional object, or functor, that can be passed to qSort() + or qStableSort(). + + Example: + + \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 25 + + \sa {qLess()}{qLess()} +*/ diff --git a/doc/src/classes/qcache.qdoc b/doc/src/classes/qcache.qdoc new file mode 100644 index 0000000..6c88ede --- /dev/null +++ b/doc/src/classes/qcache.qdoc @@ -0,0 +1,244 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QCache + \brief The QCache class is a template class that provides a cache. + + \ingroup tools + \ingroup shared + \mainclass + \reentrant + + QCache\ defines a cache that stores objects of type T + associated with keys of type Key. For example, here's the + definition of a cache that stores objects of type Employee + associated with an integer key: + + \snippet doc/src/snippets/code/doc_src_qcache.qdoc 0 + + Here's how to insert an object in the cache: + + \snippet doc/src/snippets/code/doc_src_qcache.qdoc 1 + + The advantage of using QCache over some other key-based data + structure (such as QMap or QHash) is that QCache automatically + takes ownership of the objects that are inserted into the cache and + deletes them to make room for new objects, if necessary. When + inserting an object into the cache, you can specify a \e{cost}, + which should bear some approximate relationship to the amount of + memory taken by the object. When the sum of all objects' costs + (totalCost()) exceeds the cache's limit (maxCost()), QCache starts + deleting objects in the cache to keep under the limit, starting with + less recently accessed objects. + + By default, QCache's maxCost() is 100. You can specify a + different value in the QCache constructor: + + \snippet doc/src/snippets/code/doc_src_qcache.qdoc 2 + + Each time you call insert(), you can specify a cost as third + argument (after the key and a pointer to the object to insert). + After the call, the inserted object is owned by the QCache, which + may delete it at any time to make room for other objects. + + To look up objects in the cache, use object() or + operator[](). This function looks up an object by its key, and + returns either a pointer to the cached object (which is owned by + the cache) or 0. + + If you want to remove an object from the cache for a particular key, + call remove(). This will also delete the object. If you want to + remove an object from the cache without the QCache deleting it, use + take(). + + \sa QPixmapCache, QHash, QMap +*/ + +/*! \fn QCache::QCache(int maxCost = 100) + + Constructs a cache whose contents will never have a total cost + greater than \a maxCost. +*/ + +/*! \fn QCache::~QCache() + + Destroys the cache. Deletes all the objects in the cache. +*/ + +/*! \fn int QCache::maxCost() const + + Returns the maximum allowed total cost of the cache. + + \sa setMaxCost(), totalCost() +*/ + +/*! \fn void QCache::setMaxCost(int cost) + + Sets the maximum allowed total cost of the cache to \a cost. If + the current total cost is greater than \a cost, some objects are + deleted immediately. + + \sa maxCost(), totalCost() +*/ + +/*! \fn int QCache::totalCost() const + + Returns the total cost of the objects in the cache. + + This value is normally below maxCost(), but QCache makes an + exception for Qt's \l{implicitly shared} classes. If a cached + object shares its internal data with another instance, QCache may + keep the object lying around, possibly contributing to making + totalCost() larger than maxCost(). + + \sa setMaxCost() +*/ + +/*! \fn int QCache::size() const + + Returns the number of objects in the cache. + + \sa isEmpty() +*/ + +/*! \fn int QCache::count() const + + Same as size(). +*/ + +/*! \fn bool QCache::isEmpty() const + + Returns true if the cache contains no objects; otherwise + returns false. + + \sa size() +*/ + +/*! \fn QList QCache::keys() const + + Returns a list of the keys in the cache. +*/ + +/*! \fn void QCache::clear(); + + Deletes all the objects in the cache. + + \sa remove(), take() +*/ + + +/*! \fn bool QCache::insert(const Key &key, T *object, int cost = 1) + + Inserts \a object into the cache with key \a key and + associated cost \a cost. Any object with the same key already in + the cache will be removed. + + After this call, \a object is owned by the QCache and may be + deleted at any time. In particular, if \a cost is greater than + maxCost(), the object will be deleted immediately. + + The function returns true if the object was inserted into the + cache; otherwise it returns false. + + \sa take(), remove() +*/ + +/*! \fn T *QCache::object(const Key &key) const + + Returns the object associated with key \a key, or 0 if the key does + not exist in the cache. + + \warning The returned object is owned by QCache and may be + deleted at any time. + + \sa take(), remove() +*/ + +/*! \fn bool QCache::contains(const Key &key) const + + Returns true if the cache contains an object associated with key \a + key; otherwise returns false. + + \sa take(), remove() +*/ + +/*! \fn T *QCache::operator[](const Key &key) const + + Returns the object associated with key \a key, or 0 if the key does + not exist in the cache. + + This is the same as object(). + + \warning The returned object is owned by QCache and may be + deleted at any time. +*/ + +/*! \fn bool QCache::remove(const Key &key) + + Deletes the object associated with key \a key. Returns true if the + object was found in the cache; otherwise returns false. + + \sa take(), clear() +*/ + +/*! \fn T *QCache::take(const Key &key) + + Takes the object associated with key \a key out of the cache + without deleting it. Returns a pointer to the object taken out, or + 0 if the key does not exist in the cache. + + The ownership of the returned object is passed to the caller. + + \sa remove() +*/ + +/*! + \fn QCache::QCache(int maxCost, int dummy) + + Use QCache(int) instead. +*/ + +/*! + \fn T *QCache::find(const Key &key) const + + Use object() instead. +*/ diff --git a/doc/src/classes/qcolormap.qdoc b/doc/src/classes/qcolormap.qdoc new file mode 100644 index 0000000..95f7dc0 --- /dev/null +++ b/doc/src/classes/qcolormap.qdoc @@ -0,0 +1,152 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QColormap + \ingroup multimedia + + \brief The QColormap class maps device independent QColors to device + dependent pixel values. +*/ + +/*! \enum QColormap::Mode + + This enum describes how QColormap maps device independent RGB + values to device dependent pixel values. + + \value Direct Pixel values are derived directly from the RGB + values, also known as "True Color." + + \value Indexed Pixel values represent indexes into a vector of + available colors, i.e. QColormap uses the index of the color that + most closely matches an RGB value. + + \value Gray Similar to \c Indexed, pixel values represent a vector + of available gray tones. QColormap uses the index of the gray + tone that most closely matches the computed gray tone of an RGB + value. +*/ + +/*! + \fn QColormap QColormap::instance(int screen) + + Returns the colormap for the specified \a screen. If \a screen is + -1, this function returns the colormap for the default screen. +*/ + +/*! + \fn QColormap::QColormap(const QColormap &colormap) + + Constructs a copy of another \a colormap. +*/ + +/*! + \fn QColormap::~QColormap() + + Destroys the colormap. +*/ + +/*! + \fn int QColormap::size() const + + Returns the size of the colormap for \c Indexed and \c Gray modes; + Returns -1 for \c Direct mode. + + \sa colormap() +*/ + +/*! + \fn uint QColormap::pixel(const QColor &color) const + + Returns a device dependent pixel value for the \a color. + + \sa colorAt() +*/ + +/*! + \fn int QColormap::depth() const + + Returns the depth of the device. + + \sa size() +*/ + +/*! + \fn QColormap::Mode QColormap::mode() const + + Returns the mode of this colormap. + + \sa QColormap::Mode +*/ + +/*! + \fn const QColor QColormap::colorAt(uint pixel) const + + Returns a QColor for the \a pixel. + + \sa pixel() +*/ + +/*! + \fn const QVector QColormap::colormap() const + + Returns a vector of colors which represents the devices colormap + for \c Indexed and \c Gray modes. This function returns an empty + vector for \c Direct mode. + + \sa size() +*/ + +/*! \fn HPALETTE QColormap::hPal() + + This function is only available on Windows. + + Returns an handle to the HPALETTE used by this colormap. If no + HPALETTE is being used, this function returns zero. +*/ + +/*! \since 4.2 + + \fn QColormap &QColormap::operator=(const QColormap &colormap) + + Assigns the given \a colormap to \e this color map and returns + a reference to \e this color map. +*/ diff --git a/doc/src/classes/qdesktopwidget.qdoc b/doc/src/classes/qdesktopwidget.qdoc new file mode 100644 index 0000000..56a882d --- /dev/null +++ b/doc/src/classes/qdesktopwidget.qdoc @@ -0,0 +1,266 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QDesktopWidget + \brief The QDesktopWidget class provides access to screen information on multi-head systems. + + \ingroup advanced + \ingroup desktop + \ingroup environment + \mainclass + + QApplication::desktop() function should be used to get an instance + of the QDesktopWidget. + + Systems with more than one graphics card and monitor can manage the + physical screen space available either as multiple desktops, or as a + large virtual desktop, which usually has the size of the bounding + rectangle of all the screens (see virtualDesktop). For an + application, one of the available screens is the primary screen, i.e. + the screen where the main widget resides (see primaryScreen). All + windows opened in the context of the application should be + constrained to the boundaries of the primary screen; for example, + it would be inconvenient if a dialog box popped up on a different + screen, or split over two screens. + + The QDesktopWidget provides information about the geometry of the + available screens with screenGeometry(). The number of screens + available is returned by screenCount, and the screenCountChanged + signal is emitted when screens are added or removed during runtime. + The screen number that a particular point or widget is located in + is returned by screenNumber(). + + Widgets provided by Qt use this class, for example, to place + tooltips, menus and dialog boxes according to the parent or + application widget. Applications can use this class to save window + positions, or to place child widgets and dialogs on one particular + screen. + + \img qdesktopwidget.png Managing Multiple Screens + + In the illustration above, Application One's primary screen is + screen 0, and App Two's primary screen is screen 1. + + \target multiple screens note + \note QDesktopWidget inherits the QWidget properties, width() and + height(), which specify the size of the desktop. However, for + desktops with multiple screens, the size of the desktop is the union + of all the screen sizes, so width() and height() should \e not be + used for computing the size of a widget to be placed on one of the + screens. The correct width and height values are obtained using + availableGeometry() or screenGeometry() for a particular screen. + + \sa QApplication, QApplication::desktop(), QX11Info::appRootWindow() +*/ + +/*! + \fn QDesktopWidget::QDesktopWidget() + + \internal + + Creates the desktop widget. + + If the system supports a virtual desktop, this widget will have + the size of the virtual desktop; otherwise this widget will have + the size of the primary screen. + + Instead of using QDesktopWidget directly, use QApplication::desktop(). +*/ + +/*! + \fn QDesktopWidget::~QDesktopWidget() + + \internal + + Destroys the desktop widget and frees any allocated resources. +*/ + +/*! + \fn int QDesktopWidget::numScreens() const + + Returns the number of available screens. + + \obsolete + + This function is deprecated. Use screenCount instead. + + \sa primaryScreen +*/ + +/*! + \fn QWidget *QDesktopWidget::screen(int screen) + + Returns a widget that represents the screen with index \a screen + (a value of -1 means the default screen). + + If the system uses a virtual desktop, the returned widget will + have the geometry of the entire virtual desktop; i.e., bounding + every \a screen. + + \sa primaryScreen, screenCount, virtualDesktop +*/ + +/*! + \fn const QRect QDesktopWidget::availableGeometry(int screen) const + + Returns the available geometry of the screen with index \a screen. What + is available will be subrect of screenGeometry() based on what the + platform decides is available (for example excludes the dock and menu bar + on Mac OS X, or the task bar on Windows). The default screen is used if + \a screen is -1. + + \sa screenNumber(), screenGeometry() +*/ + +/*! + \fn const QRect QDesktopWidget::availableGeometry(const QWidget *widget) const + \overload + + Returns the available geometry of the screen which contains \a widget. + + \sa screenGeometry() +*/ + +/*! + \fn const QRect QDesktopWidget::availableGeometry(const QPoint &p) const + \overload + + Returns the available geometry of the screen which contains \a p. + + \sa screenGeometry() +*/ + + +/*! + \fn const QRect QDesktopWidget::screenGeometry(int screen) const + + Returns the geometry of the screen with index \a screen. The default + screen is used if \a screen is -1. + + \sa screenNumber() +*/ + +/*! + \fn const QRect QDesktopWidget::screenGeometry(const QWidget *widget) const + \overload + + Returns the geometry of the screen which contains \a widget. +*/ + +/*! + \fn const QRect QDesktopWidget::screenGeometry(const QPoint &p) const + \overload + + Returns the geometry of the screen which contains \a p. +*/ + + +/*! + \fn int QDesktopWidget::screenNumber(const QWidget *widget) const + + Returns the index of the screen that contains the largest + part of \a widget, or -1 if the widget not on a screen. + + \sa primaryScreen +*/ + +/*! + \fn int QDesktopWidget::screenNumber(const QPoint &point) const + + \overload + Returns the index of the screen that contains the \a point, or the + screen which is the shortest distance from the \a point. + + \sa primaryScreen +*/ + +/*! + \fn void QDesktopWidget::resizeEvent(QResizeEvent *event) + \reimp +*/ + +/*! + \fn void QDesktopWidget::resized(int screen) + + This signal is emitted when the size of \a screen changes. +*/ + +/*! + \fn void QDesktopWidget::workAreaResized(int screen) + + This signal is emitted when the work area available on \a screen changes. +*/ + +/*! + \property QDesktopWidget::screenCount + \brief the number of screens currently available on the system. + + \since 4.6 + + \sa screenCountChanged() +*/ + +/*! + \property QDesktopWidget::primaryScreen + \brief the index of the screen that is configured to be the primary screen + on the system. +*/ + +/*! + \property QDesktopWidget::virtualDesktop + + \brief if the system manages the available screens in a virtual desktop. + + For virtual desktops, screen() will always return the same widget. + The size of the virtual desktop is the size of this desktop + widget. +*/ + +/*! + \fn void QDesktopWidget::screenCountChanged(int newCount) + + \since 4.6 + + This signal is emitted when the number of screens changes to \a newCount. + + \sa screenCount +*/ diff --git a/doc/src/classes/qiterator.qdoc b/doc/src/classes/qiterator.qdoc new file mode 100644 index 0000000..416b4bc --- /dev/null +++ b/doc/src/classes/qiterator.qdoc @@ -0,0 +1,1431 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QListIterator + \inmodule QtCore + + \brief The QListIterator class provides a Java-style const iterator for QList and QQueue. + + QList has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + An alternative to using iterators is to use index positions. Most + QList member functions take an index as their first parameter, + making it possible to access, modify, and remove items without + using iterators. + + QListIterator\ allows you to iterate over a QList\ (or a + QQueue\). If you want to modify the list as you iterate over + it, use QMutableListIterator\ instead. + + The QListIterator constructor takes a QList as argument. After + construction, the iterator is located at the very beginning of + the list (before the first item). Here's how to iterate over all + the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 0 + + The next() function returns the next item in the list and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, and returns the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 1 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + Multiple iterators can be used on the same list. If the list is + modified while a QListIterator is active, the QListIterator will + continue iterating over the original list, ignoring the modified + copy. + + \sa QMutableListIterator, QList::const_iterator +*/ + +/*! + \class QLinkedListIterator + \inmodule QtCore + + \brief The QLinkedListIterator class provides a Java-style const iterator for QLinkedList. + + QLinkedList has both \l{Java-style iterators} and + \l{STL-style iterators}. The Java-style iterators are more + high-level and easier to use than the STL-style iterators; on the + other hand, they are slightly less efficient. + + QLinkedListIterator\ allows you to iterate over a + QLinkedList\. If you want to modify the list as you iterate + over it, use QMutableLinkedListIterator\ instead. + + The QLinkedListIterator constructor takes a QLinkedList as + argument. After construction, the iterator is located at the very + beginning of the list (before the first item). Here's how to + iterate over all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 2 + + The next() function returns the next item in the list and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, and returns the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 3 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + Multiple iterators can be used on the same list. If the list is + modified while a QLinkedListIterator is active, the + QLinkedListIterator will continue iterating over the original + list, ignoring the modified copy. + + \sa QMutableLinkedListIterator, QLinkedList::const_iterator +*/ + +/*! + \class QVectorIterator + \inmodule QtCore + \brief The QVectorIterator class provides a Java-style const iterator for QVector and QStack. + + QVector has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + An alternative to using iterators is to use index positions. Most + QVector member functions take an index as their first parameter, + making it possible to access, insert, and remove items without + using iterators. + + QVectorIterator\ allows you to iterate over a QVector\ + (or a QStack\). If you want to modify the vector as you + iterate over it, use QMutableVectorIterator\ instead. + + The QVectorIterator constructor takes a QVector as argument. + After construction, the iterator is located at the very beginning + of the vector (before the first item). Here's how to iterate over + all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 4 + + The next() function returns the next item in the vector and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 5 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + Multiple iterators can be used on the same vector. If the vector + is modified while a QVectorIterator is active, the QVectorIterator + will continue iterating over the original vector, ignoring the + modified copy. + + \sa QMutableVectorIterator, QVector::const_iterator +*/ + +/*! + \class QSetIterator + \inmodule QtCore + \brief The QSetIterator class provides a Java-style const iterator for QSet. + + QSet supports both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QSetIterator\ allows you to iterate over a QSet\. If you + want to modify the set as you iterate over it, use + QMutableSetIterator\ instead. + + The constructor takes a QSet as argument. After construction, the + iterator is located at the very beginning of the set (before + the first item). Here's how to iterate over all the elements + sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 6 + + The next() function returns the next item in the set and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 7 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + Multiple iterators can be used on the same set. If the set + is modified while a QSetIterator is active, the QSetIterator + will continue iterating over the original set, ignoring the + modified copy. + + \sa QMutableSetIterator, QSet::const_iterator +*/ + +/*! + \class QMutableListIterator + \inmodule QtCore + + \brief The QMutableListIterator class provides a Java-style non-const iterator for QList and QQueue. + + QList has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + An alternative to using iterators is to use index positions. Most + QList member functions take an index as their first parameter, + making it possible to access, insert, and remove items without + using iterators. + + QMutableListIterator\ allows you to iterate over a QList\ + (or a QQueue\) and modify the list. If you don't want to + modify the list (or have a const QList), use the slightly faster + QListIterator\ instead. + + The QMutableListIterator constructor takes a QList as argument. + After construction, the iterator is located at the very beginning + of the list (before the first item). Here's how to iterate over + all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 8 + + The next() function returns the next item in the list and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 9 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + If you want to remove items as you iterate over the list, use + remove(). If you want to modify the value of an item, use + setValue(). If you want to insert a new item in the list, use + insert(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 10 + + The example traverses a list, replacing negative numbers with + their absolute values, and eliminating zeroes. + + Only one mutable iterator can be active on a given list at any + time. Furthermore, no changes should be done directly to the list + while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QListIterator, QList::iterator +*/ + +/*! + \class QMutableLinkedListIterator + \inmodule QtCore + + \brief The QMutableLinkedListIterator class provides a Java-style non-const iterator for QLinkedList. + + QLinkedList has both \l{Java-style iterators} and + \l{STL-style iterators}. The Java-style iterators are more + high-level and easier to use than the STL-style iterators; on the + other hand, they are slightly less efficient. + + QMutableLinkedListIterator\ allows you to iterate over a + QLinkedList\ and modify the list. If you don't want to modify + the list (or have a const QLinkedList), use the slightly faster + QLinkedListIterator\ instead. + + The QMutableLinkedListIterator constructor takes a QLinkedList as + argument. After construction, the iterator is located at the very + beginning of the list (before the first item). Here's how to + iterate over all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 11 + + The next() function returns the next item in the list and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 12 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + If you want to remove items as you iterate over the list, use + remove(). If you want to modify the value of an item, use + setValue(). If you want to insert a new item in the list, use + insert(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 13 + + The example traverses a list, replacing negative numbers with + their absolute values, and eliminating zeroes. + + Only one mutable iterator can be active on a given list at any + time. Furthermore, no changes should be done directly to the list + while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QLinkedListIterator, QLinkedList::iterator +*/ + +/*! + \class QMutableVectorIterator + \inmodule QtCore + + \brief The QMutableVectorIterator class provides a Java-style non-const iterator for QVector and QStack. + + QVector has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + An alternative to using iterators is to use index positions. Most + QVector member functions take an index as their first parameter, + making it possible to access, insert, and remove items without + using iterators. + + QMutableVectorIterator\ allows you to iterate over a + QVector\ and modify the vector. If you don't want to modify + the vector (or have a const QVector), use the slightly faster + QVectorIterator\ instead. + + The QMutableVectorIterator constructor takes a QVector as + argument. After construction, the iterator is located at the very + beginning of the list (before the first item). Here's how to + iterate over all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 14 + + The next() function returns the next item in the vector and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 15 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. + + If you want to remove items as you iterate over the vector, use + remove(). If you want to modify the value of an item, use + setValue(). If you want to insert a new item in the vector, use + insert(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 16 + + The example traverses a vector, replacing negative numbers with + their absolute values, and eliminating zeroes. + + Only one mutable iterator can be active on a given vector at any + time. Furthermore, no changes should be done directly to the + vector while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QVectorIterator, QVector::iterator +*/ + +/*! + \class QMutableSetIterator + \inmodule QtCore + \since 4.2 + + \brief The QMutableSetIterator class provides a Java-style non-const iterator for QSet. + + QSet has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QMutableSetIterator\ allows you to iterate over a QSet\ + and remove items from the set as you iterate. If you don't want + to modify the set (or have a const QSet), use the slightly faster + QSetIterator\ instead. + + The QMutableSetIterator constructor takes a QSet as argument. + After construction, the iterator is located at the very beginning + of the set (before the first item). Here's how to iterate over + all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 17 + + The next() function returns the next item in the set and + advances the iterator. Unlike STL-style iterators, Java-style + iterators point \e between items rather than directly \e at + items. The first call to next() advances the iterator to the + position between the first and second item, and returns the first + item; the second call to next() advances the iterator to the + position between the second and third item, returning the second + item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 18 + + If you want to remove items as you iterate over the set, use + remove(). + + Only one mutable iterator can be active on a given set at any + time. Furthermore, no changes should be done directly to the set + while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QSetIterator, QSet::iterator +*/ + +/*! + \fn QListIterator::QListIterator(const QList &list) + \fn QLinkedListIterator::QLinkedListIterator(const QLinkedList &list) + \fn QMutableListIterator::QMutableListIterator(QList &list) + \fn QMutableLinkedListIterator::QMutableLinkedListIterator(QLinkedList &list) + + Constructs an iterator for traversing \a list. The iterator is + set to be at the front of the list (before the first item). + + \sa operator=() +*/ + +/*! + \fn QVectorIterator::QVectorIterator(const QVector &vector) + \fn QMutableVectorIterator::QMutableVectorIterator(QVector &vector) + + Constructs an iterator for traversing \a vector. The iterator is + set to be at the front of the vector (before the first item). + + \sa operator=() +*/ + +/*! + \fn QSetIterator::QSetIterator(const QSet &set) + \fn QMutableSetIterator::QMutableSetIterator(QSet &set) + + Constructs an iterator for traversing \a set. The iterator is + set to be at the front of the set (before the first item). + + \sa operator=() +*/ + +/*! + \fn QMutableListIterator::~QMutableListIterator() + \fn QMutableLinkedListIterator::~QMutableLinkedListIterator() + \fn QMutableVectorIterator::~QMutableVectorIterator() + \fn QMutableSetIterator::~QMutableSetIterator() + + Destroys the iterator. + + \sa operator=() +*/ + +/*! \fn QMutableListIterator &QMutableListIterator::operator=(QList &list) + \fn QMutableLinkedListIterator &QMutableLinkedListIterator::operator=(QLinkedList &list) + \fn QListIterator &QListIterator::operator=(const QList &list) + \fn QLinkedListIterator &QLinkedListIterator::operator=(const QLinkedList &list) + + Makes the iterator operate on \a list. The iterator is set to be + at the front of the list (before the first item). + + \sa toFront(), toBack() +*/ + +/*! \fn QVectorIterator &QVectorIterator::operator=(const QVector &vector) + \fn QMutableVectorIterator &QMutableVectorIterator::operator=(QVector &vector) + + Makes the iterator operate on \a vector. The iterator is set to be + at the front of the vector (before the first item). + + \sa toFront(), toBack() +*/ + +/*! \fn QSetIterator &QSetIterator::operator=(const QSet &set) + \fn QMutableSetIterator &QMutableSetIterator::operator=(QSet &set) + + Makes the iterator operate on \a set. The iterator is set to be + at the front of the set (before the first item). + + \sa toFront(), toBack() +*/ + +/*! \fn void QListIterator::toFront() + \fn void QLinkedListIterator::toFront() + \fn void QVectorIterator::toFront() + \fn void QSetIterator::toFront() + \fn void QMutableListIterator::toFront() + \fn void QMutableLinkedListIterator::toFront() + \fn void QMutableVectorIterator::toFront() + \fn void QMutableSetIterator::toFront() + + Moves the iterator to the front of the container (before the + first item). + + \sa toBack(), next() +*/ + +/*! \fn void QListIterator::toBack() + \fn void QLinkedListIterator::toBack() + \fn void QVectorIterator::toBack() + \fn void QSetIterator::toBack() + \fn void QMutableListIterator::toBack() + \fn void QMutableLinkedListIterator::toBack() + \fn void QMutableVectorIterator::toBack() + \fn void QMutableSetIterator::toBack() + + Moves the iterator to the back of the container (after the last + item). + + \sa toFront(), previous() +*/ + +/*! \fn bool QListIterator::hasNext() const + \fn bool QLinkedListIterator::hasNext() const + \fn bool QVectorIterator::hasNext() const + \fn bool QSetIterator::hasNext() const + \fn bool QMutableListIterator::hasNext() const + \fn bool QMutableLinkedListIterator::hasNext() const + \fn bool QMutableVectorIterator::hasNext() const + \fn bool QMutableSetIterator::hasNext() const + + Returns true if there is at least one item ahead of the iterator, + i.e. the iterator is \e not at the back of the container; + otherwise returns false. + + \sa hasPrevious(), next() +*/ + +/*! \fn const T &QListIterator::next() + \fn const T &QLinkedListIterator::next() + \fn const T &QVectorIterator::next() + \fn const T &QSetIterator::next() + \fn const T &QMutableSetIterator::next() + + Returns the next item and advances the iterator by one position. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), peekNext(), previous() +*/ + +/*! \fn T &QMutableListIterator::next() + \fn T &QMutableLinkedListIterator::next() + \fn T &QMutableVectorIterator::next() + + Returns a reference to the next item, and advances the iterator + by one position. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), peekNext(), previous() +*/ + +/*! \fn const T &QListIterator::peekNext() const + \fn const T &QLinkedListIterator::peekNext() const + \fn const T &QVectorIterator::peekNext() const + \fn const T &QSetIterator::peekNext() const + \fn const T &QMutableSetIterator::peekNext() const + + Returns the next item without moving the iterator. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), next(), peekPrevious() +*/ + +/*! \fn T &QMutableListIterator::peekNext() const + \fn T &QMutableLinkedListIterator::peekNext() const + \fn T &QMutableVectorIterator::peekNext() const + + Returns a reference to the next item, without moving the iterator. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), next(), peekPrevious() +*/ + +/*! \fn bool QListIterator::hasPrevious() const + \fn bool QLinkedListIterator::hasPrevious() const + \fn bool QVectorIterator::hasPrevious() const + \fn bool QSetIterator::hasPrevious() const + \fn bool QMutableListIterator::hasPrevious() const + \fn bool QMutableLinkedListIterator::hasPrevious() const + \fn bool QMutableVectorIterator::hasPrevious() const + \fn bool QMutableSetIterator::hasPrevious() const + + Returns true if there is at least one item behind the iterator, + i.e. the iterator is \e not at the front of the container; + otherwise returns false. + + \sa hasNext(), previous() +*/ + +/*! \fn const T &QListIterator::previous() + \fn const T &QLinkedListIterator::previous() + \fn const T &QVectorIterator::previous() + \fn const T &QSetIterator::previous() + \fn const T &QMutableSetIterator::previous() + + Returns the previous item and moves the iterator back by one + position. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), peekPrevious(), next() +*/ + +/*! \fn T &QMutableListIterator::previous() + \fn T &QMutableLinkedListIterator::previous() + \fn T &QMutableVectorIterator::previous() + + Returns a reference to the previous item and moves the iterator + back by one position. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), peekPrevious(), next() +*/ + +/*! \fn const T &QListIterator::peekPrevious() const + \fn const T &QLinkedListIterator::peekPrevious() const + \fn const T &QVectorIterator::peekPrevious() const + \fn const T &QSetIterator::peekPrevious() const + \fn const T &QMutableSetIterator::peekPrevious() const + + Returns the previous item without moving the iterator. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), previous(), peekNext() +*/ + +/*! \fn T &QMutableListIterator::peekPrevious() const + \fn T &QMutableLinkedListIterator::peekPrevious() const + \fn T &QMutableVectorIterator::peekPrevious() const + + Returns a reference to the previous item, without moving the iterator. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), previous(), peekNext() +*/ + +/*! \fn bool QListIterator::findNext(const T &value) + \fn bool QLinkedListIterator::findNext(const T &value) + \fn bool QVectorIterator::findNext(const T &value) + \fn bool QSetIterator::findNext(const T &value) + \fn bool QMutableListIterator::findNext(const T &value) + \fn bool QMutableLinkedListIterator::findNext(const T &value) + \fn bool QMutableVectorIterator::findNext(const T &value) + \fn bool QMutableSetIterator::findNext(const T &value) + + Searches for \a value starting from the current iterator position + forward. Returns true if \a value is found; otherwise returns false. + + After the call, if \a value was found, the iterator is positioned + just after the matching item; otherwise, the iterator is + positioned at the back of the container. + + \sa findPrevious() +*/ + +/*! \fn bool QListIterator::findPrevious(const T &value) + \fn bool QLinkedListIterator::findPrevious(const T &value) + \fn bool QVectorIterator::findPrevious(const T &value) + \fn bool QSetIterator::findPrevious(const T &value) + \fn bool QMutableListIterator::findPrevious(const T &value) + \fn bool QMutableLinkedListIterator::findPrevious(const T &value) + \fn bool QMutableVectorIterator::findPrevious(const T &value) + \fn bool QMutableSetIterator::findPrevious(const T &value) + + Searches for \a value starting from the current iterator position + backward. Returns true if \a value is found; otherwise returns + false. + + After the call, if \a value was found, the iterator is positioned + just before the matching item; otherwise, the iterator is + positioned at the front of the container. + + \sa findNext() +*/ + +/*! \fn void QMutableListIterator::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), previous(), findNext(), findPrevious()). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 19 + + \sa insert(), setValue() +*/ + +/*! \fn void QMutableLinkedListIterator::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), previous(), findNext(), findPrevious()). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 20 + + \sa insert(), setValue() +*/ + +/*! \fn void QMutableVectorIterator::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), previous(), findNext(), findPrevious()). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 21 + + \sa insert(), setValue() +*/ + +/*! \fn void QMutableSetIterator::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), previous(), findNext(), findPrevious()). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 22 + + \sa value() +*/ + +/*! \fn void QMutableListIterator::setValue(const T &value) const + + Replaces the value of the last item that was jumped over using + one of the traversal functions with \a value. + + The traversal functions are next(), previous(), findNext(), and + findPrevious(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 23 + + \sa value(), remove(), insert() +*/ + +/*! \fn void QMutableLinkedListIterator::setValue(const T &value) const + + Replaces the value of the last item that was jumped over using + one of the traversal functions with \a value. + + The traversal functions are next(), previous(), findNext(), and + findPrevious(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 24 + + \sa value(), remove(), insert() +*/ + +/*! \fn void QMutableVectorIterator::setValue(const T &value) const + + Replaces the value of the last item that was jumped over using + one of the traversal functions with \a value. + + The traversal functions are next(), previous(), findNext(), and + findPrevious(). + + Example: + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 25 + + \sa value(), remove(), insert() +*/ + +/*! \fn const T &QMutableListIterator::value() const + \fn const T &QMutableLinkedListIterator::value() const + \fn const T &QMutableVectorIterator::value() const + \fn const T &QMutableSetIterator::value() const + + Returns the value of the last item that was jumped over using one + of the traversal functions (next(), previous(), findNext(), + findPrevious()). + + After a call to next() or findNext(), value() is equivalent to + peekPrevious(). After a call to previous() or findPrevious(), value() is + equivalent to peekNext(). +*/ + +/*! + \fn T &QMutableListIterator::value() + \fn T &QMutableLinkedListIterator::value() + \fn T &QMutableVectorIterator::value() + \overload + + Returns a non-const reference to the value of the last item that + was jumped over using one of the traversal functions. +*/ + +/*! \fn void QMutableListIterator::insert(const T &value) + \fn void QMutableLinkedListIterator::insert(const T &value) + \fn void QMutableVectorIterator::insert(const T &value) + + Inserts \a value at the current iterator position. After the + call, the iterator is located just after the inserted item. + + \sa remove(), setValue() +*/ + +/*! + \class QMapIterator + \inmodule QtCore + + \brief The QMapIterator class provides a Java-style const iterator for QMap and QMultiMap. + + QMap has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QMapIterator\ allows you to iterate over a QMap (or a + QMultiMap). If you want to modify the map as you iterate over + it, use QMutableMapIterator instead. + + The QMapIterator constructor takes a QMap as argument. After + construction, the iterator is located at the very beginning of + the map (before the first item). Here's how to iterate over all + the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 26 + + The next() function returns the next item in the map and + advances the iterator. The key() and value() functions return the + key and value of the last item that was jumped over. + + Unlike STL-style iterators, Java-style iterators point \e between + items rather than directly \e at items. The first call to next() + advances the iterator to the position between the first and + second item, and returns the first item; the second call to + next() advances the iterator to the position between the second + and third item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 27 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. For example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 28 + + Multiple iterators can be used on the same map. If the map is + modified while a QMapIterator is active, the QMapIterator will + continue iterating over the original map, ignoring the modified + copy. + + \sa QMutableMapIterator, QMap::const_iterator +*/ + +/*! + \class QHashIterator + \inmodule QtCore + + \brief The QHashIterator class provides a Java-style const iterator for QHash and QMultiHash. + + QHash has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QHashIterator\ allows you to iterate over a QHash (or a + QMultiHash). If you want to modify the hash as you iterate over + it, use QMutableHashIterator instead. + + The QHashIterator constructor takes a QHash as argument. After + construction, the iterator is located at the very beginning of + the hash (before the first item). Here's how to iterate over all + the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 29 + + The next() function returns the next item in the hash and + advances the iterator. The key() and value() functions return the + key and value of the last item that was jumped over. + + Unlike STL-style iterators, Java-style iterators point \e between + items rather than directly \e at items. The first call to next() + advances the iterator to the position between the first and + second item, and returns the first item; the second call to + next() advances the iterator to the position between the second + and third item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 30 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. For example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 31 + + Multiple iterators can be used on the same hash. If the hash is + modified while a QHashIterator is active, the QHashIterator will + continue iterating over the original hash, ignoring the modified + copy. + + \sa QMutableHashIterator, QHash::const_iterator +*/ + +/*! + \class QMutableMapIterator + \inmodule QtCore + + \brief The QMutableMapIterator class provides a Java-style non-const iterator for QMap and QMultiMap. + + QMap has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QMutableMapIterator\ allows you to iterate over a QMap + (or a QMultiMap) and modify the map. If you don't want to modify + the map (or have a const QMap), use the slightly faster + QMapIterator instead. + + The QMutableMapIterator constructor takes a QMap as argument. + After construction, the iterator is located at the very beginning + of the map (before the first item). Here's how to iterate over + all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 32 + + The next() function returns the next item in the map and + advances the iterator. The key() and value() functions return the + key and value of the last item that was jumped over. + + Unlike STL-style iterators, Java-style iterators point \e between + items rather than directly \e at items. The first call to next() + advances the iterator to the position between the first and + second item, and returns the first item; the second call to + next() advances the iterator to the position between the second + and third item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 33 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. For example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 34 + + If you want to remove items as you iterate over the map, use + remove(). If you want to modify the value of an item, use + setValue(). + + Example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 35 + + The example removes all (key, value) pairs where the key and the + value are the same. + + Only one mutable iterator can be active on a given map at any + time. Furthermore, no changes should be done directly to the map + while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QMapIterator, QMap::iterator +*/ + +/*! + \class QMutableHashIterator + \inmodule QtCore + + \brief The QMutableHashIterator class provides a Java-style non-const iterator for QHash and QMultiHash. + + QHash has both \l{Java-style iterators} and \l{STL-style + iterators}. The Java-style iterators are more high-level and + easier to use than the STL-style iterators; on the other hand, + they are slightly less efficient. + + QMutableHashIterator\ allows you to iterate over a QHash + (or a QMultiHash) and modify the hash. If you don't want to modify + the hash (or have a const QHash), use the slightly faster + QHashIterator instead. + + The QMutableHashIterator constructor takes a QHash as argument. + After construction, the iterator is located at the very beginning + of the hash (before the first item). Here's how to iterate over + all the elements sequentially: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 36 + + The next() function returns the next item in the hash and + advances the iterator. The key() and value() functions return the + key and value of the last item that was jumped over. + + Unlike STL-style iterators, Java-style iterators point \e between + items rather than directly \e at items. The first call to next() + advances the iterator to the position between the first and + second item, and returns the first item; the second call to + next() advances the iterator to the position between the second + and third item; and so on. + + \img javaiterators1.png + + Here's how to iterate over the elements in reverse order: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 37 + + If you want to find all occurrences of a particular value, use + findNext() or findPrevious() in a loop. For example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 38 + + If you want to remove items as you iterate over the hash, use + remove(). If you want to modify the value of an item, use + setValue(). + + Example: + + \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 39 + + The example removes all (key, value) pairs where the key and the + value are the same. + + Only one mutable iterator can be active on a given hash at any + time. Furthermore, no changes should be done directly to the hash + while the iterator is active (as opposed to through the + iterator), since this could invalidate the iterator and lead to + undefined behavior. + + \sa QHashIterator, QHash::iterator +*/ + +/*! \fn QMapIterator::QMapIterator(const QMap &map) + \fn QMutableMapIterator::QMutableMapIterator(QMap &map) + + Constructs an iterator for traversing \a map. The iterator is set + to be at the front of the map (before the first item). + + \sa operator=() +*/ + +/*! \fn QHashIterator::QHashIterator(const QHash &hash) + \fn QMutableHashIterator::QMutableHashIterator(QHash &hash) + + Constructs an iterator for traversing \a hash. The iterator is + set to be at the front of the hash (before the first item). + + \sa operator=() +*/ + +/*! + \fn QMutableMapIterator::~QMutableMapIterator() + \fn QMutableHashIterator::~QMutableHashIterator() + + Destroys the iterator. + + \sa operator=() +*/ + +/*! \fn QMapIterator &QMapIterator::operator=(const QMap &map) + \fn QMutableMapIterator &QMutableMapIterator::operator=(QMap &map) + + Makes the iterator operate on \a map. The iterator is set to be + at the front of the map (before the first item). + + \sa toFront(), toBack() +*/ + +/*! \fn QHashIterator &QHashIterator::operator=(const QHash &hash) + \fn QMutableHashIterator &QMutableHashIterator::operator=(QHash &hash) + + Makes the iterator operate on \a hash. The iterator is set to be + at the front of the hash (before the first item). + + \sa toFront(), toBack() +*/ + +/*! \fn void QMapIterator::toFront() + \fn void QHashIterator::toFront() + \fn void QMutableMapIterator::toFront() + \fn void QMutableHashIterator::toFront() + + Moves the iterator to the front of the container (before the + first item). + + \sa toBack(), next() +*/ + +/*! \fn void QMapIterator::toBack() + \fn void QHashIterator::toBack() + \fn void QMutableMapIterator::toBack() + \fn void QMutableHashIterator::toBack() + + Moves the iterator to the back of the container (after the last + item). + + \sa toFront(), previous() +*/ + +/*! \fn bool QMapIterator::hasNext() const + \fn bool QHashIterator::hasNext() const + \fn bool QMutableMapIterator::hasNext() const + \fn bool QMutableHashIterator::hasNext() const + + Returns true if there is at least one item ahead of the iterator, + i.e. the iterator is \e not at the back of the container; + otherwise returns false. + + \sa hasPrevious(), next() +*/ + +/*! \fn QMapIterator::Item QMapIterator::next() + \fn QHashIterator::Item QHashIterator::next() + + Returns the next item and advances the iterator by one position. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), peekNext(), previous() +*/ + +/*! \fn QMutableMapIterator::Item QMutableMapIterator::next() + \fn QMutableHashIterator::Item QMutableHashIterator::next() + + Returns the next item and advances the iterator by one position. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), peekNext(), previous() +*/ + +/*! \fn QMapIterator::Item QMapIterator::peekNext() const + \fn QHashIterator::Item QHashIterator::peekNext() const + + Returns the next item without moving the iterator. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), next(), peekPrevious() +*/ + +/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekNext() const + \fn QMutableHashIterator::Item QMutableHashIterator::peekNext() const + + Returns a reference to the next item without moving the iterator. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the back of the + container leads to undefined results. + + \sa hasNext(), next(), peekPrevious() +*/ + +/*! \fn bool QMapIterator::hasPrevious() const + \fn bool QHashIterator::hasPrevious() const + \fn bool QMutableMapIterator::hasPrevious() const + \fn bool QMutableHashIterator::hasPrevious() const + + Returns true if there is at least one item behind the iterator, + i.e. the iterator is \e not at the front of the container; + otherwise returns false. + + \sa hasNext(), previous() +*/ + +/*! \fn QMapIterator::Item QMapIterator::previous() + \fn QHashIterator::Item QHashIterator::previous() + + Returns the previous item and moves the iterator back by one + position. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), peekPrevious(), next() +*/ + +/*! \fn QMutableMapIterator::Item QMutableMapIterator::previous() + \fn QMutableHashIterator::Item QMutableHashIterator::previous() + + Returns the previous item and moves the iterator back by one + position. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), peekPrevious(), next() +*/ + +/*! \fn QMapIterator::Item QMapIterator::peekPrevious() const + \fn QHashIterator::Item QHashIterator::peekPrevious() const + + Returns the previous item without moving the iterator. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), previous(), peekNext() +*/ + +/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekPrevious() const + \fn QMutableHashIterator::Item QMutableHashIterator::peekPrevious() const + + Returns the previous item without moving the iterator. + + Call key() on the return value to obtain the item's key, and + value() to obtain the value. + + Calling this function on an iterator located at the front of the + container leads to undefined results. + + \sa hasPrevious(), previous(), peekNext() +*/ + +/*! \fn const T &QMapIterator::value() const + \fn const T &QHashIterator::value() const + + Returns the value of the last item that was jumped over using one + of the traversal functions (next(), previous(), findNext(), + findPrevious()). + + After a call to next() or findNext(), value() is + equivalent to peekPrevious().value(). After a call to previous() + or findPrevious(), value() is equivalent to peekNext().value(). + + \sa key() +*/ + +/*! + \fn const T &QMutableMapIterator::value() const + \fn const T &QMutableHashIterator::value() const + + Returns the value of the last item that was jumped over using one + of the traversal functions (next(), previous(), findNext(), + findPrevious()). + + After a call to next() or findNext(), value() is + equivalent to peekPrevious().value(). After a call to previous() + or findPrevious(), value() is equivalent to peekNext().value(). + + \sa key(), setValue() +*/ + +/*! + \fn T &QMutableMapIterator::value() + \fn T &QMutableHashIterator::value() + \overload + + Returns a non-const reference to the value of + the last item that was jumped over using one + of the traversal functions. +*/ + +/*! \fn const Key &QMapIterator::key() const + \fn const Key &QHashIterator::key() const + \fn const Key &QMutableMapIterator::key() const + \fn const Key &QMutableHashIterator::key() const + + Returns the key of the last item that was jumped over using one + of the traversal functions (next(), previous(), findNext(), + findPrevious()). + + After a call to next() or findNext(), key() is + equivalent to peekPrevious().key(). After a call to previous() or + findPrevious(), key() is equivalent to peekNext().key(). + + \sa value() +*/ + +/*! \fn bool QMapIterator::findNext(const T &value) + \fn bool QHashIterator::findNext(const T &value) + \fn bool QMutableMapIterator::findNext(const T &value) + \fn bool QMutableHashIterator::findNext(const T &value) + + Searches for \a value starting from the current iterator position + forward. Returns true if a (key, value) pair with value \a value + is found; otherwise returns false. + + After the call, if \a value was found, the iterator is positioned + just after the matching item; otherwise, the iterator is + positioned at the back of the container. + + \sa findPrevious() +*/ + +/*! \fn bool QMapIterator::findPrevious(const T &value) + \fn bool QHashIterator::findPrevious(const T &value) + \fn bool QMutableMapIterator::findPrevious(const T &value) + \fn bool QMutableHashIterator::findPrevious(const T &value) + + Searches for \a value starting from the current iterator position + backward. Returns true if a (key, value) pair with value \a value + is found; otherwise returns false. + + After the call, if \a value was found, the iterator is positioned + just before the matching item; otherwise, the iterator is + positioned at the front of the container. + + \sa findNext() +*/ + +/*! \fn void QMutableMapIterator::remove() + \fn void QMutableHashIterator::remove() + + Removes the last item that was jumped over using one of the + traversal functions (next(), previous(), findNext(), findPrevious()). + + \sa setValue() +*/ + +/*! \fn void QMutableMapIterator::setValue(const T &value) + \fn void QMutableHashIterator::setValue(const T &value) + + Replaces the value of the last item that was jumped over using + one of the traversal functions with \a value. + + The traversal functions are next(), previous(), findNext(), and + findPrevious(). + + \sa key(), value(), remove() +*/ diff --git a/doc/src/classes/qmacstyle.qdoc b/doc/src/classes/qmacstyle.qdoc new file mode 100644 index 0000000..ae2d95b --- /dev/null +++ b/doc/src/classes/qmacstyle.qdoc @@ -0,0 +1,261 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +/*! + \class QMacStyle + \brief The QMacStyle class provides a Mac OS X style using the Apple Appearance Manager. + + \ingroup appearance + + This class is implemented as a wrapper to the HITheme + APIs, allowing applications to be styled according to the current + theme in use on Mac OS X. This is done by having primitives + in QStyle implemented in terms of what Mac OS X would normally theme. + + \warning This style is only available on Mac OS X because it relies on the + HITheme APIs. + + There are additional issues that should be taken + into consideration to make an application compatible with the + \link http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html + Apple Human Interface Guidelines \endlink. Some of these issues are outlined + below. + + \list + + \i Layout - The restrictions on window layout are such that some + aspects of layout that are style-dependent cannot be achieved + using QLayout. Changes are being considered (and feedback would be + appreciated) to make layouts QStyle-able. Some of the restrictions + involve horizontal and vertical widget alignment and widget size + (covered below). + + \i Widget size - Mac OS X allows widgets to have specific fixed sizes. Qt + does not fully implement this behavior so as to maintain cross-platform + compatibility. As a result some widgets sizes may be inappropriate (and + subsequently not rendered correctly by the HITheme APIs).The + QWidget::sizeHint() will return the appropriate size for many + managed widgets (widgets enumerated in \l QStyle::ContentsType). + + \i Effects - QMacStyle uses HITheme for performing most of the drawing, but + also uses emulation in a few cases where HITheme does not provide the + required functionality (for example, tab bars on Panther, the toolbar + separator, etc). We tried to make the emulation as close to the original as + possible. Please report any issues you see in effects or non-standard + widgets. + + \endlist + + There are other issues that need to be considered in the feel of + your application (including the general color scheme to match the + Aqua colors). The Guidelines mentioned above will remain current + with new advances and design suggestions for Mac OS X. + + Note that the functions provided by QMacStyle are + reimplementations of QStyle functions; see QStyle for their + documentation. + + \img qmacstyle.png + \sa QWindowsXPStyle, QWindowsStyle, QPlastiqueStyle, QCDEStyle, QMotifStyle +*/ + + +/*! + \enum QMacStyle::WidgetSizePolicy + + \value SizeSmall + \value SizeLarge + \value SizeMini + \value SizeDefault + \omitvalue SizeNone +*/ + +/*! \fn QMacStyle::QMacStyle() + Constructs a QMacStyle object. +*/ + +/*! \fn QMacStyle::~QMacStyle() + Destructs a QMacStyle object. +*/ + +/*! \fn void QMacStyle::polish(QPalette &pal) + \reimp +*/ + +/*! \fn void QMacStyle::polish(QApplication *) + \reimp +*/ + +/*! \fn void QMacStyle::unpolish(QApplication *) + \reimp +*/ + +/*! \fn void QMacStyle::polish(QWidget* w) + \reimp +*/ + +/*! \fn void QMacStyle::unpolish(QWidget* w) + \reimp +*/ + +/*! \fn int QMacStyle::pixelMetric(PixelMetric metric, const QStyleOption *opt, const QWidget *widget) const + \reimp +*/ + +/*! \fn QPalette QMacStyle::standardPalette() const + \reimp +*/ + +/*! \fn int QMacStyle::styleHint(StyleHint sh, const QStyleOption *opt, const QWidget *w, QStyleHintReturn *hret) const + \reimp +*/ + +/*! \fn QPixmap QMacStyle::generatedIconPixmap(QIcon::Mode iconMode, const QPixmap &pixmap, const QStyleOption *opt) const + \reimp +*/ + +/*! \fn QPixmap QMacStyle::standardPixmap(StandardPixmap standardPixmap, const QStyleOption *opt, const QWidget *widget) const + \reimp +*/ + +/*! + \enum QMacStyle::FocusRectPolicy + + This type is used to signify a widget's focus rectangle policy. + + \value FocusEnabled show a focus rectangle when the widget has focus. + \value FocusDisabled never show a focus rectangle for the widget. + \value FocusDefault show a focus rectangle when the widget has + focus and the widget is a QSpinWidget, QDateTimeEdit, QLineEdit, + QListBox, QListView, editable QTextEdit, or one of their + subclasses. +*/ + +/*! \fn void QMacStyle::setFocusRectPolicy(QWidget *w, FocusRectPolicy policy) + \obsolete + Sets the focus rectangle policy of \a w. The \a policy can be one of + \l{QMacStyle::FocusRectPolicy}. + + This is now simply an interface to the Qt::WA_MacShowFocusRect attribute and the + FocusDefault value does nothing anymore. If you want to set a widget back + to its default value, you must save the old value of the attribute before + you change it. + + \sa focusRectPolicy() QWidget::setAttribute() +*/ + +/*! \fn QMacStyle::FocusRectPolicy QMacStyle::focusRectPolicy(const QWidget *w) + \obsolete + Returns the focus rectangle policy for the widget \a w. + + The focus rectangle policy can be one of \l{QMacStyle::FocusRectPolicy}. + + In 4.3 and up this function will simply test for the + Qt::WA_MacShowFocusRect attribute and will never return + QMacStyle::FocusDefault. + + \sa setFocusRectPolicy(), QWidget::testAttribute() +*/ + +/*! \fn void QMacStyle::setWidgetSizePolicy(const QWidget *widget, WidgetSizePolicy policy) + + \obsolete + + Call QWidget::setAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, + or Qt::WA_MacNormalSize instead. +*/ + +/*! \fn QMacStyle::WidgetSizePolicy QMacStyle::widgetSizePolicy(const QWidget *widget) + \obsolete + + Call QWidget::testAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, + or Qt::WA_MacNormalSize instead. +*/ + +/*! \fn void QMacStyle::drawPrimitive(PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w) const + + \reimp +*/ + +/*! \fn void QMacStyle::drawControl(ControlElement ce, const QStyleOption *opt, QPainter *p, const QWidget *w) const + + \reimp +*/ + +/*! \fn QRect QMacStyle::subElementRect(SubElement sr, const QStyleOption *opt, const QWidget *widget) const + + \reimp +*/ + +/*! \fn void QMacStyle::drawComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *widget) const + \reimp +*/ + +/*! \fn QStyle::SubControl QMacStyle::hitTestComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *widget) const + \reimp +*/ + +/*! \fn QRect QMacStyle::subControlRect(ComplexControl cc, const QStyleOptionComplex *opt, SubControl sc, const QWidget *widget) const + \reimp +*/ + +/*! \fn QSize QMacStyle::sizeFromContents(ContentsType ct, const QStyleOption *opt, const QSize &csz, const QWidget *widget) const + \reimp +*/ + +/*! \fn void QMacStyle::drawItemText(QPainter *p, const QRect &r, int flags, const QPalette &pal, bool enabled, const QString &text, QPalette::ColorRole textRole) const + \reimp +*/ + +/*! \fn bool QMacStyle::event(QEvent *e) + \reimp +*/ + +/*! \fn QIcon QMacStyle::standardIconImplementation(StandardPixmap standardIcon, const QStyleOption *opt, const QWidget *widget) const + \internal +*/ + +/*! \fn int QMacStyle::layoutSpacingImplementation(QSizePolicy::ControlType control1, QSizePolicy::ControlType control2, Qt::Orientation orientation, const QStyleOption *option, const QWidget *widget) const + + \internal +*/ + diff --git a/doc/src/classes/qpagesetupdialog.qdoc b/doc/src/classes/qpagesetupdialog.qdoc new file mode 100644 index 0000000..7f0b09e --- /dev/null +++ b/doc/src/classes/qpagesetupdialog.qdoc @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QPageSetupDialog + + \brief The QPageSetupDialog class provides a configuration dialog + for the page-related options on a printer. + + On Windows and Mac OS X the page setup dialog is implemented using + the native page setup dialogs. + + Note that on Windows and Mac OS X custom paper sizes won't be + reflected in the native page setup dialogs. Additionally, custom + page margins set on a QPrinter won't show in the native Mac OS X + page setup dialog. + + \sa QPrinter, QPrintDialog +*/ + + +/*! + \fn QPageSetupDialog::QPageSetupDialog(QPrinter *printer, QWidget *parent) + + Constructs a page setup dialog that configures \a printer with \a + parent as the parent widget. +*/ + +/*! + \since 4.5 + + \fn QPageSetupDialog::QPageSetupDialog(QWidget *parent) + + Constructs a page setup dialog that configures a default-constructed + QPrinter with \a parent as the parent widget. + + \sa printer() +*/ + +/*! + \fn QPrinter *QPageSetupDialog::printer() + + Returns the printer that was passed to the QPageSetupDialog + constructor. +*/ + diff --git a/doc/src/classes/qpaintdevice.qdoc b/doc/src/classes/qpaintdevice.qdoc new file mode 100644 index 0000000..0f4e9a0 --- /dev/null +++ b/doc/src/classes/qpaintdevice.qdoc @@ -0,0 +1,289 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QPaintDevice + \brief The QPaintDevice class is the base class of objects that + can be painted. + + \ingroup multimedia + + A paint device is an abstraction of a two-dimensional space that + can be drawn using a QPainter. Its default coordinate system has + its origin located at the top-left position. X increases to the + right and Y increases downwards. The unit is one pixel. + + The drawing capabilities of QPaintDevice are currently implemented + by the QWidget, QImage, QPixmap, QGLPixelBuffer, QPicture, and + QPrinter subclasses. + + To implement support for a new backend, you must derive from + QPaintDevice and reimplement the virtual paintEngine() function to + tell QPainter which paint engine should be used to draw on this + particular device. Note that you also must create a corresponding + paint engine to be able to draw on the device, i.e derive from + QPaintEngine and reimplement its virtual functions. + + \warning Qt requires that a QApplication object exists before + any paint devices can be created. Paint devices access window + system resources, and these resources are not initialized before + an application object is created. + + The QPaintDevice class provides several functions returning the + various device metrics: The depth() function returns its bit depth + (number of bit planes). The height() function returns its height + in default coordinate system units (e.g. pixels for QPixmap and + QWidget) while heightMM() returns the height of the device in + millimeters. Similiarily, the width() and widthMM() functions + return the width of the device in default coordinate system units + and in millimeters, respectively. Alternatively, the protected + metric() function can be used to retrieve the metric information + by specifying the desired PaintDeviceMetric as argument. + + The logicalDpiX() and logicalDpiY() functions return the + horizontal and vertical resolution of the device in dots per + inch. The physicalDpiX() and physicalDpiY() functions also return + the resolution of the device in dots per inch, but note that if + the logical and vertical resolution differ, the corresponding + QPaintEngine must handle the mapping. Finally, the numColors() + function returns the number of different colors available for the + paint device. + + \sa QPaintEngine, QPainter, {The Coordinate System}, {The Paint + System} +*/ + +/*! + \enum QPaintDevice::PaintDeviceMetric + + Describes the various metrics of a paint device. + + \value PdmWidth The width of the paint device in default + coordinate system units (e.g. pixels for QPixmap and QWidget). See + also width(). + + \value PdmHeight The height of the paint device in default + coordinate system units (e.g. pixels for QPixmap and QWidget). See + also height(). + + \value PdmWidthMM The width of the paint device in millimeters. See + also widthMM(). + + \value PdmHeightMM The height of the paint device in millimeters. See + also heightMM(). + + \value PdmNumColors The number of different colors available for + the paint device. See also numColors(). + + \value PdmDepth The bit depth (number of bit planes) of the paint + device. See also depth(). + + \value PdmDpiX The horizontal resolution of the device in dots per + inch. See also logicalDpiX(). + + \value PdmDpiY The vertical resolution of the device in dots per inch. See + also logicalDpiY(). + + \value PdmPhysicalDpiX The horizontal resolution of the device in + dots per inch. See also physicalDpiX(). + + \value PdmPhysicalDpiY The vertical resolution of the device in + dots per inch. See also physicalDpiY(). + + \sa metric() +*/ + +/*! + \fn QPaintDevice::QPaintDevice() + + Constructs a paint device. This constructor can be invoked only from + subclasses of QPaintDevice. +*/ + +/*! + \fn QPaintDevice::~QPaintDevice() + + Destroys the paint device and frees window system resources. +*/ + +/*! + \fn int QPaintDevice::devType() const + + \internal + + Returns the device type identifier, which is QInternal::Widget + if the device is a QWidget, QInternal::Pixmap if it's a + QPixmap, QInternal::Printer if it's a QPrinter, + QInternal::Picture if it's a QPicture, or + QInternal::UnknownDevice in other cases. +*/ + +/*! + \fn bool QPaintDevice::paintingActive() const + + Returns true if the device is currently being painted on, i.e. someone has + called QPainter::begin() but not yet called QPainter::end() for + this device; otherwise returns false. + + \sa QPainter::isActive() +*/ + +/*! + \fn QPaintEngine *QPaintDevice::paintEngine() const + + Returns a pointer to the paint engine used for drawing on the + device. +*/ + +/*! + \fn int QPaintDevice::metric(PaintDeviceMetric metric) const + + Returns the metric information for the given paint device \a metric. + + \sa PaintDeviceMetric +*/ + +/*! + \fn int QPaintDevice::width() const + + Returns the width of the paint device in default coordinate system + units (e.g. pixels for QPixmap and QWidget). + + \sa widthMM() +*/ + +/*! + \fn int QPaintDevice::height() const + + Returns the height of the paint device in default coordinate + system units (e.g. pixels for QPixmap and QWidget). + + \sa heightMM() +*/ + +/*! + \fn int QPaintDevice::widthMM() const + + Returns the width of the paint device in millimeters. Due to platform + limitations it may not be possible to use this function to determine + the actual physical size of a widget on the screen. + + \sa width() +*/ + +/*! + \fn int QPaintDevice::heightMM() const + + Returns the height of the paint device in millimeters. Due to platform + limitations it may not be possible to use this function to determine + the actual physical size of a widget on the screen. + + \sa height() +*/ + +/*! + \fn int QPaintDevice::numColors() const + + Returns the number of different colors available for the paint + device. Since this value is an int, it will not be sufficient to represent + the number of colors on 32 bit displays, in this case INT_MAX is + returned instead. +*/ + +/*! + \fn int QPaintDevice::depth() const + + Returns the bit depth (number of bit planes) of the paint device. +*/ + +/*! + \fn int QPaintDevice::logicalDpiX() const + + Returns the horizontal resolution of the device in dots per inch, + which is used when computing font sizes. For X11, this is usually + the same as could be computed from widthMM(). + + Note that if the logicalDpiX() doesn't equal the physicalDpiX(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa logicalDpiY(), physicalDpiX() +*/ + +/*! + \fn int QPaintDevice::logicalDpiY() const + + Returns the vertical resolution of the device in dots per inch, + which is used when computing font sizes. For X11, this is usually + the same as could be computed from heightMM(). + + Note that if the logicalDpiY() doesn't equal the physicalDpiY(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa logicalDpiX(), physicalDpiY() +*/ + +/*! + \fn int QPaintDevice::physicalDpiX() const + + Returns the horizontal resolution of the device in dots per inch. + For example, when printing, this resolution refers to the physical + printer's resolution. The logical DPI on the other hand, refers to + the resolution used by the actual paint engine. + + Note that if the physicalDpiX() doesn't equal the logicalDpiX(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa physicalDpiY(), logicalDpiX() +*/ + +/*! + \fn int QPaintDevice::physicalDpiY() const + + Returns the horizontal resolution of the device in dots per inch. + For example, when printing, this resolution refers to the physical + printer's resolution. The logical DPI on the other hand, refers to + the resolution used by the actual paint engine. + + Note that if the physicalDpiY() doesn't equal the logicalDpiY(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa physicalDpiX(), logicalDpiY() +*/ diff --git a/doc/src/classes/qpair.qdoc b/doc/src/classes/qpair.qdoc new file mode 100644 index 0000000..6d8a0f9 --- /dev/null +++ b/doc/src/classes/qpair.qdoc @@ -0,0 +1,229 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QPair + \brief The QPair class is a template class that stores a pair of items. + + \ingroup tools + + QPair\ can be used in your application if the STL \c + pair type is not available. It stores one value of type T1 and + one value of type T2. It can be used as a return value for a + function that needs to return two values, or as the value type of + a \l{generic container}. + + Here's an example of a QPair that stores one QString and one \c + double value: + + \snippet doc/src/snippets/code/doc_src_qpair.qdoc 0 + + The components are accessible as public data members called \l + first and \l second. For example: + + \snippet doc/src/snippets/code/doc_src_qpair.qdoc 1 + + QPair's template data types (T1 and T2) must be \l{assignable + data types}. You cannot, for example, store a QWidget as a value; + instead, store a QWidget *. A few functions have additional + requirements; these requirements are documented on a per-function + basis. + + \sa {Generic Containers} +*/ + +/*! \typedef QPair::first_type + + The type of the first element in the pair (T1). + + \sa first +*/ + +/*! \typedef QPair::second_type + + The type of the second element in the pair (T2). + + \sa second +*/ + +/*! \variable QPair::first + + The first element in the pair. +*/ + +/*! \variable QPair::second + + The second element in the pair. +*/ + +/*! \fn QPair::QPair() + + Constructs an empty pair. The \c first and \c second elements are + initialized with \l{default-constructed values}. +*/ + +/*! + \fn QPair::QPair(const T1 &value1, const T2 &value2) + + Constructs a pair and initializes the \c first element with \a + value1 and the \c second element with \a value2. + + \sa qMakePair() +*/ + +/*! + \fn QPair &QPair::operator=(const QPair &other) + + Assigns \a other to this pair. +*/ + +/*! \fn bool operator==(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is equal to \a p2; otherwise returns false. + Two pairs compare equal if their \c first data members compare + equal and if their \c second data members compare equal. + + This function requires the T1 and T2 types to have an + implementation of \c operator==(). +*/ + +/*! \fn bool operator!=(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is not equal to \a p2; otherwise returns + false. Two pairs compare as not equal if their \c first data + members are not equal or if their \c second data members are not + equal. + + This function requires the T1 and T2 types to have an + implementation of \c operator==(). +*/ + +/*! \fn bool operator<(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is less than \a p2; otherwise returns + false. The comparison is done on the \c first members of \a p1 + and \a p2; if they compare equal, the \c second members are + compared to break the tie. + + This function requires the T1 and T2 types to have an + implementation of \c operator<(). +*/ + +/*! \fn bool operator>(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is greater than \a p2; otherwise returns + false. The comparison is done on the \c first members of \a p1 + and \a p2; if they compare equal, the \c second members are + compared to break the tie. + + This function requires the T1 and T2 types to have an + implementation of \c operator<(). +*/ + +/*! \fn bool operator<=(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is less than or equal to \a p2; otherwise + returns false. The comparison is done on the \c first members of + \a p1 and \a p2; if they compare equal, the \c second members are + compared to break the tie. + + This function requires the T1 and T2 types to have an + implementation of \c operator<(). +*/ + +/*! \fn bool operator>=(const QPair &p1, const QPair &p2) + + \relates QPair + + Returns true if \a p1 is greater than or equal to \a p2; + otherwise returns false. The comparison is done on the \c first + members of \a p1 and \a p2; if they compare equal, the \c second + members are compared to break the tie. + + This function requires the T1 and T2 types to have an + implementation of \c operator<(). +*/ + +/*! + \fn QPair qMakePair(const T1 &value1, const T2 &value2) + + \relates QPair + + Returns a QPair\ that contains \a value1 and \a value2. + Example: + + \snippet doc/src/snippets/code/doc_src_qpair.qdoc 2 + + This is equivalent to QPair(\a value1, \a value2), but + usually requires less typing. +*/ + +/*! \fn QDataStream &operator>>(QDataStream &in, QPair &pair) + + \relates QPair + + Reads a pair from stream \a in into \a pair. + + This function requires the T1 and T2 types to implement \c operator>>(). + + \sa {Format of the QDataStream operators} +*/ + +/*! \fn QDataStream &operator<<(QDataStream &out, const QPair &pair) + + \relates QPair + + Writes the pair \a pair to stream \a out. + + This function requires the T1 and T2 types to implement \c operator<<(). + + \sa {Format of the QDataStream operators} +*/ diff --git a/doc/src/classes/qpatternistdummy.cpp b/doc/src/classes/qpatternistdummy.cpp new file mode 100644 index 0000000..a690184 --- /dev/null +++ b/doc/src/classes/qpatternistdummy.cpp @@ -0,0 +1,1010 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* + + This file exists only to make internal all the classes you see + below. they are all in the QPatternist namespace, but they don't + have qdoc documentation because they are all declared in xxx_p.h files. Without these \internal declarations, the class names + appear on the Inheritance Hierarchy page, which is bad because + clicking on them brings up the "File not found" page. + */ + +#include "qitem_p.h" +#include "qbuiltintypes_p.h" +#include "qitem_p.h" +#include "qschematypefactory_p.h" +#include "qxmlname.h" +#include "qatomictype_p.h" + +QT_BEGIN_NAMESPACE + +using namespace QPatternist; + +/*! + \class AtomicCaster + \internal + */ + +/*! + \class AtomicComparator + \internal + */ + +/*! + \class AtomicMathematician + \internal + */ + +/*! + \class AtomicValue + \internal + */ + +/*! + \class AbstractDateTime + \internal + */ + +/*! + \class AbstractDuration + \internal + */ + +/*! + \class AbstractFloatComparator + \internal + */ + +/*! + \class AtomicString + \internal + */ + +/*! + \class Base64Binary + \internal + */ + +/*! + \class FunctionCall + \internal + */ + +/*! + \class AddingAggregate + \internal + */ + +/*! + \class AdjustTimezone + \internal + */ + +/*! + \class Aggregator + \internal + */ + +/*! + \class ComparesCaseAware + \internal + */ + +/*! + \class EncodeString + \internal + */ + +/*! + \class ExtractFromDateTimeFN + \internal + */ + +/*! + \class ExtractFromDurationFN + \internal + */ + +/*! + \class FunctionFactory + \internal + */ + +/*! + \class Numeric + \internal + */ + +/*! + \class ReportContext + \internal + */ + +/*! + \class AbstractFunctionFactory + \internal + */ + +/*! + \class DynamicContext + \internal + */ + +/*! + \class IdFN + \internal + */ + +/*! + \class IntegerType + \internal + */ + +/*! + \class NamespaceResolver + \internal + */ + +/*! + \class PatternPlatform + \internal + */ + +/*! \class DocumentProjector + \internal */ +/*! \class NodeBuilder + \internal */ +/*! \class AccelTreeBuilder + \internal */ +/*! \class OutputValidator + \internal */ +/*! \class NetworkLoop + \internal */ +/*! \class QIODeviceDelegate + \internal */ +/*! \class URILoader + \internal */ +/*! \class AbsFN + \internal */ +/*! \class AbstractDateTimeComparator + \internal */ +/*! \class AbstractDateTimeMathematician + \internal */ +/*! \class AbstractDateTimeToDateCaster + \internal */ +/*! \class AbstractDateTimeToDateTimeCaster + \internal */ +/*! \class AbstractDateTimeToGDayCaster + \internal */ +/*! \class AbstractDateTimeToGMonthCaster + \internal */ +/*! \class AbstractDateTimeToGMonthDayCaster + \internal */ +/*! \class AbstractDateTimeToGYearCaster + \internal */ +/*! \class AbstractDateTimeToGYearMonthCaster + \internal */ +/*! \class AbstractDateTimeToTimeCaster + \internal */ +/*! \class AbstractDurationComparator + \internal */ +/*! \class AbstractDurationToDayTimeDurationCaster + \internal */ +/*! \class AbstractDurationToDurationCaster + \internal */ +/*! \class AbstractDurationToYearMonthDurationCaster + \internal */ +/*! \class AbstractFloat + \internal */ +/*! \class AbstractFloatMathematician + \internal */ +/*! \class AbstractFloatSortComparator + \internal */ +/*! \class ConstructorFunctionsFactory + \internal */ +/*! \class XPath10CoreFunctions + \internal */ +/*! \class XPath20CoreFunctions + \internal */ +/*! \class AdjustDateTimeToTimezoneFN + \internal */ +/*! \class AdjustDateToTimezoneFN + \internal */ +/*! \class AdjustTimeToTimezoneFN + \internal */ +/*! \class AnyToDerivedStringCaster + \internal */ +/*! \class AnyURI + \internal */ +/*! \class Atomizer + \internal */ +/*! \class AvgFN + \internal */ +/*! \class Base64BinaryComparatorLocator + \internal */ +/*! \class Base64BinaryToHexBinaryCaster + \internal */ +/*! \class Base64BinaryType + \internal */ +/*! \class BaseURIFN + \internal */ +/*! \class BinaryDataComparator + \internal */ +/*! \class Boolean + \internal */ +/*! \class BooleanComparator + \internal */ +/*! \class BooleanComparatorLocator + \internal */ +/*! \class BooleanFN + \internal */ +/*! \class BooleanToAbstractFloatCaster + \internal */ +/*! \class BooleanToDecimalCaster + \internal */ +/*! \class BooleanToDerivedIntegerCaster + \internal */ +/*! \class BooleanToIntegerCaster + \internal */ +/*! \class BooleanType + \internal */ +/*! \class BuiltinNodeType + \internal */ +/*! \class CardinalityVerifier + \internal */ +/*! \class CaseInsensitiveStringComparator + \internal */ +/*! \class CeilingFN + \internal */ +/*! \class CodepointEqualFN + \internal */ +/*! \class CodepointsToStringFN + \internal */ +/*! \class CollectionFN + \internal */ +/*! \class CompareFN + \internal */ +/*! \class ComparingAggregator + \internal */ +/*! \class ConcatFN + \internal */ +/*! \class ContainsFN + \internal */ +/*! \class CountFN + \internal */ +/*! \class CurrentDateFN + \internal */ +/*! \class CurrentDateTimeFN + \internal */ +/*! \class CurrentTimeFN + \internal */ +/*! \class Date + \internal */ +/*! \class DateComparatorLocator + \internal */ +/*! \class DateMathematicianLocator + \internal */ +/*! \class DateTime + \internal */ +/*! \class DateTimeComparatorLocator + \internal */ +/*! \class DateTimeDurationMathematician + \internal */ +/*! \class DateTimeFN + \internal */ +/*! \class DateTimeMathematicianLocator + \internal */ +/*! \class DateTimeType + \internal */ +/*! \class DateType + \internal */ +/*! \class DayFromAbstractDateTimeFN + \internal */ +/*! \class DayTimeDuration + \internal */ +/*! \class DayTimeDurationComparatorLocator + \internal */ +/*! \class DayTimeDurationMathematicianLocator + \internal */ +/*! \class DayTimeDurationType + \internal */ +/*! \class DaysFromDurationFN + \internal */ +/*! \class Decimal + \internal */ +/*! \class DecimalComparator + \internal */ +/*! \class DecimalComparatorLocator + \internal */ +/*! \class DecimalMathematician + \internal */ +/*! \class DecimalMathematicianLocator + \internal */ +/*! \class DecimalType + \internal */ +/*! \class DeduplicateIterator + \internal */ +/*! \class DeepEqualFN + \internal */ +/*! \class DefaultCollationFN + \internal */ +/*! \class DerivedInteger + \internal */ +/*! \class DerivedString + \internal */ +/*! \class DistinctValuesFN + \internal */ +/*! \class DocAvailableFN + \internal */ +/*! \class DocFN + \internal */ +/*! \class DocumentURIFN + \internal */ +/*! \class DoubleComparatorLocator + \internal */ +/*! \class DoubleMathematicianLocator + \internal */ +/*! \class DoubleType + \internal */ +/*! \class Duration + \internal */ +/*! \class DurationComparatorLocator + \internal */ +/*! \class DurationDurationDivisor + \internal */ +/*! \class DurationDurationMathematician + \internal */ +/*! \class DurationNumericMathematician + \internal */ +/*! \class DurationType + \internal */ +/*! \class DelegatingDynamicContext + \internal */ +/*! \class Focus + \internal */ +/*! \class ReceiverDynamicContext + \internal */ +/*! \class EmptyIterator + \internal */ +/*! \class EncodeForURIFN + \internal */ +/*! \class EndsWithFN + \internal */ +/*! \class ErrorFN + \internal */ +/*! \class EscapeHtmlURIFN + \internal */ +/*! \class EvaluationCache + \internal */ +/*! \class Existence + \internal */ +/*! \class ExpressionVisitor + \internal */ +/*! \class ExpressionVisitorResult + \internal */ +/*! \class FalseFN + \internal */ +/*! \class FloatComparatorLocator + \internal */ +/*! \class FloatMathematicianLocator + \internal */ +/*! \class FloatType + \internal */ +/*! \class FloorFN + \internal */ +/*! \class FunctionArgument + \internal */ +/*! \class FunctionAvailableFN + \internal */ +/*! \class FunctionFactoryCollection + \internal */ +/*! \class FunctionSignature + \internal */ +/*! \class GDay + \internal */ +/*! \class GDayComparatorLocator + \internal */ +/*! \class GDayType + \internal */ +/*! \class GMonth + \internal */ +/*! \class GMonthComparatorLocator + \internal */ +/*! \class GMonthDay + \internal */ +/*! \class GMonthDayComparatorLocator + \internal */ +/*! \class GMonthDayType + \internal */ +/*! \class GMonthType + \internal */ +/*! \class GYear + \internal */ +/*! \class GYearComparatorLocator + \internal */ +/*! \class GYearMonth + \internal */ +/*! \class GYearMonthComparatorLocator + \internal */ +/*! \class GYearMonthType + \internal */ +/*! \class GYearType + \internal */ +/*! \class HexBinary + \internal */ +/*! \class HexBinaryComparatorLocator + \internal */ +/*! \class HexBinaryToBase64BinaryCaster + \internal */ +/*! \class HexBinaryType + \internal */ +/*! \class HoursFromAbstractDateTimeFN + \internal */ +/*! \class HoursFromDurationFN + \internal */ +/*! \class IdrefFN + \internal */ +/*! \class ImplicitTimezoneFN + \internal */ +/*! \class InScopePrefixesFN + \internal */ +/*! \class IndexOfFN + \internal */ +/*! \class InsertBeforeFN + \internal */ +/*! \class Integer + \internal */ +/*! \class IntegerComparator + \internal */ +/*! \class IntegerComparatorLocator + \internal */ +/*! \class IntegerMathematician + \internal */ +/*! \class IntegerMathematicianLocator + \internal */ +/*! \class DerivedIntegerType + \internal */ +/*! \class IriToURIFN + \internal */ +/*! \class ItemMappingIterator + \internal */ +/*! \class ItemVerifier + \internal */ +/*! \class LangFN + \internal */ +/*! \class LastFN + \internal */ +/*! \class LocalNameFN + \internal */ +/*! \class LocalNameFromQNameFN + \internal */ +/*! \class LowerCaseFN + \internal */ +/*! \class MinutesFromAbstractDateTimeFN + \internal */ +/*! \class MinutesFromDurationFN + \internal */ +/*! \class MonthFromAbstractDateTimeFN + \internal */ +/*! \class MonthsFromDurationFN + \internal */ +/*! \class NOTATIONType + \internal */ +/*! \class NameFN + \internal */ +/*! \class NamePool + \internal */ +/*! \class DelegatingNamespaceResolver + \internal */ +/*! \class GenericNamespaceResolver + \internal */ +/*! \class NodeNamespaceResolver + \internal */ +/*! \class NamespaceURIFN + \internal */ +/*! \class NamespaceURIForPrefixFN + \internal */ +/*! \class NamespaceURIFromQNameFN + \internal */ +/*! \class NilledFN + \internal */ +/*! \class NodeNameFN + \internal */ +/*! \class NormalizeSpaceFN + \internal */ +/*! \class NormalizeUnicodeFN + \internal */ +/*! \class NotFN + \internal */ +/*! \class NumberFN + \internal */ +/*! \class NumericToAbstractFloatCaster + \internal */ +/*! \class NumericToBooleanCaster + \internal */ +/*! \class NumericToDecimalCaster + \internal */ +/*! \class NumericToDerivedIntegerCaster + \internal */ +/*! \class OperandSwitcherMathematician + \internal */ +/*! \class ParserContext + \internal */ +/*! \class MatchesFN + \internal */ +/*! \class ReplaceFN + \internal */ +/*! \class TokenizeFN + \internal */ +/*! \class PositionFN + \internal */ +/*! \class PrefixFromQNameFN + \internal */ +/*! \class AccelTree + \internal */ +/*! \class QNameComparator + \internal */ +/*! \class QNameComparatorLocator + \internal */ +/*! \class QNameFN + \internal */ +/*! \class QNameType + \internal */ +/*! \class QNameValue + \internal */ +/*! \class RemoveFN + \internal */ +/*! \class ResolveQNameFN + \internal */ +/*! \class ResolveURIFN + \internal */ +/*! \class ResourceLoader + \internal */ +/*! \class AccelTreeResourceLoader + \internal */ +/*! \class ReverseFN + \internal */ +/*! \class RootFN + \internal */ +/*! \class RoundFN + \internal */ +/*! \class RoundHalfToEvenFN + \internal */ +/*! \class SchemaTime + \internal */ +/*! \class SchemaTimeComparatorLocator + \internal */ +/*! \class SchemaTimeMathematicianLocator + \internal */ +/*! \class SchemaTimeType + \internal */ +/*! \class SecondsFromAbstractDateTimeFN + \internal */ +/*! \class SecondsFromDurationFN + \internal */ +/*! \class SelfToSelfCaster + \internal */ +/*! \class SequenceMappingIterator + \internal */ +/*! \class SingletonIterator + \internal */ +/*! \class SortTuple + \internal */ +/*! \class StartsWithFN + \internal */ +/*! \class StaticBaseURIFN + \internal */ +/*! \class StaticContext + \internal */ +/*! \class DelegatingStaticContext + \internal */ +/*! \class StaticFocusContext + \internal */ +/*! \class StaticNamespaceContext + \internal */ +/*! \class GenericStaticContext + \internal */ +/*! \class StringComparator + \internal */ +/*! \class StringComparatorLocator + \internal */ +/*! \class StringFN + \internal */ +/*! \class StringJoinFN + \internal */ +/*! \class StringLengthFN + \internal */ +/*! \class StringToAbstractFloatCaster + \internal */ +/*! \class StringToBase64BinaryCaster + \internal */ +/*! \class StringToBooleanCaster + \internal */ +/*! \class StringToCodepointsFN + \internal */ +/*! \class StringToDateCaster + \internal */ +/*! \class StringToDateTimeCaster + \internal */ +/*! \class StringToDayTimeDurationCaster + \internal */ +/*! \class StringToDecimalCaster + \internal */ +/*! \class StringToDerivedIntegerCaster + \internal */ +/*! \class StringToDurationCaster + \internal */ +/*! \class StringToGDayCaster + \internal */ +/*! \class StringToGMonthCaster + \internal */ +/*! \class StringToGMonthDayCaster + \internal */ +/*! \class StringToGYearCaster + \internal */ +/*! \class StringToGYearMonthCaster + \internal */ +/*! \class StringToHexBinaryCaster + \internal */ +/*! \class StringToIntegerCaster + \internal */ +/*! \class StringToTimeCaster + \internal */ +/*! \class StringToYearMonthDurationCaster + \internal */ +/*! \class StringType + \internal */ +/*! \class DerivedStringType + \internal */ +/*! \class SubsequenceFN + \internal */ +/*! \class SubstringAfterFN + \internal */ +/*! \class SubstringBeforeFN + \internal */ +/*! \class SubstringFN + \internal */ +/*! \class SumFN + \internal */ +/*! \class SystemPropertyFN + \internal */ +/*! \class TimezoneFromAbstractDateTimeFN + \internal */ +/*! \class ToAnyURICaster + \internal */ +/*! \class ToAnyURICasterLocator + \internal */ +/*! \class ToBase64BinaryCasterLocator + \internal */ +/*! \class ToBooleanCasterLocator + \internal */ +/*! \class ToDateCasterLocator + \internal */ +/*! \class ToDateTimeCasterLocator + \internal */ +/*! \class ToDayTimeDurationCasterLocator + \internal */ +/*! \class ToDecimalCasterLocator + \internal */ +/*! \class ToDoubleCasterLocator + \internal */ +/*! \class ToDurationCasterLocator + \internal */ +/*! \class ToFloatCasterLocator + \internal */ +/*! \class ToGDayCasterLocator + \internal */ +/*! \class ToGMonthCasterLocator + \internal */ +/*! \class ToGMonthDayCasterLocator + \internal */ +/*! \class ToGYearCasterLocator + \internal */ +/*! \class ToGYearMonthCasterLocator + \internal */ +/*! \class ToHexBinaryCasterLocator + \internal */ +/*! \class ToIntegerCasterLocator + \internal */ +/*! \class ToDerivedIntegerCasterLocator + \internal */ +/*! \class ToQNameCasterLocator + \internal */ +/*! \class ToSchemaTimeCasterLocator + \internal */ +/*! \class ToStringCaster + \internal */ +/*! \class ToStringCasterLocator + \internal */ +/*! \class ToDerivedStringCasterLocator + \internal */ +/*! \class ToUntypedAtomicCaster + \internal */ +/*! \class ToUntypedAtomicCasterLocator + \internal */ +/*! \class ToYearMonthDurationCasterLocator + \internal */ +/*! \class Tokenizer + \internal */ +/*! \class XQueryTokenizer + \internal */ +/*! \class TraceFN + \internal */ +/*! \class TranslateFN + \internal */ +/*! \class TrueFN + \internal */ +/*! \class UntypedAtomic + \internal */ +/*! \class UntypedAtomicConverter + \internal */ +/*! \class ArgumentConverter + \internal */ +/*! \class UntypedAtomicType + \internal */ +/*! \class UpperCaseFN + \internal */ +/*! \class ValidationError + \internal */ +/*! \class VariableDeclaration + \internal */ +/*! \class VariableLoader + \internal */ +/*! \class YearFromAbstractDateTimeFN + \internal */ +/*! \class YearMonthDuration + \internal */ +/*! \class YearMonthDurationComparatorLocator + \internal */ +/*! \class YearMonthDurationMathematicianLocator + \internal */ +/*! \class YearMonthDurationType + \internal */ +/*! \class YearsFromDurationFN + \internal + */ +/*! \class DocumentContentValidator + \internal */ +/*! \class AtomicTypeVisitor + \internal */ +/*! \class AtomicCasterLocator + \internal */ +/*! \class AtomicTypeVisitorResult + \internal */ +/*! \class Expression + \internal */ +/*! \class EmptyContainer + \internal */ +/*! \class AxisStep + \internal */ +/*! \class ContextItem + \internal */ +/*! \class EmptySequence + \internal */ +/*! \class ExternalVariableReference + \internal */ +/*! \class Literal + \internal */ +/*! \class LiteralSequence + \internal */ +/*! \class NamespaceConstructor + \internal */ +/*! \class ParentNodeAxis + \internal */ +/*! \class VariableReference + \internal */ +/*! \class ArgumentReference + \internal */ +/*! \class ExpressionVariableReference + \internal */ +/*! \class PositionalVariableReference + \internal */ +/*! \class RangeVariableReference + \internal */ +/*! \class PairContainer + \internal */ +/*! \class AndExpression + \internal */ +/*! \class OrExpression + \internal */ +/*! \class ArithmeticExpression + \internal */ +/*! \class UnaryExpression + \internal */ +/*! \class AttributeConstructor + \internal */ +/*! \class CombineNodes + \internal */ +/*! \class ElementConstructor + \internal */ +/*! \class ForClause + \internal */ +/*! \class GeneralComparison + \internal */ +/*! \class GenericPredicate + \internal */ +/*! \class TruthPredicate + \internal */ +/*! \class LetClause + \internal */ +/*! \class NodeComparison + \internal */ +/*! \class Path + \internal */ +/*! \class ProcessingInstructionConstructor + \internal */ +/*! \class QuantifiedExpression + \internal */ +/*! \class RangeExpression + \internal */ +/*! \class ValueComparison + \internal */ +/*! \class SingleContainer + \internal */ +/*! \class AttributeNameValidator + \internal */ +/*! \class CastAs + \internal */ +/*! \class CastableAs + \internal */ +/*! \class CollationChecker + \internal */ +/*! \class CommentConstructor + \internal */ +/*! \class CopyOf + \internal */ +/*! \class DocumentConstructor + \internal */ +/*! \class DynamicContextStore + \internal */ +/*! \class FirstItemPredicate + \internal */ +/*! \class InstanceOf + \internal */ +/*! \class NCNameConstructor + \internal */ +/*! \class NodeSortExpression + \internal */ +/*! \class OrderBy + \internal */ +/*! \class QNameConstructor + \internal */ +/*! \class SimpleContentConstructor + \internal */ +/*! \class TextNodeConstructor + \internal */ +/*! \class TreatAs + \internal */ +/*! \class TripleContainer + \internal */ +/*! \class IfThenClause + \internal */ +/*! \class UnlimitedContainer + \internal */ +/*! \class ExpressionSequence + \internal */ +/*! \class ReturnOrderBy + \internal */ +/*! \class UserFunctionCallsite + \internal */ +/*! \class ExpressionCreator + \internal */ +/*! \class ByIDCreator + \internal */ +/*! \class ExpressionFactory + \internal */ +/*! \class ExpressionIdentifier + \internal */ +/*! \class BooleanIdentifier + \internal */ +/*! \class ByIDIdentifier + \internal */ +/*! \class BySequenceTypeIdentifier + \internal */ +/*! \class ComparisonIdentifier + \internal */ +/*! \class IntegerIdentifier + \internal */ +/*! \class ExternalVariableLoader + \internal */ +/*! \class ItemType + \internal */ +/*! \class AnyItemType + \internal */ +/*! \class AnyNodeType + \internal */ +/*! \class AbstractNodeTest + \internal */ +/*! \class LocalNameTest + \internal */ +/*! \class NamespaceNameTest + \internal */ +/*! \class QNameTest + \internal */ +/*! \class AtomicType + \internal */ +/*! \class BuiltinAtomicType + \internal */ +/*! \class AnyAtomicType + \internal */ +/*! \class AnyURIType + \internal */ +/*! \class NumericType + \internal */ +/*! \class EBVType + \internal */ +/*! \class EmptySequenceType + \internal */ +/*! \class MultiItemType + \internal */ +/*! \class NoneType + \internal */ +/*! \class OptimizationPass + \internal */ +/*! \class ParameterizedAtomicTypeVisitor + \internal */ +/*! \class AtomicComparatorLocator + \internal */ +/*! \class AtomicMathematicianLocator + \internal */ +/*! \class SchemaComponent + \internal */ +/*! \class SchemaType + \internal */ +/*! \class AnyType + \internal */ +/*! \class AnySimpleType + \internal */ +/*! \class Untyped + \internal */ +/*! \class SchemaTypeFactory + \internal */ +/*! \class BasicTypesFactory + \internal */ +/*! \class SequenceType + \internal */ +/*! \class GenericSequenceType + \internal */ +/*! \class UserFunction + \internal +*/ +QT_END_NAMESPACE diff --git a/doc/src/classes/qplugin.qdoc b/doc/src/classes/qplugin.qdoc new file mode 100644 index 0000000..4fbd198 --- /dev/null +++ b/doc/src/classes/qplugin.qdoc @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \headerfile + \title Macros for Defining Plugins + + \brief The header files defines macros for defining plugins. + + \sa {How to Create Qt Plugins} +*/ + +/*! + \macro Q_DECLARE_INTERFACE(ClassName, Identifier) + \relates + + This macro associates the given \a Identifier (a string literal) + to the interface class called \a ClassName. The \a Identifier must + be unique. For example: + + \snippet examples/tools/plugandpaint/interfaces.h 3 + + This macro is normally used right after the class definition for + \a ClassName, in a header file. See the + \l{tools/plugandpaint}{Plug & Paint} example for details. + + If you want to use Q_DECLARE_INTERFACE with interface classes + declared in a namespace then you have to make sure the Q_DECLARE_INTERFACE + is not inside a namespace though. For example: + \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 0 + + \sa Q_INTERFACES(), Q_EXPORT_PLUGIN2(), {How to Create Qt Plugins} +*/ + +/*! + \macro Q_EXPORT_PLUGIN(ClassName) + \relates + \obsolete + + Use Q_EXPORT_PLUGIN2() instead. This macro is equivalent to + Q_EXPORT_PLUGIN2(\a ClassName, \a ClassName). +*/ + +/*! + \macro Q_EXPORT_PLUGIN2(PluginName, ClassName) + \relates + \since 4.1 + \keyword Q_EXPORT_PLUGIN2 + + This macro exports the plugin class \a ClassName for the plugin specified + by \a PluginName. The value of \a PluginName should correspond to the + \l{qmake Variable Reference#TARGET}{TARGET} specified in the plugin's + project file. + + There should be exactly one occurrence of this macro in the source code + for a Qt plugin, and it should be used where the implementation is written + rather than in a header file. + + Example: + + \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 1 + + See the \l{tools/plugandpaint}{Plug & Paint} example for details. + + \sa Q_DECLARE_INTERFACE(), {How to Create Qt Plugins} +*/ + +/*! + \macro Q_IMPORT_PLUGIN(PluginName) + \relates + + This macro imports the plugin named \a PluginName, corresponding + to the \l{qmake Variable Reference#TARGET}{TARGET} specified in the + plugin's project file. + + Inserting this macro into your application's source code will allow + you to make use of a static plugin. + + Example: + + \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 2 + + Static plugins must also be included by the linker when your + application is built. For Qt's predefined plugins, + you can use the \c QTPLUGIN to add + the required plugins to your build. For example: + + \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 3 + + \sa {Static Plugins}, {How to Create Qt Plugins}, {Using qmake} +*/ + +/*! + \macro Q_EXPORT_STATIC_PLUGIN(ClassName) + \relates + \internal +*/ diff --git a/doc/src/classes/qprintdialog.qdoc b/doc/src/classes/qprintdialog.qdoc new file mode 100644 index 0000000..8011f62 --- /dev/null +++ b/doc/src/classes/qprintdialog.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifdef QT3_SUPPORT +/*! + \fn QPrinter *QPrintDialog::printer() const + + Returns a pointer to the printer this dialog configures, or 0 if + this dialog does not operate on any printer. + + This function is available for Unix platforms only. +*/ + +/*! + \fn void QPrintDialog::setPrinter(QPrinter *printer, bool pickupSettings) + + Sets this dialog to configure printer \a printer, or no printer if \a printer + is null. If \a pickupSettings is true, the dialog reads most of + its settings from \a printer. If \a pickupSettings is false (the + default) the dialog keeps its old settings. + + This function is available for Unix platforms only. +*/ + +/*! + \fn void QPrintDialog::addButton(QPushButton *button) + + Adds the \a button to the layout of the print dialog. The added + buttons are arranged from the left to the right below the + last groupbox of the printdialog. + + This function is available for Unix platforms only. +*/ +#endif diff --git a/doc/src/classes/qprinterinfo.qdoc b/doc/src/classes/qprinterinfo.qdoc new file mode 100644 index 0000000..a4ffeb2 --- /dev/null +++ b/doc/src/classes/qprinterinfo.qdoc @@ -0,0 +1,137 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QPrinterInfo + + \brief The QPrinterInfo class gives access to information about + existing printers. + + Use the static functions to generate a list of QPrinterInfo + objects. Each QPrinterInfo object in the list represents a single + printer and can be queried for name, supported paper sizes, and + whether or not it is the default printer. + + \since 4.4 +*/ + +/*! + \fn QList QPrinterInfo::availablePrinters() + + Returns a list of available printers on the system. +*/ + +/*! + \fn QPrinterInfo QPrinterInfo::defaultPrinter() + + Returns the default printer on the system. + + The return value should be checked using isNull() before being + used, in case there is no default printer. + + \sa isNull() +*/ + +/*! + \fn QPrinterInfo::QPrinterInfo() + + Constructs an empty QPrinterInfo object. + + \sa isNull() +*/ + +/*! + \fn QPrinterInfo::QPrinterInfo(const QPrinterInfo& src) + + Constructs a copy of \a src. +*/ + +/*! + \fn QPrinterInfo::QPrinterInfo(const QPrinter& printer) + + Constructs a QPrinterInfo object from \a printer. +*/ + +/*! + \fn QPrinterInfo::~QPrinterInfo() + + Destroys the QPrinterInfo object. References to the values in the + object become invalid. +*/ + +/*! + \fn QPrinterInfo& QPrinterInfo::operator=(const QPrinterInfo& src) + + Sets the QPrinterInfo object to be equal to \a src. +*/ + +/*! + \fn QString QPrinterInfo::printerName() const + + Returns the name of the printer. + + \sa QPrinter::setPrinterName() +*/ + +/*! + \fn bool QPrinterInfo::isNull() const + + Returns whether this QPrinterInfo object holds a printer definition. + + An empty QPrinterInfo object could result for example from calling + defaultPrinter() when there are no printers on the system. +*/ + +/*! + \fn bool QPrinterInfo::isDefault() const + + Returns whether this printer is the default printer. +*/ + +/*! + \fn QList< QPrinter::PaperSize> QPrinterInfo::supportedPaperSizes() const + \since 4.4 + + Returns a list of supported paper sizes by the printer. + + Not all printer drivers support this query, so the list may be empty. + On Mac OS X 10.3, this function always returns an empty list. +*/ diff --git a/doc/src/classes/qset.qdoc b/doc/src/classes/qset.qdoc new file mode 100644 index 0000000..0db3775 --- /dev/null +++ b/doc/src/classes/qset.qdoc @@ -0,0 +1,953 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QSet + \brief The QSet class is a template class that provides a hash-table-based set. + + \ingroup tools + \ingroup shared + \reentrant + \mainclass + + QSet is one of Qt's generic \l{container classes}. It stores + values in an unspecified order and provides very fast lookup of + the values. Internally, QSet is implemented as a QHash. + + Here's an example QSet with QString values: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 0 + + To insert a value into the set, use insert(): + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 1 + + Another way to insert items into the set is to use operator<<(): + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 2 + + To test whether an item belongs to the set or not, use contains(): + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 3 + + If you want to navigate through all the values stored in a QSet, + you can use an iterator. QSet supports both \l{Java-style + iterators} (QSetIterator and QMutableSetIterator) and \l{STL-style + iterators} (QSet::iterator and QSet::const_iterator). Here's how + to iterate over a QSet using a Java-style iterator: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 4 + + Here's the same code, but using an STL-style iterator: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 5 + + QSet is unordered, so an iterator's sequence cannot be assumed to + be predictable. If ordering by key is required, use a QMap. + + To navigate through a QSet, you can also use \l{foreach}: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 6 + + Items can be removed from the set using remove(). There is also a + clear() function that removes all items. + + QSet's value data type must be an \l{assignable data type}. You + cannot, for example, store a QWidget as a value; instead, store a + QWidget *. In addition, the type must provide \c operator==(), and + there must also be a global qHash() function that returns a hash + value for an argument of the key's type. See the QHash + documentation for a list of types supported by qHash(). + + Internally, QSet uses a hash table to perform lookups. The hash + table automatically grows and shrinks to provide fast lookups + without wasting memory. You can still control the size of the hash + table by calling reserve(), if you already know approximately how + many elements the QSet will contain, but this isn't necessary to + obtain good performance. You can also call capacity() to retrieve + the hash table's size. + + \sa QSetIterator, QMutableSetIterator, QHash, QMap +*/ + +/*! + \fn QSet::QSet() + + Constructs an empty set. + + \sa clear() +*/ + +/*! + \fn QSet::QSet(const QSet &other) + + Constructs a copy of \a other. + + This operation occurs in \l{constant time}, because QSet is + \l{implicitly shared}. This makes returning a QSet from a + function very fast. If a shared instance is modified, it will be + copied (copy-on-write), and this takes \l{linear time}. + + \sa operator=() +*/ + +/*! + \fn QSet &QSet::operator=(const QSet &other) + + Assigns the \a other set to this set and returns a reference to + this set. +*/ + +/*! + \fn bool QSet::operator==(const QSet &other) const + + Returns true if the \a other set is equal to this set; otherwise + returns false. + + Two sets are considered equal if they contain the same elements. + + This function requires the value type to implement \c operator==(). + + \sa operator!=() +*/ + +/*! + \fn bool QSet::operator!=(const QSet &other) const + + Returns true if the \a other set is not equal to this set; otherwise + returns false. + + Two sets are considered equal if they contain the same elements. + + This function requires the value type to implement \c operator==(). + + \sa operator==() +*/ + +/*! + \fn int QSet::size() const + + Returns the number of items in the set. + + \sa isEmpty(), count() +*/ + +/*! + \fn bool QSet::isEmpty() const + + Returns true if the set contains no elements; otherwise returns + false. + + \sa size() +*/ + +/*! + \fn int QSet::capacity() const + + Returns the number of buckets in the set's internal hash + table. + + The sole purpose of this function is to provide a means of fine + tuning QSet's memory usage. In general, you will rarely ever need + to call this function. If you want to know how many items are in + the set, call size(). + + \sa reserve(), squeeze() +*/ + +/*! \fn void QSet::reserve(int size) + + Ensures that the set's internal hash table consists of at + least \a size buckets. + + This function is useful for code that needs to build a huge set + and wants to avoid repeated reallocation. For example: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 7 + + Ideally, \a size should be slightly more than the maximum number + of elements expected in the set. \a size doesn't have to be prime, + because QSet will use a prime number internally anyway. If \a size + is an underestimate, the worst that will happen is that the QSet + will be a bit slower. + + In general, you will rarely ever need to call this function. + QSet's internal hash table automatically shrinks or grows to + provide good performance without wasting too much memory. + + \sa squeeze(), capacity() +*/ + +/*! + \fn void QSet::squeeze() + + Reduces the size of the set's internal hash table to save + memory. + + The sole purpose of this function is to provide a means of fine + tuning QSet's memory usage. In general, you will rarely ever + need to call this function. + + \sa reserve(), capacity() +*/ + +/*! + \fn void QSet::detach() + + \internal + + Detaches this set from any other sets with which it may share + data. + + \sa isDetached() +*/ + +/*! \fn bool QSet::isDetached() const + + \internal + + Returns true if the set's internal data isn't shared with any + other set object; otherwise returns false. + + \sa detach() +*/ + +/*! + \fn void QSet::setSharable(bool sharable) + \internal +*/ + +/*! + \fn void QSet::clear() + + Removes all elements from the set. + + \sa remove() +*/ + +/*! + \fn bool QSet::remove(const T &value) + + Removes any occurrence of item \a value from the set. Returns + true if an item was actually removed; otherwise returns false. + + \sa contains(), insert() +*/ + +/*! + \fn QSet::iterator QSet::erase(iterator pos) + \since 4.2 + + Removes the item at the iterator position \a pos from the set, and + returns an iterator positioned at the next item in the set. + + Unlike remove(), this function never causes QSet to rehash its + internal data structure. This means that it can safely be called + while iterating, and won't affect the order of items in the set. + + \sa remove(), find() +*/ + +/*! \fn QSet::const_iterator QSet::find(const T &value) const + \since 4.2 + + Returns a const iterator positioned at the item \a value in the + set. If the set contains no item \a value, the function returns + constEnd(). + + \sa constFind(), contains() +*/ + +/*! \fn QSet::iterator QSet::find(const T &value) + \since 4.2 + \overload + + Returns a non-const iterator positioned at the item \a value in + the set. If the set contains no item \a value, the function + returns end(). +*/ + +/*! \fn QSet::const_iterator QSet::constFind(const T &value) const + \since 4.2 + + Returns a const iterator positioned at the item \a value in the + set. If the set contains no item \a value, the function returns + constEnd(). + + \sa find(), contains() +*/ + +/*! + \fn bool QSet::contains(const T &value) const + + Returns true if the set contains item \a value; otherwise returns + false. + + \sa insert(), remove(), find() +*/ + +/*! + \fn bool QSet::contains(const QSet &other) const + \since 4.6 + + Returns true if the set contains all items from the \a other set; + otherwise returns false. + + \sa insert(), remove(), find() +*/ + +/*! \fn QSet::const_iterator QSet::begin() const + + Returns a const \l{STL-style iterator} positioned at the first + item in the set. + + \sa constBegin(), end() +*/ + +/*! \fn QSet::iterator QSet::begin() + \since 4.2 + \overload + + Returns a non-const \l{STL-style iterator} positioned at the first + item in the set. +*/ + +/*! \fn QSet::const_iterator QSet::constBegin() const + + Returns a const \l{STL-style iterator} positioned at the first + item in the set. + + \sa begin(), constEnd() +*/ + +/*! \fn QSet::const_iterator QSet::end() const + + Returns a const \l{STL-style iterator} positioned at the imaginary + item after the last item in the set. + + \sa constEnd(), begin() +*/ + +/*! \fn QSet::iterator QSet::end() + \since 4.2 + \overload + + Returns a non-const \l{STL-style iterator} pointing to the + imaginary item after the last item in the set. +*/ + +/*! \fn QSet::const_iterator QSet::constEnd() const + + Returns a const \l{STL-style iterator} pointing to the imaginary + item after the last item in the set. + + \sa constBegin(), end() +*/ + +/*! + \typedef QSet::Iterator + \since 4.2 + + Qt-style synonym for QSet::iterator. +*/ + +/*! + \typedef QSet::ConstIterator + + Qt-style synonym for QSet::const_iterator. +*/ + +/*! + \typedef QSet::const_pointer + + Typedef for const T *. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::const_reference + + Typedef for const T &. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::difference_type + + Typedef for const ptrdiff_t. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::key_type + + Typedef for T. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::pointer + + Typedef for T *. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::reference + + Typedef for T &. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::size_type + + Typedef for int. Provided for STL compatibility. +*/ + +/*! + \typedef QSet::value_type + + Typedef for T. Provided for STL compatibility. +*/ + +/*! + \fn QSet::const_iterator QSet::insert(const T &value) + + Inserts item \a value into the set, if \a value isn't already + in the set, and returns an iterator pointing at the inserted + item. + + \sa operator<<(), remove(), contains() +*/ + +/*! + \fn QSet &QSet::unite(const QSet &other) + + Each item in the \a other set that isn't already in this set is + inserted into this set. A reference to this set is returned. + + \sa operator|=(), intersect(), subtract() +*/ + +/*! + \fn QSet &QSet::intersect(const QSet &other) + + Removes all items from this set that are not contained in the + \a other set. A reference to this set is returned. + + \sa operator&=(), unite(), subtract() +*/ + +/*! + \fn QSet &QSet::subtract(const QSet &other) + + Removes all items from this set that are contained in the + \a other set. Returns a reference to this set. + + \sa operator-=(), unite(), intersect() +*/ + +/*! + \fn bool QSet::empty() const + + Returns true if the set is empty. This function is provided + for STL compatibility. It is equivalent to isEmpty(). +*/ + +/*! + \fn bool QSet::count() const + + Same as size(). +*/ + +/*! + \fn QSet &QSet::operator<<(const T &value) + \fn QSet &QSet::operator+=(const T &value) + \fn QSet &QSet::operator|=(const T &value) + + Inserts a new item \a value and returns a reference to the set. + If \a value already exists in the set, the set is left unchanged. + + \sa insert() +*/ + +/*! + \fn QSet &QSet::operator-=(const T &value) + + Removes the occurrence of item \a value from the set, if + it is found, and returns a reference to the set. If the + \a value is not contained the set, nothing is removed. + + \sa remove() +*/ + +/*! + \fn QSet &QSet::operator|=(const QSet &other) + \fn QSet &QSet::operator+=(const QSet &other) + + Same as unite(\a other). + + \sa operator|(), operator&=(), operator-=() +*/ + +/*! + \fn QSet &QSet::operator&=(const QSet &other) + + Same as intersect(\a other). + + \sa operator&(), operator|=(), operator-=() +*/ + +/*! + \fn QSet &QSet::operator&=(const T &value) + + \overload + + Same as intersect(\e{other}), if we consider \e{other} to be a set + that contains the singleton \a value. +*/ + + +/*! + \fn QSet &QSet::operator-=(const QSet &other) + + Same as subtract(\a{other}). + + \sa operator-(), operator|=(), operator&=() +*/ + +/*! + \fn QSet QSet::operator|(const QSet &other) const + \fn QSet QSet::operator+(const QSet &other) const + + Returns a new QSet that is the union of this set and the + \a other set. + + \sa unite(), operator|=(), operator&(), operator-() +*/ + +/*! + \fn QSet QSet::operator&(const QSet &other) const + + Returns a new QSet that is the intersection of this set and the + \a other set. + + \sa intersect(), operator&=(), operator|(), operator-() +*/ + +/*! + \fn QSet QSet::operator-(const QSet &other) const + + Returns a new QSet that is the set difference of this set and + the \a other set, i.e., this set - \a other set. + + \sa subtract(), operator-=(), operator|(), operator&() +*/ + +/*! + \fn QSet QSet::operator-(const QSet &other) + \fn QSet QSet::operator|(const QSet &other) + \fn QSet QSet::operator+(const QSet &other) + \fn QSet QSet::operator&(const QSet &other) + \internal + + These will go away in Qt 5. +*/ + +/*! + \class QSet::iterator + \since 4.2 + \brief The QSet::iterator class provides an STL-style non-const iterator for QSet. + + QSet features both \l{STL-style iterators} and + \l{Java-style iterators}. The STL-style iterators are more + low-level and more cumbersome to use; on the other hand, they are + slightly faster and, for developers who already know STL, have + the advantage of familiarity. + + QSet::iterator allows you to iterate over a QSet and to remove + items (using QSet::erase()) while you iterate. (QSet doesn't let + you \e modify a value through an iterator, because that + would potentially require moving the value in the internal hash + table used by QSet.) If you want to iterate over a const QSet, + you should use QSet::const_iterator. It is generally good + practice to use QSet::const_iterator on a non-const QSet as well, + unless you need to change the QSet through the iterator. Const + iterators are slightly faster, and can improve code readability. + + QSet\::iterator allows you to iterate over a QSet\ and + modify it as you go (using QSet::erase()). However, + + The default QSet::iterator constructor creates an uninitialized + iterator. You must initialize it using a function like + QSet::begin(), QSet::end(), or QSet::insert() before you can + start iterating. Here's a typical loop that prints all the items + stored in a set: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 8 + + Here's a loop that removes certain items (all those that start + with 'J') from a set while iterating: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 9 + + STL-style iterators can be used as arguments to \l{generic + algorithms}. For example, here's how to find an item in the set + using the qFind() algorithm: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 10 + + Multiple iterators can be used on the same set. However, you may + not attempt to modify the container while iterating on it. + + \sa QSet::const_iterator, QMutableSetIterator +*/ + +/*! + \class QSet::const_iterator + \brief The QSet::const_iterator class provides an STL-style const iterator for QSet. + \since 4.2 + + QSet features both \l{STL-style iterators} and + \l{Java-style iterators}. The STL-style iterators are more + low-level and more cumbersome to use; on the other hand, they are + slightly faster and, for developers who already know STL, have + the advantage of familiarity. + + QSet\::const_iterator allows you to iterate over a QSet. + If you want to modify the QSet as you iterate over it, you must + use QSet::iterator instead. It is generally good practice to use + QSet::const_iterator on a non-const QSet as well, unless you need + to change the QSet through the iterator. Const iterators are + slightly faster, and can improve code readability. + + The default QSet::const_iterator constructor creates an + uninitialized iterator. You must initialize it using a function + like QSet::begin(), QSet::end(), or QSet::insert() before you can + start iterating. Here's a typical loop that prints all the items + stored in a set: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 11 + + STL-style iterators can be used as arguments to \l{generic + algorithms}. For example, here's how to find an item in the set + using the qFind() algorithm: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 12 + + Multiple iterators can be used on the same set. However, you may + not attempt to modify the container while iterating on it. + + \sa QSet::iterator, QSetIterator +*/ + +/*! + \fn QSet::iterator::iterator() + \fn QSet::const_iterator::const_iterator() + + Constructs an uninitialized iterator. + + Functions like operator*() and operator++() should not be called + on an uninitialized iterator. Use operator=() to assign a value + to it before using it. + + \sa QSet::begin(), QSet::end() +*/ + +/*! + \fn QSet::iterator::iterator(typename Hash::iterator i) + \fn QSet::const_iterator::const_iterator(typename Hash::const_iterator i) + + \internal +*/ + +/*! + \typedef QSet::iterator::iterator_category + \typedef QSet::const_iterator::iterator_category + + Synonyms for \e {std::bidirectional_iterator_tag} indicating + these iterators are bidirectional iterators. + */ + +/*! + \typedef QSet::iterator::difference_type + \typedef QSet::const_iterator::difference_type + + \internal +*/ + +/*! + \typedef QSet::iterator::value_type + \typedef QSet::const_iterator::value_type + + \internal +*/ + +/*! + \typedef QSet::iterator::pointer + \typedef QSet::const_iterator::pointer + + \internal +*/ + +/*! + \typedef QSet::iterator::reference + \typedef QSet::const_iterator::reference + + \internal +*/ + +/*! + \fn QSet::iterator::iterator(const iterator &other) + \fn QSet::const_iterator::const_iterator(const const_iterator &other) + + Constructs a copy of \a other. +*/ + +/*! + \fn QSet::const_iterator::const_iterator(const iterator &other) + \since 4.2 + \overload + + Constructs a copy of \a other. +*/ + +/*! + \fn QSet::iterator &QSet::iterator::operator=(const iterator &other) + \fn QSet::const_iterator &QSet::const_iterator::operator=(const const_iterator &other) + + Assigns \a other to this iterator. +*/ + +/*! + \fn const T &QSet::iterator::operator*() const + \fn const T &QSet::const_iterator::operator*() const + + Returns a reference to the current item. + + \sa operator->() +*/ + +/*! + \fn const T *QSet::iterator::operator->() const + \fn const T *QSet::const_iterator::operator->() const + + Returns a pointer to the current item. + + \sa operator*() +*/ + +/*! + \fn bool QSet::iterator::operator==(const iterator &other) const + \fn bool QSet::const_iterator::operator==(const const_iterator &other) const + + Returns true if \a other points to the same item as this + iterator; otherwise returns false. + + \sa operator!=() +*/ + +/*! + \fn bool QSet::iterator::operator==(const const_iterator &other) const + \fn bool QSet::iterator::operator!=(const const_iterator &other) const + + \overload +*/ + +/*! + \fn bool QSet::iterator::operator!=(const iterator &other) const + \fn bool QSet::const_iterator::operator!=(const const_iterator &other) const + + Returns true if \a other points to a different item than this + iterator; otherwise returns false. + + \sa operator==() +*/ + +/*! + \fn QSet::iterator &QSet::iterator::operator++() + \fn QSet::const_iterator &QSet::const_iterator::operator++() + + The prefix ++ operator (\c{++it}) advances the iterator to the + next item in the set and returns an iterator to the new current + item. + + Calling this function on QSet::constEnd() leads to + undefined results. + + \sa operator--() +*/ + +/*! + \fn QSet::iterator QSet::iterator::operator++(int) + \fn QSet::const_iterator QSet::const_iterator::operator++(int) + + \overload + + The postfix ++ operator (\c{it++}) advances the iterator to the + next item in the set and returns an iterator to the previously + current item. +*/ + +/*! + \fn QSet::iterator &QSet::iterator::operator--() + \fn QSet::const_iterator &QSet::const_iterator::operator--() + + The prefix -- operator (\c{--it}) makes the preceding item + current and returns an iterator to the new current item. + + Calling this function on QSet::begin() leads to undefined + results. + + \sa operator++() +*/ + +/*! + \fn QSet::iterator QSet::iterator::operator--(int) + \fn QSet::const_iterator QSet::const_iterator::operator--(int) + + \overload + + The postfix -- operator (\c{it--}) makes the preceding item + current and returns an iterator to the previously current item. +*/ + +/*! + \fn QSet::iterator QSet::iterator::operator+(int j) const + \fn QSet::const_iterator QSet::const_iterator::operator+(int j) const + + Returns an iterator to the item at \a j positions forward from + this iterator. (If \a j is negative, the iterator goes backward.) + + This operation can be slow for large \a j values. + + \sa operator-() +*/ + +/*! + \fn QSet::iterator QSet::iterator::operator-(int j) const + \fn QSet::const_iterator QSet::const_iterator::operator-(int j) const + + Returns an iterator to the item at \a j positions backward from + this iterator. (If \a j is negative, the iterator goes forward.) + + This operation can be slow for large \a j values. + + \sa operator+() +*/ + +/*! + \fn QSet::iterator &QSet::iterator::operator+=(int j) + \fn QSet::const_iterator &QSet::const_iterator::operator+=(int j) + + Advances the iterator by \a j items. (If \a j is negative, the + iterator goes backward.) + + This operation can be slow for large \a j values. + + \sa operator-=(), operator+() +*/ + +/*! + \fn QSet::iterator &QSet::iterator::operator-=(int j) + \fn QSet::const_iterator &QSet::const_iterator::operator-=(int j) + + Makes the iterator go back by \a j items. (If \a j is negative, + the iterator goes forward.) + + This operation can be slow for large \a j values. + + \sa operator+=(), operator-() +*/ + +/*! \fn QList QSet::toList() const + + Returns a new QList containing the elements in the set. The + order of the elements in the QList is undefined. + + Example: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 13 + + \sa fromList(), QList::fromSet(), qSort() +*/ + +/*! \fn QList QSet::values() const + + Returns a new QList containing the elements in the set. The + order of the elements in the QList is undefined. + + This is the same as toList(). + + \sa fromList(), QList::fromSet(), qSort() +*/ + + +/*! \fn QSet QSet::fromList(const QList &list) + + Returns a new QSet object containing the data contained in \a + list. Since QSet doesn't allow duplicates, the resulting QSet + might be smaller than the \a list, because QList can contain + duplicates. + + Example: + + \snippet doc/src/snippets/code/doc_src_qset.qdoc 14 + + \sa toList(), QList::toSet() +*/ + +/*! + \fn QDataStream &operator<<(QDataStream &out, const QSet &set) + \relates QSet + + Writes the \a set to stream \a out. + + This function requires the value type to implement \c operator<<(). + + \sa \link datastreamformat.html Format of the QDataStream operators \endlink +*/ + +/*! + \fn QDataStream &operator>>(QDataStream &in, QSet &set) + \relates QSet + + Reads a set from stream \a in into \a set. + + This function requires the value type to implement \c operator>>(). + + \sa \link datastreamformat.html Format of the QDataStream operators \endlink +*/ diff --git a/doc/src/classes/qsignalspy.qdoc b/doc/src/classes/qsignalspy.qdoc new file mode 100644 index 0000000..4ee7590 --- /dev/null +++ b/doc/src/classes/qsignalspy.qdoc @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QSignalSpy + \inmodule QtTest + + \brief The QSignalSpy class enables introspection of signal emission. + + QSignalSpy can connect to any signal of any object and records its emission. + QSignalSpy itself is a list of QVariant lists. Each emission of the signal + will append one item to the list, containing the arguments of the signal. + + The following example records all signal emissions for the \c clicked() signal + of a QCheckBox: + + \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 0 + + \c{spy.takeFirst()} returns the arguments for the first emitted signal, as a + list of QVariant objects. The \c clicked() signal has a single bool argument, + which is stored as the first entry in the list of arguments. + + The example below catches a signal from a custom object: + + \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 1 + + \bold {Note:} Non-standard data types need to be registered, using + the qRegisterMetaType() function, before you can create a + QSignalSpy. For example: + + \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 2 + + To retrieve the \c QModelIndex, you can use qvariant_cast: + + \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 3 + */ + +/*! \fn QSignalSpy::QSignalSpy(QObject *object, const char *signal) + + Constructs a new QSignalSpy that listens for emissions of the \a signal + from the QObject \a object. Neither \a signal nor \a object can be null. + + Example: + \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 4 +*/ + +/*! \fn QSignalSpy::isValid() const + + Returns true if the signal spy listens to a valid signal, otherwise false. +*/ + +/*! \fn QSignalSpy::signal() const + + Returns the normalized signal the spy is currently listening to. +*/ + +/*! \fn int QSignalSpy::qt_metacall(QMetaObject::Call call, int id, void **a) + \internal +*/ + diff --git a/doc/src/classes/qsizepolicy.qdoc b/doc/src/classes/qsizepolicy.qdoc new file mode 100644 index 0000000..c74beb8 --- /dev/null +++ b/doc/src/classes/qsizepolicy.qdoc @@ -0,0 +1,522 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QSizePolicy + \brief The QSizePolicy class is a layout attribute describing horizontal + and vertical resizing policy. + + \ingroup appearance + \ingroup geomanagement + + The size policy of a widget is an expression of its willingness to + be resized in various ways, and affects how the widget is treated + by the \l{Layout Management}{layout engine}. Each widget returns a + QSizePolicy that describes the horizontal and vertical resizing + policy it prefers when being laid out. You can change this for + a specific widget by changing its QWidget::sizePolicy property. + + QSizePolicy contains two independent QSizePolicy::Policy values + and two stretch factors; one describes the widgets's horizontal + size policy, and the other describes its vertical size policy. It + also contains a flag to indicate whether the height and width of + its preferred size are related. + + The horizontal and vertical policies can be set in the + constructor, and altered using the setHorizontalPolicy() and + setVerticalPolicy() functions. The stretch factors can be set + using the setHorizontalStretch() and setVerticalStretch() + functions. The flag indicating whether the widget's + \l{QWidget::sizeHint()}{sizeHint()} is width-dependent (such as a + menu bar or a word-wrapping label) can be set using the + setHeightForWidth() function. + + The current size policies and stretch factors be retrieved using + the horizontalPolicy(), verticalPolicy(), horizontalStretch() and + verticalStretch() functions. Alternatively, use the transpose() + function to swap the horizontal and vertical policies and + stretches. The hasHeightForWidth() function returns the current + status of the flag indicating the size hint dependencies. + + Use the expandingDirections() function to determine whether the + associated widget can make use of more space than its + \l{QWidget::sizeHint()}{sizeHint()} function indicates, as well as + find out in which directions it can expand. + + Finally, the QSizePolicy class provides operators comparing this + size policy to a given policy, as well as a QVariant operator + storing this QSizePolicy as a QVariant object. + + \sa QSize, QWidget::sizeHint(), QWidget::sizePolicy, + QLayoutItem::sizeHint() +*/ + +/*! + \enum QSizePolicy::PolicyFlag + + These flags are combined together to form the various \l{Policy} + values: + + \value GrowFlag The widget can grow beyond its size hint if necessary. + \value ExpandFlag The widget should get as much space as possible. + \value ShrinkFlag The widget can shrink below its size hint if necessary. + \value IgnoreFlag The widget's size hint is ignored. The widget will get + as much space as possible. + + \sa Policy +*/ + +/*! + \enum QSizePolicy::Policy + + This enum describes the various per-dimension sizing types used + when constructing a QSizePolicy. + + \value Fixed The QWidget::sizeHint() is the only acceptable + alternative, so the widget can never grow or shrink (e.g. the + vertical direction of a push button). + + \value Minimum The sizeHint() is minimal, and sufficient. The + widget can be expanded, but there is no advantage to it being + larger (e.g. the horizontal direction of a push button). + It cannot be smaller than the size provided by sizeHint(). + + \value Maximum The sizeHint() is a maximum. The widget can be + shrunk any amount without detriment if other widgets need the + space (e.g. a separator line). + It cannot be larger than the size provided by sizeHint(). + + \value Preferred The sizeHint() is best, but the widget can be + shrunk and still be useful. The widget can be expanded, but there + is no advantage to it being larger than sizeHint() (the default + QWidget policy). + + \value Expanding The sizeHint() is a sensible size, but the + widget can be shrunk and still be useful. The widget can make use + of extra space, so it should get as much space as possible (e.g. + the horizontal direction of a horizontal slider). + + \value MinimumExpanding The sizeHint() is minimal, and sufficient. + The widget can make use of extra space, so it should get as much + space as possible (e.g. the horizontal direction of a horizontal + slider). + + \value Ignored The sizeHint() is ignored. The widget will get as + much space as possible. + + \sa PolicyFlag, setHorizontalPolicy(), setVerticalPolicy() +*/ + +/*! + \fn QSizePolicy::QSizePolicy() + + Constructs a QSizePolicy object with \l Fixed as its horizontal + and vertical policies. + + The policies can be altered using the setHorizontalPolicy() and + setVerticalPolicy() functions. Use the setHeightForWidth() + function if the preferred height of the widget is dependent on the + width of the widget (for example, a QLabel with line wrapping). + + \sa setHorizontalStretch(), setVerticalStretch() +*/ + +/*! + \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical) + + Constructs a QSizePolicy object with the given \a horizontal and + \a vertical policies, and DefaultType as the control type. + + Use setHeightForWidth() if the preferred height of the widget is + dependent on the width of the widget (for example, a QLabel with + line wrapping). + + \sa setHorizontalStretch(), setVerticalStretch() +*/ + +/*! + \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, ControlType type) + \since 4.3 + + Constructs a QSizePolicy object with the given \a horizontal and + \a vertical policies, and the specified control \a type. + + Use setHeightForWidth() if the preferred height of the widget is + dependent on the width of the widget (for example, a QLabel with + line wrapping). + + \sa setHorizontalStretch(), setVerticalStretch(), controlType() +*/ + +/*! + \fn QSizePolicy::Policy QSizePolicy::horizontalPolicy() const + + Returns the horizontal component of the size policy. + + \sa setHorizontalPolicy(), verticalPolicy(), horizontalStretch() +*/ + +/*! + \fn QSizePolicy::Policy QSizePolicy::verticalPolicy() const + + Returns the vertical component of the size policy. + + \sa setVerticalPolicy(), horizontalPolicy(), verticalStretch() +*/ + +/*! + \fn void QSizePolicy::setHorizontalPolicy(Policy policy) + + Sets the horizontal component to the given \a policy. + + \sa horizontalPolicy(), setVerticalPolicy(), setHorizontalStretch() +*/ + +/*! + \fn void QSizePolicy::setVerticalPolicy(Policy policy) + + Sets the vertical component to the given \a policy. + + \sa verticalPolicy(), setHorizontalPolicy(), setVerticalStretch() +*/ + +/*! + \fn Qt::Orientations QSizePolicy::expandingDirections() const + + Returns whether a widget can make use of more space than the + QWidget::sizeHint() function indicates. + + A value of Qt::Horizontal or Qt::Vertical means that the widget + can grow horizontally or vertically (i.e., the horizontal or + vertical policy is \l Expanding or \l MinimumExpanding), whereas + Qt::Horizontal | Qt::Vertical means that it can grow in both + dimensions. + + \sa horizontalPolicy(), verticalPolicy() +*/ + +/*! + \fn ControlType QSizePolicy::controlType() const + \since 4.3 + + Returns the control type associated with the widget for which + this size policy applies. +*/ + +/*! + \fn void QSizePolicy::setControlType(ControlType type) + \since 4.3 + + Sets the control type associated with the widget for which this + size policy applies to \a type. + + The control type specifies the type of the widget for which this + size policy applies. It is used by some styles, notably + QMacStyle, to insert proper spacing between widgets. For example, + the Mac OS X Aqua guidelines specify that push buttons should be + separated by 12 pixels, whereas vertically stacked radio buttons + only require 6 pixels. + + \sa QStyle::layoutSpacing() +*/ + +/*! + \fn void QSizePolicy::setHeightForWidth(bool dependent) + + Sets the flag determining whether the widget's preferred height + depends on its width, to \a dependent. + + \sa hasHeightForWidth() +*/ + +/*! + \fn bool QSizePolicy::hasHeightForWidth() const + + Returns true if the widget's preferred height depends on its + width; otherwise returns false. + + \sa setHeightForWidth() +*/ + +/*! + \fn bool QSizePolicy::operator==(const QSizePolicy &other) const + + Returns true if this policy is equal to \a other; otherwise + returns false. + + \sa operator!=() +*/ + +/*! + \fn bool QSizePolicy::operator!=(const QSizePolicy &other) const + + Returns true if this policy is different from \a other; otherwise + returns false. + + \sa operator==() +*/ + +/*! + \fn int QSizePolicy::horizontalStretch() const + + Returns the horizontal stretch factor of the size policy. + + \sa setHorizontalStretch(), verticalStretch(), horizontalPolicy() +*/ + +/*! + \fn int QSizePolicy::verticalStretch() const + + Returns the vertical stretch factor of the size policy. + + \sa setVerticalStretch(), horizontalStretch(), verticalPolicy() +*/ + +/*! + \fn void QSizePolicy::setHorizontalStretch(uchar stretchFactor) + + Sets the horizontal stretch factor of the size policy to the given \a + stretchFactor. + + \sa horizontalStretch(), setVerticalStretch(), setHorizontalPolicy() +*/ + +/*! + \fn void QSizePolicy::setVerticalStretch(uchar stretchFactor) + + Sets the vertical stretch factor of the size policy to the given + \a stretchFactor. + + \sa verticalStretch(), setHorizontalStretch(), setVerticalPolicy() +*/ + +/*! + \fn void QSizePolicy::transpose() + + Swaps the horizontal and vertical policies and stretches. +*/ + +/*! + \enum QSizePolicy::ControlType + \since 4.3 + + This enum specifies the different types of widgets in terms of + layout interaction: + + \value DefaultType The default type, when none is specified. + \value ButtonBox A QDialogButtonBox instance. + \value CheckBox A QCheckBox instance. + \value ComboBox A QComboBox instance. + \value Frame A QFrame instance. + \value GroupBox A QGroupBox instance. + \value Label A QLabel instance. + \value Line A QFrame instance with QFrame::HLine or QFrame::VLine. + \value LineEdit A QLineEdit instance. + \value PushButton A QPushButton instance. + \value RadioButton A QRadioButton instance. + \value Slider A QAbstractSlider instance. + \value SpinBox A QAbstractSpinBox instance. + \value TabWidget A QTabWidget instance. + \value ToolButton A QToolButton instance. + + \sa setControlType(), controlType() +*/ + +#ifdef QT3_SUPPORT +/*! + \typedef QSizePolicy::SizeType + \compat + + Use the QSizePolicy::Policy enum instead. +*/ + +/*! + \enum QSizePolicy::ExpandData + \compat + + Use the Qt::Orientations enum instead. + + \value NoDirection Use 0 instead. + \value Horizontally Use Qt::Horizontal instead. + \value Vertically Use Qt::Vertical instead. + \value BothDirections Use Qt::Horizontal | Qt::Vertical instead. +*/ + +/*! + \fn bool QSizePolicy::mayShrinkHorizontally() const + + Use the horizontalPolicy() function combined with the + QSizePolicy::PolicyFlag enum instead. + + \oldcode + bool policy = mayShrinkHorizontally(); + \newcode + bool policy = horizontalPolicy() & QSizePolicy::ShrinkFlag; + \endcode +*/ + +/*! + \fn bool QSizePolicy::mayShrinkVertically() const + + Use the verticalPolicy() function combined with the + QSizePolicy::PolicyFlag enum instead. + + \oldcode + bool policy = mayShrinkVertically(); + \newcode + bool policy = verticalPolicy() & QSizePolicy::ShrinkFlag; + \endcode +*/ + +/*! + \fn bool QSizePolicy::mayGrowHorizontally() const + + Use the horizontalPolicy() function combined with the + QSizePolicy::PolicyFlag enum instead. + + \oldcode + bool policy = mayGrowHorizontally(); + \newcode + bool policy = horizontalPolicy() & QSizePolicy::GrowFlag; + \endcode +*/ + +/*! + \fn bool QSizePolicy::mayGrowVertically() const + + Use the verticalPolicy() function combined with the + QSizePolicy::PolicyFlag enum instead. + + \oldcode + bool policy = mayGrowVertically(); + \newcode + bool policy = verticalPolicy() & QSizePolicy::GrowFlag; + \endcode +*/ + +/*! + \fn Qt::QSizePolicy::Orientations QSizePolicy::expanding() const + + Use expandingDirections() instead. +*/ + +/*! + \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, bool dependent) + + Use the QSizePolicy() constructor and the setHeightForWidth() + function instead. + + \oldcode + QSizePolicy *policy = new QSizePolicy(horizontal, vertical, dependent); + \newcode + QSizePolicy *policy = new QSizePolicy(horizontal, vertical); + policy->setHeightForWidth(dependent); + \endcode +*/ + +/*! + \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, uchar horizontalStretch, + uchar verticalStretch, bool dependent) + + Use the QSizePolicy() constructor and call the + setHorizontalStretch(), setVerticalStretch(), and + setHeightForWidth() functions instead. + + \oldcode + QSizePolicy *policy = new QSizePolicy(horizontal, vertical, + horizontalStretch, verticalStretch, + dependent); + \newcode + QSizePolicy *policy = new QSizePolicy(horizontal, vertical); + policy->setHorizontalStretch(horizontalStretch); + policy->setVerticalStretch(verticalStretch); + policy->setHeightForWidth(dependent); + \endcode +*/ + +/*! + \fn QSizePolicy::Policy QSizePolicy::horData() const + + Use horizontalPolicy() instead. +*/ + +/*! + \fn QSizePolicy::Policy QSizePolicy::verData() const + + Use verticalPolicy() instead. +*/ + +/*! + \fn void QSizePolicy::setHorData(Policy policy) + + Use setHorizontalPolicy() instead. +*/ + +/*! + \fn void QSizePolicy::setVerData(Policy policy) + + Use setVerticalPolicy() instead. +*/ + +/*! + \fn uint QSizePolicy::horStretch() const + + Use horizontalStretch() instead. +*/ + +/*! + \fn uint QSizePolicy::verStretch() const + + Use verticalStretch() instead. +*/ + +/*! + \fn void QSizePolicy::setHorStretch(uchar stretch) + + Use setHorizontalStretch() instead. +*/ + +/*! + \fn void QSizePolicy::setVerStretch(uchar stretch) + + Use setVerticalStretch() instead. +*/ +#endif diff --git a/doc/src/classes/qtdesigner-api.qdoc b/doc/src/classes/qtdesigner-api.qdoc new file mode 100644 index 0000000..d7c47b1 --- /dev/null +++ b/doc/src/classes/qtdesigner-api.qdoc @@ -0,0 +1,1413 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QDesignerMemberSheetExtension + + \brief The QDesignerMemberSheetExtension class 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. + + \inmodule QtDesigner + + QDesignerMemberSheetExtension is a collection of functions that is + typically used to query a widget's member functions, and to + manipulate the member functions' appearance in \QD's signals and + slots editing mode. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 2 + + When implementing a custom widget plugin, a pointer to \QD's + current QDesignerFormEditorInterface object (\c formEditor in the + example above) is provided by the + QDesignerCustomWidgetInterface::initialize() function's parameter. + + The member sheet (and any other extension), can be retrieved by + querying \QD's extension manager using the qt_extension() + function. When you want to release the extension, you only need to + delete the pointer. + + All widgets have a default member sheet used in \QD's signals and + slots editing mode with the widget's member functions. But + QDesignerMemberSheetExtension also provides an interface for + creating custom member sheet extensions. + + \warning \QD uses the QDesignerMemberSheetExtension to facilitate + the signal and slot editing mode. Whenever a connection between + two widgets is requested, \QD will query for the widgets' member + sheet extensions. If a widget has an implemented member sheet + extension, this extension will override the default member sheet. + + To create a member sheet extension, your extension class must + inherit from both QObject and QDesignerMemberSheetExtension. Then, + since we are implementing an interface, we must ensure that it's + made known to the meta object system using the Q_INTERFACES() + macro: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 3 + + This enables \QD to use qobject_cast() to query for + supported interfaces using nothing but a QObject pointer. + + In \QD the extensions are not created until they are + required. For that reason, when implementing a member sheet + extension, you must also create a QExtensionFactory, i.e a class + that is able to make an instance of your extension, and register + it using \QD's \l {QExtensionManager}{extension manager}. + + When a widget's member sheet extension is required, \QD's \l + {QExtensionManager}{extension manager} will run through all its + registered factories calling QExtensionFactory::createExtension() + for each until the first one that is able to create a member sheet + extension for that widget, is found. This factory will then make + an instance of the extension. If no such factory is found, \QD + will use the default member sheet. + + There are four available types of extensions in \QD: + QDesignerContainerExtension, QDesignerMemberSheetExtension, + QDesignerPropertySheetExtension and + QDesignerTaskMenuExtension. \QD's behavior is the same whether the + requested extension is associated with a multi page container, a + member sheet, a property sheet or a task menu. + + The QExtensionFactory class provides a standard extension + factory, and can also be used as an interface for custom + extension factories. You can either create a new + QExtensionFactory and reimplement the + QExtensionFactory::createExtension() function. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 4 + + Or you can use an existing factory, expanding the + QExtensionFactory::createExtension() function to make the factory + able to create a member sheet extension as well. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 5 + + For a complete example using an extension class, see \l + {designer/taskmenuextension}{Task Menu Extension example}. The + example shows how to create a custom widget plugin for Qt + Designer, and how to to use the QDesignerTaskMenuExtension class + to add custom items to \QD's task menu. + + \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget + Extensions} +*/ + +/*! + \fn QDesignerMemberSheetExtension::~QDesignerMemberSheetExtension() + + Destroys the member sheet extension. +*/ + +/*! + \fn int QDesignerMemberSheetExtension::count() const + + Returns the extension's number of member functions. +*/ + +/*! + \fn int QDesignerMemberSheetExtension::indexOf(const QString &name) const + + Returns the index of the member function specified by the given \a + name. + + \sa memberName() +*/ + +/*! + \fn QString QDesignerMemberSheetExtension::memberName(int index) const + + Returns the name of the member function with the given \a index. + + \sa indexOf() +*/ + +/*! + \fn QString QDesignerMemberSheetExtension::memberGroup(int index) const + + Returns the name of the member group specified for the function + with the given \a index. + + \sa indexOf(), setMemberGroup() +*/ + +/*! + \fn void QDesignerMemberSheetExtension::setMemberGroup(int index, const QString &group) + + Sets the member group of the member function with the given \a + index, to \a group. + + \sa indexOf(), memberGroup() +*/ + +/*! + \fn bool QDesignerMemberSheetExtension::isVisible(int index) const + + Returns true if the member function with the given \a index is + visible in \QD's signal and slot editor, otherwise false. + + \sa indexOf(), setVisible() +*/ + +/*! + \fn void QDesignerMemberSheetExtension::setVisible(int index, bool visible) + + If \a visible is true, the member function with the given \a index + is visible in \QD's signals and slots editing mode; otherwise the + member function is hidden. + + \sa indexOf(), isVisible() +*/ + +/*! + \fn virtual bool QDesignerMemberSheetExtension::isSignal(int index) const + + Returns true if the member function with the given \a index is a + signal, otherwise false. + + \sa indexOf() +*/ + +/*! + \fn bool QDesignerMemberSheetExtension::isSlot(int index) const + + Returns true if the member function with the given \a index is a + slot, otherwise false. + + \sa indexOf() +*/ + +/*! + \fn bool QDesignerMemberSheetExtension::inheritedFromWidget(int index) const + + Returns true if the member function with the given \a index is + inherited from QWidget, otherwise false. + + \sa indexOf() +*/ + +/*! + \fn QString QDesignerMemberSheetExtension::declaredInClass(int index) const + + Returns the name of the class in which the member function with + the given \a index is declared. + + \sa indexOf() +*/ + +/*! + \fn QString QDesignerMemberSheetExtension::signature(int index) const + + Returns the signature of the member function with the given \a + index. + + \sa indexOf() +*/ + +/*! + \fn QList QDesignerMemberSheetExtension::parameterTypes(int index) const + + Returns the parameter types of the member function with the given + \a index, as a QByteArray list. + + \sa indexOf(), parameterNames() +*/ + +/*! + \fn QList QDesignerMemberSheetExtension::parameterNames(int index) const + + Returns the parameter names of the member function with the given + \a index, as a QByteArray list. + + \sa indexOf(), parameterTypes() +*/ + + +// Doc: Interface only + +/*! + \class QDesignerLayoutDecorationExtension + \brief The QDesignerLayoutDecorationExtension class provides an extension to a layout in \QD. + \inmodule QtDesigner + \internal +*/ + +/*! + \enum QDesignerLayoutDecorationExtension::InsertMode + + This enum describes the modes that are used to insert items into a layout. + + \value InsertWidgetMode Widgets are inserted into empty cells in a layout. + \value InsertRowMode Whole rows are inserted into a vertical or grid layout. + \value InsertColumnMode Whole columns are inserted into a horizontal or grid layout. +*/ + +/*! + \fn virtual QDesignerLayoutDecorationExtension::~QDesignerLayoutDecorationExtension() + + Destroys the extension. +*/ + +/*! + \fn virtual QList QDesignerLayoutDecorationExtension::widgets(QLayout *layout) const + + Returns the widgets that are managed by the given \a layout. + + \sa insertWidget(), removeWidget() +*/ + +/*! + \fn QRect QDesignerLayoutDecorationExtension::itemInfo(int index) const + + Returns the rectangle covered by the item at the given \a index in the layout. +*/ + +/*! + \fn int QDesignerLayoutDecorationExtension::indexOf(QWidget *widget) const + + Returns the index of the specified \a widget in the layout. +*/ + +/*! + \fn int QDesignerLayoutDecorationExtension::indexOf(QLayoutItem *item) const + + Returns the index of the specified layout \a item. +*/ + +/*! + \fn QDesignerLayoutDecorationExtension::InsertMode QDesignerLayoutDecorationExtension::currentInsertMode() const + + Returns the current insertion mode. +*/ + +/*! + \fn int QDesignerLayoutDecorationExtension::currentIndex() const + + Returns the current index in the layout. +*/ + +/*! + \fn QPair QDesignerLayoutDecorationExtension::currentCell() const + + Returns a pair containing the row and column of the current cell in the layout. +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::insertWidget(QWidget *widget, const QPair &cell) + + Inserts the given \a widget into the specified \a cell in the layout. + + \sa removeWidget() +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::removeWidget(QWidget *widget) + + Removes the specified \a widget from the layout. + + \sa insertWidget() +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::insertRow(int row) + + Inserts a new row into the form at the position specified by \a row. +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::insertColumn(int column) + + Inserts a new column into the form at the position specified by \a column. +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::simplify() + + Simplifies the layout by removing unnecessary empty rows and columns, and by changing the + number of rows or columns spanned by widgets. +*/ + +/*! + \fn int QDesignerLayoutDecorationExtension::findItemAt(const QPoint &position) const + + Returns the index of the item in the layout that covers the given \a position. +*/ + +/*! + \fn int QDesignerLayoutDecorationExtension::findItemAt(int row, int column) const + + Returns the item in the layout that occupies the specified \a row and \a column in the layout. + + Currently, this only applies to grid layouts. +*/ + +/*! + \fn void QDesignerLayoutDecorationExtension::adjustIndicator(const QPoint &position, int index) + + Adjusts the indicator for the item specified by \a index so that + it lies at the given \a position on the form. +*/ + + +// Doc: Interface only + +/*! + \class QDesignerContainerExtension + \brief The QDesignerContainerExtension class allows you to add pages to + a custom multi-page container in Qt Designer's workspace. + \inmodule QtDesigner + + QDesignerContainerExtension provide an interface for creating + custom container extensions. A container extension consists of a + collection of functions that \QD needs to manage a multi-page + container plugin, and a list of the container's pages. + + \image containerextension-example.png + + \warning This is \e not an extension for container plugins in + general, only custom \e multi-page containers. + + To create a container extension, your extension class must inherit + from both QObject and QDesignerContainerExtension. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 6 + + Since we are implementing an interface, we must ensure that it's + made known to the meta object system using the Q_INTERFACES() + macro. This enables \QD to use the qobject_cast() function to + query for supported interfaces using nothing but a QObject + pointer. + + You must reimplement several functions to enable \QD to manage a + custom multi-page container widget: \QD uses count() to keep track + of the number pages in your container, widget() to return the page + at a given index in the list of the container's pages, and + currentIndex() to return the list index of the selected page. \QD + uses the addWidget() function to add a given page to the + container, expecting it to be appended to the list of pages, while + it expects the insertWidget() function to add a given page to the + container by inserting it at a given index. + + In \QD the extensions are not created until they are + required. For that reason you must also create a + QExtensionFactory, i.e a class that is able to make an instance of + your extension, and register it using \QD's \l + {QExtensionManager}{extension manager}. + + When a container extension is required, \QD's \l + {QExtensionManager}{extension manager} will run through all its + registered factories calling QExtensionFactory::createExtension() + for each until the first one that is able to create a container + extension, is found. This factory will then create the extension + for the plugin. + + There are four available types of extensions in \QD: + QDesignerContainerExtension , QDesignerMemberSheetExtension, + QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. + \QD's behavior is the same whether the requested extension is + associated with a multi page container, a member sheet, a property + sheet or a task menu. + + The QExtensionFactory class provides a standard extension factory, + and can also be used as an interface for custom extension + factories. You can either create a new QExtensionFactory and + reimplement the QExtensionFactory::createExtension() function. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 7 + + Or you can use an existing factory, expanding the + QExtensionFactory::createExtension() function to make the factory + able to create a container extension as well. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 8 + + For a complete example using the QDesignerContainerExtension + class, see the \l {designer/containerextension}{Container + Extension example}. The example shows how to create a custom + multi-page plugin for \QD. + + \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget + Extensions} +*/ + +/*! + \fn QDesignerContainerExtension::~QDesignerContainerExtension() + + Destroys the extension. +*/ + +/*! + \fn int QDesignerContainerExtension::count() const + + Returns the number of pages in the container. +*/ + +/*! + \fn QWidget *QDesignerContainerExtension::widget(int index) const + + Returns the page at the given \a index in the extension's list of + pages. + + \sa addWidget(), insertWidget() +*/ + +/*! + \fn int QDesignerContainerExtension::currentIndex() const + + Returns the index of the currently selected page in the + container. + + \sa setCurrentIndex() +*/ + +/*! + \fn void QDesignerContainerExtension::setCurrentIndex(int index) + + Sets the currently selected page in the container to be the + page at the given \a index in the extension's list of pages. + + \sa currentIndex() +*/ + +/*! + \fn void QDesignerContainerExtension::addWidget(QWidget *page) + + Adds the given \a page to the container by appending it to the + extension's list of pages. + + \sa insertWidget(), remove(), widget() +*/ + +/*! + \fn void QDesignerContainerExtension::insertWidget(int index, QWidget *page) + + Adds the given \a page to the container by inserting it at the + given \a index in the extension's list of pages. + + \sa addWidget(), remove(), widget() +*/ + +/*! + \fn void QDesignerContainerExtension::remove(int index) + + Removes the page at the given \a index from the extension's list + of pages. + + \sa addWidget(), insertWidget() +*/ + + +// Doc: Interface only + +/*! + \class QDesignerTaskMenuExtension + \brief The QDesignerTaskMenuExtension class allows you to add custom + menu entries to Qt Designer's task menu. + \inmodule QtDesigner + + QDesignerTaskMenuExtension provides an interface for creating + custom task menu extensions. It is typically used to create task + menu entries that are specific to a plugin in \QD. + + \QD uses the QDesignerTaskMenuExtension to feed its task + menu. Whenever a task menu is requested, \QD will query + for the selected widget's task menu extension. + + \image taskmenuextension-example-faded.png + + A task menu extension is a collection of QActions. The actions + appear as entries in the task menu when the plugin with the + specified extension is selected. The image above shows the custom + \gui {Edit State...} action which appears in addition to \QD's + default task menu entries: \gui Cut, \gui Copy, \gui Paste etc. + + To create a custom task menu extension, your extension class must + inherit from both QObject and QDesignerTaskMenuExtension. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 9 + + Since we are implementing an interface, we must ensure that it + is made known to the meta-object system using the Q_INTERFACES() + macro. This enables \QD to use the qobject_cast() function to + query for supported interfaces using nothing but a QObject + pointer. + + You must reimplement the taskActions() function to return a list + of actions that will be included in \QD task menu. Optionally, you + can reimplement the preferredEditAction() function to set the + action that is invoked when selecting your plugin and pressing + \key F2. The preferred edit action must be one of the actions + returned by taskActions() and, if it's not defined, pressing the + \key F2 key will simply be ignored. + + In \QD, extensions are not created until they are required. A + task menu extension, for example, is created when you click the + right mouse button over a widget in \QD's workspace. For that + reason you must also construct an extension factory, using either + QExtensionFactory or a subclass, and register it using \QD's + \l {QExtensionManager}{extension manager}. + + When a task menu extension is required, \QD's \l + {QExtensionManager}{extension manager} will run through all its + registered factories calling QExtensionFactory::createExtension() + for each until it finds one that is able to create a task menu + extension for the selected widget. This factory will then make an + instance of the extension. + + There are four available types of extensions in \QD: + QDesignerContainerExtension, QDesignerMemberSheetExtension, + QDesignerPropertySheetExtension, and QDesignerTaskMenuExtension. + \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. + + The QExtensionFactory class provides a standard extension factory, + and can also be used as an interface for custom extension + factories. You can either create a new QExtensionFactory and + reimplement the QExtensionFactory::createExtension() function. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 10 + + Or you can use an existing factory, expanding the + QExtensionFactory::createExtension() function to make the factory + able to create a task menu extension as well. For example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 11 + + For a complete example using the QDesignerTaskMenuExtension class, + see the \l {designer/taskmenuextension}{Task Menu Extension + example}. The example shows how to create a custom widget plugin + for \QD, and how to to use the QDesignerTaskMenuExtension + class to add custom items to \QD's task menu. + + \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget + Extensions} +*/ + +/*! + \fn QDesignerTaskMenuExtension::~QDesignerTaskMenuExtension() + + Destroys the task menu extension. +*/ + +/*! + \fn QAction *QDesignerTaskMenuExtension::preferredEditAction() const + + Returns the action that is invoked when selecting a plugin with + the specified extension and pressing \key F2. + + The action must be one of the actions returned by taskActions(). +*/ + +/*! + \fn QList QDesignerTaskMenuExtension::taskActions() const + + Returns the task menu extension as a list of actions which will be + included in \QD's task menu when a plugin with the specified + extension is selected. + + The function must be reimplemented to add actions to the list. +*/ + + +// Doc: Interface only + +/*! + \class QDesignerCustomWidgetCollectionInterface + + \brief The QDesignerCustomWidgetCollectionInterface class allows + you to include several custom widgets in one single library. + + \inmodule QtDesigner + + When implementing a custom widget plugin, you build it as a + separate library. If you want to include several custom widget + plugins in the same library, you must in addition subclass + QDesignerCustomWidgetCollectionInterface. + + QDesignerCustomWidgetCollectionInterface contains one single + function returning a list of the collection's + QDesignerCustomWidgetInterface objects. For example, if you have + several custom widgets \c CustomWidgetOne, \c CustomWidgetTwo and + \c CustomWidgetThree, the class definition may look like this: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 12 + + In the class constructor you add the interfaces to your custom + widgets to the list which you return in the customWidgets() + function: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 13 + + Note that instead of exporting each custom widget plugin using the + Q_EXPORT_PLUGIN2() macro, you export the entire collection. The + Q_EXPORT_PLUGIN2() macro ensures that \QD can access and construct + the custom widgets. Without this macro, there is no way for \QD to + use them. + + \sa QDesignerCustomWidgetInterface, {Creating Custom Widgets for + Qt Designer} +*/ + +/*! + \fn QDesignerCustomWidgetCollectionInterface::~QDesignerCustomWidgetCollectionInterface() { + + Destroys the custom widget collection interface. +*/ + +/*! + \fn QList QDesignerCustomWidgetCollectionInterface::customWidgets() const + + Returns a list of interfaces to the collection's custom widgets. +*/ + + +// Doc: Interface only + +/*! + \class QDesignerCustomWidgetInterface + + \brief The QDesignerCustomWidgetInterface class enables Qt Designer + to access and construct custom widgets. + + \inmodule QtDesigner + + QDesignerCustomWidgetInterface provides a custom widget with an + interface. The class contains a set of functions that must be subclassed + to return basic information about the widget, such as its class name and + the name of its header file. Other functions must be implemented to + initialize the plugin when it is loaded, and to construct instances of + the custom widget for \QD to use. + + When implementing a custom widget you must subclass + QDesignerCustomWidgetInterface to expose your widget to \QD. For + example, this is the declaration for the plugin used in the + \l{Custom Widget Plugin Example}{Custom Widget Plugin example} that + enables an analog clock custom widget to be used by \QD: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.h 0 + + Note that the only part of the class definition that is specific + to this particular custom widget is the class name. In addition, + since we are implementing an interface, we must ensure that it's + made known to the meta object system using the Q_INTERFACES() + macro. This enables \QD to use the qobject_cast() function to + query for supported interfaces using nothing but a QObject + pointer. + + After \QD loads a custom widget plugin, it calls the interface's + initialize() function to enable it to set up any resources that it + may need. This function is called with a QDesignerFormEditorInterface + parameter that provides the plugin with a gateway to all of \QD's API. + + \QD constructs instances of the custom widget by calling the plugin's + createWidget() function with a suitable parent widget. Plugins must + construct and return an instance of a custom widget with the specified + parent widget. + + In the implementation of the class you must remember to export + your custom widget plugin to \QD using the Q_EXPORT_PLUGIN2() + macro. For example, if a library called \c libcustomwidgetplugin.so + (on Unix) or \c libcustomwidget.dll (on Windows) contains a widget + class called \c MyCustomWidget, we can export it by adding the + following line to the file containing the plugin implementation: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 14 + + This macro ensures that \QD can access and construct the custom widget. + Without this macro, there is no way for \QD to use it. + + When implementing a custom widget plugin, you build it as a + separate library. If you want to include several custom widget + plugins in the same library, you must in addition subclass + QDesignerCustomWidgetCollectionInterface. + + \warning If your custom widget plugin contains QVariant + properties, be aware that only the following \l + {QVariant::Type}{types} are supported: + + \list + \o QVariant::ByteArray + \o QVariant::Bool + \o QVariant::Color + \o QVariant::Cursor + \o QVariant::Date + \o QVariant::DateTime + \o QVariant::Double + \o QVariant::Int + \o QVariant::Point + \o QVariant::Rect + \o QVariant::Size + \o QVariant::SizePolicy + \o QVariant::String + \o QVariant::Time + \o QVariant::UInt + \endlist + + For a complete example using the QDesignerCustomWidgetInterface + class, see the \l {designer/customwidgetplugin}{Custom Widget + Example}. The example shows how to create a custom widget plugin + for \QD. + + \sa QDesignerCustomWidgetCollectionInterface {Creating Custom + Widgets for Qt Designer} +*/ + +/*! + \fn QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface() + + Destroys the custom widget interface. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::name() const + + Returns the class name of the custom widget supplied by the interface. + + The name returned \e must be identical to the class name used for the + custom widget. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::group() const + + Returns the name of the group to which the custom widget belongs. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::toolTip() const + + Returns a short description of the widget that can be used by \QD + in a tool tip. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::whatsThis() const + + Returns a description of the widget that can be used by \QD in + "What's This?" help for the widget. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::includeFile() const + + Returns the path to the include file that \l uic uses when + creating code for the custom widget. +*/ + +/*! + \fn QIcon QDesignerCustomWidgetInterface::icon() const + + Returns the icon used to represent the custom widget in \QD's + widget box. +*/ + +/*! + \fn bool QDesignerCustomWidgetInterface::isContainer() const + + Returns true if the custom widget is intended to be used as a + container; otherwise returns false. + + Most custom widgets are not used to hold other widgets, so their + implementations of this function will return false, but custom + containers will return true to ensure that they behave correctly + in \QD. +*/ + +/*! + \fn QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent) + + Returns a new instance of the custom widget, with the given \a + parent. +*/ + +/*! + \fn bool QDesignerCustomWidgetInterface::isInitialized() const + + Returns true if the widget has been initialized; otherwise returns + false. + + \sa initialize() +*/ + +/*! + \fn void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor) + + Initializes the widget for use with the specified \a formEditor + interface. + + \sa isInitialized() +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::domXml() const + + Returns the XML that is used to describe the custom widget's + properties to \QD. +*/ + +/*! + \fn QString QDesignerCustomWidgetInterface::codeTemplate() const + + This function is reserved for future use by \QD. + + \omit + Returns the code template that \QD includes in forms that contain + the custom widget when they are saved. + \endomit +*/ + +/*! + \macro QDESIGNER_WIDGET_EXPORT + \relates QDesignerCustomWidgetInterface + \since 4.1 + + This macro is used when defining custom widgets to ensure that they are + correctly exported from plugins for use with \QD. + + On some platforms, the symbols required by \QD to create new widgets + are removed from plugins by the build system, making them unusable. + Using this macro ensures that the symbols are retained on those platforms, + and has no side effects on other platforms. + + For example, the \l{designer/worldtimeclockplugin}{World Time Clock Plugin} + example exports a custom widget class with the following declaration: + + \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 0 + \dots + \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 2 + + \sa {Creating Custom Widgets for Qt Designer} +*/ + + +// Doc: Abstract class + +/*! + \class QDesignerDnDItemInterface + \brief The QDesignerDnDItemInterface class provides an interface that is used to manage items + during a drag and drop operation. + \inmodule QtDesigner + \internal +*/ + +/*! + \enum QDesignerDnDItemInterface::DropType + + This enum describes the result of a drag and drop operation. + + \value MoveDrop The item was moved. + \value CopyDrop The item was copied. +*/ + +/*! + \fn QDesignerDnDItemInterface::QDesignerDnDItemInterface() + + Constructs a new interface to a drag and drop item. +*/ + +/*! + \fn QDesignerDnDItemInterface::~QDesignerDnDItemInterface() + + Destroys the interface to the item. +*/ + +/*! + \fn DomUI *QDesignerDnDItemInterface::domUi() const + + Returns a user interface object for the item. +*/ + +/*! + \fn QWidget *QDesignerDnDItemInterface::widget() const + + Returns the widget being copied or moved in the drag and drop operation. + + \sa source() +*/ + +/*! + \fn QWidget *QDesignerDnDItemInterface::decoration() const + + Returns the widget used to represent the item. +*/ + +/*! + \fn QPoint QDesignerDnDItemInterface::hotSpot() const + + Returns the cursor's hotspot. + + \sa QDrag::hotSpot() +*/ + +/*! + \fn DropType QDesignerDnDItemInterface::type() const + + Returns the type of drag and drop operation in progress. +*/ + +/*! + \fn QWidget *QDesignerDnDItemInterface::source() const + + Returns the widget that is the source of the drag and drop operation; i.e. the original + container of the widget being dragged. + + \sa widget() +*/ + + +// Doc: Abstract class + +/*! + \class QDesignerIconCacheInterface + \brief The QDesignerIconCacheInterface class provides an interface to \QD's icon cache. + \inmodule QtDesigner + \internal +*/ + +/*! + \fn QDesignerIconCacheInterface::QDesignerIconCacheInterface(QObject *parent) + + Constructs a new interface with the given \a parent. +*/ + +/*! + \fn QIcon QDesignerIconCacheInterface::nameToIcon(const QString &filePath, const QString &qrcPath) + + Returns the icon associated with the name specified by \a filePath in the resource + file specified by \a qrcPath. + + If \a qrcPath refers to a valid resource file, the name used for the file path is a path + within those resources; otherwise the file path refers to a local file. + + \sa {The Qt Resource System}, nameToPixmap() +*/ + +/*! + \fn QPixmap QDesignerIconCacheInterface::nameToPixmap(const QString &filePath, const QString &qrcPath) + + Returns the pixmap associated with the name specified by \a filePath in the resource + file specified by \a qrcPath. + + If \a qrcPath refers to a valid resource file, the name used for the file path is a path + within those resources; otherwise the file path refers to a local file. + + \sa {The Qt Resource System}, nameToIcon() +*/ + +/*! + \fn QString QDesignerIconCacheInterface::iconToFilePath(const QIcon &icon) const + + Returns the file path associated with the given \a icon. The file path is a path within + an application resources. +*/ + +/*! + \fn QString QDesignerIconCacheInterface::iconToQrcPath(const QIcon &icon) const + + Returns the path to the resource file that refers to the specified \a icon. The resource + path refers to a local file. +*/ + +/*! + \fn QString QDesignerIconCacheInterface::pixmapToFilePath(const QPixmap &pixmap) const + + Returns the file path associated with the given \a pixmap. The file path is a path within + an application resources. +*/ + +/*! + \fn QString QDesignerIconCacheInterface::pixmapToQrcPath(const QPixmap &pixmap) const + + Returns the path to the resource file that refers to the specified \a pixmap. The resource + path refers to a local file. +*/ + +/*! + \fn QList QDesignerIconCacheInterface::pixmapList() const + + Returns a list of pixmaps for the icons provided by the icon cache. +*/ + +/*! + \fn QList QDesignerIconCacheInterface::iconList() const + + Returns a list of icons provided by the icon cache. +*/ + +/*! + \fn QString QDesignerIconCacheInterface::resolveQrcPath(const QString &filePath, const QString &qrcPath, const QString &workingDirectory) const + + Returns a path to a resource specified by the \a filePath within + the resource file located at \a qrcPath. If \a workingDirectory is + a valid path to a directory, the path returned will be relative to + that directory; otherwise an absolute path is returned. + + \omit + ### Needs checking + \endomit +*/ + + +// Doc: Interface only + +/*! + \class QDesignerPropertySheetExtension + + \brief The QDesignerPropertySheetExtension class allows you to + manipulate a widget's properties which is displayed in Qt + Designer's property editor. + + \sa QDesignerDynamicPropertySheetExtension + + \inmodule QtDesigner + + QDesignerPropertySheetExtension provides a collection of functions that + are typically used to query a widget's properties, and to + manipulate the properties' appearance in the property editor. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 15 + + Note that if you change the value of a property using the + QDesignerPropertySheetExtension::setProperty() function, the undo + stack is not updated. To ensure that a property's value can be + reverted using the undo stack, you must use the + QDesignerFormWindowCursorInterface::setProperty() function, or its + buddy \l + {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, + instead. + + When implementing a custom widget plugin, a pointer to \QD's + current QDesignerFormEditorInterface object (\c formEditor in the + example above) is provided by the + QDesignerCustomWidgetInterface::initialize() function's parameter. + + The property sheet, or any other extension, can be retrieved by + querying \QD's extension manager using the qt_extension() + function. When you want to release the extension, you only need to + delete the pointer. + + All widgets have a default property sheet which populates \QD's + property editor with the widget's properties (i.e the ones defined + with the Q_PROPERTY() macro). But QDesignerPropertySheetExtension + also provides an interface for creating custom property sheet + extensions. + + \warning \QD uses the QDesignerPropertySheetExtension to feed its + property editor. Whenever a widget is selected in its workspace, + \QD will query for the widget's property sheet extension. If the + selected widget has an implemented property sheet extension, this + extension will override the default property sheet. + + To create a property sheet extension, your extension class must + inherit from both QObject and + QDesignerPropertySheetExtension. Then, since we are implementing + an interface, we must ensure that it's made known to the meta + object system using the Q_INTERFACES() macro: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 16 + + This enables \QD to use qobject_cast() to query for supported + interfaces using nothing but a QObject pointer. + + In \QD the extensions are not created until they are + required. For that reason, when implementing a property sheet + extension, you must also create a QExtensionFactory, i.e a class + that is able to make an instance of your extension, and register + it using \QD's \l {QExtensionManager}{extension manager}. + + When a property sheet extension is required, \QD's \l + {QExtensionManager}{extension manager} will run through all its + registered factories calling QExtensionFactory::createExtension() + for each until the first one that is able to create a property + sheet extension for the selected widget, is found. This factory + will then make an instance of the extension. If no such factory + can be found, \QD will use the default property sheet. + + There are four available types of extensions in \QD: + QDesignerContainerExtension, QDesignerMemberSheetExtension, + QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. Qt + Designer's behavior is the same whether the requested extension is + associated with a multi page container, a member sheet, a property + sheet or a task menu. + + The QExtensionFactory class provides a standard extension factory, + and can also be used as an interface for custom extension + factories. You can either create a new QExtensionFactory and + reimplement the QExtensionFactory::createExtension() function. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 17 + + Or you can use an existing factory, expanding the + QExtensionFactory::createExtension() function to make the factory + able to create a property sheet extension extension as well. For + example: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 18 + + For a complete example using an extension class, see the \l + {designer/taskmenuextension}{Task Menu Extension example}. The + example shows how to create a custom widget plugin for Qt + Designer, and how to to use the QDesignerTaskMenuExtension class + to add custom items to \QD's task menu. + + \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget + Extensions} +*/ + +/*! + \fn QDesignerPropertySheetExtension::~QDesignerPropertySheetExtension() + + Destroys the property sheet extension. +*/ + +/*! + \fn int QDesignerPropertySheetExtension::count() const + + Returns the selected widget's number of properties. +*/ + +/*! + \fn int QDesignerPropertySheetExtension::indexOf(const QString &name) const + + Returns the index for a given property \a name. + + \sa propertyName() +*/ + +/*! + \fn QString QDesignerPropertySheetExtension::propertyName(int index) const + + Returns the name of the property at the given \a index. + + \sa indexOf() +*/ + +/*! + \fn QString QDesignerPropertySheetExtension::propertyGroup(int index) const + + Returns the property group for the property at the given \a index. + + \QD's property editor supports property groups, i.e. sections of + related properties. A property can be related to a group using the + setPropertyGroup() function. The default group of any property is + the name of the class that defines it. For example, the + QObject::objectName property appears within the QObject property + group. + + \sa indexOf(), setPropertyGroup() +*/ + +/*! + \fn void QDesignerPropertySheetExtension::setPropertyGroup(int index, const QString &group) + + Sets the property group for the property at the given \a index to + \a group. + + Relating a property to a group makes it appear within that group's + section in the property editor. The default property group of any + property is the name of the class that defines it. For example, + the QObject::objectName property appears within the QObject + property group. + + \sa indexOf(), property(), propertyGroup() +*/ + +/*! + \fn bool QDesignerPropertySheetExtension::hasReset(int index) const + + Returns true if the property at the given \a index has a reset + button in \QD's property editor, otherwise false. + + \sa indexOf(), reset() +*/ + +/*! + \fn bool QDesignerPropertySheetExtension::reset(int index) + + Resets the value of the property at the given \a index, to the + default value. Returns true if a default value could be found, otherwise false. + + \sa indexOf(), hasReset(), isChanged() +*/ + +/*! + \fn bool QDesignerPropertySheetExtension::isVisible(int index) const + + Returns true if the property at the given \a index is visible in + \QD's property editor, otherwise false. + + \sa indexOf(), setVisible() +*/ + +/*! + \fn void QDesignerPropertySheetExtension::setVisible(int index, bool visible) + + If \a visible is true, the property at the given \a index is + visible in \QD's property editor; otherwise the property is + hidden. + + \sa indexOf(), isVisible() +*/ + +/*! + \fn bool QDesignerPropertySheetExtension::isAttribute(int index) const + + Returns true if the property at the given \a index is an attribute, + which will be \e excluded from the UI file, otherwise false. + + \sa indexOf(), setAttribute() +*/ + +/*! + \fn void QDesignerPropertySheetExtension::setAttribute(int index, bool attribute) + + If \a attribute is true, the property at the given \a index is + made an attribute which will be \e excluded from the UI file; + otherwise it will be included. + + \sa indexOf(), isAttribute() +*/ + +/*! + \fn QVariant QDesignerPropertySheetExtension::property(int index) const + + Returns the value of the property at the given \a index. + + \sa indexOf(), setProperty(), propertyGroup() +*/ + +/*! + \fn void QDesignerPropertySheetExtension::setProperty(int index, const QVariant &value) + + Sets the \a value of the property at the given \a index. + + \warning If you change the value of a property using this + function, the undo stack is not updated. To ensure that a + property's value can be reverted using the undo stack, you must + use the QDesignerFormWindowCursorInterface::setProperty() + function, or its buddy \l + {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, + instead. + + \sa indexOf(), property(), propertyGroup() +*/ + +/*! + \fn bool QDesignerPropertySheetExtension::isChanged(int index) const + + Returns true if the value of the property at the given \a index + differs from the property's default value, otherwise false. + + \sa indexOf(), setChanged(), reset() +*/ + +/*! + \fn void QDesignerPropertySheetExtension::setChanged(int index, bool changed) + + Sets whether the property at the given \a index is different from + its default value, or not, depending on the \a changed parameter. + + \sa indexOf(), isChanged() +*/ + +// Doc: Interface only + +/*! + \class QDesignerDynamicPropertySheetExtension + + \brief The QDesignerDynamicPropertySheetExtension class allows you to + manipulate a widget's dynamic properties in Qt Designer's property editor. + + \sa QDesignerPropertySheetExtension, {QObject#Dynamic Properties}{Dynamic Properties} + + \inmodule QtDesigner + \since 4.3 +*/ + +/*! + \fn QDesignerDynamicPropertySheetExtension::~QDesignerDynamicPropertySheetExtension() + + Destroys the dynamic property sheet extension. +*/ + +/*! + \fn bool QDesignerDynamicPropertySheetExtension::dynamicPropertiesAllowed() const + + Returns true if the widget supports dynamic properties; otherwise returns false. +*/ + +/*! + \fn int QDesignerDynamicPropertySheetExtension::addDynamicProperty(const QString &propertyName, const QVariant &value) + + Adds a dynamic property named \a propertyName and sets its value to \a value. + Returns the index of the property if it was added successfully; otherwise returns -1 to + indicate failure. +*/ + +/*! + \fn bool QDesignerDynamicPropertySheetExtension::removeDynamicProperty(int index) + + Removes the dynamic property at the given \a index. + Returns true if the operation succeeds; otherwise returns false. +*/ + +/*! + \fn bool QDesignerDynamicPropertySheetExtension::isDynamicProperty(int index) const + + Returns true if the property at the given \a index is a dynamic property; otherwise + returns false. +*/ + +/*! + \fn bool QDesignerDynamicPropertySheetExtension::canAddDynamicProperty(const QString &propertyName) const + + Returns true if \a propertyName is a valid, unique name for a dynamic + property; otherwise returns false. + +*/ diff --git a/doc/src/classes/qtendian.qdoc b/doc/src/classes/qtendian.qdoc new file mode 100644 index 0000000..dcffb5d --- /dev/null +++ b/doc/src/classes/qtendian.qdoc @@ -0,0 +1,168 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \headerfile + \title Endian Conversion Functions + \ingroup architecture + \brief The header provides functions to convert between + little and big endian representations of numbers. +*/ + +/*! + \fn T qFromBigEndian(const uchar *src) + \since 4.3 + \relates + + Reads a big-endian number from memory location \a src and returns the number in the + host byte order representation. + On CPU architectures where the host byte order is little-endian (such as x86) this + will swap the byte order; otherwise it will just read from \a src. + + \note Template type \c{T} can either be a qint16, qint32 or qint64. Other types of + integers, e.g., qlong, are not applicable. + + There are no data alignment constraints for \a src. + + \sa qFromLittleEndian() + \sa qToBigEndian() + \sa qToLittleEndian() +*/ +/*! + \fn T qFromBigEndian(T src) + \since 4.3 + \relates + \overload + + Converts \a src from big-endian byte order and returns the number in host byte order + representation of that number. + On CPU architectures where the host byte order is little-endian (such as x86) this + will return \a src with the byte order swapped; otherwise it will return \a src + unmodified. +*/ +/*! + \fn T qFromLittleEndian(const uchar *src) + \since 4.3 + \relates + + Reads a little-endian number from memory location \a src and returns the number in + the host byte order representation. + On CPU architectures where the host byte order is big-endian (such as PowerPC) this + will swap the byte order; otherwise it will just read from \a src. + + \note Template type \c{T} can either be a qint16, qint32 or qint64. Other types of + integers, e.g., qlong, are not applicable. + + There are no data alignment constraints for \a src. + + \sa qFromBigEndian() + \sa qToBigEndian() + \sa qToLittleEndian() +*/ +/*! + \fn T qFromLittleEndian(T src) + \since 4.3 + \relates + \overload + + Converts \a src from little-endian byte order and returns the number in host byte + order representation of that number. + On CPU architectures where the host byte order is big-endian (such as PowerPC) this + will return \a src with the byte order swapped; otherwise it will return \a src + unmodified. +*/ +/*! + \fn void qToBigEndian(T src, uchar *dest) + \since 4.3 + \relates + + Writes the number \a src with template type \c{T} to the memory location at \a dest + in big-endian byte order. + + Note that template type \c{T} can only be an integer data type (signed or unsigned). + + There are no data alignment constraints for \a dest. + + \sa qFromBigEndian() + \sa qFromLittleEndian() + \sa qToLittleEndian() +*/ +/*! + \fn T qToBigEndian(T src) + \since 4.3 + \relates + \overload + + Converts \a src from host byte order and returns the number in big-endian byte order + representation of that number. + On CPU architectures where the host byte order is little-endian (such as x86) this + will return \a src with the byte order swapped; otherwise it will return \a src + unmodified. +*/ +/*! + \fn void qToLittleEndian(T src, uchar *dest) + \since 4.3 + \relates + + Writes the number \a src with template type \c{T} to the memory location at \a dest + in little-endian byte order. + + Note that template type \c{T} can only be an integer data type (signed or unsigned). + + There are no data alignment constraints for \a dest. + + \sa qFromBigEndian() + \sa qFromLittleEndian() + \sa qToBigEndian() +*/ +/*! + \fn T qToLittleEndian(T src) + \since 4.3 + \relates + \overload + + Converts \a src from host byte order and returns the number in little-endian byte + order representation of that number. + On CPU architectures where the host byte order is big-endian (such as PowerPC) this + will return \a src with the byte order swapped; otherwise it will return \a src + unmodified. +*/ + diff --git a/doc/src/classes/qtestevent.qdoc b/doc/src/classes/qtestevent.qdoc new file mode 100644 index 0000000..2e111b3 --- /dev/null +++ b/doc/src/classes/qtestevent.qdoc @@ -0,0 +1,191 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QTestEventList + \inmodule QtTest + + \brief The QTestEventList class provides a list of GUI events. + + QTestEventList inherits from QList, and provides + convenience functions for populating the list. + + A QTestEventList can be populated with GUI events that can be + stored as test data for later usage, or be replayed on any + QWidget. + + Example: + \snippet doc/src/snippets/code/doc_src_qtestevent.qdoc 0 + + The example above simulates the user entering the character \c a + followed by a backspace, waiting for 200 milliseconds and + repeating it. +*/ + +/*! \fn QTestEventList::QTestEventList() + + Constructs an empty QTestEventList. +*/ + +/*! \fn QTestEventList::QTestEventList(const QTestEventList &other) + + Constructs a new QTestEventList as a copy of \a other. +*/ + +/*! \fn QTestEventList::~QTestEventList() + + Empties the list and destroys all stored events. +*/ + +/*! \fn void QTestEventList::clear() + + Removes all events from the list. +*/ + +/*! \fn void QTestEventList::addKeyClick(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + Adds a new key click to the list. The event will simulate the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyClick() +*/ + +/*! \fn void QTestEventList::addKeyPress(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + Adds a new key press to the list. The event will press the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyPress() +*/ + +/*! \fn void QTestEventList::addKeyRelease(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + Adds a new key release to the list. The event will release the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyRelease() + +*/ + +/*! \fn void QTestEventList::addKeyEvent(QTest::KeyAction action, Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + \internal +*/ + +/*! \fn void QTestEventList::addKeyClick(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + \overload + + Adds a new key click to the list. The event will simulate the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyClick() + +*/ + +/*! \fn void QTestEventList::addKeyPress(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + \overload + + Adds a new key press to the list. The event will press the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyPress() +*/ + +/*! \fn void QTestEventList::addKeyRelease(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + \overload + + Adds a new key release to the list. The event will release the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. + + \sa QTest::keyRelease() +*/ + +/*! \fn void QTestEventList::addKeyClicks(const QString &keys, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + + Adds new keyboard entries to the list. The event will press the \a keys with the \a modifiers and wait \a msecs milliseconds between each key. + + \sa QTest::keyClicks() +*/ + +/*! \fn void QTestEventList::addKeyEvent(QTest::KeyAction action, char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) + \internal +*/ + +/*! \fn void QTestEventList::addDelay(int msecs) + + Adds a \a msecs milliseconds delay. + + \sa QTest::qWait() +*/ + +/*! \fn void QTestEventList::simulate(QWidget *w) + + Simulates the events from the list one by one on the widget \a w. + For an example, please read the \l QTestEventList class documentation. +*/ + +/*! \fn void QTestEventList::addMousePress(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) + + Add a mouse press to the list. The event will press the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. + + \sa QTest::mousePress() +*/ +/*! \fn void QTestEventList::addMouseRelease(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) + + Add a mouse release to the list. The event will release the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. + + \sa QTest::mouseRelease() +*/ +/*! \fn void QTestEventList::addMouseClick(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) + + Add a mouse click to the list. The event will click the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. + + \sa QTest::mouseClick() +*/ +/*! \fn void QTestEventList::addMouseDClick(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) + + Add a double mouse click to the list. The event will double click the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. + + \sa QTest::mousePress() +*/ +/*! \fn void QTestEventList::addMouseMove(QPoint pos = QPoint(), int delay=-1) + + Adds a mouse move to the list. The event will move the mouse to the position \a pos. If a \a delay (in milliseconds) is set, the test will wait after moving the mouse. The default position is the center of the widget. + + \sa QTest::mousePress() +*/ + diff --git a/doc/src/classes/qvarlengtharray.qdoc b/doc/src/classes/qvarlengtharray.qdoc new file mode 100644 index 0000000..ac6bb6e --- /dev/null +++ b/doc/src/classes/qvarlengtharray.qdoc @@ -0,0 +1,274 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QVarLengthArray + \brief The QVarLengthArray class provides a low-level variable-length array. + + \ingroup tools + \reentrant + + The C++ language doesn't support variable-length arrays on the stack. + For example, the following code won't compile: + + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 0 + + The alternative is to allocate the array on the heap (with + \c{new}): + + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 1 + + However, if myfunc() is called very frequently from the + application's inner loop, heap allocation can be a major source + of slowdown. + + QVarLengthArray is an attempt to work around this gap in the C++ + language. It allocates a certain number of elements on the stack, + and if you resize the array to a larger size, it automatically + uses the heap instead. Stack allocation has the advantage that + it is much faster than heap allocation. + + Example: + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 2 + + In the example above, QVarLengthArray will preallocate 1024 + elements on the stack and use them unless \c{n + 1} is greater + than 1024. If you omit the second template argument, + QVarLengthArray's default of 256 is used. + + QVarLengthArray's value type must be an \l{assignable data type}. + This covers most data types that are commonly used, but the + compiler won't let you, for example, store a QWidget as a value; + instead, store a QWidget *. + + QVarLengthArray, like QVector, provides a resizable array data + structure. The main differences between the two classes are: + + \list + \o QVarLengthArray's API is much more low-level. It provides no + iterators and lacks much of QVector's functionality. + + \o QVarLengthArray doesn't initialize the memory if the value is + a basic type. (QVector always does.) + + \o QVector uses \l{implicit sharing} as a memory optimization. + QVarLengthArray doesn't provide that feature; however, it + usually produces slightly better performance due to reduced + overhead, especially in tight loops. + \endlist + + In summary, QVarLengthArray is a low-level optimization class + that only makes sense in very specific cases. It is used a few + places inside Qt and was added to Qt's public API for the + convenience of advanced users. + + \sa QVector, QList, QLinkedList +*/ + +/*! \fn QVarLengthArray::QVarLengthArray(int size) + + Constructs an array with an initial size of \a size elements. + + If the value type is a primitive type (e.g., char, int, float) or + a pointer type (e.g., QWidget *), the elements are not + initialized. For other types, the elements are initialized with a + \l{default-constructed value}. +*/ + +/*! \fn QVarLengthArray::~QVarLengthArray() + + Destroys the array. +*/ + +/*! \fn int QVarLengthArray::size() const + + Returns the number of elements in the array. + + \sa isEmpty(), resize() +*/ + +/*! \fn int QVarLengthArray::count() const + + Same as size(). + + \sa isEmpty(), resize() +*/ + +/*! \fn bool QVarLengthArray::isEmpty() const + + Returns true if the array has size 0; otherwise returns false. + + \sa size(), resize() +*/ + +/*! \fn void QVarLengthArray::clear() + + Removes all the elements from the array. + + Same as resize(0). +*/ + +/*! \fn void QVarLengthArray::resize(int size) + + Sets the size of the array to \a size. If \a size is greater than + the current size, elements are added to the end. If \a size is + less than the current size, elements are removed from the end. + + If the value type is a primitive type (e.g., char, int, float) or + a pointer type (e.g., QWidget *), new elements are not + initialized. For other types, the elements are initialized with a + \l{default-constructed value}. + + \sa size() +*/ + +/*! \fn int QVarLengthArray::capacity() const + + Returns the maximum number of elements that can be stored in the + array without forcing a reallocation. + + The sole purpose of this function is to provide a means of fine + tuning QVarLengthArray's memory usage. In general, you will rarely ever + need to call this function. If you want to know how many items are + in the array, call size(). + + \sa reserve() +*/ + +/*! \fn void QVarLengthArray::reserve(int size) + + Attempts to allocate memory for at least \a size elements. If you + know in advance how large the array can get, you can call this + function and if you call resize() often, you are likely to get + better performance. If \a size is an underestimate, the worst + that will happen is that the QVarLengthArray will be a bit + slower. + + The sole purpose of this function is to provide a means of fine + tuning QVarLengthArray's memory usage. In general, you will + rarely ever need to call this function. If you want to change the + size of the array, call resize(). + + \sa capacity() +*/ + +/*! \fn T &QVarLengthArray::operator[](int i) + + Returns a reference to the item at index position \a i. + + \a i must be a valid index position in the array (i.e., 0 <= \a i + < size()). + + \sa data() +*/ + +/*! \fn const T &QVarLengthArray::operator[](int i) const + + \overload +*/ + + +/*! + \fn void QVarLengthArray::append(const T &t) + + Appends item \a t to the array, extending the array if necessary. + + \sa removeLast() +*/ + + +/*! + \fn inline void QVarLengthArray::removeLast() + \since 4.5 + + Decreases the size of the array by one. The allocated size is not changed. + + \sa append() +*/ + +/*! + \fn void QVarLengthArray::append(const T *buf, int size) + + Appends \a size amount of items referenced by \a buf to this array. +*/ + + +/*! \fn T *QVarLengthArray::data() + + Returns a pointer to the data stored in the array. The pointer can + be used to access and modify the items in the array. + + Example: + \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 3 + + The pointer remains valid as long as the array isn't reallocated. + + This function is mostly useful to pass an array to a function + that accepts a plain C++ array. + + \sa constData(), operator[]() +*/ + +/*! \fn const T *QVarLengthArray::data() const + + \overload +*/ + +/*! \fn const T *QVarLengthArray::constData() const + + Returns a const pointer to the data stored in the array. The + pointer can be used to access the items in the array. The + pointer remains valid as long as the array isn't reallocated. + + This function is mostly useful to pass an array to a function + that accepts a plain C++ array. + + \sa data(), operator[]() +*/ + +/*! \fn QVarLengthArray &QVarLengthArray::operator=(const QVarLengthArray &other) + Assigns \a other to this array and returns a reference to this array. + */ + +/*! \fn QVarLengthArray::QVarLengthArray(const QVarLengthArray &other) + Constructs a copy of \a other. + */ + diff --git a/doc/src/classes/qwaitcondition.qdoc b/doc/src/classes/qwaitcondition.qdoc new file mode 100644 index 0000000..ae94e35 --- /dev/null +++ b/doc/src/classes/qwaitcondition.qdoc @@ -0,0 +1,188 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QWaitCondition + \brief The QWaitCondition class provides a condition variable for + synchronizing threads. + + \threadsafe + + \ingroup thread + \ingroup environment + + QWaitCondition allows a thread to tell other threads that some + sort of condition has been met. One or many threads can block + waiting for a QWaitCondition to set a condition with wakeOne() or + wakeAll(). Use wakeOne() to wake one randomly selected condition or + wakeAll() to wake them all. + + For example, let's suppose that we have three tasks that should + be performed whenever the user presses a key. Each task could be + split into a thread, each of which would have a + \l{QThread::run()}{run()} body like this: + + \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 0 + + Here, the \c keyPressed variable is a global variable of type + QWaitCondition. + + A fourth thread would read key presses and wake the other three + threads up every time it receives one, like this: + + \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 1 + + The order in which the three threads are woken up is undefined. + Also, if some of the threads are still in \c do_something() when + the key is pressed, they won't be woken up (since they're not + waiting on the condition variable) and so the task will not be + performed for that key press. This issue can be solved using a + counter and a QMutex to guard it. For example, here's the new + code for the worker threads: + + \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 2 + + Here's the code for the fourth thread: + + \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 3 + + The mutex is necessary because the results of two threads + attempting to change the value of the same variable + simultaneously are unpredictable. + + Wait conditions are a powerful thread synchronization primitive. + The \l{threads/waitconditions}{Wait Conditions} example shows how + to use QWaitCondition as an alternative to QSemaphore for + controlling access to a circular buffer shared by a producer + thread and a consumer thread. + + \sa QMutex, QSemaphore, QThread, {Wait Conditions Example} +*/ + +/*! + \fn QWaitCondition::QWaitCondition() + + Constructs a new wait condition object. +*/ + +/*! + \fn QWaitCondition::~QWaitCondition() + + Destroys the wait condition object. +*/ + +/*! + \fn void QWaitCondition::wakeOne() + + Wakes one thread waiting on the wait condition. The thread that + is woken up depends on the operating system's scheduling + policies, and cannot be controlled or predicted. + + If you want to wake up a specific thread, the solution is + typically to use different wait conditions and have different + threads wait on different conditions. + + \sa wakeAll() +*/ + +/*! + \fn void QWaitCondition::wakeAll() + + Wakes all threads waiting on the wait condition. The order in + which the threads are woken up depends on the operating system's + scheduling policies and cannot be controlled or predicted. + + \sa wakeOne() +*/ + +/*! + \fn bool QWaitCondition::wait(QMutex *mutex, unsigned long time) + + Releases the locked \a mutex and waits on the wait condition. The + \a mutex must be initially locked by the calling thread. If \a + mutex is not in a locked state, this function returns + immediately. If \a mutex is a recursive mutex, this function + returns immediately. The \a mutex will be unlocked, and the + calling thread will block until either of these conditions is met: + + \list + \o Another thread signals it using wakeOne() or wakeAll(). This + function will return true in this case. + \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX + (the default), then the wait will never timeout (the event + must be signalled). This function will return false if the + wait timed out. + \endlist + + The mutex will be returned to the same locked state. This + function is provided to allow the atomic transition from the + locked state to the wait state. + + \sa wakeOne(), wakeAll() +*/ + +/*! + \fn bool QWaitCondition::wait(QReadWriteLock *readWriteLock, unsigned long time) + \since 4.4 + + Releases the locked \a readWriteLock and waits on the wait + condition. The \a readWriteLock must be initially locked by the + calling thread. If \a readWriteLock is not in a locked state, this + function returns immediately. The \a readWriteLock must not be + locked recursively, otherwise this function will not release the + lock properly. The \a readWriteLock will be unlocked, and the + calling thread will block until either of these conditions is met: + + \list + \o Another thread signals it using wakeOne() or wakeAll(). This + function will return true in this case. + \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX + (the default), then the wait will never timeout (the event + must be signalled). This function will return false if the + wait timed out. + \endlist + + The \a readWriteLock will be returned to the same locked + state. This function is provided to allow the atomic transition + from the locked state to the wait state. + + \sa wakeOne(), wakeAll() +*/ diff --git a/doc/src/phonon-api.qdoc b/doc/src/phonon-api.qdoc deleted file mode 100644 index 09274bf..0000000 --- a/doc/src/phonon-api.qdoc +++ /dev/null @@ -1,5023 +0,0 @@ -/* - This file is part of the KDE project - Copyright (C) 2005-2007 Matthias Kretz - Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). - Contact: Nokia Corporation (qt-info@nokia.com) - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Library General Public - License version 2 as published by the Free Software Foundation. - - This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Library General Public License for more details. - - You should have received a copy of the GNU Library General Public License - along with this library; see the file COPYING.LIB. If not, write to - the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - Boston, MA 02110-1301, USA. -*/ - - -/*! - \enum Phonon::DiscType - Enum to identify the media discs supported by MediaObject. - - \value NoDisc - No disc was selected. This is only useful as a return value from - MediaSource::diskType(). - \value Cd Identifies Audio CDs. - \value Dvd Identifies DVDs (not arbitrary data DVDs, only movie DVDs). - \value Vcd Identifies Video CDs. - - \sa MediaSource, MediaObject -*/ - -/*! - \enum Phonon::MetaData - - Provided as keys for Phonon::MediaObject::metaData(). The enum - values matches strings defined in the Ogg Vorbis specification - - \value ArtistMetaData - \value AlbumMetaData - \value TitleMetaData - \value DateMetaData - \value GenreMetaData - \value TracknumberMetaData - \value DescriptionMetaData - \value MusicBrainzDiscIdMetaData -*/ - -/*! - \enum Phonon::State - \since 4.4 - - The state enum describes the different states a media object can - take. Several functions of \l{Phonon::}{MediaObject} are - asynchronous, so even if a you have requested a state change - through a function call, e.g., through - \l{Phonon::MediaObject::}{play()}, you cannot be sure that the - change has taken place before you receive the - \l{Phonon::MediaObject::}{stateChanged()} signal. - - A media object can at any time change into any state, regardless - of the state it previously had. \omit In the - \l{Phonon::}{MediaObject} class description explains the typical - state changes in the life of a media object. \endomit - - \value LoadingState - After construction it might take a while before the media object - is ready to \l{Phonon::MediaObject::}{play()}. This state is - commonly used by backends to initialize the \l{Phonon - Overview}{media graph} and loading the source. When - the object leaves the loading state, it will enter the - StoppedState unless an error occurred or another state is - requested through a function call, e.g., - \l{Phonon::}{MediaObject::play()}. - - \value StoppedState - In the stopped state, the media object is ready to play its - current media source. The current - \l{MediaObject::seek()}{position} in the media stream is then 0. - - \value PlayingState - The media object is playing back its media source. - - \value BufferingState - The Player is waiting for data to be able to start or continue - playing. This state is commonly used to wait for media data over a - network connection. - - \value PausedState - The media player has currently paused its playback, i.e., it - stops playing but keeps the current playback position in the - stream. - - \value ErrorState - When a media object enters the error state a problem with the - playback has occurred. The possible errors are grouped into - two categories by Phonon::ErrorType, and the type can be - queried through \l{Phonon::MediaObject::}{errorType()}. A - \l{Phonon::}{FatalError} implies that the playback - cannot continue, but one can still try with a new media - source. With a \l{Phonon::}{NormalError} it might - be possible to continue playback, and a media object may - therefore change state from the ErrorState. - - \sa MediaObject -*/ - -/*! - \enum Phonon::Category - - Sets the category your program should be listed in in the mixer. - - \value NoCategory - Will make use of the default device. - \value NotificationCategory - If the sounds produced are notifications (ping, beep and such) you - should use this category. - \value MusicCategory - If your application is a music player (like a jukebox or media player - playing an audio file). - \value VideoCategory - If the sound is the audio channel of a video. - \value CommunicationCategory - If your applications produces sounds from communication with somebody - else (VoIP, voice chat). - \value GameCategory - Sound produced by a computer game should go into this category. - \value AccessibilityCategory - Sounds produced for accessibility (e.g., Text-To-Speech) - \omitvalue LastCategory - Holds the largest value of categories. - \omitvalue AccessibilityCategory - - A Jukebox will set this to Music, a VoIP program to Communication, a - DVD player to video, and so on. - - \note These categories can also become useful for an application that - controls the volumes automatically, like turning down the music when a call - comes in, or turning down the notifications when the media player knows - it's playing classical music. -*/ - -/*! - \enum Phonon::ErrorType - - This enum describes the severity when an error has occurred during - playback. - - After a media object has entered the \l{Phonon::}{ErrorState}, one - can query the type of error from - \l{Phonon::}{MediaObject::errorType()}. Note that you should query - the error when receiving the - \l{Phonon::}{MediaObject::stateChanged()} signal, because the - error type will be lost if the media object leaves the error - state. - - \value NoError No error. MediaObject::errorType() returns this if - MediaObject::state() != Phonon::ErrorState. - - \value NormalError An error has occurred with the playback of the current - source. It might be possible to continue playback, for instance, if only the - audio stream in a video cannot be played back. The media object will then - leave the error state again. - - \value FatalError. Something important does not work. Your program cannot continue - the playback of the current source, but it might be possible to try another. - - \sa MediaObject::errorType() -*/ - -/*! - \fn QString Phonon::categoryToString(Category c) - - Returns a (translated) string to show to the user identifying the given - Category (\a c). -*/ - -/*! - \enum Phonon::ObjectDescriptionType - \relates Phonon::ObjectDescription - - This enum defines the type of information that is contained in a - \l{Phonon::}{ObjectDescription} object. - - \value AudioOutputDeviceType An audio output device (\l{Phonon::}{AudioOutputDevice}). - This can be soundcards (with different drivers), - sound servers, or other virtual outputs like playback on a different - computer on the network. - - \value EffectType An audio effect (\l{Phonon::}{EffectDescription}). - \omitvalue SubtitleType - \omitvalue AudioCaptureDeviceType - \omitvalue AudioChannelType -*/ - -/*! - \typedef Phonon::AudioOutputDevice - \relates Phonon::ObjectDescription - - This typedef of \l{Phonon::}{ObjectDescription} describes an audio output - device, such as soundcards (with different drivers), sound servers, or other - virtual outputs like playback on a different computer on the network. - - \omit - For Hardware devices the backend should use libkaudiodevicelist - (AudioDevice and AudioDeviceEnumerator) which will list removable - devices even when they are unplugged and provide a unique identifier - that can make backends use the same identifiers. - \endomit - - A list of available devices is given by the backend with - Backendcapabilities::availableAudioOutputDevices() - - \snippet doc/src/snippets/phononobjectdescription.cpp 1 - -*/ - -/*! - \fn Phonon::phononVersion() - \inmodule Phonon - \since 4.5 - - Returns the Phonon version. -*/ - -/*! - \class Phonon::ObjectDescription - \inmodule Phonon - \inheaderfile Phonon/ObjectDescription - \since 4.4 - \brief The ObjectDescription class provides information about Phonon objects. - - Phonon currently uses this class to describe audio effects and - audio output devices - using the typedefs AudioOutputDevice and - EffectDescription. The type of an ObjectDescription is also - described through the \l{Phonon::}{ObjectDescriptionType} enum. - Objects of the same \l{Phonon::ObjectDescriptionType}{type} are - uniquely identified by an index(). - - The class gives a description() and a name() of the object, both - of which are strings appropriate for end users of a Phonon - application. You can also check whether the device or effect - described is \l{isValid()}{valid}. This does not guarantee that - the device or effect functions as expected, but that the - ObjectDescription describes an existing device or effect. - - Audio output devices and effect descriptions are used to select - the audio output device to be used for playback and to create - effects; we show examples of this in the snippet below. The - available descriptions can be fetched with - \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()} - and \l{Phonon::BackendCapabilities::}{availableAudioEffects()} - static functions in the Phonon::BackendCapabilities namespace - - \snippet doc/src/snippets/phononobjectdescription.cpp 0 - - Other types of ObjectDescriptions might be possible in the future, - e.g., descriptions of audio capture devices, such as microphones. - - \omit Not implemented yet. - Need a new paragraph on that some descriptions 'belong - together', such as chained audio effects. - - Some parts give the end user choices, e.g. what source to capture - audio from. These choices are described by the name and - description methods of this class and identified with the id - method. Subclasses then define additional information like which - audio and video choices belong together. \endomit - - \sa Phonon::AudioOutputDevice, Phonon::EffectDescription, {Capabilities Example}, {Phonon Module} -*/ - -/*! - \fn Phonon::ObjectDescription::ObjectDescription() - \brief constructs a new object description. - \internal -*/ - -/*! - \fn Phonon::ObjectDescription::ObjectDescription (int index, const QHash & properties) - \internal -*/ - -/*! - \fn Phonon::ObjectDescription::ObjectDescription(const QExplicitlySharedDataPointer &dd) - \internal -*/ - -/*! - \fn static inline ObjectDescription Phonon::ObjectDescription::fromIndex(int index) - \internal - - \omit Currently indices are not unique for all ObjectDescription types, making - the behavior of this function undefined. \endomit - - Returns a new description object that describes the - device/effect/codec/... with the given \a index. -*/ - -/*! - \fn inline bool Phonon::ObjectDescription::operator==(const ObjectDescription &otherDescription) const - - Returns \c true if this ObjectDescription describes the same - object as \a otherDescription; otherwise, returns \c false. -*/ - -/*! - \fn inline bool Phonon::ObjectDescription::operator!=(const ObjectDescription &otherDescription) const - Returns \c false if this ObjectDescription describes the same - as \a otherDescription; otherwise, returns \c true. -*/ - -/*! - \fn inline QString Phonon::ObjectDescription::name() const - - Returns a string appropriate for a user to select between - object descriptions, e.g., from a QComboBox. - - \sa description() -*/ - -/*! - \fn inline QString Phonon::ObjectDescription::description() const - - Returns a more extensive description than the name() function. - - For example, in the case of \l{Phonon::}{AudioOutputDevice}s, this - text should make clear which sound source is described; this is - sometimes hard to describe or understand from just the name. - - The text is appropriate to present to an end user in for example - tool tips of items, with the name()'s as text, in a QComboBox. - -*/ - -/*! - \fn inline QVariant Phonon::ObjectDescription::property(const char *name) const - - Returns the property named \a name. A property can be used for - extended information, such as the manufacturer of a sound card. The - information will usually be given as text. - - If the property is not set an invalid QVariant is returned. - - Qt's backends do not use properties at the time of this writing. - - \sa propertyNames() -*/ - -/*! - \fn inline QList Phonon::ObjectDescription::propertyNames() const - - Properties can be used for extended information about a - ObjectDescription, e.g., a manufacturer of a sound card. The - information will usually be given text. - - This function returns all names that return valid data when - property() is called. - - Currently, Qt backends do not use properties for their object - descriptions. - - \sa property() -*/ - -/*! - \fn inline bool Phonon::ObjectDescription::isValid() const - - Returns true if the device or effect described exists. - - An ObjectDescription that is invalid, will also have an - index() of -1. - - \sa index() -*/ - -/*! - \fn inline int Phonon::ObjectDescription::index() const - - Returns a unique identifier for this ObjectDescription. Used - internally to distinguish between the descriptions. - - Notice that the identifiers are only unique to the type of - description, e.g., \l{Phonon::}{AudioOutputDevice} or - \l{Phonon::}{EffectDescription}. -*/ - -/*! - \class Phonon::ObjectDescriptionPrivate - \inmodule Phonon - \since 4.4 - \internal - -*/ - -/*! - \class Phonon::StreamInterface - \inmodule Phonon - \since 4.4 - \brief Backend interface to handle media streams (AbstractMediaStream). - \internal -*/ - -/*! - \fn virtual Phonon::StreamInterface::~StreamInterface() -*/ - -/*! - \fn virtual void Phonon::StreamInterface::writeData(const QByteArray &data) = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::StreamInterface::endOfData() = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::StreamInterface::setStreamSize(qint64 newSize) = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::StreamInterface::setStreamSeekable(bool s) = 0 - \internal -*/ - -/*! - \fn void Phonon::StreamInterface::connectToSource(const MediaSource &mediaSource) - \internal -*/ - -/*! - \fn void Phonon::StreamInterface::needData() - \internal -*/ - -/*! - \fn void Phonon::StreamInterface::enoughData() - \internal -*/ - -/*! - \fn void Phonon::StreamInterface::seekStream(qint64) - \internal -*/ - -/*! - \fn void Phonon::StreamInterface::reset() - \internal -*/ - -/*! - \fn Phonon::StreamInterface::StreamInterface() - \internal - \omit - For subclasses. - \endomit -*/ - -/*! - \class StreamInterfacePrivate - \inmodule Phonon - \internal -*/ - -/*! - \class Phonon::AbstractVideoOutput - \inmodule Phonon - \internal - \since 4.4 - \brief The AbstractVideoOutput class is the common base class for all video output classes. - - \sa VideoWidget -*/ - -/*! - \namespace Phonon::Experimental - \internal -*/ - -/*! - \fn Phonon::AbstractVideoOutput::AbstractVideoOutput(AbstractVideoOutputPrivate &d) - \internal - - Constructor that is called from derived classes. - - \param parent Standard QObject parent. -*/ - -/*! - \class Phonon::AbstractVideoOutputPrivate - \inmodule Phonon - \internal - \since 4.4 -*/ - -/*! - \class Phonon::VolumeFaderEffect - \inmodule Phonon - \internal - \since 4.4 - - This effect differs from gradually changing the output volume in that - a dedicated effect can change the volume in the smallest possible - steps while every other volume control will make more or less - noticeable steps. - - \sa AudioOutput::volume() -*/ - -/*! - \property Phonon::VolumeFaderEffect::volume - - This is the current volume of the output as voltage factor. - Setting this property changes the volume immediately. - - 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% - - \sa volumeDecibel -*/ - -/*! - \property Phonon::VolumeFaderEffect::volumeDecibel - - This is the current volume of the output in decibel. - Setting this property changes the volume immediately. - - 0 dB means no change in volume, -6dB means an attenuation of the - voltage to 50% and an attenuation of the power to 25%, -inf dB means - silence. - - \sa volume -*/ - -/*! - \property Phonon::VolumeFaderEffect::fadeCurve - - This property holds the fade curve to be used for the fadeIn(), fadeOut() - and fadeTo() slots. - - Defaults to Fade3Decibel. - - \sa FadeCurve -*/ - -/*! - \enum Phonon::VolumeFaderEffect::FadeCurve - Determines the curve of the volume change. - - \value Fade3Decibel Crossfade curve/fast fade out. - This is the default fade curve. - \value Fade6Decibel Linear fade out. - \value Fade9Decibel Slow fade out. - \value Fade12Decibel A more extreme version of the -9dB fade. - - \bold{Notes:} - - \c Fade3Decibel is often the best fade for a crossfade, as after half - of the time the volume reached -3dB. This means that half the - possible power (which is proportional to the square of the - voltage) is reached. Summed, the maximum power of two audio - signals fading with a -3dB curve will always be equal. - - For fading in or out the -3dB curve is too abrupt in the end. - - With a -6dB fade curve, a volume of -6dB is reached after half of - the fading time. -6dB is equal to half of the voltage meaning - that the voltage multiplier changes linearly from the start - of the fade to the end. - - With the \c Fade9Decibel fade, a volume of -9dB is reached after - half of the fade time, so the fade is fast in the beginning and - slow at the end. This is a good fade for ending music. -*/ - -/*! - \fn void Phonon::VolumeFaderEffect::fadeIn(int fadeTime) - - Tells the Fader to change the volume from the current volume to 100% - in \a fadeTime milliseconds. - - Short for \c fadeTo(1.0, fadeTime). - - \param fadeTime the fade duration in milliseconds - - \sa fadeTo(), volume -*/ - -/*! - \fn void Phonon::VolumeFaderEffect::fadeOut(int fadeTime) - - Tells the Fader to change the volume from the current volume to 0% - in \a fadeTime milliseconds. - Short for \c fadeTo(0.0, fadeTime). - - \param fadeTime the fade duration in milliseconds - - \sa fadeTo -*/ - -/*! - \fn void Phonon::VolumeFaderEffect::fadeTo(float volume, int fadeTime) - - Tells the Fader to change the volume from the current value to - \a volume in \a fadeTime milliseconds. - - \sa fadeIn(), fadeOut() -*/ - -/*! - \class Phonon::VolumeFaderEffectPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::VolumeFaderInterface - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn virtual Phonon::VolumeFaderInterface::~VolumeFaderInterface() - \internal -*/ - -/*! - \fn virtual float Phonon::VolumeFaderInterface::volume() const - \internal -*/ - -/*! - \fn virtual void Phonon::VolumeFaderInterface::setVolume(float) - \internal -*/ - -/*! - \fn virtual Phonon::VolumeFaderEffect::FadeCurve Phonon::VolumeFaderInterface::fadeCurve() const - \internal -*/ - -/*! - \fn virtual void Phonon::VolumeFaderInterface::setFadeCurve(Phonon::VolumeFaderEffect::FadeCurve) - \internal -*/ - -/*! - \fn virtual void Phonon::VolumeFaderInterface::fadeTo(float, int) - \internal -*/ - -/*! - \class Phonon::AbstractMediaStream - \inmodule Phonon - \internal - \since 4.4 - \brief The AbstractMediaStream class is the base class for custom media data streams. - \inheaderfile Phonon/AbstractMediaStream - - This class is subclassed to provide custom data streams for - \l{Phonon::}{MediaSource}s. - - The \l{Phonon::}{MediaSource} knows how to handle the most common - media sources, such as files and CD. If you need to fetch - multimedia from other sources, you can reimplement this class, - which can be used by a \l{Phonon::}{MediaSource}. - - When a backend needs more data from the stream, needData() will be - called. You must then use writeData() to write the data to the - backend. You can either write one time and wait for a new - needData() call, or continue to write data until you receive an - enoughData() call. When the stream is at its end, call endOfData() - instead of writeData(). - - Before the custom stream is passed to a \l{Phonon::}{MediaSource}, - setStreamSize() needs to be called, and also setStreamSeekable() - (if the stream is seekable). A good place to do this work is in - the constructor. A seekable stream must also reimplement - seekStream(). - - We show two examples. The first writes data repeatedly until it - receives the enoughData() call, while the second only writes once - and waits for a new needData() call. - - Example where data is written repeatedly. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 0 - - Example where data is written once: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 1 - - \sa Phonon::MediaSource, Phonon::MediaObject - -*/ - -/*! - \fn Phonon::AbstractMediaStream::AbstractMediaStream(QObject *parent = 0) - \internal - - Constructs an AbstractMediaStream object with the given \a parent. - -*/ - -/*! - \fn qint64 Phonon::AbstractMediaStream::streamSize() const - - Returns the stream size that was set with setStreamSize(). - - A negative value means that the length of the stream cannot be known. - - Defaults to 0. - - \sa setStreamSize() -*/ - -/*! - \fn void Phonon::AbstractMediaStream::setStreamSize(qint64 size) - - Sets the \a size of the stream in number of bytes. - - A negative value means that the length of the stream cannot be known. - - Defaults to 0. - - This function has to be called. A backend will not call needData() - until the stream size is set. - - \sa streamSize() - -*/ - -/*! - \fn bool Phonon::AbstractMediaStream::streamSeekable() const - - Returns whether your data stream is set as seekable. - - Defaults to \c false. - - \sa setStreamSeekable() - -*/ - -/*! - \fn void Phonon::AbstractMediaStream::setStreamSeekable(bool s) - - Sets whether your data stream is seekable. \a s should be true if - the stream is seekable; otherwise false. - - Defaults to \c false. - - If you set this to \c true you have to implement the seekStream() - function. - - \sa streamSeekable() -*/ - -/*! - \fn void Phonon::AbstractMediaStream::writeData(const QByteArray &data) - - Sends the media \a data to the backend for decoding. - - Use this function to send data to the backend after needData() has - been called. - - If your stream is a push stream, data should be written until the - enoughData() function is called. For a pull stream, write data - once before the call to needData() function returns. - - If the data is depleted, call endOfData() instead of writeData(). - - \warning Don't call this function before the first needData() is emitted. - - \sa needData(), endOfData() - -*/ - -/*! - \fn void Phonon::AbstractMediaStream::endOfData() - - Tells the backend that the media data stream is at its end. - - \warning Don't call this function before the first needData() is emitted. - - \sa writeData(), needData() -*/ - -/*! - \fn void Phonon::AbstractMediaStream::error(Phonon::ErrorType errorType, const QString &errorString) - - If an I/O error occurs you should call this function to make - MediaObject go into ErrorState. \c errorType classifies the error, - while \a errorString is a textual description of the error suitable - for users of Phonon applications. - - \sa MediaObject::errorType(), MediaObject::errorString() -*/ - -/*! - \fn virtual void Phonon::AbstractMediaStream::reset() = 0 - - Reimplement this function to reset the stream. Subsequent calls to writeData should start - from the first position of the data unless a seek is requested. - - The function is necessary for the case where a non-seekable MediaStream is - played more than once. For a seekable stream the implementation can simply call - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 2 - - \sa writeData(), needData() -*/ - -/*! - \fn virtual void Phonon::AbstractMediaStream::needData() = 0 - - Reimplement this function to be notified when the backend needs data. - - When this function is called you should write data to the backend - (See writeData()). - - \sa writeData(), endOfData(), enoughData() -*/ - -/*! - \fn virtual void Phonon::AbstractMediaStream::enoughData() - - If your stream is a push stream, reimplement this function to be - notified when the backend has enough data and your stream object - may take a break. - - This method is important for pushing data to the backend in order - to not fill the backend buffer unnecessarily. - - \sa needData() -*/ - -/*! - \fn virtual void Phonon::AbstractMediaStream::seekStream(qint64 offset) - - Reimplement this function if your stream is seekable. - - When this function is called the next call to writeData has to be at the - requested \a offset. - - \warning Do not call the parent implementation. - - \sa setStreamSeekable(), streamSeekable(), needData() -*/ - -/*! - \class Phonon::BackendInterface - \inmodule Phonon - \since 4.4 - \brief Main Backend class interface - \internal - - This interface defines the main factory of the backend. The createObject() function creates all the - objects needed by the frontend. - - The objectDescriptionIndexes and objectDescriptionProperties functions return information about - available devices, effects and codecs. - - An implementation could look like this: - \snippet snippets/phonon/samplebackend/main.cpp snippet - -*/ - -/*! - \fn virtual Phonon::BackendInterface::~BackendInterface() - \internal - - Silence gcc's warning. -*/ - -/*! - \enum Phonon::BackendInterface::Class - \internal - - Classes that the createObject() function has to handle. - - \value MediaObjectClass Request to return a \c MediaObject object. - \value VolumeFaderEffectClass Request to return a \c VolumeFaderEffect - object. - \value AudioOutputClass Request to return an \c AudioOutput object. - \value AudioDataOutputClass Request to return an \c AudioDataOutput object. - \value VisualizationClass Request to return a \c Visualization object. - \value VideoDataOutputClass Request to return a \c VideoDataOutput object. - \value EffectClass Request to return a \c Effect object. - Takes an additional int that specifies the effect ID. - \value VideoWidgetClass Request to return a \c VideoWidget object. -*/ - -/*! - \fn virtual QObject *Phonon::BackendInterface::createObject(Class c, QObject *parent, const QList &args = QList()) = 0 - \internal - - Returns a new instance of the requested class. - - \param c The requested class. - \param parent The parent object. - \param args Additional arguments (documented in Class). -*/ - - -/*! - \fn virtual QList Phonon::BackendInterface::objectDescriptionIndexes(ObjectDescriptionType type) const = 0 - \internal - - Returns the unique identifiers for the devices/effects/codecs of the given \a type. - - \param type see ObjectDescriptionType -*/ - -/*! - \fn virtual QHash Phonon::BackendInterface::objectDescriptionProperties(ObjectDescriptionType type, int index) const = 0 - \internal - - Given a unique identifier that was returned from objectDescriptionIndexes this function - returns a hash mapping property names to values. - - The property "name" must always be present. All other properties are optional. - - \table - \header \o Property \o Description - \row \o name \o The name of the device/effect/codec/... - \row \o description \o A text explaining what this device/effect/codec/... is/can do - \row \o icon \o An icon name (using the freedesktop naming scheme) or a QIcon for this - device/effect/codec/... - \row \o available \o A bool telling whether the device is present or unplugged. - \endtable - - \param type see ObjectDescriptionType - \param index The unique identifier that is returned from objectDescriptionIndexes -*/ - -/*! - \fn virtual bool Phonon::BackendInterface::startConnectionChange(QSet) = 0; - \internal - - When this function is called the nodes given in the parameter list should - not lose any signal data when connections are changed. -*/ - -/*! - \fn virtual bool Phonon::BackendInterface::connectNodes(QObject *, QObject *) = 0 - \internal - - Defines a signal connection between the two given nodes. -*/ - -/*! - \fn virtual bool Phonon::BackendInterface::disconnectNodes(QObject *, QObject *) = 0 - \internal - - Cuts a signal connection between the two given nodes. -*/ - -/*! - \fn virtual bool Phonon::BackendInterface::endConnectionChange(QSet) = 0 - \internal - - When this function is called the nodes given in the parameter list may lose - signal data when a port is not connected. -*/ - -/*! - \fn virtual QStringList Phonon::BackendInterface::availableMimeTypes() const = 0 - \internal - - Returns all available MIME types. -*/ - -/*! - \class Phonon::MediaSource - \inmodule Phonon - \inheaderfile Phonon/MediaSource - \since 4.4 - \brief The MediaSource class provides multimedia data for media objects. - - The MediaSource class manages a source of multimedia content, such - as a music or video file, of which data is given to a - \l{Phonon::}{MediaObject}. - - The media source knows how fetch its data from several sources, - e.g., from files, a QIODevice, or a CD. The possible source types - are described by the \l{MediaSource::}{Type} enum. The type of the - source is set by the media source itself, and is dependent on the - constructor used to create it. Note that it is possible to provide - data from any source by implementing a QIODevice. - - The class has several functions to acquire information about the - source it manages, e.g., fileName() and url(). The return from - these functions are dependent on the type() of the media source. - - Normally, a programmer does not need to be concerned with media - sources. It's constructors are implicit, so one can, for instance, - send an URL or filename directly to the constructors of the - \l{Phonon::}{MediaObject}. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 3 - - A MediaSource object cannot be reused for another multimedia - source. It is possible to play the same source again, and also - stop and start a non-seekable media source, such as a radio - stream, with the same MediaSource object. - - \section1 Qt Backends - - Currently, Qt's backends support files in local and remote - locations. Support for other sources, such as CD/DVD, are planned - for the future. - - \sa MediaObject, {Phonon Module} -*/ - -/*! - \enum Phonon::MediaSource::Type - - Identifies the type of media described by the MediaSource object. - - \value Invalid The MediaSource object does not describe any valid source. - \value LocalFile The MediaSource object describes a local file. - \value Url The MediaSource object describes an URL, which can be either a - local file or a file on the network. - \value Disc The MediaSource object describes a disc, e.g., a CD. - \value Stream The MediaSource object describes a data stream. - This is the type used for \l{QIODevice}s. Note - that a stream opened with a QUrl, will still be of the Url type. - \value Empty The media source doesn't have a source. - - \sa MediaSource::type() -*/ - -/*! - \fn Phonon::MediaSource::MediaSource() - \internal - - Creates an invalid MediaSource object. - - \sa Invalid -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(const QString &fileName) - - Creates a MediaSource object for the file specified by \a - fileName. You can also use this constructor with \l{The Qt - Resource System}{Qt resources} - - \omit - \param fileName file name of a local media file or a Qt resource that was compiled in. - \endomit -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(const QUrl &url) - - Creates a MediaSource object for a the URL specified by \a url. - - If the multimedia content you would like to play back is on a - remote network location, you should use this constructor; though, - it also possible to specify an URL to a local file. - - \sa QUrl -*/ - - -/*! - \fn Phonon::MediaSource::MediaSource(Phonon::DiscType discType, const QString &deviceName = QString()) - - Creates a MediaSource object for the type of disc specified by \a discType in the named - device referred to by \a deviceName. - - \note \a deviceName is a platform dependent device name. It can be useful to specify this - if the computer has more than one CD drive. On KDE, it is recommended to use the Solid - hardware discovery framework to retrieve the device name in a portable way. -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(AbstractMediaStream *stream) - \internal - Creates a MediaSource object for a data stream. - - Your application can provide the media data by subclassing AbstractMediaStream and - passing a pointer to that object. Phonon will never delete the \a stream. - - \param stream The AbstractMediaStream subclass to provide the media data. - - \sa setAutoDelete -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(QIODevice *ioDevice) - - Creates a MediaSource object for the QIODevice specified by \a ioDevice. - - This constructor can be very handy in the combination of - QByteArray and QBuffer. - - If you need to fetch multimedia data from a source that is not - supported by MediaSource, you should subclass QIODevice and use - this MediaSource constructor. It is important that you reimplement - QIODevice::isSequential(), as it is used by MediaSource to - determine if the media source is seekable. - - \a ioDevice is an arbitrary readable QIODevice subclass. If the device is not opened - MediaSource will open it as QIODevice::ReadOnly. - - \note Sequential devices can also be used, but MediaObject::isSeekable() will - return false as a result. - - \warning On Windows, we only support \l{QIODevice}s containing the - \c avi, \c mp3, or \c mpg formats. Use the constructor that takes - a file name to open files (the Qt backend does not use a QFile - internally). - - \sa setAutoDelete() -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(MediaSourcePrivate &) - \internal -*/ - -/*! - \fn Phonon::MediaSource::~MediaSource() - - Destroys the MediaSource object. You should never delete a - MediaSource yourself, the MediaObject will handle this. - -*/ - -/*! - \fn Phonon::MediaSource::MediaSource(const MediaSource &other) - - Constructs a copy of the \a other media source. - - This constructor is fast thanks to explicit sharing. -*/ - -/*! - \fn MediaSource &Phonon::MediaSource::operator=(const MediaSource &other) - - Assigns the \a other media source to this media source and returns a - reference to it. - - This operation is fast thanks to explicit sharing. -*/ - -/*! - \fn bool Phonon::MediaSource::operator==(const MediaSource &other) const - - Returns true if this media source is equal to the \a other media source; - otherwise returns false. -*/ - -/*! - \fn void Phonon::MediaSource::setAutoDelete(bool enable) - - If \a enable is true, the media source will take ownership of the - object passed in the \l{Phonon::}{MediaSource}'s constructor - object that was passed in the constructor; otherwise, the - programmer is responsible for deletion of this object. - - This setting is false by default. If you enable it, you should - only access the stream or device as long as you keep the media - source object around. As long as you keep the media source - wrapping the stream or device, the object will not get deleted. - - \sa autoDelete() -*/ - -/*! - \fn bool Phonon::MediaSource::autoDelete() const - - Returns the setting of the auto-delete option. The default is - false. - - \sa setAutoDelete() -*/ - -/*! - \fn Type Phonon::MediaSource::type() const - - Returns the type of the MediaSource (depends on the constructor - that was used). - - \sa Type -*/ - -/*! - \fn QString Phonon::MediaSource::fileName() const - - Returns the file name of the MediaSource if type() == - LocalFile; otherwise, returns QString(). - - \sa type() -*/ - -/*! - \fn QUrl Phonon::MediaSource::url() const - Returns the URL of the MediaSource if type() == URL or type() == LocalFile; - otherwise returns QUrl(). - - \sa type() -*/ - -/*! - \fn Phonon::DiscType Phonon::MediaSource::discType() const - Returns the disc type of the MediaSource if type() == Disc; otherwise - returns NoDisc. - - \sa type() -*/ - -/*! - \fn QString Phonon::MediaSource::deviceName() const - - Returns the device name of the MediaSource if type() == Disc; otherwise - returns QString(). - - \sa type() -*/ - -/*! - \fn AbstractMediaStream *Phonon::MediaSource::stream() const - \internal - Returns the media stream of the MediaSource if type() == Stream; otherwise - returns 0. - QIODevices are handled as streams, too. -*/ - -/*! - \class Phonon::MediaSourcePrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::SeekSlider - \inmodule Phonon - \inheaderfile Phonon/SeekSlider - \since 4.4 - \brief The SeekSlider class provides a slider for seeking to positions in media streams. - - The SeekSlider connects to a \l{Phonon::}{MediaObject}, and - controls the seek position in the object's media stream. - - The slider will connect to the necessary signals to keep track of - the sliders maximum, minimum, and current values. It will also - disable itself for non-seekable streams, and update the media - object when the current value of the slider changes. - - Here follows a typical example of SeekSlider usage: - - \snippet doc/src/snippets/seekslider.cpp 0 - - \sa Phonon::VolumeSlider, Phonon::VideoWidget, {Music Player Example}, {Phonon Module} - -*/ - -/*! - \property Phonon::SeekSlider::iconVisible - \brief whether the icon next to the slider is visible - - By default the icon is visible if the platform provides an icon; else - it's hidden. - -*/ - -/*! - \property Phonon::SeekSlider::tracking - \brief whether slider tracking is enabled - - If tracking is enabled (the default), the media seeks - while the slider is being dragged. If tracking is - disabled, the media seeks only when the user - releases the slider. -*/ - -/*! - \property Phonon::SeekSlider::pageStep - \brief the page step interval - - The larger of two natural steps that a slider provides and - typically corresponds to the user pressing PageUp or PageDown. - - Defaults to 5 seconds. -*/ - -/*! - \property Phonon::SeekSlider::singleStep - \brief the single step interval - - The smaller of two natural steps that a slider provides and - typically corresponds to the user pressing an arrow key. - - Defaults to 0.5 seconds. -*/ - -/*! - \property Phonon::SeekSlider::orientation - \brief the orientation of the slider - - The orientation must be Qt::Vertical or Qt::Horizontal (the default). -*/ - -/*! - \property Phonon::SeekSlider::iconSize - \brief the icon size used for the mute button/icon. - - The default size is defined by the GUI style. -*/ - -/*! - \fn explicit Phonon::SeekSlider::SeekSlider(QWidget *parent = 0) - - Constructs a seek slider widget with the given \a parent. -*/ - -/*! - \fn explicit Phonon::SeekSlider::SeekSlider(MediaObject *media, QWidget *parent = 0) - - Constructs a seek slider widget for the specified \a media with the - given \a parent. -*/ - -/*! - \fn Phonon::SeekSlider::~SeekSlider() - Destroys the seek slider. -*/ - -/*! - \fn Phonon::MediaObject *Phonon::SeekSlider::mediaObject() const - - Return the media object this SeekSlider controls. -*/ - -/*! - \class Phonon::SeekSliderPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn void Phonon::SeekSlider::setMediaObject(MediaObject *media) - - Sets the media object to be controlled by this slider to the \a media specified. -*/ - -/*! - \class Phonon::VideoPlayer - \inmodule Phonon - \inheaderfile Phonon/VideoPlayer - \since 4.4 - \brief The VideoPlayer widget is used to perform playback of video. - - With VideoPlayer you can get results quickly and easily. You can - do the standard playback tasks like play(), pause(), and stop(), - but also set a playback volume and seek - if the media and backend - supports seeking. - - VideoPlayer is provided for convenience and removes the need to - create a media graph with a \l{Phonon::}{MediaObject}, - \l{Phonon::}{AudioOutput}, and \l{Phonon::}{VideoWidget}. If - you need functionality not supported by the player, you can build - this \l{Building Graphs}{graph} yourself. - - Keep in mind that when the VideoPlayer instance is deleted the - playback will stop. - - Note also that most of the functions in this class are - asynchronous. For instance, a media source may not play - immediately after you call the play() function. - - A play and forget code example: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 4 - - \sa {Phonon Module}, MediaObject -*/ - -/*! - \fn Phonon::VideoPlayer::VideoPlayer(QWidget *parent = 0) - - Constructs a new video widget with a \a parent using - Phonon::VideoCategory as its category. - - \param parent The QObject parent. -*/ - -/*! - \fn Phonon::VideoPlayer::VideoPlayer(Phonon::Category category, QWidget *parent = 0) - - Constructs a new VideoPlayer instance with the specified \a - parent. - - \a category is the category used for the audio output device. -*/ - -/*! - \fn Phonon::VideoPlayer::~VideoPlayer() - - On destruction the playback is stopped, also the audio output is - removed so that the desktop mixer will not show the application - anymore. If you need a persistent audio output don't use - VideoPlayer but MediaObject, VideoPath and VideoOutput. -*/ - -/*! - \fn qint64 Phonon::VideoPlayer::totalTime() const - - Get the total time (in milliseconds) of the file currently being played. -*/ - -/*! - \fn qint64 Phonon::VideoPlayer::currentTime() const - - Get the current time (in milliseconds) of the file currently being played. -*/ - -/*! - \fn float Phonon::VideoPlayer::volume() const - - This is the current volume of the output as voltage factor. - - 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% -*/ - -/*! - \fn bool Phonon::VideoPlayer::isPlaying() const - - Returns true if it is currently playing; otherwise returns false if it - is currently stopped or paused -*/ - -/*! - \fn bool Phonon::VideoPlayer::isPaused() const - - Returns true if it is currently paused; otherwise returns false if it - is currently playing or stopped. -*/ - -/*! - \fn void Phonon::VideoPlayer::load(const Phonon::MediaSource &source) - - Starts pre-loading the media data from the specified \a source and - filling audio buffers in the backend. - - When there's already a media playing (or paused) it will be stopped - (the finished signal will not be emitted). - - \sa MediaObject::setCurrentSource() -*/ - -/*! - \fn void Phonon::VideoPlayer::play(const Phonon::MediaSource &source) - - Plays the media from the given \a source. Starts playback as fast as - possible. - This can take a considerable time depending on the URL and the - backend. - - If you need low latency between calling play() and the sound actually - starting to play on your output device you need to use MediaObject - and be able to set the URL before calling play(). Note that - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 5 - doesn't make a difference: the application should be idle between the - load and play calls so that the backend can start preloading the - media and fill audio buffers. -*/ - -/*! - \fn void Phonon::VideoPlayer::play() - - Continues playback of paused media. Restarts playback of a stopped - (or newly loaded) media. - - \sa MediaObject::play(), play() -*/ - -/*! - \fn void Phonon::VideoPlayer::pause() - - Pauses the playback. - - \sa MediaObject::pause() -*/ - -/*! - \fn void Phonon::VideoPlayer::stop() - - Stops the playback. - - \sa MediaObject::stop() -*/ - -/*! - \fn void Phonon::VideoPlayer::seek(qint64 ms) - - Seeks to the requested time. Note that the backend is free to - ignore the seek request if the media source isn't seekable; you - can check this by asking the media object of the VideoPlayer. - - \snippet doc/src/snippets/videomedia.cpp 0 - - The \a ms parameter is the time in milliseconds from the start of - the media. - - The call is asynchronous, so currentTime() can still be the old - value right after this method was called. If all you need is a - slider that shows the current position and allows the user to - seek, use the class SeekSlider. - - \sa MediaObject::seek(), MediaObject::isSeekable(), mediaObject() -*/ - -/*! - \fn void Phonon::VideoPlayer::setVolume(float volume) - - Sets the \a volume of the output as voltage factor. - - 1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0% -*/ - -/*! - \fn MediaObject *Phonon::VideoPlayer::mediaObject() const - - Returns the media object being used by the player. - - The media object can be accessed directly instead of using the - \l{VideoPlayer}s convenience functions, e.g., play() and stop(). - It is also possible to give the object to other Phonon widgets, - e.g., a \l{Phonon::}{SeekSlider} or a \l{Phonon::}{VolumeSlider}. - - \sa Phonon::SeekSlider, Phonon::MediaObject -*/ - -/*! - \fn AudioOutput *Phonon::VideoPlayer::audioOutput() const - - Returns the audio output object being used by the player. - -*/ - -/*! - \fn VideoWidget *Phonon::VideoPlayer::videoWidget() const - - Returns the video widget being used by the player. -*/ - -/*! - \fn void Phonon::VideoPlayer::finished() - - This signal is emitted when the playback finished. - -*/ - -/*! - \class Phonon::VideoWidgetPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::MediaObject - \inmodule Phonon - \inheaderfile Phonon/MediaObject - \since 4.4 - \brief The MediaObject class provides an interface for media playback. - - - The media object manages a \l{Phonon::}{MediaSource}, which - supplies the media object with multimedia content, e.g., from a - file. A playback in Phonon is always started by calling the - \l{Phonon::MediaObject::}{play()} function. - - The state of play (play, pause, stop, seek) is controlled by the - media object, and you can also query the current - \l{Phonon::MediaObject::}{state()}. It keeps track of the playback - position in the media stream, and emits the - \l{Phonon::MediaObject::}{tick()} signal when the current position - in the stream changes. - - Notice that most functions of this class are asynchronous, so you - cannot rely on that a state is entered after a function call - before you receive the \l{Phonon::MediaObject::}{stateChanged()} - signal. The description of the \l{Phonon::}{State} enum gives a - description of the different states. - - Before play() is called, the media object should be connected to - \l{Sinks}{output nodes}, which outputs the media to the - underlying hardware. The output nodes required are dependent on - the contents of the multimedia file that is played back. Phonon - has currently two output nodes: the \l{Phonon::}{AudioOutput} for - audio content and \l{Phonon::}{VideoWidget} for video content. If - a \l{Phonon::}{MediaSource} contains both audio and video, both - nodes need to be connected to the media object. - - \snippet snippets/phonon.cpp 4 - \snippet snippets/phonon.cpp 5 - - The media object can queue sources for playback. When it has - finished to play one source, it will start playing the next in the - queue; the new source is then removed from the queue. The - queue can be altered at any time. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 7 - - You can also make use of the - \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is - guaranteed to be emitted in time for altering the queue. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 8 - - When playback is finishing, i.e., when a media source has been - played to the end and the queue is empty, several signals are - emitted. First, the media object will emit aboutToFinish() - - shortly before the playback has finished - and then finished(). - The stateChanged() signal will also be emitted with - \l{Phonon::}{PausedState}, which is the state the media object - takes when the playback is finished. If you wish to enter another - state, you can connect a slot to finished() and set a new state - there. - - The media object resolves the meta information, such as title, - artist, and album. The meta data is not resolved immediately after - a new source is provided, but will be resolved before the object - leaves the \l{Phonon::}{LoadingState}. The data is queried by - string keys - which should follow the Ogg Vorbis specification - \l http://xiph.org/vorbis/doc/v-comment.html - or by using the - \l{Phonon::}{MetaData} enum. The data available will depend on the - type and content of the individual media files. metaDataChanged() - will be emitted when the media object has resolved new meta data. - - Errors encountered during playback and loading of media sources - are reported by emitting a state changed signal with - \l{Phonon::}{ErrorState}. The severity of the error can be queried - by the \l{Phonon::}{ErrorType}. With a \l{Phonon::}{NormalError}, - it might be possible to continue the playback, for instance, if - only audio playback fails for a media source which also has video. - A \l{Phonon::}{FatalError} indicates that Phonon cannot continue - playback of the current source, but it is possible to try with a - different one. A user readable error message is given by - errorString(). - - \sa Phonon::MediaSource, Phonon::AudioOutput, VideoWidget, - {Music Player Example}, {Phonon Overview}, Phonon::VideoPlayer, - Phonon::createPlayer(), {Phonon Module} - -*/ - -/*! - \property Phonon::MediaObject::transitionTime - \brief Defines the time between playback of two media sources - in the media queue. - - A positive transition time defines a gap of silence between queued - media sources. - - A transition time of 0 ms requests gapless playback (i.e., the - next source in the media queue starts immediately after the - playback of the current source finishes). - - A negative transition time defines a crossfade between the queued - media sources. - - Defaults to 0 (gapless playback). - - \warning This feature might not work reliably with every - backend. -*/ - -/*! - \property Phonon::MediaObject::prefinishMark - \brief the time when the prefinishMarkReached signal is emitted before playback ends. - - This property specifies the time in milliseconds the - prefinishMarkReached() signal is emitted before the playback - finishes. A value of \c 0 disables the signal. The signal is only - emitted for the last source in the \l{queue()}{media queue}. - - Defaults to \c 0 (disabled). - - \warning For some media data the total time cannot be determined - accurately, therefore the accuracy of the prefinishMarkReached signal - can be bad sometimes. Still, it is better to use this method than to - look at totalTime() and currentTime() to emulate the behavior - because the backend might have more information available than your - application does through totalTime() and currentTime(). - - \sa prefinishMarkReached() -*/ - -/*! - \property Phonon::MediaObject::tickInterval - \brief The time interval in milliseconds between two ticks. - - The tick() signal is emitted continuously during playback. - The tick interval is the time that elapses between the emission of two tick signals. - If you set the interval to \c 0 the tick signal gets disabled. - - The tick() signal can, for instance, be used to update widgets - that show the current position in the playback of a media source. - - Defaults to \c 0 (disabled). - - \warning The back-end is free to choose a different tick interval close - to what you asked for. This means that the following code \c may fail: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 9 - On the other hand the following is guaranteed: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 10 - - \sa tick() -*/ - -/*! - \fn Phonon::MediaObject::~MediaObject() - - Destroys the MediaObject. -*/ - -/*! - \fn State Phonon::MediaObject::state() const - - Returns the current Phonon::State of the object. - - \sa Phonon::State, stateChanged() -*/ - -/*! - \fn bool Phonon::MediaObject::hasVideo() const - - Check whether the current media source includes a video stream. - - \warning This information is not resolved immediately after a - media object gets a new source. Listen to the hasVideoChanged() - signal instead. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 11 - - Returns \c true if the media contains video data; otherwise, - returns \c false. - - \sa hasVideoChanged() -*/ - -/*! - \fn bool Phonon::MediaObject::isSeekable() const - - Check whether it is possible to seek, i.e., change the - playback position in the media stream. - - \warning This information is not solved immediately after the - media object gets a new media source. The hasVideoChanged() signal - is emitted after this information is available. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 12 - - Returns \c true if the current media may be seeked; otherwise, - returns \c false. - - \sa seekableChanged() -*/ - -/*! - \fn QStringList Phonon::MediaObject::metaData(const QString &key) const - - Returns the strings associated with the given \a key. - - Backends should use the keys specified in the Ogg Vorbis - documentation: \l http://xiph.org/vorbis/doc/v-comment.html - - Therefore the following should work with every backend: - - Note that meta data is not resolved before the \c - metaDataChanged() signal is emitted. - - A typical usage looks like this: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 13 -*/ - -/*! - \fn QStringList Phonon::MediaObject::metaData(Phonon::MetaData key) const - - Returns the strings associated with the given \a key. - - Same as above except that the keys are defined in the - Phonon::MetaData enum. - - \sa metaDataChanged() -*/ - -/*! - \fn QMultiMap Phonon::MediaObject::metaData() const - - Returns all meta data in a multi map. - - \sa metaDataChanged() -*/ - -/*! - \fn QString Phonon::MediaObject::errorString() const - - Returns a human-readable description of the last error that occurred. - The strings given may vary between backends. - - The error description can be used to give a message to the user - - and the developer - when the stateChanged() signal is emitted with - \l{Phonon::}{ErrorState}. - - \section1 Qt Backends - - On Windows, Qt fetches its error messages from the DirectShow - backend. This usually includes an error number, which can be - looked up in the DirectShow documentation: - \l{http://msdn.microsoft.com/archive/default.asp?url=/archive/en-us/dx81_c/directx_cpp/htm/errorandsuccesscodes.asp}. - - On Linux and Mac, the error strings are not fetched directly from - the backend, but are created in the backend. - - \sa Phonon::ErrorState, stateChanged() -*/ - -/*! - \fn ErrorType Phonon::MediaObject::errorType() const - - Tells your program what to do about the last error that occurred. - Use this function after receiving a stateChanged() signal with - \l{Phonon::}{ErrorState}. - - \sa Phonon::ErrorType, Phonon::ErrorState, stateChanged() -*/ - -/*! - \fn MediaSource Phonon::MediaObject::currentSource() const - - Returns the current media source, i.e., the media source that is - being played back. The current source is either set with - setCurrentSource() or taken from the media queue() when a media - source has finished playing. - - \sa setCurrentSource() -*/ - -/*! - \fn void Phonon::MediaObject::setCurrentSource(const MediaSource &source) - - Set the media source the MediaObject should use. - - After the media object receives a new source, it will enter the - \l{Phonon::}{LoadingState}. When it is ready to play, it - enters the \l{Phonon::}{StoppedState} unless another state - has been requested, e.g., by calling play(). - - \a source is the MediaSource object to the media data. You can - just as well use a QUrl or QString (for a local file) here. - - We show an example: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 14 - - \sa currentSource(), MediaSource -*/ - -/*! - \fn QList Phonon::MediaObject::queue() const - - Returns the queued media sources. - - This does list does not include the current source, - returned by currentSource(). - - \sa enqueue() -*/ - -/*! - \fn void Phonon::MediaObject::setQueue(const QList &sources) - - Set the \a sources to play when the current source has finished. - - This function will overwrite the current queue. - - \sa clearQueue(), enqueue() -*/ - -/*! - \fn void Phonon::MediaObject::setQueue(const QList &urls) - - Set the \a urls to play when the current media has finished. - - This function overwrites the current queue. - - \sa clearQueue(), enqueue() -*/ - -/*! - \fn void Phonon::MediaObject::enqueue(const MediaSource &source) - - Appends \a source to the queue. - - You can use this function to provide the next source after the - aboutToFinish() signal has been emitted. - - \sa aboutToFinish(), setQueue(), clearQueue() -*/ - -/*! - \fn void Phonon::MediaObject::enqueue(const QList &sources) - - Appends multiple \a sources to the queue. - - \sa setQueue(), clearQueue() -*/ - -/*! - \fn void Phonon::MediaObject::enqueue(const QList &urls) - - Appends the URLs in \a urls to the media source queue. - - The function will create \l{MediaSource}s from the \l{QUrl}s, and - append these to the queue. - - \sa setQueue(), clearQueue() -*/ - -/*! - \fn void Phonon::MediaObject::clearQueue() - - Clears the queue of media sources. - - \sa queue(), enqueue() -*/ - -/*! - \fn qint64 Phonon::MediaObject::currentTime() const - - Returns the current time (in milliseconds), i.e., position in the - media stream, of the file currently being played. - - \sa tick(), totalTime(), remainingTime() -*/ - -/*! - \fn qint64 Phonon::MediaObject::totalTime() const - - Get the total time (in milliseconds) of the file currently being played. - - Returns the total time in milliseconds. - - \warning The total time is not defined before the media object - enters the \l{Phonon::}{LoadingState}. - - \sa totalTimeChanged() -*/ - -/*! - \fn qint64 Phonon::MediaObject::remainingTime() const - - Get the remaining time (in milliseconds) of the file currently being played. - - Returns the remaining time in milliseconds. - - \sa totalTime(), currentTime(), totalTimeChanged() -*/ - -/*! - \fn void Phonon::MediaObject::play() - - Requests playback of the media data to start. - - Playback starts when the stateChanged() signal is emitted with - \l{Phonon::}{PlayingState}. - - If the media object is already in a - \l{Phonon::}{PlayingState}, nothing happens. - - \sa stop(), pause(), stateChanged() -*/ - -/*! - \fn void Phonon::MediaObject::pause() - - Requests playback to pause, and the media object to enter the - \l{Phonon::}{PausedState}. If it was paused already, nothing - changes. - - This function is asynchronous and the media might not be paused - immediately. - - \sa play(), stop(), stateChanged() -*/ - -/*! - \fn void Phonon::MediaObject::stop() - - Requests playback to stop, and the media object to enter the - \l{Phonon::}{StoppedState}. If it was stopped before - nothing changes. - - This function is asynchronous and the media might not be - stopped immediately. - - \sa play(), pause(), stateChanged() -*/ - -/*! - \fn void Phonon::MediaObject::seek(qint64 time) - - Requests a seek to the \a time indicated, specified in milliseconds. - - You can only seek if state() is PlayingState, BufferingState or PausedState. - - The call is asynchronous, so currentTime can still be the old - value right after this method was called. If all you need is a - slider that shows the current position and allows the user to - seek, use the class SeekSlider. - - If the current source of the media object is not seekable, calls - to this functions do nothing. - - \sa SeekSlider, tick() -*/ - -/*! - \fn void Phonon::MediaObject::clear() - - Stops and removes all playing and enqueued media sources. - - \sa setCurrentSource() -*/ - - -/*! - \fn void Phonon::MediaObject::stateChanged(Phonon::State newstate, Phonon::State oldstate) - - This signal is emitted when the state of the MediaObject has changed. - The \a oldstate and \a newstate parameters indicate the previous - state and current state of the media object. - - If you are only interested in the new state of the media object, you can - connect this signal to a slot that accepts only one State argument. -*/ - -/*! - \fn void Phonon::MediaObject::tick(qint64 time) - - This signal is emitted in intervals defined by the - \l{tickInterval} property. The current position of the media - object in the stream is given by the \a time parameter. The \a - time is specified in milliseconds. - - \sa tickInterval -*/ - -/*! - \fn void Phonon::MediaObject::metaDataChanged() - - This signal is emitted when the media object has resolved new meta - data. This will happen before the media object leaves the - \l{Phonon::}{LoadingState} after a new source has been set. - - This signal is not emitted when the media object removes the - current data, i.e., when a new source is set or an error has - occurred. If you need to know this, you can listen for the - \l{Phonon::}{ErrorState}, and connect to the - \l{Phonon::MediaObject::}{currentSourceChanged()} signal. - - You can get the new meta data with the metaData methods. - - \sa metaData(), currentSourceChanged(), stateChanged(), Phonon::State -*/ - -/*! - \fn void Phonon::MediaObject::seekableChanged(bool isSeekable) - - This signal is emitted when the media object's ability to seek in - the media stream changes. \a isSeekable is true if it is possible - to seek(); otherwise, it is false. - - Change in the ability to seek in the stream usually happens when - the current source changes or when an error occurs. - - \omit Emitted whenever the return value of isSeekable() - changes. \endomit - - Normally you'll check isSeekable() after setting a new media - source, and then let this signal tell you when seeking is - possible. That way you don't have to poll isSeekable(). -*/ - -/*! - \fn void Phonon::MediaObject::hasVideoChanged(bool hasVideo) - - Emitted whenever the return value of hasVideo() changes, i.e., - the media source being played back contains video. - - Normally you'll check hasVideo() first and then let this signal - tell you whether video is available now or not. That way you - don't have to poll hasVideo(). - - \a hasVideo is true when the stream contains video and adding a - VideoWidget will show a video, and false if there is no video data - in the stream and adding a VideoWidget will show an empty (black) - VideoWidget. -*/ - -/*! - \fn void Phonon::MediaObject::bufferStatus(int percentFilled) - - Provides information about the status of the buffer. - - When a MediaObject is in the \l{Phonon::}{BufferingState}, it will - send this signal regularly. \a percentFilled is a number between 0 - and 100 telling you how much the buffer is filled. - - You can use this signal to show a progress bar to the user when - in BufferingState: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 15 - - Note that the \l{Phonon::}{BufferingState} is commonly used when - waiting for data over a network connection, but this might not be - true for all backends. -*/ - -/*! - \fn void Phonon::MediaObject::finished() - - Emitted when the object has finished playback. It is not emitted - if you call stop(), pause() or load(). It is emitted only when the - current media source has finished playing and the media queue() is - empty, or when a \l{Phonon::FatalError}{fatal error} occurs. - - \warning This signal is not emitted when the current source has - finished and there's another source in the queue. It is only - emitted when the queue is empty. - - \sa currentSourceChanged(), aboutToFinish(), prefinishMarkReached() -*/ - -/*! - \fn void Phonon::MediaObject::currentSourceChanged(const Phonon::MediaSource &newSource) - - Emitted when the MediaObject fetches a new MediaSource from the - queue() and before it enters the \l{Phonon::}{LoadingState} for - the new source. The media object will take a new source from the - queue() when it has finished the playback of the - \l{currentSource()}{current source}. - - \a newSource is the source that starts to play at the time the - signal is emitted. -*/ - -/*! - \fn void Phonon::MediaObject::aboutToFinish() - - Emitted before the playback of the whole queue ends. When this - signal is emitted you still have time to enqueue() a new - MediaSource, so that playback continues. - - If you need a signal to be emitted at a specific time before - playback is finished, you should use the prefinishMarkReached() - signal instead. - - \sa enqueue(), prefinishMark, prefinishMarkReached() -*/ - -/*! - \fn void Phonon::MediaObject::prefinishMarkReached(qint32 msecToEnd) - - Emitted when there are only \a msecToEnd milliseconds left - of playback. - - \warning This signal is not emitted when there is another source - in the queue. It is only emitted when the queue is empty. - - \sa setPrefinishMark(), prefinishMark(), aboutToFinish(), finished() -*/ - -/*! - \fn void Phonon::MediaObject::totalTimeChanged(qint64 newTotalTime) - - This signal is emitted as soon as the total time of the media file is - known or has changed. For most non-local media data the total - time of the media can only be known after some time. At that time the - totalTime function can not return useful information. You have - to wait for this signal to know the real total time. - - \a newTotalTime is the length of the media file in milliseconds. - - \sa totalTime() -*/ - -/*! - \fn MediaObject *Phonon::createPlayer(Phonon::Category category, const MediaSource &source = MediaSource()) - - Convenience function to create a MediaObject and AudioOutput - connected by a path. The \l{Phonon::}{MediaObject} return will - have \a source set as its current source and the specified \a - category. - -*/ - -/*! - \class Phonon::MediaObjectPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \namespace Phonon::BackendCapabilities - \inmodule Phonon - \since 4.4 - \brief The BackendCapabilities namespace contains functions to describe the capabilities of the multimedia backend. - -*/ - -/*! - \class Phonon::BackendCapabilitiesPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::BackendCapabilities::Notifier - \since 4.4 - \inmodule Phonon - \inheaderfile Phonon/BackendCapabilities - - Notifications about backend capabilities. -*/ - -/*! - \fn void Phonon::BackendCapabilities::Notifier::capabilitiesChanged() - - This signal is emitted if the capabilities have changed. This can - happen if the user has requested a backend change. -*/ - -/*! - \fn void Phonon::BackendCapabilities::Notifier::availableAudioOutputDevicesChanged() - - This signal is emitted when audio output devices were plugged or - unplugged. - - Check BackendCapabilities::availableAudioOutputDevices to get the - current list of available devices. -*/ - -/*! - \fn Notifier *Phonon::BackendCapabilities::notifier() - - Use this function to get a QObject pointer to connect to the capabilitiesChanged signal. - - \return a pointer to a QObject. - - The capabilitiesChanged signal is emitted if the capabilities have changed. This can - happen if the user has requested a backend change. - - To connect to this signal do the following: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 16 - - \sa Notifier::capabilitiesChanged() -*/ - -/*! - \fn QStringList Phonon::BackendCapabilities::availableMimeTypes() - - Returns a list of mime types that the Backend can decode. - - \sa isMimeTypeAvailable() -*/ - -/*! - \fn bool Phonon::BackendCapabilities::isMimeTypeAvailable(const QString &mimeType) - - Often all you want to know is whether one given MIME type can be - decoded by the backend. Use this method in favor of - availableMimeTypes() as it can give you a negative answer without - having a backend loaded. - - Returns true if the given \a mimeType is supported by the backend; - otherwise, returns false. - - \sa availableMimeTypes() -*/ - -/*! - \fn QList Phonon::BackendCapabilities::availableAudioOutputDevices() - - Returns the audio output devices the backend supports. - - \return A list of AudioOutputDevice objects that give a name and - description for every supported audio output device. -*/ - -/*! - \fn QList Phonon::BackendCapabilities::availableAudioEffects() - - Returns descriptions for the audio effects the backend supports. - - \return A list of AudioEffectDescription objects that give a name and - description for every supported audio effect. -*/ - -/*! - \internal - \class ObjectDescriptionModelData - \internal - \inmodule Phonon - \brief Data class for models for ObjectDescription objects. -*/ - -/*! - \typedef Phonon::EffectDescription - \relates Phonon::ObjectDescription - - EffectDescription gives a description of an \l{Processors}{audio - effect}. It is a typedef of the \l{Phonon::}{ObjectDescription} - class. Please see its class description for details. - - EffectDescription is used to create audio \l{Phonon::}{Effect}s, - which can be inserted into a media graph, altering an audio - stream. - - \sa Phonon::ObjectDescription, {Capabilities Example}, {Media - Player} - -*/ - -/*! - \class Phonon::ObjectDescriptionModel - \inmodule Phonon - \internal - \since 4.4 - \brief The ObjectDescriptionModel class provides a model from - a list of ObjectDescription objects. - - ObjectDescriptionModel is a read only model that supplies a list - using ObjectDescription::name() for the text and - ObjectDescription::description() for the tooltip. If set the properties - "icon" and "available" are used to set the decoration and disable the - item (disabled only visually, you can still select and drag it). - - It also provides the methods moveUp() and moveDown() to order the list. - Additionally drag and drop is possible so that - QAbstractItemView::InternalMove can be used. - The resulting order of the ObjectDescription::index() values can then be - retrieved using tupleIndexOrder(). - - An example use case would be to give the user a QComboBox to select - the output device: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 17 - - And to retrieve the selected AudioOutputDevice: - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 18 - -*/ - -/*! - \fn inline int Phonon::ObjectDescriptionModel::rowCount(const QModelIndex &parent = QModelIndex()) const - - Returns the number of rows in the model. This value corresponds - to the size of the list passed through setModelData. - - \param parent The optional \a parent argument is used in most models to specify - the parent of the rows to be counted. Because this is a list if a - valid parent is specified the result will always be 0. - - Reimplemented from QAbstractItemModel. - - \sa QAbstractItemModel::rowCount() -*/ - -/*! - \fn inline QVariant Phonon::ObjectDescriptionModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const - - Returns data from the item with the given \a index for the specified - \a role. - If the view requests an invalid index, an invalid variant is - returned. - - Reimplemented from QAbstractItemModel. - - \sa QAbstractItemModel::data(), Qt::ItemDataRole -*/ - -/*! - \fn inline Qt::ItemFlags Phonon::ObjectDescriptionModel::flags(const QModelIndex &index) const - \internal - - Reimplemented to show unavailable devices as disabled (but still - selectable). The \a index of the model index for which to return - flags. - -*/ - -/*! - \fn inline QList Phonon::ObjectDescriptionModel::tupleIndexOrder() const - - Returns a list of indexes in the same order as they are in the - model. The indexes come from the ObjectDescription::index - method. - - This is useful to let the user define a list of preference. -*/ - -/*! - \fn inline int Phonon::ObjectDescriptionModel::tupleIndexAtPositionIndex(int positionIndex) const - - Returns the ObjectDescription::index for the tuple - at the given position \a positionIndex. For example a - QComboBox will give you the currentIndex as the - position in the list. But to select the according - AudioOutputDevice using AudioOutputDevice::fromIndex - you can use this method. - - \param positionIndex The position in the list. -*/ - -/*! - \class Phonon::ObjectDescriptionModelDataPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn inline QMimeData *Phonon::ObjectDescriptionModel::mimeData(const QModelIndexList &indexes) const - \internal - - Returns the MIME data that dropMimeData() can use to create new - items. -*/ - -/*! - \fn inline void Phonon::ObjectDescriptionModel::moveUp(const QModelIndex &index) - - Moves the item at the given \a index up. In the resulting list - the items at index.row() and index.row() - 1 are swapped. - - Connected views are updated automatically. -*/ - -/*! - \fn inline void Phonon::ObjectDescriptionModel::moveDown(const QModelIndex &index) - - Moves the item at the given \a index down. In the resulting list - the items at index.row() and index.row() + 1 are swapped. - - Connected views are updated automatically. -*/ - -/*! - \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(QObject *parent = 0) - - Constructs a ObjectDescription model with the - given \a parent. -*/ - -/*! - \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(const QList > &data, QObject *parent = 0) - - Constructs a ObjectDescription model with the - given \a parent and the given \a data. -*/ - -/*! - \fn inline void Phonon::ObjectDescriptionModel::setModelData(const QList > &data) - - Sets the model data using the list provided by \a data. - - All previous model data is cleared. -*/ - -/*! - \fn inline QList > Phonon::ObjectDescriptionModel::modelData() const - - Returns the model data. - - As the order of the list might have changed this can be different - to what was set using setModelData(). -*/ - -/*! - \fn inline ObjectDescription Phonon::ObjectDescriptionModel::modelData(const QModelIndex &index) const - - Returns one ObjectDescription of the model data for the given \a index. -*/ - -/*! - \fn inline Qt::DropActions Phonon::ObjectDescriptionModel::supportedDropActions() const - - This model supports drag and drop to copy or move - items. -*/ - -/*! - \fn inline bool Phonon::ObjectDescriptionModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) - - Accept drops from other models of the same ObjectDescriptionType. - - The \a data is dropped at the given \a row and \a column; you - also receive the \a parent model index. - - If a valid \a parent is given the dropped items will be inserted - above that item. -*/ - -/*! - \fn inline bool Phonon::ObjectDescriptionModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex()) - - Removes count rows starting with the given row. - - If a valid \a parent is given no rows are removed since this is a - list model. - - Returns true if the rows were successfully removed; otherwise returns false. -*/ - -/*! - \fn inline QStringList Phonon::ObjectDescriptionModel::mimeTypes() const - - Returns a list of supported drag and drop MIME types. Currently - it only supports one type used internally. -*/ - -/*! - \class Phonon::EffectInterface - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::Effect - \inmodule Phonon - \inheaderfile Phonon/Effect - \since 4.4 - \brief The Effect class is used to transform audio streams. - - An effect is a media node which is inserted into a path between a - \l{Phonon::}{MediaObject} and an audio output node, for instance, - an \l{Phonon::}{AudioOutput}. The Effect transforms the media - stream on that path. - - Examples may include simple modifiers, such as fading or pitch - shifting, and more complex mathematical transformations. You can - query the backend for available effects with - BackendCapabilities::availableAudioEffects(). Note that the - effects available is dependent on the underlying system - (DirectDraw, GStreamer, or QuickTime). - - In order to use an effect, insert it into the path as follows: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 19 - - The effect will immediately begin applying it's transformations on - the path. To stop it, remove the Effect from the path. - - To create an effect, you use the \l{Phonon::}{EffectDescription} - class, which you get from - \l{BackendCapabilities::}{availableAudioEffects()}. We give a code - example below. - - \snippet doc/src/snippets/audioeffects.cpp 0 - - An effect can have one or more parameters, which let you alter how - the effect works, for instance, by specifying the depth of a - reverb effect. See the EffectParameter class description for - details. - - Phonon also provides EffectWidget, which lets the user modify the - parameters of an effect an the fly; e.g., with combo boxes. - - \sa {Phonon Module}, EffectWidget -*/ - -/*! - \fn explicit Phonon::Effect::Effect(const EffectDescription &description, QObject *parent = 0) - - Constructs a new effect object with the given \a description and \a parent object. - - The EffectDescription object determines the type of the effect. - - \sa {Phonon::BackendCapabilities::availableAudioEffects()} -*/ - -/*! - \fn Phonon::Effect::Effect(EffectPrivate &dd, QObject *parent) - \internal -*/ - -/*! - \fn Phonon::Effect::~Effect() - \internal -*/ - -/*! - \fn QVariant Phonon::Effect::parameterValue(const EffectParameter ¶meter) const - - Returns the value of the given effect \a parameter. You can fetch - the available parameters for an effect with parameters(). - - \sa setParameterValue(), EffectParameter -*/ - -/*! - \fn void Phonon::Effect::setParameterValue(const EffectParameter ¶meter, const QVariant &value) - - Sets the given effect \a parameter to the specified \a value. - - Parameters for an effect are returned by parameters(). You can - check which QVariant::Type an EffectParameter takes with the - EffectParameter::type() function. - - \sa parameterValue(), EffectParameter -*/ - -/*! - \fn EffectDescription Phonon::Effect::description() const; - - Returns the description of this effect. This is the same - description that was passed to the constructor. -*/ - -/*! - \fn QList Phonon::Effect::parameters() const; - - Returns a list of parameters that this effect provides to control - its behavior. - - \sa EffectParameter, EffectWidget -*/ - -/*! - \class Phonon::EffectPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::AudioOutput - \inmodule Phonon - \inheaderfile Phonon/AudioOutput - \since 4.4 - \brief The AudioOutput class is used to send data to audio output devices. - - The AudioOutput class plays sound over a sound device. The audio - output needs to be connected to a \l{Phonon::}{MediaObject} using - \l{Phonon::}{createPath()}. To start playback, you call - \l{Phonon::MediaObject::}{play()} on the media object. - - \snippet snippets/phonon.cpp 2 - - The class supports changing the volume(). It is also possible to - mute the sound. - - To find out what \l{Phonon::}{AudioOutputDevice}s are available - for AudioOutput, you can call - BackendCapabilities::availableAudioOutputDevices(). A default device is - selected by the backend, but it is possible to set the device to - be used with setOutputDevice(). The outputDeviceChanged() signal - will be emitted if the device changes. - - If an error occurs with the playback, for instance, if no valid - output device is found, the media object will receive a - stateChanged() signal with the \l{Phonon::}{ErrorState}. - - Note that the default values of properties are dependent on the - backend. - - \sa Phonon::VolumeSlider, {Music Player Example}, BackendCapabilities, {Phonon Module} -*/ - -/*! - \property Phonon::AudioOutput::name - - This is the name that appears in Mixer applications that control - the volume of this output. - -*/ - -/*! - \property Phonon::AudioOutput::volume - - This is the current loudness of the output. \omit The volume is a - real value between 0.0 (minimum) and 1.0 (maximum). The volume - follows the sound device used, with 1.0 being the maximum volume - the device can produce. \endomit - - (it is using Stevens' law - to calculate the change in voltage internally). - - \sa volumeDecibel -*/ - -/*! - \property Phonon::AudioOutput::volumeDecibel - - This is the current volume of the output in decibel. - - 0 dB means no change in volume, -6dB means an attenuation of the - voltage to 50% and an attenuation of the power to 25%, -inf dB means - silence. - - \sa volume -*/ - -/*! - \property Phonon::AudioOutput::outputDevice - This property holds the (hardware) destination for the output. - - The default device is determined by the \l{Phonon::}{Category} and the global - configuration for that category. Normally you don't need - to override this setting - letting the user change the global - configuration is the right choice. You can still override the - device though, if you have good reasons to do so. - - \sa outputDeviceChanged() -*/ - -/*! - \property Phonon::AudioOutput::muted - This property tells whether the output is muted. - - Muting the output has the same effect as calling setVolume(0.0). -*/ - -/*! - \fn explicit Phonon::AudioOutput::AudioOutput(Phonon::Category category, QObject *parent = 0) - - Creates a new AudioOutput with the given \a parent that defines - output to a physical device. - - The \a category can be used by mixer applications to group volume - controls of applications into categories. That makes it easier for - the user to identify the programs. - The category is also used for the default output device that is - configured centrally. As an example: often users want to have the - audio signal of a VoIP application go to their USB headset while - all other sounds should go to the internal soundcard. - - \sa Phonon::categoryToString(), outputDevice -*/ - -/*! - \fn explicit Phonon::AudioOutput::AudioOutput(QObject *parent = 0) - - Creates a new AudioOutput that defines output to the system - default device with the \{Phonon::Category::}{NoCategory} category - - \sa Phonon::categoryToString(), outputDevice -*/ - -/*! - \fn Phonon::Category Phonon::AudioOutput::category() const - - Returns the category of this output. - - \sa Phonon::AudioOutput::AudioOutput() -*/ - -/*! - \fn void Phonon::AudioOutput::volumeChanged(qreal newVolume) - - This signal is emitted whenever the volume has changed. As the - volume can change without a call to setVolume (calls over dbus) - this is important to keep a widget showing the current volume up - to date. - - \a newVolume is the new volume level. - - \sa setVolume(), volume() -*/ - -/*! - \fn void Phonon::AudioOutput::mutedChanged(bool muted) - - This signal is emitted when the muted property has changed. The \a muted - value passed by the signal indicates the state of the muted property. - As this property can change by IPC (DBus) calls a UI element showing - the muted property should listen to this signal. -*/ - -/*! - \fn void Phonon::AudioOutput::outputDeviceChanged(const Phonon::AudioOutputDevice &newAudioOutputDevice) - - This signal is emitted when the (hardware) device for the output - has changed. \a newAudioOutputDevice is the new device. - - The change can happen either through setOutputDevice or if the - global configuration for the used category has changed. - - \sa outputDevice -*/ - -/*! - \class Phonon::AudioOutputPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::EffectParameter - \inmodule Phonon - \inheaderfile Phonon/EffectParameter - \since 4.4 - \brief The EffectParameter class describes one parameter of an effect. - - You fetch the parameters of an \l{Phonon::}{Effect} with - \l{Phonon::}{Effect::parameters()}. - - \snippet doc/src/snippets/phononeffectparameter.cpp 0 - - To describe itself, an effect parameter gives a name() and - possibly description() (depending on the backend used). These are - suited to present the effect parameter to the user of a Phonon - application. - - Note that effects are created by the backend, and that - their name and descriptions may vary. - - The value of an effect parameter is stored in a \l{QVariant}, - of which type() is usually \c int or \c double. - - The value is retrieved with \l{Phonon::}{Effect::parameterValue()} - and set with \l{Phonon::Effect::}{setParameterValue()} - both of - which takes the EffectParameter as argument. Note that not all - effect parameters support setting of their value. - - You get the values a parameter can take with possibleValues(); an - empty list is returned if the values are continuous. - - A parameter may also specify default(), minimum(), and maximum() - values. Values are returned as \l{QVariant}s. If the parameter - does not have the requested value, an \l{QVariant::Invalid} - invalid QVariant is returned from these functions. - - The \l{Phonon::}{EffectWidget} provides a widget with which one - can control the parameters of an \l{Phonon::}{Effect}. - - \snippet doc/src/snippets/phononeffectparameter.cpp 1 - - \sa Effect, EffectWidget, {Capabilities Example}, {Phonon Module} -*/ - -/*! - \fn Phonon::EffectParameter::EffectParameter() - \internal - - Creates an invalid effect parameter. -*/ - -/*! - \fn Phonon::EffectParameter::~EffectParameter() - - Destroys the effect parameter. -*/ - -/*! - \fn Phonon::EffectParameter::EffectParameter(const EffectParameter &other) - - Constructs a copy of the \a other effect parameter. -*/ - -/*! - \fn const QString &Phonon::EffectParameter::name() const - - The name of the parameter. Can be used as the label. - - \return A label for the parameter. -*/ - -/*! - \fn const QString &Phonon::EffectParameter::description() const - - The parameter may come with a description (LADSPA doesn't have a - field for this, so don't expect many effects to provide a - description). - - The description can be used for a tooltip or WhatsThis help. - - \return A text describing the parameter. -*/ - -/*! - \fn QVariant::Type Phonon::EffectParameter::type() const - - Returns the parameter type. - - Common types are QVariant::Int, QVariant::Double, QVariant::Bool and QVariant::String. When - QVariant::String is returned you get the possible values from possibleValues. -*/ - -/*! - \fn bool Phonon::EffectParameter::isLogarithmicControl() const - - Returns whether the parameter should be - displayed using a logarithmic scale. This is particularly useful for - frequencies and gains. -*/ - -/*! - \fn QVariant Phonon::EffectParameter::minimumValue() const - - The minimum value to be used for the control to edit the parameter. - - If the returned QVariant is invalid the value is not bounded from - below. -*/ - -/*! - \fn QVariant Phonon::EffectParameter::maximumValue() const - - The maximum value to be used for the control to edit the parameter. - - If the returned QVariant is invalid the value is not bounded from - above. -*/ - -/*! - \fn QVariant Phonon::EffectParameter::defaultValue() const - - The default value. -*/ - -/*! - \fn QVariantList Phonon::EffectParameter::possibleValues() const - - The possible values to be used for the control to edit the parameter. - - if the value of this parameter is to be picked from predefined values - this returns the list (otherwise it returns an empty QVariantList). -*/ - -/*! - \fn bool Phonon::EffectParameter::operator<(const EffectParameter &rhs) const - - \internal - compares the ids of the parameters -*/ - -/*! - \fn bool Phonon::EffectParameter::operator>(const EffectParameter &rhs) const - - \internal - compares the ids of the parameters -*/ - -/*! - \fn bool Phonon::EffectParameter::operator==(const EffectParameter &rhs) const - - \internal - compares the ids of the parameters -*/ - -/*! - \fn Phonon::EffectParameter &Phonon::EffectParameter::operator=(const EffectParameter &other) - - Assigns the \a other effect parameter to this parameter and returns - a reference to this parameter. -*/ - -/*! - \enum Phonon::EffectParameter::Hint - - Only for backend developers: - - Flags to set the return values of isToggleControl(), - isLogarithmicControl(), isIntegerControl(), isBoundedBelow() and - isBoundedAbove(). The values of the flags correspond to the values - used for LADSPA effects. - - \value ToggledHint - If this hint is set it means that - the control has only two states: zero and non-zero - (see isToggleControl()). - - \value LogarithmicHint - LADSPA's SAMPLE_RATE hint needs to be translated by the backend - to normal bounds, as the backend knows the sample rate - and the - frontend doesn't (see isLogarithmicControl()). - - \value IntegerHint See isIntegerControl(). -*/ - -/*! - \fn Phonon::EffectParameter::EffectParameter(int parameterId, - const QString &name, EffectParameter::Hints hints, - const QVariant &defaultValue, const QVariant &min = QVariant(), - const QVariant &max = QVariant(), const QVariantList &values = QVariantList(), - const QString &description = QString()) - - Only to be used by backend implementations: - - Creates a new effect parameter. - - \a parameterId This is a number to uniquely identify the - parameter. The id is used for value() and setValue(). - - \a name is the name/label for this parameter. - - \a hints sets the hints for the type of parameter. - - \a defaultValue The value that should be used as a default. - - \a min is the minimum value allowed for this parameter. You only - need to set this if the BoundedBelowHint is set. - - \a max is the maximum value allowed for this parameter. You only - need to set this if the BoundedAboveHint is set. - - The \a values parameter is the values that the effect parameter - can take (only applies if non-continuous) - - \a description is a descriptive text for the parameter - (explaining what it controls) to be used as a tooltip or - WhatsThis help. -*/ - -/*! - \fn int Phonon::EffectParameter::id() const - - \internal - - Returns the parameter's identifier. -*/ - -/*! - \typedef Phonon::AudioOutputInterface - \inmodule Phonon - \internal -*/ - -/*! - \class Phonon::AudioOutputInterface40 - \inmodule Phonon - \since 4.4 - \internal - \brief Interface for AudioOutput objects - -*/ - -/*! - \fn virtual Phonon::AudioOutputInterface40::~AudioOutputInterface40() - \internal -*/ - -/*! - \fn virtual qreal Phonon::AudioOutputInterface40::volume() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::AudioOutputInterface40::setVolume(qreal) = 0 - \internal -*/ - -/*! - \fn virtual int Phonon::AudioOutputInterface40::outputDevice() const = 0 - \internal -*/ - -/*! - \fn virtual bool Phonon::AudioOutputInterface40::setOutputDevice(int) = 0 - \internal -*/ - -/*! - \class Phonon::Path - \inmodule Phonon - \inheaderfile Phonon/Path - \since 4.4 - \brief The Path class describes connections between media nodes. - - In a \l{Building Graphs}{media graph}, \l{Phonon::}{MediaNode}s - are connected by Paths. The multimedia travels in streams over - these paths. - - You create a path between two media nodes using the static - Phonon::createPath() function, which takes two nodes as arguments. - The first argument will send the media stream to the second. - Please refer to the class description of the individual media - nodes and the Phonon \l{Phonon Overview}{overview} to see which - nodes can be connected to each other. - - Paths are also used to insert audio \l{Phonon::}{Effect}s between - two media nodes. The effect will then alter the stream on the - path. Notice that \l{Phonon::}{Effect}s also are media nodes, but - that insertEffect() - instead of Phonon::createPath() - is used to - insert them into the media graph. - - The following code example shows how to create a path between two - media nodes and insert an effect on that path. - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 20 - - \sa Phonon::MediaNode, Phonon::MediaObject, Phonon::AudioOutput, - Phonon::VideoWidget, {Phonon Module} -*/ - -/*! - \fn Phonon::Path::~Path(); - - Destroys this reference to the Path. If the path was valid the connection is not broken - as both the source and the sink MediaNodes still keep a reference to the Path. - - \sa disconnect() -*/ - -/*! - \fn Phonon::Path::Path(); - - Creates an invalid path. - - You can still make it a valid path by calling reconnect. It is - recommended to use the Phonon::createPath() function to create - paths. - - \sa Phonon::createPath(), isValid() -*/ - -/*! - \fn Phonon::Path::Path(const Path &path); - - Constructs a copy of the other \a path specified. - - This constructor is fast thanks to explicit sharing. -*/ - -/*! - \fn bool Phonon::Path::isValid() const; - - A path is considered valid if it is connected to two media nodes, - in which case this function returns true. If it is connected to - one or no media nodes, it is consider invalid, and this function - will then return false. -*/ - -/*! - \fn Effect *Phonon::Path::insertEffect(const EffectDescription &desc, Effect *insertBefore = 0); - - Creates and inserts an effect into the path. - - You may insert effects of the same class as often as you like, - but if you insert the same object, the call will fail. - - \a desc is the EffectDescription object for the effect to be inserted. - - If you already inserted an effect you can - tell with \a insertBefore in which order the data gets - processed. If this is \c 0 the effect is appended at the end of - the processing list. If the effect has not been inserted before - the method will do nothing and return \c false. - - Returns a pointer to the effect object if it could be inserted - at the specified position. If \c 0 is returned, the effect was not - inserted. - - Below is a code example for inserting an effect into a path: - - \snippet doc/src/snippets/audioeffects.cpp 0 - - \sa removeEffect(), effects() -*/ - -/*! - \fn bool Phonon::Path::insertEffect(Effect *effect, Effect *insertBefore = 0); - - Inserts the given \a effect into the path before the effect specified by \a insertBefore - and returns true if successful; otherwise returns false. - - If \a insertBefore is zero, the effect is appended to the processing list. - - You may insert effects of the same class as often as you like, but if you insert - the same object, the call will fail. - - \a effect will be inserted right before \a insertBefore. If - \a insertBefore is \c 0, the effect is appended at the end of the - processing list. If the effect has not been inserted before the - method will do nothing and return \c false. - - Returns whether the effect could be inserted at the specified - position. If \c false is returned the effect was not inserted. - - \sa removeEffect(), effects() -*/ - -/*! - \fn bool Phonon::Path::removeEffect(Effect *effect); - - Removes the given \a effect from the path and returns true; otherwise returns false. - - Removes an \a effect from the path. - - If the effect is deleted while it is still connected, the effect will be removed - automatically. - - \omit - \param effect The effect to be removed. - - \return Returns whether the call was successful. If it returns - \c false the effect could not be found in the path, meaning it - has not been inserted before. - \endomit - - \sa insertEffect(), effects() -*/ - -/*! - \fn QList Phonon::Path::effects() const; - - Returns a list of Effect objects that are currently - used as effects. The order in the list determines the order the - signal is sent through the effects. - - \return A list with all current effects. - - \sa insertEffect(), removeEffect() -*/ - -/*! - \fn bool Phonon::Path::reconnect(MediaNode *source, MediaNode *sink); - - Changes the media nodes the path is connected to by connecting the path - to the \a source and \a sink nodes specified. Returns true if successful; - otherwise returns false. - - If unsuccessful, the path remains connected to the same nodes as before. - - \sa Phonon::createPath(), {Phonon Overview} -*/ - -/*! - \fn bool Phonon::Path::disconnect(); - - Tries to disconnect the path from the MediaNodes it is connected to, returning - true if successful or false if unsuccessful. - - If successful, the path is invalidated: isValid() will returns false. -*/ - -/*! - \fn Path &Phonon::Path::operator=(const Path &p); - - Assigns \a p to this Path and returns a reference to this Path. - - This operation is fast thanks to explicit sharing. -*/ - -/*! - \fn bool Phonon::Path::operator==(const Path &p) const; - - Returns true if this Path is equal to \a p; otherwise returns false; -*/ - -/*! - \fn bool Phonon::Path::operator!=(const Path &p) const; - - Returns true if this Path is not equal to \a p; otherwise returns false. -*/ - -/*! - \fn MediaNode *Phonon::Path::source() const; - - Returns the source MediaNode used by the path. -*/ - -/*! - \fn MediaNode *Phonon::Path::sink() const; - - Returns the sink MediaNode used by the path. -*/ - -/*! - \fn Path Phonon::createPath(MediaNode *source, MediaNode *sink); - - \relates Phonon::Path - Creates a new Path connecting the two MediaNodes \a source and \a sink. - - The implementation will automatically select the right format and media type. E.g. connecting a - MediaObject and AudioOutput will create a Path object connecting the audio. This might be - represented as PCM or perhaps even AC3 depending on the AudioOutput object. - - \param source The MediaNode to connect an output from - \param sink The MediaNode to connect to. -*/ - -/*! - \class Phonon::PathPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::MediaObjectInterface - \inmodule Phonon - \since 4.4 - \internal - \brief Backend interface for media sources. - - The backend implementation has to provide two signals, that are not defined - in this interface: - \list - \o \target phonon_MediaObjectInterface_stateChanged - void stateChanged(Phonon::State newstate, Phonon::State oldstate) - - Emitted when the state of the MediaObject has changed. - In case you're not interested in the old state you can also - connect to a slot that only has one State argument. - - \param newstate The state the Player is in now. - \param oldstate The state the Player was in before. - - \o \target phonon_MediaObjectInterface_tick - void tick(qint64 time) - - This signal gets emitted every tickInterval milliseconds. - - \param time The position of the media file in milliseconds. - - \sa setTickInterval() - \sa tickInterval() - \endlist - - \sa MediaObject -*/ - -/*! - \fn virtual Phonon::MediaObjectInterface::~MediaObjectInterface() - \internal -*/ - -/*! - \fn virtual qint64 Phonon::MediaObjectInterface::remainingTime() const - \internal -*/ - -/*! - \fn virtual qint32 Phonon::MediaObjectInterface::prefinishMark() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::setPrefinishMark(qint32) = 0 - \internal -*/ - -/*! - \fn virtual qint32 Phonon::MediaObjectInterface::transitionTime() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::setTransitionTime(qint32) = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::play() = 0 - \internal - - Requests the playback to start. - - This method is only called if the state transition to PlayingState is possible. - - The backend should react immediately - by either going into PlayingState or BufferingState if the - former is not possible. -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::pause() = 0 - \internal - - Requests the playback to pause. - - This method is only called if the state transition to PausedState is possible. - - The backend should react as fast as possible. Go to PausedState - as soon as playback is paused. -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::stop() = 0 - \internal - - Requests the playback to be stopped. - - This method is only called if the state transition to StoppedState is possible. - - The backend should react as fast as possible. Go to StoppedState - as soon as playback is stopped. - - A subsequent call to play() will start playback at the beginning of - the media. -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::seek(qint64 milliseconds) = 0 - \internal - - Requests the playback to be seeked to the given time. - - The backend does not have to finish seeking while in this function - (i.e. the backend does not need to block the thread until the seek is - finished; even worse it might lead to deadlocks when using a - ByteStream which gets its data from the thread this function would - block). - - As soon as the seek is done the currentTime() function and - the tick() signal will report it. - - \param milliseconds The time where playback should seek to in - milliseconds. -*/ - -/*! - \fn virtual qint32 Phonon::MediaObjectInterface::tickInterval() const = 0 - \internal - - Return the time interval in milliseconds between two ticks. - - Returns the tick interval that it was set to (might not - be the same as you asked for). -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::setTickInterval(qint32 interval) = 0 - \internal - - Change the interval the tick signal is emitted. Set \a interval to 0 to - disable the signal. - - \a interval tick interval in milliseconds - - Returns the tick interval that it was set to (might not be the same as you - asked for). - -*/ - -/*! - \fn virtual bool Phonon::MediaObjectInterface::hasVideo() const = 0 - \internal - - Check whether the media data includes a video stream. - - Returns true if the media contains video data. -*/ - -/*! - \fn virtual bool Phonon::MediaObjectInterface::isSeekable() const = 0 - \internal - - If the current media may be seeked this function returns true; - otherwise, false. - - Returns whether the current media may be seeked. -*/ - -/*! - \fn virtual qint64 Phonon::MediaObjectInterface::currentTime() const = 0 - \internal - - Get the current time (in milliseconds) of the file currently being played. -*/ - -/*! - \fn virtual Phonon::State Phonon::MediaObjectInterface::state() const = 0 - \internal - - Get the current state. -*/ - -/*! - \fn virtual QString Phonon::MediaObjectInterface::errorString() const = 0 - \internal - - A translated string describing the error. -*/ - -/*! - \fn virtual Phonon::ErrorType Phonon::MediaObjectInterface::errorType() const = 0 - \internal - - Tells your program what to do about the error. - - \sa Phonon::ErrorType -*/ - -/*! - \fn virtual qint64 Phonon::MediaObjectInterface::totalTime() const = 0 - \internal - - Returns the total time of the media in milliseconds. - - If the total time is not know return -1. Do not block until it is - known, instead emit the totalTimeChanged signal as soon as the total - time is known or changes. -*/ - -/*! - \fn virtual MediaSource Phonon::MediaObjectInterface::source() const = 0 - \internal - - Returns the current source. -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::setSource(const MediaSource &) = 0 - \internal - - Sets the current source. When this function is called the MediaObject is - expected to stop all current activity and start loading the new - source (i.e. go into LoadingState). - - It is expected that the - backend now starts preloading the media data, filling the audio - and video buffers and making all media meta data available. It - will also trigger the totalTimeChanged signal. - - If the backend does not know how to handle the source it needs to - change state to Phonon::ErrorState. Don't bother about handling KIO - URLs. It is enough to handle AbstractMediaStream sources correctly. - - \warning Keep the MediaSource object around as long as the backend - uses the AbstractMediaStream returned by the MediaSource. In case - that no other reference to the MediaSource exists and it is set to - MediaSource::autoDelete, the AbstractMediaStream is deleted when the - last MediaSource ref is deleted. -*/ - -/*! - \fn virtual void Phonon::MediaObjectInterface::setNextSource(const MediaSource &source) = 0 - \internal - - Sets the next source to be used for transitions. When a next source - is set playback should continue with the new source. In that case - finished and prefinishMarkReached are not emitted. - - \param source The source to transition to (crossfade/gapless/gap). If - \a source is an invalid MediaSource object then the queue is empty - and the playback should stop normally. - - \warning Keep the MediaSource object around as long as the backend - uses the AbstractMediaStream returned by the MediaSource. In case - that no other reference to the MediaSource exists and it is set to - MediaSource::autoDelete, the AbstractMediaStream is deleted when the - last MediaSource ref is deleted. -*/ - -/*! - \class Phonon::EffectWidget effectwidget.h Phonon/EffectWidget - \inmodule Phonon - \inheaderfile Phonon/EffectWidget - \since 4.4 - \brief The EffectWidget class provides a widget to control the parameters of an Effect. - - The EffectWidget class provides a widget, with which an effects - parameters can be controlled. The widget does not have an API, - and is constructed with the \l{Phonon::}{Effect}, of which - parameters should be controlled. - - \snippet doc/src/snippets/audioeffects.cpp 1 - - The following image shows an example of an effect widget. - - \image effectwidget.png - - Note that some audio effects do not have parameters, and the - widget will then not \l{QWidget::}{show()} at all. - - \sa Effect, BackendCapabilities, EffectDescription, {Phonon Module} -*/ - -/*! - \class Phonon::AbstractAudioOutput - \inmodule Phonon - \internal - \brief Provides a common base class for all audio outputs. - - \sa AudioOutput -*/ - -/*! - \fn Phonon::AbstractAudioOutput::~AbstractAudioOutput() - \internal -*/ - -/*! - \class Phonon::AbstractAudioOutputPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class AudioOutputAdaptor - \inmodule Phonon - \brief Provides an adaptor class for interface org.kde.Phonon.AudioOutput - \internal -*/ - -/*! - \class Phonon::VolumeSlider - \inmodule Phonon - \inheaderfile Phonon/VolumeSlider - \since 4.4 - \brief The VolumeSlider widget provides a slider that is used to control the volume of an audio output device. - - The slider also displays an icon indicating if the volume of the - \l{Phonon::}{AudioOutput} it is connected to is muted. The icon - can be removed with setMuteVisible(). - - It is possible to set the \l{maximumVolume}{maximum} value of the - slider. By default, the minimum and maximum values of the slider - are 0.0 (no sound) to 1.0 (the maximum volume the audio output can - produce). - - Here follows a code example: - - \snippet doc/src/snippets/volumeslider.cpp 0 - - \omit mention how to change the style of the slider. \endomit - - \sa {Phonon Module} -*/ - -/*! - \property Phonon::VolumeSlider::maximumVolume - - This property holds the maximum volume that can be set with this slider. - - By default the maximum value is 1.0 (100%). -*/ - -/*! - \property Phonon::VolumeSlider::orientation - This property holds the orientation of the slider. - - The orientation must be Qt::Vertical (the default) or Qt::Horizontal. -*/ - -/*! - \property Phonon::VolumeSlider::tracking - This property holds whether slider tracking is enabled. - - If tracking is enabled (the default), the volume changes - while the slider is being dragged. If tracking is - disabled, the volume changes only when the user - releases the slider. -*/ - -/*! - \property Phonon::VolumeSlider::pageStep - This property holds the page step. - - The larger of two natural steps that a slider provides and - typically corresponds to the user pressing PageUp or PageDown. - - Defaults to 5 (5% of the voltage). -*/ - -/*! - \property Phonon::VolumeSlider::singleStep - This property holds the single step. - - The smaller of two natural steps that a slider provides and - typically corresponds to the user pressing an arrow key. - - Defaults to 1 (1% of the voltage). -*/ - -/*! - \property Phonon::VolumeSlider::muteVisible - This property holds whether the mute button/icon next to the slider is visible. - - By default the mute button/icon is visible. -*/ - -/*! - \property Phonon::VolumeSlider::iconSize - \brief the icon size used for the mute button/icon. - - The default size is defined by the GUI style. -*/ - -/*! - \fn explicit Phonon::VolumeSlider::VolumeSlider(QWidget *parent = 0) - Constructs a new volume slider with the given \a parent. -*/ - -/*! - \fn explicit Phonon::VolumeSlider::VolumeSlider(AudioOutput *output, QWidget *parent = 0) - Constructs a new volume slider with the given \a output object and \a parent. -*/ - -/*! - \fn Phonon::VolumeSlider::~VolumeSlider() -*/ - -/*! - \fn AudioOutput *Phonon::VolumeSlider::audioOutput() const -*/ - -/*! - \fn void Phonon::VolumeSlider::setAudioOutput(Phonon::AudioOutput *output) - - Sets the audio output object to be controlled by this slider to the specified - \a output object. -*/ - -/*! - \class Phonon::VolumeSliderPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::MediaController - \inmodule Phonon - \inheaderfile Phonon/MediaController - \since 4.4 - \brief The MediaController class controls optional features of a media file/device. - - Some media sources have content that the \l{Phonon::}{MediaObject} - does not provide control over, for instance, chapters in a DVD - file. The functionality the media controller offers is - dependent on the type of media source that is played back. - Commonly, the media controller allows you to: - - \list - \o Navigate between \bold chapters. - \o Navigate between \bold titles. - \o Select between \bold angles. - \endlist - - The \l{Phonon::MediaController::}{Feature} enum explains these - terms in more detail, and their context in playback of CD and DVD. - - The media controller keeps a \l{Phonon::}{MediaObject}, of which - \l{Phonon::MediaObject::currentSource()}{media source} is played - back. You can still call the media object's functions, e.g., - \l{Phonon::MediaObject::}{stop()}; this is all handled correctly - by the media controller. You have the option of letting the media - controller play all titles of a source in sequence by setting the - \l{autoplayTitles()}{autoplay titles} option. - - To start a playback using a media object, you call - \l{Phonon::MediaObject::}{play()} on the media object. To play a - specific title, use setCurrentTitle() and then call - \l{Phonon::MediaObject::}{play()}. - - \warning The Phonon::MediaController class is not yet supported by - Qt backends. - - \sa {Phonon Module} -*/ - -/*! - \fn int Phonon::MediaController::availableAudioChannels() const - \internal -*/ - -/*! - \fn void Phonon::MediaController::availableAudioChannelsChanged() - \internal -*/ - -/*! - \fn QList Phonon::MediaController::availableSubtitles() const - \internal -*/ - -/*! - \fn void Phonon::MediaController::availableSubtitlesChanged() - \internal -*/ - -/*! - \fn AudioChannelDescription Phonon::MediaController::currentAudioChannel() const - \internal -*/ - -/*! - \fn SubtitleDescription Phonon::MediaController::currentSubtitle() const - \internal -*/ - -/*! - \fn void Phonon::MediaController::setCurrentAudioChannel(const Phonon::AudioChannelDescription &stream) - \internal -*/ - -/*! - \fn void Phonon::MediaController::setCurrentSubtitle(const Phonon::SubtitleDescription &stream) - \internal -*/ - -/*! - \fn Phonon::BackendCapabilities::availableAudioCaptureDevices() - \internal -*/ - -/*! - \fn Phonon::BackendCapabilities::Notifier::availableAudioCaptureDevicesChanged() - \internal -*/ - -/*! - \enum Phonon::MediaController::Feature - - The values of this enum are interpreted differently depending on - the type of media source, e.g., DVD or CD. We give examples for - these sources. - - \value Angles In the VOB (DVD) format, it is possible to to give - several video streams of the same scene, each of which displays - the scene from a different angle. The DVD viewer can then change - between these angles. - - \value Chapters In the VOB format, chapters are points in a - single video stream that can be played and seeked to - separately. - - \value Titles On a CD, a title is a separate sound track. On DVD, - a title is a separate VOB file. - -*/ - -/*! - \fn Phonon::MediaController::MediaController(MediaObject *parent) - - Constructs a new MediaController with the media object (\a parent) - to be used by the media controller. - - \sa MediaObject, Feature -*/ - -/*! - \fn Phonon::MediaController::~MediaController() -*/ - -/*! - \fn Features Phonon::MediaController::supportedFeatures() const -*/ - -/*! - \fn int Phonon::MediaController::availableAngles() const - - Returns the available angles that is available for the current - media source. - - \sa Feature -*/ - -/*! - \fn int Phonon::MediaController::currentAngle() const - - Returns the angle that is currently used. - - \sa Feature -*/ - -/*! - \fn int Phonon::MediaController::availableChapters() const - - Returns the number of chapters the current media source - contains. - - \sa Feature -*/ - -/*! - \fn int Phonon::MediaController::currentChapter() const - - Returns the chapter that is currently being played back. - - \sa Feature -*/ - -/*! - \fn int Phonon::MediaController::availableTitles() const - - Returns the number of titles that the current media source - contains. - - \sa Feature -*/ - -/*! - \fn int Phonon::MediaController::currentTitle() const - - Returns the title that is currently played back. - - The current title is 0 (the first) by default. - - \sa Feature -*/ - -/*! - \fn bool Phonon::MediaController::autoplayTitles() const - - Returns true if titles will automatically be played when the media - is played; otherwise returns false. - - The media controller will play the titles of the media source in - sequence when the media object's \l{Phonon::MediaObject::}{play()} - function is called. If the autoplay option is disabled, the media - object will play the - \l{Phonon::}{MediaController::currentTitle()}{current title} and then - finish the playback. - - \sa setAutoplayTitles(), currentTitle() -*/ - -/*! - \fn void Phonon::MediaController::setAutoplayTitles(bool enable) - - Sets the titles to play automatically when the media is played if - \a enable is true; otherwise disables this option. - - The media controller will play the titles of the media source in - sequence when the media object's \l{Phonon::MediaObject::}{play()} - function is called. If the autoplay option is disabled, the media - object will play the - \l{Phonon::}{MediaController::currentTitle()}{current title} and then - finish the playback. - - \sa autoplayTitles(), currentTitle() -*/ - -/*! - \fn void Phonon::MediaController::setCurrentAngle(int angleNumber) - - Sets the current angle to the given \a angleNumber if the media - file or device supports navigation by angle number. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::setCurrentChapter(int chapterNumber) - - Sets the current chapter to the given \a chapterNumber if the media - file or device supports navigation by chapter number. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::setCurrentTitle(int titleNumber) - - Skips to the given title \a titleNumber. - - If it was playing before the title change it will start playback on the new title if - autoplayTitles is enabled. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::nextTitle() - - Skips to the next title. - - If it was playing before the title change it will start playback on the next title if - autoplayTitles is enabled. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::previousTitle() - - Skips to the previous title. - - If it was playing before the title change it will start playback on the previous title if - autoplayTitles is enabled. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::availableAnglesChanged(int availableAngles) - - This signal is emitted whenever the number of available angles changes. - The new number of available angles is given by \a availableAngles. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::angleChanged(int angleNumber) - - This signal is emitted whenever the current angle changes. - The new angle number is given by \a angleNumber. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::availableChaptersChanged(int availableChapters) - - This signal is emitted whenever the number of available chapters changes. - The new number of available chapters is given by \a availableChapters. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::chapterChanged(int chapterNumber) - - This signal is emitted whenever the current chapter changes. - The new chapter number is given by \a chapterNumber. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::availableTitlesChanged(int availableTitles) - - This signal is emitted whenever the number of available titles changes. - The new number of available titles is given by \a availableTitles. - - \sa Feature -*/ - -/*! - \fn void Phonon::MediaController::titleChanged(int titleNumber) - - This signal is emitted whenever the current title changes. - The new title number is given by \a titleNumber. - - \sa Feature -*/ - -/*! - \class Phonon::VideoWidget - \inmodule Phonon - \inheaderfile Phonon/VideoWidget - \since 4.4 - \ingroup advanced - \ingroup multimedia - \brief The VideoWidget class provides a widget that is used to display video. - - The VideoWidget class renders the video of a media stream on a - QWidget. It is connected to the \l{Phonon::}{MediaObject}, of - which video stream it should render. You connect the two objects - using the Phonon::createPath() function. - - The widget has some possibilities to manipulate the video - stream. You can change the brightness(), hue(), saturation(), - and contrast(). - - Resizing of the video is handled automatically, but you can affect - the way the video is resized with the aspectRatio and scaleMode - properties. By default, the widget will use the aspect ratio of - the video stream itself. - - The video widget takes the size of the video when it receives a new video - stream (i.e., when a new MediaSource is set on the MediaObject to which it is - connected). If you need to know the size of the video, you can call - \l{QWidget::}{sizeHint()} after the video has been loaded (i.e., after the - MediaObject leaves the \l{Phonon::}{LoadingState}). - - It is also possible to go to \l{fullScreen}{full screen} mode. - - A typical example of usage follows below: - - \snippet doc/src/snippets/code/doc_src_phonon-api.qdoc 21 - - \sa {Phonon Module} -*/ - -/*! - \fn Phonon::VideoWidget::VideoWidget(QWidget *parent = 0) - - Constructs a new video widget with the specified \a parent. -*/ - -/*! - \fn Phonon::VideoWidget::VideoWidget(VideoWidgetPrivate &d, QWidget *parent) - \internal - - Constructs a new video widget with the specified \a parent. -*/ - -/*! - \fn bool Phonon::VideoWidget::event(QEvent *) - \reimp -*/ - -/*! - \fn void Phonon::VideoWidget::mouseMoveEvent(QMouseEvent *) - \reimp -*/ - -/*! - \enum Phonon::VideoWidget::ScaleMode - - The ScaleMode enum describes how to treat aspect ratio during - resizing of video. - - \value FitInView The video will be fitted to fill the view - keeping aspect ratio. - \value ScaleAndCrop The video is scaled -*/ - -/*! - \property Phonon::VideoWidget::fullScreen - This property holds whether the video is shown using the complete - screen. - - The property differs from QWidget::fullScreen in that it is - writeable. - - By default the widget is not shown in fullScreen. - - \warning When switching to full screen mode using setFullScreen(), - the widget onto which the video is rendered is shown as a - top-level window. Key event forwarding is handled by VideoWidget, - but if you need to handle other events, e.g., mouse events, you - should handle fullscreen mode yourself. -*/ - -/*! - \property Phonon::VideoWidget::aspectRatio - Defaults to AspectRatioAuto. - - \sa AspectRatio -*/ - -/*! - \property Phonon::VideoWidget::scaleMode - - If the size of the widget and the size of the video are not equal. - The video will be zoomed to fit the widget. The smaller zoom - (AddBarsScaleMode) adds black bars at the left/right or top/bottom to - make all of the image visible (default). The bigger zoom (ExpandMode) - fills the widget completely, keeping all information in one direction - and leaving parts of the image outside of the widget in the other - direction. -*/ - -/*! - \property Phonon::VideoWidget::brightness - - This property holds brightness of the video. - - Default is 0. Acceptable values are in range of -1, 1. -*/ - -/*! - \property Phonon::VideoWidget::contrast - - This property holds the contrast of the video. - - Default is 0. Acceptable values are in range of -1, 1. -*/ - -/*! - \property Phonon::VideoWidget::hue - - This property holds the hue of the video. - - Default is 0. Acceptable values are in range of -1, 1. -*/ - -/*! - \property Phonon::VideoWidget::saturation - - This property holds saturation of the video. - - Default is 0. Acceptable values are in range of -1, 1. -*/ - -/*! - \enum Phonon::VideoWidget::AspectRatio - - Defines the width:height to be used for the video. - - \value AspectRatioAuto - Let the decoder find the aspect ratio automatically from the - media file (this is the default). - - \value AspectRatioWidget - Fits the video into the widget making the aspect ratio depend - solely on the size of the widget. This way the aspect ratio - is freely resizeable by the user. - - \value AspectRatio4_3 - Make width/height == 4/3, which is the old TV size and - monitor size (1024/768 == 4/3). (4:3) - - \value AspectRatio16_9 - Make width/height == 16/9, which is the size of most current - media. (16:9) -*/ - -/*! - \fn void Phonon::VideoWidget::exitFullScreen() - - Convenience slot, calling setFullScreen(false) -*/ - - -/*! - \fn void Phonon::VideoWidget::enterFullScreen() - - Convenience slot, calling setFullScreen(true) -*/ - -/*! - \class Phonon::VideoWidgetInterface - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn virtual Phonon::VideoWidgetInterface::~VideoWidgetInterface() -*/ - -/*! - \fn virtual Phonon::VideoWidget::AspectRatio Phonon::VideoWidgetInterface::aspectRatio() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setAspectRatio(Phonon::VideoWidget::AspectRatio ratio) = 0 - \internal -*/ - -/*! - \fn virtual qreal Phonon::VideoWidgetInterface::brightness() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setBrightness(qreal) = 0 - \internal -*/ - -/*! - \fn virtual Phonon::VideoWidget::ScaleMode Phonon::VideoWidgetInterface::scaleMode() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setScaleMode(Phonon::VideoWidget::ScaleMode mode) = 0 - \internal -*/ - -/*! - \fn virtual qreal Phonon::VideoWidgetInterface::contrast() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setContrast(qreal) = 0 - \internal -*/ - -/*! - \fn virtual qreal Phonon::VideoWidgetInterface::hue() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setHue(qreal) = 0 - \internal -*/ - -/*! - \fn virtual qreal Phonon::VideoWidgetInterface::saturation() const = 0 - \internal -*/ - -/*! - \fn virtual void Phonon::VideoWidgetInterface::setSaturation(qreal) = 0 - \internal -*/ - -/*! - \fn virtual QWidget *Phonon::VideoWidgetInterface::widget() = 0 - \internal -*/ - -/*! - \class Phonon::PlatformPlugin - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn virtual AbstractMediaStream *Phonon::PlatformPlugin::createMediaStream(const QUrl &url, QObject *parent) = 0 - - Creates a AbstractMediaStream object with the given \a parent that provides the data - for the given URL specified by \a url. - \omit - On KDE this uses KIO. - \endomit -*/ - -/*! - \fn virtual QIcon Phonon::PlatformPlugin::icon(const QString &name) const = 0 - - Returns the icon for the given icon name. -*/ - -/*! - \fn virtual void Phonon::PlatformPlugin::notification(const char *notificationName, const QString &text, - const QStringList &actions, QObject *receiver, const char *actionSlot) const = 0 - - Shows a notification pop-up with the given \a notificationName and \a text. - Each action in the associated list of \a actions is connected to the \a actionSlot - of the specified \a receiver object, which is expected to act on the actions as - they are triggered by the user. -*/ - -/*! - \fn virtual QString Phonon::PlatformPlugin::applicationName() const = 0 - - Returns the name of the application. For most Qt application this is - QCoreApplication::applicationName(), but for KDE this is overridden by KAboutData. -*/ - - -/*! - \fn virtual QObject *Phonon::PlatformPlugin::createBackend() = 0 - - Creates a backend object. This way the platform can decide the backend preference. -*/ - -/*! - \fn virtual QObject *Phonon::PlatformPlugin::createBackend(const QString &library, const QString &version) = 0 - - Using the library loader of the platform, loads a given backend provided the - specified \a library and \a version. -*/ - -/*! - \fn virtual bool Phonon::PlatformPlugin::isMimeTypeAvailable(const QString &mimeType) const = 0 - - Tries to check whether the default backend supports the MIME type specified by \a mimeType - without loading the actual backend library. - \omit - On KDE this reads the MIME type list from the .desktop file of - the backend. - \endomit -*/ - -/*! - \fn virtual void Phonon::PlatformPlugin::saveVolume(const QString &outputName, qreal volume) = 0 - - Saves the volume for the given output. -*/ - -/*! - \fn virtual qreal Phonon::PlatformPlugin::loadVolume(const QString &outputName) const = 0 - - Loads the volume for the given output. -*/ - -/*! - \class Phonon::MediaNode - \inmodule Phonon - \inheaderfile Phonon/MediaNode - \since 4.4 - \brief The MediaNode class is the base class for all nodes in a media graph. - - In all phonon applications, one builds a media graph consisting of - MediaNodes. The graph will take multimedia content, e.g., from a - file, as input. After its nodes have processed the multimedia, the - graph will output the media again, e.g., to a sound card. - - The multimedia content is streamed over \l{Phonon::}{Path}s - between the nodes in the graph. You can query the paths that are - connected to a media node with inputPaths() and outputPaths(). - - You can check whether the node is implemented by the current - backend by calling isValid(). This does not guarantee that an - instance of the class works as expected, but that the backend has - implemented functionality for the class. - - Currently, Phonon has four media nodes: \l{Phonon::}{MediaObject}, - \l{Phonon::}{AudioOutput}, \l{Phonon::}{VideoWidget}, and \l{Phonon::}{Effect}. - Please refer to their class descriptions for details about their usage, and to - find out which nodes can be connected to each other. See also \l{Building - Graphs} in Phonon's \l{Phonon Overview}{overview} document. - - Two nodes are connected to each other using the - Phonon::createPath() or \l{Phonon::}{Path::insertEffect()} - functions (only \l{Phonon::Effect}s use - \l{Phonon::Path::}{insertEffect()}). We show a code example below, - in which we build a media graph for video playback and then query - its media nodes for their \l{Phonon::}{Path}s: - - \snippet doc/src/snippets/medianodesnippet.cpp 0 - - When you create a Phonon application, you will likely build the - graph yourself. This makes isValid() the most useful function of - this class. The other two functions help navigate the graph, which - you do not need to do as you created the nodes yourself. - - \sa {Phonon Overview}, Phonon::MediaObject, - Phonon::AudioOutput, Phonon::VideoWidget, {Phonon Module} -*/ - -/*! - \fn virtual Phonon::MediaNode::~MediaNode() - - Destroys the media node and any paths connecting it to other - nodes. Any \l{Phonon::}{Effect}s connected to these paths will - also be deleted. -*/ - -/*! - \fn bool Phonon::MediaNode::isValid() const - - Returns true if the backend provides an implementation of this - class; otherwise returns false. - - This does not guarantee that instances of the class works as - expected, but that the backend has implemented the functionality - for this class. For instance, Qt's GStreamer backend will return - true for instances of the \l{Phonon::}{AudioOutput} class, even if - there is a problem with GStreamer and it could not play sound. - -*/ - -/*! - \fn QList Phonon::MediaNode::inputPaths() const - - Returns the paths that inputs multimedia to this media node. - - \sa outputPaths() -*/ - -/*! - \fn QList Phonon::MediaNode::outputPaths() const - - Returns the paths to which this media node outputs media. - - \sa inputPaths() -*/ - -/*! - \fn Phonon::MediaNode::MediaNode(MediaNodePrivate &dd) - \internal -*/ - -/*! - \class Phonon::GlobalConfig - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn Phonon::GlobalConfig::GlobalConfig() - \internal -*/ - -/*! - \fn Phonon::GlobalConfig::~GlobalConfig() - \internal -*/ - -/*! - \fn QList Phonon::GlobalConfig::audioOutputDeviceListFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const - \internal -*/ - -/*! - \fn int Phonon::GlobalConfig::audioOutputDeviceFor(Phonon::Category category, int override = AdvancedDevicesFromSettings) const - \internal -*/ - -/*! - \class Phonon::ObjectDescriptionData - \inmodule Phonon - \since 4.4 - \internal - \brief Data class for objects describing devices or features of the backend. - - \sa Phonon::BackendCapabilities -*/ - -/*! - \fn bool Phonon::ObjectDescriptionData::operator==(const ObjectDescriptionData &otherDescription) const - - Returns \c true if this ObjectDescription describes the same - as \a otherDescription; otherwise returns \c false. -*/ - -/*! - \fn QString Phonon::ObjectDescriptionData::name() const - - Returns the name of the capture source. - - \return A string that should be presented to the user to - choose the capture source. -*/ - -/*! - \fn QString Phonon::ObjectDescriptionData::description() const - - Returns a description of the capture source. This text should - make clear what sound source this is, which is sometimes hard - to describe or understand from just the name. - - \return A string describing the capture source. -*/ - -/*! - \fn QVariant Phonon::ObjectDescriptionData::property(const char *name) const - - Returns a named property. - - If the property is not set an invalid value is returned. - - \sa propertyNames() -*/ - -/*! - \fn QList Phonon::ObjectDescriptionData::propertyNames() const - - Returns all names that return valid data when property() is called. - - \sa property() -*/ - -/*! - \fn bool Phonon::ObjectDescriptionData::isValid() const - - Returns true if the Tuple is valid (index != -1); otherwise returns - false. -*/ - -/*! - \fn int Phonon::ObjectDescriptionData::index() const - - A unique identifier for this device/. Used internally - to distinguish between the devices/. - - \return An integer that uniquely identifies every device. -*/ - -/*! - \fn static ObjectDescriptionData *Phonon::ObjectDescriptionData::fromIndex(ObjectDescriptionType type, int index) - \internal -*/ - -/*! - \fn Phonon::ObjectDescriptionData::~ObjectDescriptionData() - \internal -*/ - -/*! - \fn Phonon::ObjectDescriptionData::ObjectDescriptionData(ObjectDescriptionPrivate * = 0) - \internal -*/ - -/*! - \class Phonon::AddonInterface - \inmodule Phonon - \since 4.4 - \internal - \brief Interface for Menu, Chapter, Angle and Title/Track control. -*/ - -/*! - \fn virtual Phonon::AddonInterface::~AddonInterface() - \internal -*/ - -/*! - \enum Phonon::AddonInterface::Interface - - This enum describes the type of interface represented by an AddonInterface object. - - \value NavigationInterface - \value ChapterInterface - \value AngleInterface - \value TitleInterface -*/ - -/*! - \enum Phonon::AddonInterface::NavigationCommand - \internal - \value Menu1Button -*/ - -/*! - \enum Phonon::AddonInterface::ChapterCommand - \internal - \value availableChapters - \value chapter - \value setChapter -*/ - -/*! - \enum Phonon::AddonInterface::AngleCommand - \internal - \value availableAngles - \value angle - \value setAngle -*/ - -/*! - \enum Phonon::AddonInterface::TitleCommand - \internal - \value availableTitles - \value title - \value setTitle - \value autoplayTitles - \value setAutoplayTitles -*/ - -/*! - \fn virtual bool Phonon::AddonInterface::hasInterface(Interface iface) const = 0 - \internal -*/ - -/*! - \fn virtual QVariant Phonon::AddonInterface::interfaceCall(Interface iface, int command, - const QList &arguments) = 0 - \internal -*/ - -/*! - \class Phonon::MediaNodePrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \namespace Phonon::Factory - \inmodule Phonon - \internal -*/ - -/*! - \fn Sender *Phonon::Factory::sender() - - Returns a pointer to the object emitting the signals. - - \sa Sender::backendChanged() -*/ - -/*! - \fn QObject *Phonon::Factory::createMediaObject(QObject *parent = 0) - - Create a new backend object for a MediaObject. - - \return a pointer to the MediaObject the backend provides. -*/ - -/*! - \fn QObject *Phonon::Factory::createEffect(int effectId, QObject *parent = 0) - - Create a new backend object for a Effect. - - \return a pointer to the Effect the backend provides. -*/ - -/*! - \fn QObject *Phonon::Factory::createVolumeFaderEffect(QObject *parent = 0) - - Create a new backend object for a VolumeFaderEffect. - - \return a pointer to the VolumeFaderEffect the backend provides. -*/ - -/*! - \fn QObject *Phonon::Factory::createAudioOutput(QObject *parent = 0) - - Create a new backend object for a AudioOutput. - - \return a pointer to the AudioOutput the backend provides. -*/ - -/*! - \fn QObject *Phonon::Factory::createVideoWidget(QObject *parent = 0) - - Create a new backend object for a VideoWidget. - - \return a pointer to the VideoWidget the backend provides. -*/ - -/*! - \fn QObject *Phonon::Factory::backend(bool createWhenNull = true) - - \return a pointer to the backend interface. -*/ - -/*! - \fn QString Phonon::Factory::identifier() - - Unique identifier for the Backend. Can be used in configuration files - for example. -*/ - - -/*! - \fn QString Phonon::Factory::backendName() - - Get the name of the Backend. - \omit - It's the name from the .desktop file. - \endomit -*/ - -/*! - \fn QString Phonon::Factory::backendComment() - - Get the comment of the Backend. - \omit - It's the comment from the .desktop file. - \endomit -*/ - -/*! - \fn QString Phonon::Factory::backendVersion() - - Get the version of the Backend. - \omit - It's the version from the .desktop file. - \endomit - - The version is especially interesting if there are several versions - available for binary incompatible versions of the backend's media - framework. -*/ - -/*! - \fn QString Phonon::Factory::backendIcon() - - Get the icon (name) of the Backend. - \omit - It's the icon from the .desktop file. - \endomit -*/ - -/*! - \fn QString Phonon::Factory::backendWebsite() - - Get the website of the Backend. - \omit - It's the website from the .desktop file. - \endomit -*/ - -/*! - \fn QObject *Phonon::Factory::registerQObject(QObject *object) - - Registers the given backend \a object with the factory. -*/ - -/*! - \fn bool Phonon::Factory::isMimeTypeAvailable(const QString &mimeType) -*/ - -/*! - \fn void Phonon::Factory::registerFrontendObject(MediaNodePrivate *) - \internal -*/ - -/*! - \fn void Phonon::Factory::deregisterFrontendObject(MediaNodePrivate *) - \internal -*/ - -/*! - \fn void Phonon::Factory::setBackend(QObject *) -*/ - -/*! - \fn PlatformPlugin *Phonon::Factory::platformPlugin() -*/ - -/*! -/*! - \class Phonon::AbstractMediaStreamPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::FrontendInterfacePrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::EffectWidgetPrivate - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::IODeviceStream - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \fn explicit Phonon::IODeviceStream::IODeviceStream(QIODevice *ioDevice, QObject *parent = 0) - \internal - - Creates a new IODeviceStream with the given \a ioDevice and \a - parent. - -*/ - -/*! - \fn Phonon::IODeviceStream::~IODeviceStream() - \internal -*/ - -/*! - \fn void Phonon::IODeviceStream::reset() - \internal -*/ - -/*! - \fn void Phonon::IODeviceStream::needData() - \internal -*/ - -/*! - \fn void Phonon::IODeviceStream::seekStream(qint64) - \internal -*/ - -/*! - \namespace Phonon::Platform - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::EffectDescriptionModel - \inmodule Phonon - \brief provides a item view model containing available audio effects. - -*/ - -/*! - \typedef Phonon::SubtitleDescription - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::SubtitleDescriptionModel - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::AudioChannelDescription - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::AudioChannelDescriptionModel - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::AudioCaptureDevice - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::AudioCaptureDeviceModel - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::CleanUpFunction - \inmodule Phonon - \internal -*/ - -/*! - \typedef Phonon::QObjectPair - \inmodule Phonon - \since 4.4 - \internal - -*/ - -/*! - \typedef Phonon::AudioOutputDeviceModel - \inmodule Phonon - \brief provides an item view model containing available audio output devices. - -*/ - -/*! - \fn uint Phonon::qHash(const Phonon::EffectParameter ¶m) - \internal - -*/ - -/*! - \fn Phonon::CleanUpGlobalStatic::~CleanUpGlobalStatic() - \internal -*/ - -/*! - \class Phonon::ConstIface - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::CleanUpGlobalStatic - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class Phonon::EffectParameterPrivate - \inmodule Phonon - \since 4.4 - \internal - -*/ - -/*! - \class Phonon::QSettingsGroup - \inmodule Phonon - \since 4.4 - \internal - -*/ - -/*! - \class Phonon::MediaNodeDestructionHandler - \inmodule Phonon - \since 4.4 - \internal - -*/ - -/*! - \fn Phonon::MediaNodeDestructionHandler::~MediaNodeDestructionHandler() - \internal - Called from Base::~Base if this object was registered - using BasePrivate::addDestructionHandler(). -*/ - -/*! - \fn Phonon::MediaNodeDestructionHandler::phononObjectDestroyed(MediaNodePrivate *) - \internal -*/ - -/*! - \fn explicit Phonon::EffectWidget::EffectWidget(Effect *effect, QWidget *parent = 0) - \internal - - Constructs a new EffectWidget for the specified \a effect and with - the specified \a parent. -*/ - -/*! - \fn Phonon::EffectWidget::~EffectWidget() - \internal -*/ - -/*! - \fn QDebug Phonon::operator<<(QDebug s, const ObjectDescription &o) - \internal -*/ - -/*! - \class Phonon::ListModelHelper - \inmodule Phonon - \since 4.4 - \internal -*/ - -/*! - \class AudioOutputInterface42 - \inmodule Phonon - \since 4.4 - \internal -*/ - diff --git a/doc/src/q3asciicache.qdoc b/doc/src/q3asciicache.qdoc deleted file mode 100644 index 43537cc..0000000 --- a/doc/src/q3asciicache.qdoc +++ /dev/null @@ -1,465 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3AsciiCache - \brief The Q3AsciiCache class is a template class that provides a cache based on char* keys. - \compat - - Q3AsciiCache is implemented as a template class. Define a template - instance Q3AsciiCache\ to create a cache that operates on - pointers to X (X*). - - A cache is a least recently used (LRU) list of cache items. The - cache items are accessed via \c char* keys. For Unicode keys use - the Q3Cache template instead, which uses QString keys. A Q3Cache - has the same performace as a Q3AsciiCache. - - Each cache item has a cost. The sum of item costs, totalCost(), - will not exceed the maximum cache cost, maxCost(). If inserting a - new item would cause the total cost to exceed the maximum cost, - the least recently used items in the cache are removed. - - Apart from insert(), by far the most important function is find() - (which also exists as operator[]()). This function looks up an - item, returns it, and by default marks it as being the most - recently used item. - - There are also methods to remove() or take() an object from the - cache. Calling \link Q3PtrCollection::setAutoDelete() - setAutoDelete(TRUE)\endlink tells the cache to delete items that - are removed. The default is to not delete items when then are - removed (i.e., remove() and take() are equivalent). - - When inserting an item into the cache, only the pointer is copied, - not the item itself. This is called a shallow copy. It is possible - to make the cache copy all of the item's data (known as a deep - copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a cache and reimplement newItem() if you want deep copies. - - When removing a cache item the virtual function - Q3PtrCollection::deleteItem() is called. Its default implementation - in Q3AsciiCache is to delete the item if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - There is a Q3AsciiCacheIterator which may be used to traverse the - items in the cache in arbitrary order. - - \sa Q3AsciiCacheIterator, Q3Cache, Q3IntCache -*/ - -/*! - \fn Q3AsciiCache::Q3AsciiCache( const Q3AsciiCache &c ) - - \internal - - Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. -*/ - - -/*! - \fn Q3AsciiCache::Q3AsciiCache( int maxCost, int size, bool caseSensitive, bool copyKeys ) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost and which is expected to contain less than - \a size items. - - \a size is actually the size of an internal hash array; it's - usually best to make it prime and at least 50% bigger than the - largest expected number of items in the cache. - - Each inserted item has an associated cost. When inserting a new - item, if the total cost of all items in the cache will exceed \a - maxCost, the cache will start throwing out the older (least - recently used) items until there is enough room for the new item - to be inserted. - - If \a caseSensitive is TRUE (the default), the cache keys are case - sensitive; if it is FALSE, they are case-insensitive. - Case-insensitive comparison only affects the 26 letters in - US-ASCII. If \a copyKeys is TRUE (the default), Q3AsciiCache makes - a copy of the cache keys, otherwise it copies just the const char - * pointer - slightly faster if you can guarantee that the keys - will never change, but very risky. -*/ - -/*! - \fn Q3AsciiCache::~Q3AsciiCache() - - Removes all items from the cache and destroys it. - All iterators that access this cache will be reset. -*/ - -/*! - \fn Q3AsciiCache& Q3AsciiCache::operator=( const Q3AsciiCache &c ) - - \internal - - Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn int Q3AsciiCache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost() totalCost() -*/ - -/*! - \fn int Q3AsciiCache::totalCost() const - - Returns the total cost of the items in the cache. This is an - integer in the range 0 to maxCost(). - - \sa setMaxCost() -*/ - -/*! - \fn void Q3AsciiCache::setMaxCost( int m ) - - Sets the maximum allowed total cost of the cache to \a m. If the - current total cost is greater than \a m, some items are removed - immediately. - - \sa maxCost() totalCost() -*/ - -/*! - \fn uint Q3AsciiCache::count() const - - Returns the number of items in the cache. - - \sa totalCost() size() -*/ - -/*! - \fn uint Q3AsciiCache::size() const - - Returns the size of the hash array used to implement the cache. - This should be a bit bigger than count() is likely to be. -*/ - -/*! - \fn bool Q3AsciiCache::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. -*/ - -/*! - \fn bool Q3AsciiCache::insert( const char *k, const type *d, int c, int p ) - - Inserts the item \a d into the cache using key \a k, and with an - associated cost of \a c. Returns TRUE if the item is successfully - inserted. Returns FALSE if the item is not inserted, for example, - if the cost of the item exceeds maxCost(). - - The cache's size is limited, and if the total cost is too high, - Q3AsciiCache will remove old, least recently used items until there - is room for this new item. - - Items with duplicate keys can be inserted. - - The parameter \a p is internal and should be left at the default - value (0). - - \warning If this function returns FALSE, you must delete \a d - yourself. Additionally, be very careful about using \a d after - calling this function, because any other insertions into the - cache, from anywhere in the application or within Qt itself, could - cause the object to be discarded from the cache and the pointer to - become invalid. -*/ - -/*! - \fn bool Q3AsciiCache::remove( const char *k ) - - Removes the item with key \a k and returns TRUE if the item was - present in the cache; otherwise returns FALSE. - - The item is deleted if auto-deletion has been enabled, i.e., if - you have called \link Q3PtrCollection::setAutoDelete() - setAutoDelete(TRUE)\endlink. - - If there are two or more items with equal keys, the one that was - inserted last is removed. - - All iterators that refer to the removed item are set to point to - the next item in the cache's traversal order. - - \sa take(), clear() -*/ - -/*! - \fn type *Q3AsciiCache::take( const char *k ) - - Takes the item associated with \a k out of the cache without - deleting it and returns a pointer to the item taken out, or 0 - if the key does not exist in the cache. - - If there are two or more items with equal keys, the one that was - inserted last is taken. - - All iterators that refer to the taken item are set to point to the - next item in the cache's traversal order. - - \sa remove(), clear() -*/ - -/*! - \fn void Q3AsciiCache::clear() - - Removes all items from the cache, and deletes them if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink has been - enabled. - - All cache iterators that operate on this cache are reset. - - \sa remove() take() -*/ - -/*! - \fn type *Q3AsciiCache::find( const char *k, bool ref ) const - - Returns the item with key \a k, or 0 if the key does not exist - in the cache. If \a ref is TRUE (the default), the item is moved - to the front of the least recently used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. -*/ - -/*! - \fn type *Q3AsciiCache::operator[]( const char *k ) const - - Returns the item with key \a k, or 0 if \a k does not exist in - the cache, and moves the item to the front of the least recently - used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. - - This is the same as find( k, TRUE ). - - \sa find() -*/ - -/*! - \fn void Q3AsciiCache::statistics() const - - A debug-only utility function. Prints out cache usage, hit/miss, - and distribution information using qDebug(). This function does - nothing in the release library. -*/ - -/*! - \class Q3AsciiCacheIterator - \brief The Q3AsciiCacheIterator class provides an iterator for Q3AsciiCache collections. - \compat - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. If new objects are inserted into the cache - while the iterator is active, the iterator may or may not see - them. - - Multiple iterators are completely independent, even when they - operate on the same Q3AsciiCache. Q3AsciiCache updates all iterators - that refer an item when that item is removed. - - Q3AsciiCacheIterator provides an operator++() and an operator+=() - to traverse the cache; current() and currentKey() to access the - current cache item and its key. It also provides atFirst() and - atLast(), which return TRUE if the iterator points to the first or - last item in the cache respectively. The isEmpty() function - returns TRUE if the cache is empty; and count() returns the number - of items in the cache. - - Note that atFirst() and atLast() refer to the iterator's arbitrary - ordering, not to the cache's internal least recently used list. - - \sa Q3AsciiCache -*/ - -/*! - \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator( const Q3AsciiCache &cache ) - - Constructs an iterator for \a cache. The current iterator item is - set to point to the first item in the \a cache. -*/ - -/*! - \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator (const Q3AsciiCacheIterator & ci) - - Constructs an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current() but moves - independently from there on. -*/ - -/*! - \fn Q3AsciiCacheIterator& Q3AsciiCacheIterator::operator=( const Q3AsciiCacheIterator &ci ) - - Makes this an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently thereafter. -*/ - -/*! - \fn uint Q3AsciiCacheIterator::count() const - - Returns the number of items in the cache over which this iterator - operates. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3AsciiCacheIterator::isEmpty() const - - Returns TRUE if the cache is empty, i.e. count() == 0; otherwise - returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3AsciiCacheIterator::atFirst() const - - Returns TRUE if the iterator points to the first item in the - cache; otherwise returns FALSE. Note that this refers to the - iterator's arbitrary ordering, not to the cache's internal least - recently used list. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3AsciiCacheIterator::atLast() const - - Returns TRUE if the iterator points to the last item in the cache; - otherwise returns FALSE. Note that this refers to the iterator's - arbitrary ordering, not to the cache's internal least recently - used list. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3AsciiCacheIterator::toFirst() - - Sets the iterator to point to the first item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toLast() isEmpty() -*/ - -/*! - \fn type *Q3AsciiCacheIterator::toLast() - - Sets the iterator to point to the last item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toFirst() isEmpty() -*/ - -/*! - \fn Q3AsciiCacheIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3AsciiCacheIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn const char *Q3AsciiCacheIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the cache or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator+=( uint jump ) - - Returns the item \a jump positions after the current item, or 0 - if it is beyond the last item. Makes this the current item. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item, or 0 - if it is before the first item. Makes this the current item. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator++() - - Prefix ++ makes the iterator point to the item just after - current(), and makes that the new current item for the iterator. If - current() was the last item, operator++() returns 0. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator--() - - Prefix -- makes the iterator point to the item just before - current(), and makes that the new current item for the iterator. If - current() was the first item, operator--() returns 0. -*/ - diff --git a/doc/src/q3asciidict.qdoc b/doc/src/q3asciidict.qdoc deleted file mode 100644 index 9a51db1..0000000 --- a/doc/src/q3asciidict.qdoc +++ /dev/null @@ -1,416 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3AsciiDict - \brief The Q3AsciiDict class is a template class that provides a dictionary based on char* keys. - \compat - - Q3AsciiDict is implemented as a template class. Define a template - instance Q3AsciiDict\ to create a dictionary that operates on - pointers to X (X*). - - A dictionary is a collection of key-value pairs. The key is a - char* used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - Q3AsciiDict cannot handle Unicode keys; use the Q3Dict template - instead, which uses QString keys. A Q3Dict has the same - performace as a Q3AsciiDict. - - Example: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 0 - In this example we use a dictionary to keep track of the line - edits we're using. We insert each line edit into the dictionary - with a unique name and then access the line edits via the - dictionary. See Q3PtrDict, Q3IntDict and Q3Dict. - - See Q3Dict for full details, including the choice of dictionary - size, and how deletions are handled. - - \sa Q3AsciiDictIterator, Q3Dict, Q3IntDict, Q3PtrDict -*/ - - -/*! - \fn Q3AsciiDict::Q3AsciiDict( int size, bool caseSensitive, bool copyKeys ) - - Constructs a dictionary optimized for less than \a size entries. - - We recommend setting \a size to a suitably large prime number (a - bit larger than the expected number of entries). This makes the - hash distribution better and will improve lookup performance. - - When \a caseSensitive is TRUE (the default) Q3AsciiDict treats - "abc" and "Abc" as different keys; when it is FALSE "abc" and - "Abc" are the same. Case-insensitive comparison only considers the - 26 letters in US-ASCII. - - If \a copyKeys is TRUE (the default), the dictionary copies keys - using strcpy(); if it is FALSE, the dictionary just copies the - pointers. -*/ - -/*! - \fn Q3AsciiDict::Q3AsciiDict( const Q3AsciiDict &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3AsciiDict::~Q3AsciiDict() - - Removes all items from the dictionary and destroys it. - - The items are deleted if auto-delete is enabled. - - All iterators that access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3AsciiDict &Q3AsciiDict::operator=(const Q3AsciiDict &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared and then each item in \a dict is - inserted into this dictionary. Only the pointers are copied - (shallow copy) unless newItem() has been reimplemented(). -*/ - -/*! - \fn uint Q3AsciiDict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3AsciiDict::size() const - - Returns the size of the internal hash array (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3AsciiDict::resize( uint newsize ) - - Changes the size of the hashtable to \a newsize. The contents of - the dictionary are preserved but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3AsciiDict::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0; - otherwise it returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3AsciiDict::insert( const char *key, const type *item ) - - Inserts the \a key with the \a item into the dictionary. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3AsciiDict::replace( const char *key, const type *item ) - - Replaces an item that has a key equal to \a key with \a item. - - If the item does not already exist, it will be inserted. - - \a item may not be 0. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 1 - - If there are two or more items with equal keys, then the most - recently inserted item will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3AsciiDict::remove( const char *key ) - - Removes the item associated with \a key from the dictionary. - Returns TRUE if successful, i.e. if the key existed in the - dictionary; otherwise returns FALSE. - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary traversal order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3AsciiDict::take( const char *key ) - - Takes the item associated with \a key out of the dictionary - without deleting it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the most - recently inserted item will be taken. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary traversal order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3AsciiDict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that operate on dictionary are reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3AsciiDict::find( const char *key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - This function uses an internal hashing algorithm to optimize - lookup. - - If there are two or more items with equal keys, then the item that - was most recently inserted will be found. - - Equivalent to the [] operator. - - \sa operator[]() -*/ - -/*! - \fn type *Q3AsciiDict::operator[]( const char *key ) const - - Returns the item associated with \a key, or 0 if the key does - not exist in the dictionary. - - This function uses an internal hashing algorithm to optimize - lookup. - - If there are two or more items with equal keys, then the item that - was most recently inserted will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3AsciiDict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3AsciiDict::read( QDataStream &s, - Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3AsciiDict::write(QDataStream &s, Q3PtrCollection::Item item) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3AsciiDictIterator - \brief The Q3AsciiDictIterator class provides an iterator for Q3AsciiDict collections. - \compat - - Q3AsciiDictIterator is implemented as a template class. Define a - template instance Q3AsciiDictIterator\ to create a dictionary - iterator that operates on Q3AsciiDict\ (dictionary of X*). - - Example: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 2 - In the example we insert some line edits into a dictionary, then - iterate over the dictionary printing the strings associated with - those line edits. - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. - - Multiple iterators may independently traverse the same dictionary. - A Q3AsciiDict knows about all the iterators that are operating on - the dictionary. When an item is removed from the dictionary, - Q3AsciiDict updates all the iterators that are referring to the - removed item to point to the next item in the (arbitrary) - traversal order. - - \sa Q3AsciiDict -*/ - -/*! - \fn Q3AsciiDictIterator::Q3AsciiDictIterator( const Q3AsciiDict &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point on the first item in the \a dict. -*/ - -/*! - \fn Q3AsciiDictIterator::~Q3AsciiDictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3AsciiDictIterator::count() const - - Returns the number of items in the dictionary this iterator - operates over. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3AsciiDictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0, - otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3AsciiDictIterator::toFirst() - - Sets the current iterator item to point to the first item in the - dictionary and returns a pointer to the item. If the dictionary is - empty it sets the current item to 0 and returns 0. -*/ - -/*! - \fn Q3AsciiDictIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3AsciiDictIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn const char *Q3AsciiDictIterator::currentKey() const - - Returns a pointer to the key for the current iterator item. -*/ - -/*! - \fn type *Q3AsciiDictIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3AsciiDictIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3AsciiDictIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item, and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/q3cache.qdoc b/doc/src/q3cache.qdoc deleted file mode 100644 index d8799b6..0000000 --- a/doc/src/q3cache.qdoc +++ /dev/null @@ -1,461 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3Cache - \brief The Q3Cache class is a template class that provides a cache based on QString keys. - \compat - - A cache is a least recently used (LRU) list of cache items. Each - cache item has a key and a certain cost. The sum of item costs, - totalCost(), never exceeds the maximum cache cost, maxCost(). If - inserting a new item would cause the total cost to exceed the - maximum cost, the least recently used items in the cache are - removed. - - Q3Cache is a template class. Q3Cache\ defines a cache that - operates on pointers to X, or X*. - - Apart from insert(), by far the most important function is find() - (which also exists as operator[]()). This function looks up an - item, returns it, and by default marks it as being the most - recently used item. - - There are also methods to remove() or take() an object from the - cache. Calling setAutoDelete(TRUE) for a cache tells it to delete - items that are removed. The default is to not delete items when - they are removed (i.e., remove() and take() are equivalent). - - When inserting an item into the cache, only the pointer is copied, - not the item itself. This is called a shallow copy. It is possible - to make the cache copy all of the item's data (known as a deep - copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a cache and reimplement newItem() if you want deep copies. - - When removing a cache item, the virtual function - Q3PtrCollection::deleteItem() is called. The default - implementation deletes the item if auto-deletion is enabled, and - does nothing otherwise. - - There is a Q3CacheIterator that can be used to traverse the items - in the cache in arbitrary order. - - In Q3Cache, the cache items are accessed via QString keys, which - are Unicode strings. If you want to use non-Unicode, plain 8-bit - \c char* keys, use the Q3AsciiCache template. A Q3Cache has the - same performance as a Q3AsciiCache. - - \sa Q3CacheIterator, Q3AsciiCache, Q3IntCache -*/ - -/*! - \fn Q3Cache::Q3Cache( const Q3Cache &c ) - - \internal - - Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. -*/ - - -/*! - \fn Q3Cache::Q3Cache( int maxCost, int size, bool caseSensitive ) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost and which is expected to contain less than - \a size items. - - \a size is actually the size of an internal hash array; it's - usually best to make it a prime number and at least 50% bigger - than the largest expected number of items in the cache. - - Each inserted item has an associated cost. When inserting a new - item, if the total cost of all items in the cache will exceed \a - maxCost, the cache will start throwing out the older (least - recently used) items until there is enough room for the new item - to be inserted. - - If \a caseSensitive is TRUE (the default), the cache keys are case - sensitive; if it is FALSE, they are case-insensitive. - Case-insensitive comparison considers all Unicode letters. -*/ - -/*! - \fn Q3Cache::~Q3Cache() - - Removes all items from the cache and destroys it. All iterators - that access this cache will be reset. -*/ - -/*! - \fn Q3Cache& Q3Cache::operator=( const Q3Cache &c ) - - \internal - - Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn int Q3Cache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost() totalCost() -*/ - -/*! - \fn int Q3Cache::totalCost() const - - Returns the total cost of the items in the cache. This is an - integer in the range 0 to maxCost(). - - \sa setMaxCost() -*/ - -/*! - \fn void Q3Cache::setMaxCost( int m ) - - Sets the maximum allowed total cost of the cache to \a m. If the - current total cost is greater than \a m, some items are deleted - immediately. - - \sa maxCost() totalCost() -*/ - -/*! - \fn uint Q3Cache::count() const - - Returns the number of items in the cache. - - \sa totalCost() -*/ - -/*! - \fn uint Q3Cache::size() const - - Returns the size of the hash array used to implement the cache. - This should be a bit bigger than count() is likely to be. -*/ - -/*! - \fn bool Q3Cache::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. -*/ - -/*! - \fn bool Q3Cache::insert( const QString &k, const type *d, int c, int p ) - - Inserts the item \a d into the cache with key \a k and associated - cost, \a c. Returns TRUE if it is successfully inserted; otherwise - returns FALSE. - - The cache's size is limited, and if the total cost is too high, - Q3Cache will remove old, least recently used items until there is - room for this new item. - - The parameter \a p is internal and should be left at the default - value (0). - - \warning If this function returns FALSE (which could happen, e.g. - if the cost of this item alone exceeds maxCost()) you must delete - \a d yourself. Additionally, be very careful about using \a d - after calling this function because any other insertions into the - cache, from anywhere in the application or within Qt itself, could - cause the object to be discarded from the cache and the pointer to - become invalid. -*/ - -/*! - \fn bool Q3Cache::remove( const QString &k ) - - Removes the item associated with \a k, and returns TRUE if the - item was present in the cache; otherwise returns FALSE. - - The item is deleted if auto-deletion has been enabled, i.e., if - you have called setAutoDelete(TRUE). - - If there are two or more items with equal keys, the one that was - inserted last is removed. - - All iterators that refer to the removed item are set to point to - the next item in the cache's traversal order. - - \sa take(), clear() -*/ - -/*! - \fn type *Q3Cache::take( const QString &k ) - - Takes the item associated with \a k out of the cache without - deleting it, and returns a pointer to the item taken out, or 0 - if the key does not exist in the cache. - - If there are two or more items with equal keys, the one that was - inserted last is taken. - - All iterators that refer to the taken item are set to point to the - next item in the cache's traversal order. - - \sa remove(), clear() -*/ - -/*! - \fn void Q3Cache::clear() - - Removes all items from the cache and deletes them if auto-deletion - has been enabled. - - All cache iterators that operate this on cache are reset. - - \sa remove() take() -*/ - -/*! - \fn type *Q3Cache::find( const QString &k, bool ref ) const - - Returns the item associated with key \a k, or 0 if the key does - not exist in the cache. If \a ref is TRUE (the default), the item - is moved to the front of the least recently used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. -*/ - -/*! - \fn type *Q3Cache::operator[]( const QString &k ) const - - Returns the item associated with key \a k, or 0 if \a k does not - exist in the cache, and moves the item to the front of the least - recently used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. - - This is the same as find( k, TRUE ). - - \sa find() -*/ - -/*! - \fn void Q3Cache::statistics() const - - A debug-only utility function. Prints out cache usage, hit/miss, - and distribution information using qDebug(). This function does - nothing in the release library. -*/ - -/***************************************************************************** - Q3CacheIterator documentation - *****************************************************************************/ - -/*! - \class Q3CacheIterator qcache.h - \brief The Q3CacheIterator class provides an iterator for Q3Cache collections. - \compat - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. If new objects are inserted into the cache - while the iterator is active, the iterator may or may not see - them. - - Multiple iterators are completely independent, even when they - operate on the same Q3Cache. Q3Cache updates all iterators that - refer an item when that item is removed. - - Q3CacheIterator provides an operator++(), and an operator+=() to - traverse the cache. The current() and currentKey() functions are - used to access the current cache item and its key. The atFirst() - and atLast() return TRUE if the iterator points to the first or - last item in the cache respectively. The isEmpty() function - returns TRUE if the cache is empty, and count() returns the number - of items in the cache. - - Note that atFirst() and atLast() refer to the iterator's arbitrary - ordering, not to the cache's internal least recently used list. - - \sa Q3Cache -*/ - -/*! - \fn Q3CacheIterator::Q3CacheIterator( const Q3Cache &cache ) - - Constructs an iterator for \a cache. The current iterator item is - set to point to the first item in the \a cache. -*/ - -/*! - \fn Q3CacheIterator::Q3CacheIterator (const Q3CacheIterator & ci) - - Constructs an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently from there on. -*/ - -/*! - \fn Q3CacheIterator& Q3CacheIterator::operator=( const Q3CacheIterator &ci ) - - Makes this an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently thereafter. -*/ - -/*! - \fn uint Q3CacheIterator::count() const - - Returns the number of items in the cache on which this iterator - operates. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3CacheIterator::isEmpty() const - - Returns TRUE if the cache is empty, i.e. count() == 0; otherwise - it returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3CacheIterator::atFirst() const - - Returns TRUE if the iterator points to the first item in the - cache; otherwise returns FALSE. Note that this refers to the - iterator's arbitrary ordering, not to the cache's internal least - recently used list. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3CacheIterator::atLast() const - - Returns TRUE if the iterator points to the last item in the cache; - otherwise returns FALSE. Note that this refers to the iterator's - arbitrary ordering, not to the cache's internal least recently - used list. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3CacheIterator::toFirst() - - Sets the iterator to point to the first item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toLast() isEmpty() -*/ - -/*! - \fn type *Q3CacheIterator::toLast() - - Sets the iterator to point to the last item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toFirst() isEmpty() -*/ - -/*! - \fn Q3CacheIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3CacheIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn QString Q3CacheIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3CacheIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the cache or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3CacheIterator::operator+=( uint jump ) - - Returns the item \a jump positions after the current item, or 0 if - it is beyond the last item. Makes this the current item. -*/ - -/*! - \fn type *Q3CacheIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item, or 0 - if it is before the first item. Makes this the current item. -*/ - -/*! - \fn type *Q3CacheIterator::operator++() - - Prefix++ makes the iterator point to the item just after current() - and makes that the new current item for the iterator. If current() - was the last item, operator++() returns 0. -*/ - -/*! - \fn type *Q3CacheIterator::operator--() - - Prefix-- makes the iterator point to the item just before - current() and makes that the new current item for the iterator. If - current() was the first item, operator--() returns 0. -*/ - diff --git a/doc/src/q3dict.qdoc b/doc/src/q3dict.qdoc deleted file mode 100644 index 0e6d51d..0000000 --- a/doc/src/q3dict.qdoc +++ /dev/null @@ -1,446 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3Dict - \brief The Q3Dict class is a template class that provides a - dictionary based on QString keys. - \compat - - Q3Dict is implemented as a template class. Define a template - instance Q3Dict\ to create a dictionary that operates on - pointers to X (X *). - - A dictionary is a collection of key-value pairs. The key is a - QString used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - If you want to use non-Unicode, plain 8-bit \c char* keys, use the - Q3AsciiDict template. A Q3Dict has the same performance as a - Q3AsciiDict. If you want to have a dictionary that maps QStrings to - QStrings use QMap. - - The size() of the dictionary is very important. In order to get - good performance, you should use a suitably large prime number. - Suitable means equal to or larger than the maximum expected number - of dictionary items. Size is set in the constructor but may be - changed with resize(). - - Items are inserted with insert(); 0 pointers cannot be inserted. - Items are removed with remove(). All the items in a dictionary can - be removed with clear(). The number of items in the dictionary is - returned by count(). If the dictionary contains no items isEmpty() - returns TRUE. You can change an item's value with replace(). Items - are looked up with operator[](), or with find() which return a - pointer to the value or 0 if the given key does not exist. You can - take an item out of the dictionary with take(). - - Calling setAutoDelete(TRUE) for a dictionary tells it to delete - items that are removed. The default behavior is not to delete - items when they are removed. - - When an item is inserted, the key is converted (hashed) to an - integer index into an internal hash array. This makes lookup very - fast. - - Items with equal keys are allowed. When inserting two items with - the same key, only the last inserted item will be accessible (last - in, first out) until it is removed. - - The Q3DictIterator class can traverse the dictionary, but only in - an arbitrary order. Multiple iterators may independently traverse - the same dictionary. - - When inserting an item into a dictionary, only the pointer is - copied, not the item itself, i.e. a shallow copy is made. It is - possible to make the dictionary copy all of the item's data (a - deep copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a dictionary and reimplement newItem() if you want deep - copies. - - When removing a dictionary item, the virtual function - Q3PtrCollection::deleteItem() is called. Q3Dict's default - implementation is to delete the item if auto-deletion is enabled. - - \sa Q3DictIterator, Q3AsciiDict, Q3IntDict, Q3PtrDict -*/ - - -/*! - \fn Q3Dict::Q3Dict( int size, bool caseSensitive ) - - Constructs a dictionary optimized for less than \a size entries. - - We recommend setting \a size to a suitably large prime number - (e.g. a prime that's slightly larger than the expected number of - entries). This makes the hash distribution better which will lead - to faster lookup. - - If \a caseSensitive is TRUE (the default), keys which differ only - by case are considered different. -*/ - -/*! - \fn Q3Dict::Q3Dict( const Q3Dict &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3Dict::~Q3Dict() - - Removes all items from the dictionary and destroys it. If - setAutoDelete() is TRUE, each value is deleted. All iterators that - access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3Dict &Q3Dict::operator=(const Q3Dict &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared, then each item in \a dict is - inserted into this dictionary. Only the pointers are copied - (shallow copy), unless newItem() has been reimplemented. -*/ - -/*! - \fn uint Q3Dict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3Dict::size() const - - Returns the size of the internal hash array (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3Dict::resize( uint newsize ) - - Changes the size of the hash table to \a newsize. The contents of - the dictionary are preserved, but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3Dict::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0; - otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3Dict::insert( const QString &key, const type *item ) - - Inserts the key \a key with value \a item into the dictionary. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3Dict::replace( const QString &key, const type *item ) - - Replaces the value of the key, \a key with \a item. - - If the item does not already exist, it will be inserted. - - \a item may not be 0. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 0 - - If there are two or more items with equal keys, then the last item - that was inserted will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3Dict::remove( const QString &key ) - - Removes the item with \a key from the dictionary. Returns TRUE if - successful, i.e. if the item is in the dictionary; otherwise - returns FALSE. - - If there are two or more items with equal keys, then the last item - that was inserted will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary's traversal order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3Dict::take( const QString &key ) - - Takes the item with \a key out of the dictionary without deleting - it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the last item - that was inserted will be taken. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary traversal order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3Dict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that operate on the dictionary are reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3Dict::find( const QString &key ) const - - Returns the item with key \a key, or 0 if the key does not exist - in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the [] operator. - - \sa operator[]() -*/ - -/*! - \fn type *Q3Dict::operator[]( const QString &key ) const - - Returns the item with key \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3Dict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3Dict::read( QDataStream &s, Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3Dict::write( QDataStream &s, Q3PtrCollection::Item item ) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3DictIterator - \brief The Q3DictIterator class provides an iterator for Q3Dict collections. - \compat - - Q3DictIterator is implemented as a template class. Define a - template instance Q3DictIterator\ to create a dictionary - iterator that operates on Q3Dict\ (dictionary of X*). - - The traversal order is arbitrary; when we speak of the "first", - "last" and "next" item we are talking in terms of this arbitrary - order. - - Multiple iterators may independently traverse the same dictionary. - A Q3Dict knows about all the iterators that are operating on the - dictionary. When an item is removed from the dictionary, Q3Dict - updates all iterators that are referring to the removed item to - point to the next item in the (arbitrary) traversal order. - - Example: - \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 1 - In the example we insert some pointers to line edits into a - dictionary, then iterate over the dictionary printing the strings - associated with the line edits. - - \sa Q3Dict -*/ - -/*! - \fn Q3DictIterator::Q3DictIterator( const Q3Dict &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point to the first item in the dictionary, \a dict. First - in this context means first in the arbitrary traversal order. -*/ - -/*! - \fn Q3DictIterator::~Q3DictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3DictIterator::count() const - - Returns the number of items in the dictionary over which the - iterator is operating. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3DictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0; - otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3DictIterator::toFirst() - - Resets the iterator, making the first item the first current item. - First in this context means first in the arbitrary traversal - order. Returns a pointer to this item. - - If the dictionary is empty it sets the current item to 0 and - returns 0. -*/ - -/*! - \fn type *Q3DictIterator::operator*() - \internal -*/ - -/*! - \fn Q3DictIterator::operator type*() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - - -/*! - \fn type *Q3DictIterator::current() const - - Returns a pointer to the current iterator item's value. -*/ - -/*! - \fn QString Q3DictIterator::currentKey() const - - Returns the current iterator item's key. -*/ - -/*! - \fn type *Q3DictIterator::operator()() - - Makes the next item current and returns the original current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3DictIterator::operator++() - - Prefix ++ makes the next item current and returns the new current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3DictIterator::operator+=( uint jump ) - \internal - Sets the current item to the item \a jump positions after the current item, - and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is empty, - it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/q3intcache.qdoc b/doc/src/q3intcache.qdoc deleted file mode 100644 index dfff679..0000000 --- a/doc/src/q3intcache.qdoc +++ /dev/null @@ -1,446 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3IntCache - \brief The Q3IntCache class is a template class that provides a cache based on long keys. - \compat - - Q3IntCache is implemented as a template class. Define a template - instance Q3IntCache\ to create a cache that operates on - pointers to X, or X*. - - A cache is a least recently used (LRU) list of cache items, - accessed via \c long keys. Each cache item has a cost. The sum - of item costs, totalCost(), will not exceed the maximum cache - cost, maxCost(). If inserting a new item would cause the total - cost to exceed the maximum cost, the least recently used items in - the cache are removed. - - Apart from insert(), by far the most important function is find() - (which also exists as operator[]). This function looks up an - item, returns it, and by default marks it as being the most - recently used item. - - There are also methods to remove() or take() an object from the - cache. Calling setAutoDelete(TRUE) for a cache tells it to delete - items that are removed. The default is to not delete items when - they are removed (i.e. remove() and take() are equivalent). - - When inserting an item into the cache, only the pointer is copied, - not the item itself. This is called a shallow copy. It is possible - to make the cache copy all of the item's data (known as a deep - copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a dictionary and reimplement newItem() if you want deep - copies. - - When removing a cache item, the item will be automatically - deleted if auto-deletion is enabled. - - There is a Q3IntCacheIterator which may be used to traverse the - items in the cache in arbitrary order. - - \sa Q3IntCacheIterator, Q3Cache, Q3AsciiCache -*/ - -/*! - \fn Q3IntCache::Q3IntCache( const Q3IntCache &c ) - - \internal - - Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn Q3IntCache::Q3IntCache( int maxCost, int size ) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost and which is expected to contain less than - \a size items. - - \a size is actually the size of an internal hash array; it's - usually best to make it prime and at least 50% bigger than the - largest expected number of items in the cache. - - Each inserted item is associated with a cost. When inserting a new - item, if the total cost of all items in the cache will exceed \a - maxCost, the cache will start throwing out the older (least - recently used) items until there is enough room for the new item - to be inserted. -*/ - -/*! - \fn Q3IntCache::~Q3IntCache() - - Removes all items from the cache and then destroys the int cache. - If auto-deletion is enabled the cache's items are deleted. All - iterators that access this cache will be reset. -*/ - -/*! - \fn Q3IntCache& Q3IntCache::operator=( const Q3IntCache &c ) - - \internal - - Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn int Q3IntCache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost() totalCost() -*/ - -/*! - \fn int Q3IntCache::totalCost() const - - Returns the total cost of the items in the cache. This is an - integer in the range 0 to maxCost(). - - \sa setMaxCost() -*/ - -/*! - \fn void Q3IntCache::setMaxCost( int m ) - - Sets the maximum allowed total cost of the cache to \a m. If the - current total cost is greater than \a m, some items are removed - immediately. - - \sa maxCost() totalCost() -*/ - -/*! - \fn uint Q3IntCache::count() const - - Returns the number of items in the cache. - - \sa totalCost() -*/ - -/*! - \fn uint Q3IntCache::size() const - - Returns the size of the hash array used to implement the cache. - This should be a bit larger than count() is likely to be. -*/ - -/*! - \fn bool Q3IntCache::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. -*/ - -/*! - \fn bool Q3IntCache::insert( long k, const type *d, int c, int p ) - - Inserts the item \a d into the cache with key \a k and assigns it - a cost of \a c (default 1). Returns TRUE if it succeeds; otherwise - returns FALSE. - - The cache's size is limited, and if the total cost is too high, - Q3IntCache will remove old, least-used items until there is room - for this new item. - - The parameter \a p is internal and should be left at the default - value (0). - - \warning If this function returns FALSE (for example, the cost \c, - exceeds maxCost()), you must delete \a d yourself. Additionally, - be very careful about using \a d after calling this function. Any - other insertions into the cache, from anywhere in the application - or within Qt itself, could cause the object to be discarded from - the cache and the pointer to become invalid. -*/ - -/*! - \fn bool Q3IntCache::remove( long k ) - - Removes the item associated with \a k, and returns TRUE if the - item was present in the cache; otherwise returns FALSE. - - The item is deleted if auto-deletion has been enabled, i.e. if you - have called setAutoDelete(TRUE). - - If there are two or more items with equal keys, the one that was - inserted most recently is removed. - - All iterators that refer to the removed item are set to point to - the next item in the cache's traversal order. - - \sa take(), clear() -*/ - -/*! - \fn type * Q3IntCache::take( long k ) - - Takes the item associated with \a k out of the cache without - deleting it, and returns a pointer to the item taken out or 0 if - the key does not exist in the cache. - - If there are two or more items with equal keys, the one that was - inserted most recently is taken. - - All iterators that refer to the taken item are set to point to the - next item in the cache's traversal order. - - \sa remove(), clear() -*/ - -/*! - \fn void Q3IntCache::clear() - - Removes all items from the cache, and deletes them if - auto-deletion has been enabled. - - All cache iterators that operate this on cache are reset. - - \sa remove() take() -*/ - -/*! - \fn type * Q3IntCache::find( long k, bool ref ) const - - Returns the item associated with \a k, or 0 if the key does not - exist in the cache. If \a ref is TRUE (the default), the item is - moved to the front of the least recently used list. - - If there are two or more items with equal keys, the one that was - inserted most recently is returned. -*/ - -/*! - \fn type * Q3IntCache::operator[]( long k ) const - - Returns the item associated with \a k, or 0 if \a k does not exist - in the cache, and moves the item to the front of the least - recently used list. - - If there are two or more items with equal keys, the one that was - inserted most recently is returned. - - This is the same as find( k, TRUE ). - - \sa find() -*/ - -/*! - \fn void Q3IntCache::statistics() const - - A debug-only utility function. Prints out cache usage, hit/miss, - and distribution information using qDebug(). This function does - nothing in the release library. -*/ - -/*! - \class Q3IntCacheIterator - \brief The Q3IntCacheIterator class provides an iterator for Q3IntCache collections. - \compat - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. If new objects are inserted into the cache - while the iterator is active, the iterator may or may not see - them. - - Multiple iterators are completely independent, even when they - operate on the same Q3IntCache. Q3IntCache updates all iterators - that refer an item when that item is removed. - - Q3IntCacheIterator provides an operator++(), and an operator+=() to - traverse the cache; current() and currentKey() to access the - current cache item and its key; atFirst() atLast(), which return - TRUE if the iterator points to the first/last item in the cache; - isEmpty(), which returns TRUE if the cache is empty; and count(), - which returns the number of items in the cache. - - Note that atFirst() and atLast() refer to the iterator's arbitrary - ordering, not to the cache's internal least recently used list. - - \sa Q3IntCache -*/ - -/*! - \fn Q3IntCacheIterator::Q3IntCacheIterator( const Q3IntCache &cache ) - - Constructs an iterator for \a cache. The current iterator item is - set to point to the first item in the \a cache (or rather, the - first item is defined to be the item at which this constructor - sets the iterator to point). -*/ - -/*! - \fn Q3IntCacheIterator::Q3IntCacheIterator (const Q3IntCacheIterator & ci) - - Constructs an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently from there on. -*/ - -/*! - \fn Q3IntCacheIterator& Q3IntCacheIterator::operator=( const Q3IntCacheIterator &ci ) - - Makes this an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently thereafter. -*/ - -/*! - \fn uint Q3IntCacheIterator::count() const - - Returns the number of items in the cache on which this iterator - operates. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3IntCacheIterator::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3IntCacheIterator::atFirst() const - - Returns TRUE if the iterator points to the first item in the - cache; otherwise returns FALSE. Note that this refers to the - iterator's arbitrary ordering, not to the cache's internal least - recently used list. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3IntCacheIterator::atLast() const - - Returns TRUE if the iterator points to the last item in the cache; - otherwise returns FALSE. Note that this refers to the iterator's - arbitrary ordering, not to the cache's internal least recently - used list. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3IntCacheIterator::toFirst() - - Sets the iterator to point to the first item in the cache and - returns a pointer to the item. - - Sets the iterator to 0, and returns 0, if the cache is empty. - - \sa toLast() isEmpty() -*/ - -/*! - \fn type *Q3IntCacheIterator::toLast() - - Sets the iterator to point to the last item in the cache and - returns a pointer to the item. - - Sets the iterator to 0, and returns 0, if the cache is empty. - - \sa toFirst() isEmpty() -*/ - -/*! - \fn Q3IntCacheIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3IntCacheIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn long Q3IntCacheIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the cache or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator+=( uint jump ) - - Returns the item \a jump positions after the current item, or 0 if - it is beyond the last item. Makes this the current item. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item, or 0 - if it is beyond the first item. Makes this the current item. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator++() - - Prefix ++ makes the iterator point to the item just after - current(), and makes it the new current item for the iterator. If - current() was the last item, operator--() returns 0. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator--() - - Prefix -- makes the iterator point to the item just before - current(), and makes it the new current item for the iterator. If - current() was the first item, operator--() returns 0. -*/ diff --git a/doc/src/q3intdict.qdoc b/doc/src/q3intdict.qdoc deleted file mode 100644 index cef2e79..0000000 --- a/doc/src/q3intdict.qdoc +++ /dev/null @@ -1,390 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3IntDict - \brief The Q3IntDict class is a template class that provides a dictionary based on long keys.\ - \compat - - Q3IntDict is implemented as a template class. Define a template - instance Q3IntDict\ to create a dictionary that operates on - pointers to X (X*). - - A dictionary is a collection of key-value pairs. The key is an \c - long used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - Example: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 0 - - See Q3Dict for full details, including the choice of dictionary - size, and how deletions are handled. - - \sa Q3IntDictIterator, Q3Dict, Q3AsciiDict, Q3PtrDict -*/ - - -/*! - \fn Q3IntDict::Q3IntDict( int size ) - - Constructs a dictionary using an internal hash array of size \a - size. - - Setting \a size to a suitably large prime number (equal to or - greater than the expected number of entries) makes the hash - distribution better which leads to faster lookup. -*/ - -/*! - \fn Q3IntDict::Q3IntDict( const Q3IntDict &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3IntDict::~Q3IntDict() - - Removes all items from the dictionary and destroys it. - - All iterators that access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3IntDict &Q3IntDict::operator=(const Q3IntDict &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared and then each item in \a dict is - inserted into this dictionary. Only the pointers are copied - (shallow copy), unless newItem() has been reimplemented. -*/ - -/*! - \fn uint Q3IntDict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3IntDict::size() const - - Returns the size of the internal hash array (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3IntDict::resize( uint newsize ) - - Changes the size of the hashtable to \a newsize. The contents of - the dictionary are preserved, but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3IntDict::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3IntDict::insert( long key, const type *item ) - - Insert item \a item into the dictionary using key \a key. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3IntDict::replace( long key, const type *item ) - - If the dictionary has key \a key, this key's item is replaced with - \a item. If the dictionary doesn't contain key \a key, \a item is - inserted into the dictionary using key \a key. - - \a item may not be 0. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 1 - - If there are two or more items with equal keys, then the most - recently inserted item will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3IntDict::remove( long key ) - - Removes the item associated with \a key from the dictionary. - Returns TRUE if successful, i.e. if the \a key is in the - dictionary; otherwise returns FALSE. - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary's traversal - order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3IntDict::take( long key ) - - Takes the item associated with \a key out of the dictionary - without deleting it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the most - recently inserted item will be taken. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary's traversing order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3IntDict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that access this dictionary will be reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3IntDict::find( long key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to operator[]. - - \sa operator[]() -*/ - -/*! - \fn type *Q3IntDict::operator[]( long key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3IntDict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3IntDict::read( QDataStream &s, Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3IntDict::write( QDataStream &s, Q3PtrCollection::Item item ) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3IntDictIterator - \brief The Q3IntDictIterator class provides an iterator for Q3IntDict collections. - \compat - - Q3IntDictIterator is implemented as a template class. Define a - template instance Q3IntDictIterator\ to create a dictionary - iterator that operates on Q3IntDict\ (dictionary of X*). - - Example: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 2 - - Note that the traversal order is arbitrary; you are not guaranteed the - order shown above. - - Multiple iterators may independently traverse the same dictionary. - A Q3IntDict knows about all the iterators that are operating on the - dictionary. When an item is removed from the dictionary, Q3IntDict - updates all iterators that refer the removed item to point to the - next item in the traversal order. - - \sa Q3IntDict -*/ - -/*! - \fn Q3IntDictIterator::Q3IntDictIterator( const Q3IntDict &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point to the 'first' item in the \a dict. The first item - refers to the first item in the dictionary's arbitrary internal - ordering. -*/ - -/*! - \fn Q3IntDictIterator::~Q3IntDictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3IntDictIterator::count() const - - Returns the number of items in the dictionary this iterator - operates over. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3IntDictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise eturns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3IntDictIterator::toFirst() - - Sets the current iterator item to point to the first item in the - dictionary and returns a pointer to the item. The first item - refers to the first item in the dictionary's arbitrary internal - ordering. If the dictionary is empty it sets the current item to - 0 and returns 0. -*/ - -/*! - \fn Q3IntDictIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3IntDictIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn long Q3IntDictIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3IntDictIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3IntDictIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3IntDictIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item, and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/q3memarray.qdoc b/doc/src/q3memarray.qdoc deleted file mode 100644 index b9c1f73..0000000 --- a/doc/src/q3memarray.qdoc +++ /dev/null @@ -1,523 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3MemArray - \brief The Q3MemArray class is a template class that provides arrays of simple types. - \compat - - Q3MemArray is implemented as a template class. Define a template - instance Q3MemArray\ to create an array that contains X items. - - Q3MemArray stores the array elements directly in the array. It can - only deal with simple types (i.e. C++ types, structs, and classes - that have no constructors, destructors, or virtual functions). - Q3MemArray uses bitwise operations to copy and compare array - elements. - - The Q3PtrVector collection class is also a kind of array. Like most - old Qt collection classes, it uses pointers to the contained items. - - Q3MemArray uses explicit sharing with a - reference count. If more than one array shares common data and one - of the arrays is modified, all the arrays are modified. - - The benefit of sharing is that a program does not need to duplicate - data when it is not required, which results in lower memory use - and less copying of data. - - Example: - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 0 - - Program output: - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 1 - - Note concerning the use of Q3MemArray for manipulating structs or - classes: Compilers will often pad the size of structs of odd sizes - up to the nearest word boundary. This will then be the size - Q3MemArray will use for its bitwise element comparisons. Because - the remaining bytes will typically be uninitialized, this can - cause find() etc. to fail to find the element. Example: - - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 2 - - To work around this, make sure that you use a struct where - sizeof() returns the same as the sum of the sizes of the members - either by changing the types of the struct members or by adding - dummy members. - - Q3MemArray data can be traversed by iterators (see begin() and - end()). The number of items is returned by count(). The array can - be resized with resize() and filled using fill(). - - You can make a shallow copy of the array with assign() (or - operator=()) and a deep copy with duplicate(). - - Search for values in the array with find() and contains(). For - sorted arrays (see sort()) you can search using bsearch(). - - You can set the data directly using setRawData() and - resetRawData(), although this requires care. -*/ - -/*! \fn Q3MemArray::operator QVector() const - - Automatically converts the Q3MemArray into a QVector. -*/ - -/*! \typedef Q3MemArray::Iterator - A Q3MemArray iterator. - \sa begin() end() -*/ -/*! \typedef Q3MemArray::ConstIterator - A const Q3MemArray iterator. - \sa begin() end() -*/ -/*! \typedef Q3MemArray::ValueType - \internal -*/ - -/*! - \fn Q3MemArray::Q3MemArray() - - Constructs a null array. - - \sa isNull() -*/ - -/*! - \fn Q3MemArray::Q3MemArray( int size ) - - Constructs an array with room for \a size elements. Makes a null - array if \a size == 0. - - The elements are left uninitialized. - - \sa resize(), isNull() -*/ - -/*! - \fn Q3MemArray::Q3MemArray( const Q3MemArray &a ) - - Constructs a shallow copy of \a a. - - \sa assign() -*/ - -/*! - \fn Q3MemArray::Q3MemArray(const QVector &vector) - - Constructs a copy of \a vector. -*/ - -/*! - \fn Q3MemArray::Q3MemArray(int arg1, int arg2) - - Constructs an array \e{without allocating} array space. The - arguments \a arg1 and \a arg2 should be zero. Use at your own - risk. -*/ - -/*! - \fn Q3MemArray::~Q3MemArray() - - Dereferences the array data and deletes it if this was the last - reference. -*/ - -/*! - \fn Q3MemArray &Q3MemArray::operator=( const Q3MemArray &a ) - - Assigns a shallow copy of \a a to this array and returns a - reference to this array. - - Equivalent to assign( a ). -*/ - -/*! - \fn type *Q3MemArray::data() const - - Returns a pointer to the actual array data. - - The array is a null array if data() == 0 (null pointer). - - \sa isNull() -*/ - -/*! - \fn uint Q3MemArray::nrefs() const - - Returns the reference count for the shared array data. This - reference count is always greater than zero. -*/ - -/*! - \fn uint Q3MemArray::size() const - - Returns the size of the array (maximum number of elements). - - The array is a null array if size() == 0. - - \sa isNull(), resize() -*/ - -/*! - \fn uint Q3MemArray::count() const - - Returns the same as size(). - - \sa size() -*/ - -/*! - \fn bool Q3MemArray::isEmpty() const - - Returns TRUE if the array is empty; otherwise returns FALSE. - - isEmpty() is equivalent to isNull() for Q3MemArray (unlike - QString). -*/ - -/*! - \fn bool Q3MemArray::isNull() const - - Returns TRUE if the array is null; otherwise returns FALSE. - - A null array has size() == 0 and data() == 0. -*/ - -/*! - \fn bool Q3MemArray::resize( uint size, Optimization optim ) - - Resizes (expands or shrinks) the array to \a size elements. The - array becomes a null array if \a size == 0. - - Returns TRUE if successful, or FALSE if the memory cannot be - allocated. - - New elements are not initialized. - - \a optim is either Q3GArray::MemOptim (the default) or - Q3GArray::SpeedOptim. When optimizing for speed rather than memory - consumption, the array uses a smart grow and shrink algorithm that - might allocate more memory than is actually needed for \a size - elements. This speeds up subsequent resize operations, for example - when appending many elements to an array, since the space has - already been allocated. - - \sa size() -*/ - -/*! - \fn bool Q3MemArray::resize( uint size ) - - \overload - - Resizes (expands or shrinks) the array to \a size elements. The - array becomes a null array if \a size == 0. - - Returns TRUE if successful, i.e. if the memory can be allocated; - otherwise returns FALSE. - - New elements are not initialized. - - \sa size() -*/ - -/*! - \fn bool Q3MemArray::truncate( uint pos ) - - Truncates the array at position \a pos. - - Returns TRUE if successful, i.e. if the memory can be allocated; - otherwise returns FALSE. - - Equivalent to resize(\a pos). - - \sa resize() -*/ - -/*! - \fn bool Q3MemArray::fill( const type &v, int size ) - - Fills the array with the value \a v. If \a size is specified as - different from -1, then the array will be resized before being - filled. - - Returns TRUE if successful, i.e. if \a size is -1, or \a size is - != -1 and the memory can be allocated; otherwise returns FALSE. - - \sa resize() -*/ - -/*! - \fn void Q3MemArray::detach() - - Detaches this array from shared array data; i.e. it makes a - private, deep copy of the data. - - Copying will be performed only if the \link nrefs() reference - count\endlink is greater than one. - - \sa copy() -*/ - -/*! - \fn Q3MemArray Q3MemArray::copy() const - - Returns a deep copy of this array. - - \sa detach(), duplicate() -*/ - -/*! - \fn Q3MemArray &Q3MemArray::assign( const Q3MemArray &a ) - - Shallow copy. Dereferences the current array and references the - data contained in \a a instead. Returns a reference to this array. - - \sa operator=() -*/ - -/*! - \fn Q3MemArray &Q3MemArray::assign( const type *data, uint size ) - - \overload - - Shallow copy. Dereferences the current array and references the - array data \a data, which contains \a size elements. Returns a - reference to this array. - - Do not delete \a data later; Q3MemArray will call free() on it - at the right time. -*/ - -/*! - \fn Q3MemArray &Q3MemArray::duplicate( const Q3MemArray &a ) - - Deep copy. Dereferences the current array and obtains a copy of - the data contained in \a a instead. Returns a reference to this - array. - - \sa copy() -*/ - -/*! - \fn Q3MemArray &Q3MemArray::duplicate( const type *data, uint size ) - - \overload - - Deep copy. Dereferences the current array and obtains a copy of - the array data \a data instead. Returns a reference to this array. - The size of the array is given by \a size. - - \sa copy() -*/ - -/*! - \fn Q3MemArray &Q3MemArray::setRawData( const type *data, uint size ) - - Sets raw data and returns a reference to the array. - - Dereferences the current array and sets the new array data to \a - data and the new array size to \a size. Do not attempt to resize - or re-assign the array data when raw data has been set. Call - resetRawData(\a data, \a size) to reset the array. - - Setting raw data is useful because it sets Q3MemArray data without - allocating memory or copying data. - - Example I (intended use): - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 3 - - Example II (you don't want to do this): - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 4 - - \warning If you do not call resetRawData(), Q3MemArray will attempt - to deallocate or reallocate the raw data, which might not be too - good. Be careful. - - \sa resetRawData() -*/ - -/*! - \fn void Q3MemArray::resetRawData( const type *data, uint size ) - - Removes internal references to the raw data that was set using - setRawData(). This means that Q3MemArray no longer has access to - the \a data, so you are free to manipulate \a data as you wish. - You can now use the Q3MemArray without affecting the original \a - data, for example by calling setRawData() with a pointer to some - other data. - - The arguments must be the \a data and length, \a size, that were - passed to setRawData(). This is for consistency checking. - - \sa setRawData() -*/ - -/*! - \fn int Q3MemArray::find( const type &v, uint index ) const - - Finds the first occurrence of \a v, starting at position \a index. - - Returns the position of \a v, or -1 if \a v could not be found. - - \sa contains() -*/ - -/*! - \fn int Q3MemArray::contains( const type &v ) const - - Returns the number of times \a v occurs in the array. - - \sa find() -*/ - -/*! - \fn void Q3MemArray::sort() - - Sorts the array elements in ascending order, using bitwise - comparison (memcmp()). - - \sa bsearch() -*/ - -/*! - \fn int Q3MemArray::bsearch( const type &v ) const - - In a sorted array (as sorted by sort()), finds the first - occurrence of \a v by using a binary search. For a sorted - array this is generally much faster than find(), which does - a linear search. - - Returns the position of \a v, or -1 if \a v could not be found. - - \sa sort(), find() -*/ - -/*! - \fn type &Q3MemArray::operator[]( int index ) const - - Returns a reference to the element at position \a index in the - array. - - This can be used to both read and set an element. Equivalent to - at(). - - \sa at() -*/ - -/*! - \fn type &Q3MemArray::at( uint index ) const - - Returns a reference to the element at position \a index in the array. - - This can be used to both read and set an element. - - \sa operator[]() -*/ - -/*! - \fn Q3MemArray::operator const type *() const - - Cast operator. Returns a pointer to the array. - - \sa data() -*/ - -/*! - \fn bool Q3MemArray::operator==( const Q3MemArray &a ) const - - Returns TRUE if this array is equal to \a a; otherwise returns - FALSE. - - The two arrays are compared bitwise. - - \sa operator!=() -*/ - -/*! - \fn bool Q3MemArray::operator!=( const Q3MemArray &a ) const - - Returns TRUE if this array is different from \a a; otherwise - returns FALSE. - - The two arrays are compared bitwise. - - \sa operator==() -*/ - -/*! - \fn Iterator Q3MemArray::begin() - - Returns an iterator pointing at the beginning of this array. This - iterator can be used in the same way as the iterators of - Q3ValueList and QMap, for example. -*/ - -/*! - \fn Iterator Q3MemArray::end() - - Returns an iterator pointing behind the last element of this - array. This iterator can be used in the same way as the iterators - of Q3ValueList and QMap, for example. -*/ - -/*! - \fn ConstIterator Q3MemArray::begin() const - - \overload - - Returns a const iterator pointing at the beginning of this array. - This iterator can be used in the same way as the iterators of - Q3ValueList and QMap, for example. -*/ - -/*! - \fn ConstIterator Q3MemArray::end() const - - \overload - - Returns a const iterator pointing behind the last element of this - array. This iterator can be used in the same way as the iterators - of Q3ValueList and QMap, for example. -*/ diff --git a/doc/src/q3popupmenu.qdoc b/doc/src/q3popupmenu.qdoc deleted file mode 100644 index a2cfe08..0000000 --- a/doc/src/q3popupmenu.qdoc +++ /dev/null @@ -1,76 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PopupMenu - \brief The Q3PopupMenu class is a thin compatibility wrapper around QMenu. - \compat - - Use QMenu in new applications. Note that the menu's actions must - be \l {Q3Action}s. -*/ - -/*! - \fn Q3PopupMenu::Q3PopupMenu(QWidget *parent, const char *name) - - Constructs a menu with the given \a parent and \a name. -*/ - -/*! - \fn int Q3PopupMenu::exec() - - Pops up the menu and returns the ID of the action that was - selected. - - \sa QMenu::exec() -*/ - -/*! - \fn int Q3PopupMenu::exec(const QPoint & pos, int indexAtPoint) - - Pops up the menu at coordinate \a pos and returns the ID of the - action that was selected. - - If \a indexAtPoint is specified, the menu will pop up with the - item at index \a indexAtPoint under the mouse cursor. - - \sa QMenu::exec() -*/ diff --git a/doc/src/q3ptrdict.qdoc b/doc/src/q3ptrdict.qdoc deleted file mode 100644 index 38ca0bb..0000000 --- a/doc/src/q3ptrdict.qdoc +++ /dev/null @@ -1,388 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PtrDict - \brief The Q3PtrDict class is a template class that provides a dictionary based on void* keys. - \compat - - Q3PtrDict is implemented as a template class. Define a template - instance Q3PtrDict\ to create a dictionary that operates on - pointers to X (X*). - - A dictionary is a collection of key-value pairs. The key is a - void* used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - Example: - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 0 - In this example we use a dictionary to add an extra property (a - char*) to the line edits we're using. - - See Q3Dict for full details, including the choice of dictionary - size, and how deletions are handled. - - \sa Q3PtrDictIterator, Q3Dict, Q3AsciiDict, Q3IntDict -*/ - - -/*! - \fn Q3PtrDict::Q3PtrDict( int size ) - - Constructs a dictionary using an internal hash array with the size - \a size. - - Setting \a size to a suitably large prime number (equal to or - greater than the expected number of entries) makes the hash - distribution better and improves lookup performance. -*/ - -/*! - \fn Q3PtrDict::Q3PtrDict( const Q3PtrDict &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3PtrDict::~Q3PtrDict() - - Removes all items from the dictionary and destroys it. - - All iterators that access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3PtrDict &Q3PtrDict::operator=(const Q3PtrDict &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared and then each item in \a dict is - inserted into the dictionary. Only the pointers are copied - (shallow copy), unless newItem() has been reimplemented. -*/ - -/*! - \fn uint Q3PtrDict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3PtrDict::size() const - - Returns the size of the internal hash table (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3PtrDict::resize( uint newsize ) - - Changes the size of the hash table to \a newsize. The contents of - the dictionary are preserved, but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3PtrDict::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3PtrDict::insert( void *key, const type *item ) - - Inserts the \a key with the \a item into the dictionary. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3PtrDict::replace( void *key, const type *item ) - - If the dictionary has key \a key, this key's item is replaced with - \a item. If the dictionary doesn't contain key \a key, \a item is - inserted into the dictionary using key \a key. - - \a item may not be 0. - - Equivalent to - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 1 - - If there are two or more items with equal keys, then the most - recently inserted item will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3PtrDict::remove( void *key ) - - Removes the item associated with \a key from the dictionary. - Returns TRUE if successful, i.e. if \a key is in the dictionary; - otherwise returns FALSE. - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary traversal order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3PtrDict::take( void *key ) - - Takes the item associated with \a key out of the dictionary - without deleting it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary traversal order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3PtrDict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that access this dictionary will be - reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3PtrDict::find( void *key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to operator[]. - - \sa operator[]() -*/ - -/*! - \fn type *Q3PtrDict::operator[]( void *key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3PtrDict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3PtrDict::read( QDataStream &s, Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrDict::write( QDataStream &s, Q3PtrCollection::Item item) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3PtrDictIterator - \brief The Q3PtrDictIterator class provides an iterator for Q3PtrDict collections. - \compat - - Q3PtrDictIterator is implemented as a template class. Define a - template instance Q3PtrDictIterator\ to create a dictionary - iterator that operates on Q3PtrDict\ (dictionary of X*). - - Example: - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 2 - In the example we insert some line edits into a dictionary, - associating a string with each. We then iterate over the - dictionary printing the associated strings. - - Multiple iterators may independently traverse the same dictionary. - A Q3PtrDict knows about all the iterators that are operating on the - dictionary. When an item is removed from the dictionary, Q3PtrDict - updates all iterators that refer the removed item to point to the - next item in the traversing order. - - \sa Q3PtrDict -*/ - -/*! - \fn Q3PtrDictIterator::Q3PtrDictIterator( const Q3PtrDict &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point on the first item in the \a dict. -*/ - -/*! - \fn Q3PtrDictIterator::~Q3PtrDictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3PtrDictIterator::count() const - - Returns the number of items in the dictionary this iterator - operates on. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3PtrDictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3PtrDictIterator::toFirst() - - Sets the current iterator item to point to the first item in the - dictionary and returns a pointer to the item. If the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ - -/*! - \fn Q3PtrDictIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3PtrDictIterator::current() const - - Returns a pointer to the current iterator item's value. -*/ - -/*! - \fn void *Q3PtrDictIterator::currentKey() const - - Returns the current iterator item's key. -*/ - -/*! - \fn type *Q3PtrDictIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrDictIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrDictIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/q3ptrlist.qdoc b/doc/src/q3ptrlist.qdoc deleted file mode 100644 index 3000940..0000000 --- a/doc/src/q3ptrlist.qdoc +++ /dev/null @@ -1,1157 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PtrList - \brief The Q3PtrList class is a template class that provides a list. - \compat - - Q3ValueList is an STL-compatible alternative to this class. - - Define a template instance Q3PtrList\ to create a list that - operates on pointers to X (X*). - - The list class is indexable and has a \link at() current - index\endlink and a \link current() current item\endlink. The - first item corresponds to index position 0. The current index is - -1 if the current item is 0. - - Items are inserted with prepend(), insert() or append(). Items are - removed with remove(), removeRef(), removeFirst() and - removeLast(). You can search for an item using find(), findNext(), - findRef() or findNextRef(). The list can be sorted with sort(). - You can count the number of occurrences of an item with contains() - or containsRef(). You can get a pointer to the current item with - current(), to an item at a particular index position in the list - with at() or to the first or last item with getFirst() and - getLast(). You can also iterate over the list with first(), - last(), next() and prev() (which all update current()). The list's - deletion property is set with setAutoDelete(). - - \target example - Example: - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 0 - - The output is - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 1 - - Q3PtrList has several member functions for traversing the list, but - using a Q3PtrListIterator can be more practical. Multiple list - iterators may traverse the same list, independently of each other - and of the current list item. - - In the example above we make the call setAutoDelete(true). - Enabling auto-deletion tells the list to delete items that are - removed. The default is to not delete items when they are removed - but this would cause a memory leak in the example because there - are no other references to the list items. - - When inserting an item into a list only the pointer is copied, not - the item itself, i.e. a shallow copy. It is possible to make the - list copy all of the item's data (deep copy) when an item is - inserted. insert(), inSort() and append() call the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a list and reimplement newItem() to have deep copies. - - When removing an item from a list, the virtual function - Q3PtrCollection::deleteItem() is called. Q3PtrList's default - implementation is to delete the item if auto-deletion is enabled. - - The virtual function compareItems() can be reimplemented to - compare two list items. This function is called from all list - functions that need to compare list items, for instance - remove(const type*). If you only want to deal with pointers, there - are functions that compare pointers instead, for instance - removeRef(const type*). These functions are somewhat faster than - those that call compareItems(). - - List items are stored as \c void* in an internal Q3LNode, which - also holds pointers to the next and previous list items. The - functions currentNode(), removeNode(), and takeNode() operate - directly on the Q3LNode, but they should be used with care. The - data component of the node is available through Q3LNode::getData(). - - The Q3StrList class is a list of \c char*. - It reimplements newItem(), deleteItem() and compareItems(). (But - see QStringList for a list of Unicode QStrings.) - - \sa Q3PtrListIterator -*/ - - -/*! - \fn Q3PtrList::Q3PtrList() - - Constructs an empty list. -*/ - -/*! - \fn Q3PtrList::Q3PtrList( const Q3PtrList &list ) - - Constructs a copy of \a list. - - Each item in \a list is \link append() appended\endlink to this - list. Only the pointers are copied (shallow copy). -*/ - -/*! - \fn Q3PtrList::~Q3PtrList() - - Removes all items from the list and destroys the list. - - All list iterators that access this list will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3PtrList &Q3PtrList::operator=(const Q3PtrList &list) - - Assigns \a list to this list and returns a reference to this list. - - This list is first cleared and then each item in \a list is \link - append() appended\endlink to this list. Only the pointers are - copied (shallow copy) unless newItem() has been reimplemented. -*/ - -/*! - \fn bool Q3PtrList::operator==(const Q3PtrList &list ) const - - Compares this list with \a list. Returns TRUE if the lists contain - the same data; otherwise returns FALSE. -*/ - -/*! - \fn uint Q3PtrList::count() const - - Returns the number of items in the list. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3PtrList::operator!=(const Q3PtrList &list ) const - - Compares this list with \a list. Returns TRUE if the lists contain - different data; otherwise returns FALSE. -*/ - - -/*! - \fn void Q3PtrList::sort() - - Sorts the list by the result of the virtual compareItems() - function. - - The heap sort algorithm is used for sorting. It sorts n items with - O(n*log n) comparisons. This is the asymptotic optimal solution of - the sorting problem. - - If the items in your list support operator<() and operator==(), - you might be better off with Q3SortedList because it implements the - compareItems() function for you using these two operators. - - \sa inSort() -*/ - -/*! - \fn bool Q3PtrList::isEmpty() const - - Returns TRUE if the list is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3PtrList::insert( uint index, const type *item ) - - Inserts the \a item at position \a index in the list. - - Returns TRUE if successful, i.e. if \a index is in range; - otherwise returns FALSE. The valid range is 0 to count() - (inclusively). The item is appended if \a index == count(). - - The inserted item becomes the current list item. - - \a item must not be 0. - - \sa append(), current(), replace() -*/ - -/*! - \fn bool Q3PtrList::replace( uint index, const type *item ) - - Replaces the item at position \a index with the new \a item. - - Returns TRUE if successful, i.e. \a index is in the range 0 to - count()-1. - - \sa append(), current(), insert() -*/ - -/*! - \fn void Q3PtrList::inSort( const type *item ) - - Inserts the \a item at its sorted position in the list. - - The sort order depends on the virtual compareItems() function. All - items must be inserted with inSort() to maintain the sorting - order. - - The inserted item becomes the current list item. - - \a item must not be 0. - - \warning Using inSort() is slow. An alternative, especially if you - have lots of items, is to simply append() or insert() them and - then use sort(). inSort() takes up to O(n) compares. That means - inserting n items in your list will need O(n^2) compares whereas - sort() only needs O(n*log n) for the same task. So use inSort() - only if you already have a presorted list and want to insert just - a few additional items. - - \sa insert(), compareItems(), current(), sort() -*/ - -/*! - \fn void Q3PtrList::append( const type *item ) - - Inserts the \a item at the end of the list. - - The inserted item becomes the current list item. This is - equivalent to \c{insert( count(), item )}. - - \a item must not be 0. - - \sa insert(), current(), prepend() -*/ - -/*! - \fn void Q3PtrList::prepend( const type *item ) - - Inserts the \a item at the start of the list. - - The inserted item becomes the current list item. This is - equivalent to \c{insert( 0, item )}. - - \a item must not be 0. - - \sa append(), insert(), current() -*/ - -/*! - \fn bool Q3PtrList::remove( uint index ) - - Removes the item at position \a index in the list. - - Returns TRUE if successful, i.e. if \a index is in range; - otherwise returns FALSE. The valid range is \c{0..(count() - 1)} - inclusive. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa take(), clear(), setAutoDelete(), current() removeRef() -*/ - -/*! - \fn bool Q3PtrList::remove() - - \overload - - Removes the current list item. - - Returns TRUE if successful, i.e. if the current item isn't 0; - otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa take(), clear(), setAutoDelete(), current() removeRef() -*/ - -/*! - \fn bool Q3PtrList::remove( const type *item ) - - \overload - - Removes the first occurrence of \a item from the list. - - Returns TRUE if successful, i.e. if \a item is in the list; - otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The compareItems() function is called when searching for the item - in the list. If compareItems() is not reimplemented, it is more - efficient to call removeRef(). - - If \a item is NULL then the current item is removed from the list. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa removeRef(), take(), clear(), setAutoDelete(), compareItems(), - current() -*/ - -/*! - \fn bool Q3PtrList::removeRef( const type *item ) - - Removes the first occurrence of \a item from the list. - - Returns TRUE if successful, i.e. if \a item is in the list; - otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 2 - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa remove(), clear(), setAutoDelete(), current() -*/ - -/*! - \fn void Q3PtrList::removeNode( Q3LNode *node ) - - Removes the \a node from the list. - - This node must exist in the list, otherwise the program may crash. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The first item in the list will become the new current list item. - The current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the item succeeding this item or to the preceding item if - the removed item was the last item. - - \warning Do not call this function unless you are an expert. - - \sa takeNode(), currentNode() remove() removeRef() -*/ - -/*! - \fn bool Q3PtrList::removeFirst() - - Removes the first item from the list. Returns TRUE if successful, - i.e. if the list isn't empty; otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The first item in the list becomes the new current list item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa removeLast(), setAutoDelete(), current() remove() -*/ - -/*! - \fn bool Q3PtrList::removeLast() - - Removes the last item from the list. Returns TRUE if successful, - i.e. if the list isn't empty; otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The last item in the list becomes the new current list item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa removeFirst(), setAutoDelete(), current() -*/ - -/*! - \fn type *Q3PtrList::take( uint index ) - - Takes the item at position \a index out of the list without - deleting it (even if \link setAutoDelete() auto-deletion\endlink - is enabled). - - Returns a pointer to the item taken out of the list, or 0 if the - index is out of range. The valid range is \c{0..(count() - 1)} - inclusive. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the taken item will be set to - point to the new current item. - - \sa remove(), clear(), current() -*/ - -/*! - \fn type *Q3PtrList::take() - - \overload - - Takes the current item out of the list without deleting it (even - if \link setAutoDelete() auto-deletion\endlink is enabled). - - Returns a pointer to the item taken out of the list, or 0 if - the current item is 0. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the taken item will be set to - point to the new current item. - - \sa remove(), clear(), current() -*/ - -/*! - \fn type *Q3PtrList::takeNode( Q3LNode *node ) - - Takes the \a node out of the list without deleting its item (even - if \link setAutoDelete() auto-deletion\endlink is enabled). - Returns a pointer to the item taken out of the list. - - This node must exist in the list, otherwise the program may crash. - - The first item in the list becomes the new current list item. - - All list iterators that refer to the taken item will be set to - point to the item succeeding this item or to the preceding item if - the taken item was the last item. - - \warning Do not call this function unless you are an expert. - - \sa removeNode(), currentNode() -*/ - -/*! - \fn void Q3PtrList::clear() - - Removes all items from the list. - - The removed items are deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - All list iterators that access this list will be reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn int Q3PtrList::find( const type *item ) - - Finds the first occurrence of \a item in the list. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - The compareItems() function is called when searching for the item - in the list. If compareItems() is not reimplemented, it is more - efficient to call findRef(). - - \sa findNext(), findRef(), compareItems(), current() -*/ - -/*! - \fn int Q3PtrList::findNext( const type *item ) - - Finds the next occurrence of \a item in the list, starting from - the current list item. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - The compareItems() function is called when searching for the item - in the list. If compareItems() is not reimplemented, it is more - efficient to call findNextRef(). - - \sa find(), findNextRef(), compareItems(), current() -*/ - -/*! - \fn int Q3PtrList::findRef( const type *item ) - - Finds the first occurrence of \a item in the list. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - Calling this function is much faster than find() because find() - compares \a item with each list item using compareItems(), whereas - this function only compares the pointers. - - \sa findNextRef(), find(), current() -*/ - -/*! - \fn int Q3PtrList::findNextRef( const type *item ) - - Finds the next occurrence of \a item in the list, starting from - the current list item. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - Calling this function is much faster than findNext() because - findNext() compares \a item with each list item using - compareItems(), whereas this function only compares the pointers. - - \sa findRef(), findNext(), current() -*/ - -/*! - \fn uint Q3PtrList::contains( const type *item ) const - - Returns the number of occurrences of \a item in the list. - - The compareItems() function is called when looking for the \a item - in the list. If compareItems() is not reimplemented, it is more - efficient to call containsRef(). - - This function does not affect the current list item. - - \sa containsRef(), compareItems() -*/ - -/*! - \fn uint Q3PtrList::containsRef( const type *item ) const - - Returns the number of occurrences of \a item in the list. - - Calling this function is much faster than contains() because - contains() compares \a item with each list item using - compareItems(), whereas his function only compares the pointers. - - This function does not affect the current list item. - - \sa contains() -*/ - -/*! - \fn type *Q3PtrList::at( uint index ) - - Returns a pointer to the item at position \a index in the list, or - 0 if the index is out of range. - - Sets the current list item to this item if \a index is valid. The - valid range is \c{0..(count() - 1)} inclusive. - - This function is very efficient. It starts scanning from the first - item, last item, or current item, whichever is closest to \a - index. - - \sa current() -*/ - -/*! - \fn int Q3PtrList::at() const - - \overload - - Returns the index of the current list item. The returned value is - -1 if the current item is 0. - - \sa current() -*/ - -/*! - \fn type *Q3PtrList::current() const - - Returns a pointer to the current list item. The current item may - be 0 (implies that the current index is -1). - - \sa at() -*/ - -/*! - \fn Q3LNode *Q3PtrList::currentNode() const - - Returns a pointer to the current list node. - - The node can be kept and removed later using removeNode(). The - advantage is that the item can be removed directly without - searching the list. - - \warning Do not call this function unless you are an expert. - - \sa removeNode(), takeNode(), current() -*/ - -/*! - \fn type *Q3PtrList::getFirst() const - - Returns a pointer to the first item in the list, or 0 if the list - is empty. - - This function does not affect the current list item. - - \sa first(), getLast() -*/ - -/*! - \fn type *Q3PtrList::getLast() const - - Returns a pointer to the last item in the list, or 0 if the list - is empty. - - This function does not affect the current list item. - - \sa last(), getFirst() -*/ - -/*! - \fn type *Q3PtrList::first() - - Returns a pointer to the first item in the list and makes this the - current list item; returns 0 if the list is empty. - - \sa getFirst(), last(), next(), prev(), current() -*/ - -/*! - \fn type *Q3PtrList::last() - - Returns a pointer to the last item in the list and makes this the - current list item; returns 0 if the list is empty. - - \sa getLast(), first(), next(), prev(), current() -*/ - -/*! - \fn type *Q3PtrList::next() - - Returns a pointer to the item succeeding the current item. Returns - 0 if the current item is 0 or equal to the last item. - - Makes the succeeding item current. If the current item before this - function call was the last item, the current item will be set to - 0. If the current item was 0, this function does nothing. - - \sa first(), last(), prev(), current() -*/ - -/*! - \fn type *Q3PtrList::prev() - - Returns a pointer to the item preceding the current item. Returns - 0 if the current item is 0 or equal to the first item. - - Makes the preceding item current. If the current item before this - function call was the first item, the current item will be set to - 0. If the current item was 0, this function does nothing. - - \sa first(), last(), next(), current() -*/ - -/*! - \fn void Q3PtrList::toVector( Q3GVector *vec ) const - - Stores all list items in the vector \a vec. - - The vector must be of the same item type, otherwise the result - will be undefined. -*/ - -/*! - \typedef Q3PtrList::iterator - - \internal -*/ - -/*! - \typedef Q3PtrList::Iterator - - \internal -*/ - -/*! - \typedef Q3PtrList::ConstIterator - - \internal -*/ - -/*! - \typedef Q3PtrList::const_iterator - - \internal -*/ - -/*! - \fn Q3PtrList::constBegin() const - - \internal -*/ - -/*! - \fn Q3PtrList::constEnd() const - - \internal -*/ - -/*! - \fn Q3PtrList::erase(Iterator) - - \internal -*/ - - -/***************************************************************************** - Q3PtrListIterator documentation - *****************************************************************************/ - -/*! - \class Q3PtrListIterator - \brief The Q3PtrListIterator class provides an iterator for - Q3PtrList collections. - \compat - - Define a template instance Q3PtrListIterator\ to create a list - iterator that operates on Q3PtrList\ (list of X*). - - The following example is similar to the - example in the Q3PtrList class documentation, - but it uses Q3PtrListIterator. The class Employee is - defined there. - - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 3 - - The output is - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 4 - - Using a list iterator is a more robust way of traversing the list - than using the Q3PtrList member functions \link Q3PtrList::first() - first\endlink(), \link Q3PtrList::next() next\endlink(), \link - Q3PtrList::current() current\endlink(), etc., as many iterators can - traverse the same list independently. - - An iterator has its own current list item and can get the next and - previous list items. It doesn't modify the list in any way. - - When an item is removed from the list, all iterators that point to - that item are updated to point to Q3PtrList::current() instead to - avoid dangling references. - - \sa Q3PtrList -*/ - -/*! - \fn Q3PtrListIterator::Q3PtrListIterator( const Q3PtrList &list ) - - Constructs an iterator for \a list. The current iterator item is - set to point on the first item in the \a list. -*/ - -/*! - \fn Q3PtrListIterator::~Q3PtrListIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3PtrListIterator::count() const - - Returns the number of items in the list this iterator operates on. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3PtrListIterator::isEmpty() const - - Returns TRUE if the list is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3PtrListIterator::atFirst() const - - Returns TRUE if the current iterator item is the first list item; - otherwise returns FALSE. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3PtrListIterator::atLast() const - - Returns TRUE if the current iterator item is the last list item; - otherwise returns FALSE. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3PtrListIterator::toFirst() - - Sets the current iterator item to point to the first list item and - returns a pointer to the item. Sets the current item to 0 and - returns 0 if the list is empty. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3PtrListIterator::toLast() - - Sets the current iterator item to point to the last list item and - returns a pointer to the item. Sets the current item to 0 and - returns 0 if the list is empty. - - \sa toFirst(), atLast() -*/ - -/*! - \fn Q3PtrListIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3PtrListIterator::operator*() - - Asterisk operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3PtrListIterator::current() const - - Returns a pointer to the current iterator item. If the iterator is - positioned before the first item in the list or after the last - item in the list, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the list or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the list or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item and returns a pointer to that item. - - If that item is beyond the last item or if the list is empty, it - sets the current item to 0 and returns 0 -*/ - -/*! - \fn type *Q3PtrListIterator::operator--() - - Prefix - makes the preceding item current and returns the new - current item. - - If the current iterator item was the first item in the list or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item or 0 - if it is beyond the first item. Makes this the current item. -*/ - -/*! - \fn Q3PtrListIterator& Q3PtrListIterator::operator=( const Q3PtrListIterator &it ) - - Assignment. Makes a copy of the iterator \a it and returns a - reference to this iterator. -*/ - -/*! - \class Q3StrList - \brief The Q3StrList class provides a doubly-linked list of char*. - \compat - - If you want a string list of \l{QString}s use QStringList. - - This class is a Q3PtrList\ instance (a list of char*). - - Q3StrList can make deep or shallow copies of the strings that are - inserted. - - A deep copy means that memory is allocated for the string and then - the string data is copied into that memory. A shallow copy is just - a copy of the pointer value and not of the string data itself. - - The disadvantage of shallow copies is that because a pointer can - be deleted only once, the program must put all strings in a - central place and know when it is safe to delete them (i.e. when - the strings are no longer referenced by other parts of the - program). This can make the program more complex. The advantage of - shallow copies is that they consume far less memory than deep - copies. It is also much faster to copy a pointer (typically 4 or 8 - bytes) than to copy string data. - - A Q3StrList that operates on deep copies will, by default, turn on - auto-deletion (see setAutoDelete()). Thus, by default Q3StrList - will deallocate any string copies it allocates. - - The virtual compareItems() function is reimplemented and does a - case-sensitive string comparison. The inSort() function will - insert strings in sorted order. In general it is fastest to insert - the strings as they come and sort() at the end; inSort() is useful - when you just have to add a few extra strings to an already sorted - list. - - The Q3StrListIterator class is an iterator for Q3StrList. -*/ - -/*! - \fn Q3StrList::operator QList() const - - Automatically converts a Q3StrList into a QList. -*/ - -/*! - \fn Q3StrList::Q3StrList( bool deepCopies ) - - Constructs an empty list of strings. Will make deep copies of all - inserted strings if \a deepCopies is TRUE, or use shallow copies - if \a deepCopies is FALSE. -*/ - -/*! - \fn Q3StrList::Q3StrList(const Q3StrList &list) - \fn Q3StrList::Q3StrList(const QList &list) - - Constructs a copy of \a list. -*/ - -/*! - \fn Q3StrList::~Q3StrList() - - Destroys the list. All strings are removed. -*/ - -/*! - \fn Q3StrList& Q3StrList::operator=(const Q3StrList& list) - \fn Q3StrList &Q3StrList::operator=(const QList &list) - - Assigns \a list to this list and returns a reference to this list. -*/ - -/*! - \class Q3StrIList - \brief The Q3StrIList class provides a doubly-linked list of char* - with case-insensitive comparison. - \compat - - This class is a Q3PtrList\ instance (a list of char*). - - Q3StrIList is identical to Q3StrList except that the virtual - compareItems() function is reimplemented to compare strings - case-insensitively. The inSort() function inserts strings in a - sorted order. In general it is fastest to insert the strings as - they come and sort() at the end; inSort() is useful when you just - have to add a few extra strings to an already sorted list. - - The Q3StrListIterator class works for Q3StrIList. - - \sa QStringList -*/ - -/*! - \fn Q3StrIList::Q3StrIList( bool deepCopies ) - - Constructs a list of strings. Will make deep copies of all - inserted strings if \a deepCopies is TRUE, or use shallow copies - if \a deepCopies is FALSE. -*/ - -/*! - \fn Q3StrIList::~Q3StrIList() - - Destroys the list. All strings are removed. -*/ - -/*! - \fn int Q3PtrList::compareItems( Q3PtrCollection::Item item1, - Q3PtrCollection::Item item2 ) - - This virtual function compares two list items. - - Returns: - \list - \i zero if \a item1 == \a item2 - \i nonzero if \a item1 != \a item2 - \endlist - - This function returns \e int rather than \e bool so that - reimplementations can return three values and use it to sort by: - - \list - \i 0 if \a item1 == \a item2 - \i \> 0 (positive integer) if \a item1 \> \a item2 - \i \< 0 (negative integer) if \a item1 \< \a item2 - \endlist - - inSort() requires that compareItems() is implemented as described - here. - - This function should not modify the list because some const - functions call compareItems(). - - The default implementation compares the pointers. -*/ - -/*! - \fn QDataStream& Q3PtrList::read( QDataStream& s, - Q3PtrCollection::Item& item ) - - Reads a list item from the stream \a s and returns a reference to - the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrList::write( QDataStream& s, - Q3PtrCollection::Item item ) const - - Writes a list item, \a item to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ - -/*! \fn iterator Q3PtrList::begin() -\internal -*/ -/*! \fn const_iterator Q3PtrList::begin() const -\internal -*/ -/*! \fn iterator Q3PtrList::end() -\internal -*/ -/*! \fn const_iterator Q3PtrList::end() const -\internal -*/ - -/*! - \class Q3StrListIterator - \brief The Q3StrListIterator class is an iterator for the Q3StrList - and Q3StrIList classes. - \compat - - This class is a Q3PtrListIterator\ instance. It can traverse - the strings in the Q3StrList and Q3StrIList classes. -*/ - - -/* - \class Q3PtrListAutoDelete - \brief The Q3PtrListAutoDelete class is a template class that provides a list that auto-deletes its data. - \compat - - A Q3PtrListAutoDelete is identical to a Q3PtrList with - setAutoDelete(TRUE). -*/ diff --git a/doc/src/q3ptrqueue.qdoc b/doc/src/q3ptrqueue.qdoc deleted file mode 100644 index b3af5f6..0000000 --- a/doc/src/q3ptrqueue.qdoc +++ /dev/null @@ -1,230 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PtrQueue - \brief The Q3PtrQueue class is a template class that provides a queue. - \compat - - Q3ValueVector can be used as an STL-compatible alternative to this - class. - - A template instance Q3PtrQueue\ is a queue that operates on - pointers to X (X*). - - A queue is a first in, first out structure. Items are added to the - tail of the queue with enqueue() and retrieved from the head with - dequeue(). You can peek at the head item without dequeing it using - head(). - - You can control the queue's deletion policy with setAutoDelete(). - - For compatibility with the Q3PtrCollection classes, current() and - remove() are provided; both operate on the head(). - - \sa Q3PtrList Q3PtrStack -*/ - -/*! - \fn Q3PtrQueue::Q3PtrQueue () - - Creates an empty queue with autoDelete() set to FALSE. -*/ - -/*! - \fn Q3PtrQueue::Q3PtrQueue( const Q3PtrQueue& queue ) - - Creates a queue from \a queue. - - Only the pointers are copied; the items are not. The autoDelete() - flag is set to FALSE. -*/ - -/*! - \fn Q3PtrQueue::~Q3PtrQueue() - - Destroys the queue. Items in the queue are deleted if autoDelete() - is TRUE. -*/ - -/*! - \fn Q3PtrQueue& Q3PtrQueue::operator= (const Q3PtrQueue& queue) - - Assigns \a queue to this queue and returns a reference to this - queue. - - This queue is first cleared and then each item in \a queue is - enqueued to this queue. Only the pointers are copied. - - \warning The autoDelete() flag is not modified. If it is TRUE for - both \a queue and this queue, deleting the two lists will cause \e - double-deletion of the items. -*/ - -/*! - \fn bool Q3PtrQueue::isEmpty() const - - Returns TRUE if the queue is empty; otherwise returns FALSE. - - \sa count() dequeue() head() -*/ - -/*! - \fn void Q3PtrQueue::enqueue (const type* d) - - Adds item \a d to the tail of the queue. - - \sa count() dequeue() -*/ - -/*! - \fn type* Q3PtrQueue::dequeue () - - Takes the head item from the queue and returns a pointer to it. - Returns 0 if the queue is empty. - - \sa enqueue() count() -*/ - -/*! - \fn bool Q3PtrQueue::remove() - - Removes the head item from the queue, and returns TRUE if there - was an item, i.e. the queue wasn't empty; otherwise returns FALSE. - - The item is deleted if autoDelete() is TRUE. - - \sa head() isEmpty() dequeue() -*/ - -/*! - \fn void Q3PtrQueue::clear() - - Removes all items from the queue, and deletes them if autoDelete() - is TRUE. - - \sa remove() -*/ - -/*! - \fn uint Q3PtrQueue::count() const - - Returns the number of items in the queue. - - \sa isEmpty() -*/ - -/*! - \fn type* Q3PtrQueue::head() const - - Returns a pointer to the head item in the queue. The queue is not - changed. Returns 0 if the queue is empty. - - \sa dequeue() isEmpty() -*/ - -/*! - \fn Q3PtrQueue::operator type*() const - - Returns a pointer to the head item in the queue. The queue is not - changed. Returns 0 if the queue is empty. - - \sa dequeue() isEmpty() -*/ - -/*! - \fn type* Q3PtrQueue::current() const - - Returns a pointer to the head item in the queue. The queue is not - changed. Returns 0 if the queue is empty. - - \sa dequeue() isEmpty() -*/ - -/*! - \fn bool Q3PtrQueue::autoDelete() const - - Returns the setting of the auto-delete option. The default is - FALSE. - - \sa setAutoDelete() -*/ - -/*! - \fn void Q3PtrQueue::setAutoDelete( bool enable ) - - Sets the queue to auto-delete its contents if \a enable is TRUE - and not to delete them if \a enable is FALSE. - - If auto-deleting is turned on, all the items in a queue are - deleted when the queue itself is deleted. This can be quite - convenient if the queue has the only pointer to the items. - - The default setting is FALSE, for safety. If you turn it on, be - careful about copying the queue: you might find yourself with two - queues deleting the same items. - - \sa autoDelete() -*/ - -/*! - \fn QDataStream& Q3PtrQueue::read( QDataStream& s, - Q3PtrCollection::Item& item ) - - Reads a queue item, \a item, from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrQueue::write( QDataStream& s, - Q3PtrCollection::Item item ) const - - Writes a queue item, \a item, to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ diff --git a/doc/src/q3ptrstack.qdoc b/doc/src/q3ptrstack.qdoc deleted file mode 100644 index 1650d69..0000000 --- a/doc/src/q3ptrstack.qdoc +++ /dev/null @@ -1,217 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PtrStack - \brief The Q3PtrStack class is a template class that provides a stack. - \compat - - Q3ValueStack is an STL-compatible alternative to this class. - - Define a template instance Q3PtrStack\ to create a stack that - operates on pointers to X, (X*). - - A stack is a last in, first out (LIFO) structure. Items are added - to the top of the stack with push() and retrieved from the top - with pop(). Use top() to get a reference to the top element - without changing the stack. - - You can control the stack's deletion policy with setAutoDelete(). - - For compatibility with the Q3PtrCollection classes current() and - remove() are provided; they both operate on the top(). - - \sa Q3PtrList Q3PtrQueue -*/ - -/*! - \fn Q3PtrStack::Q3PtrStack () - - Creates an empty stack. -*/ - -/*! - \fn Q3PtrStack::Q3PtrStack (const Q3PtrStack& s) - - Creates a stack by making a shallow copy of another stack \a s. -*/ - -/*! - \fn Q3PtrStack::~Q3PtrStack () - - Destroys the stack. All items will be deleted if autoDelete() is - true. -*/ - -/*! - \fn Q3PtrStack& Q3PtrStack::operator= (const Q3PtrStack& s) - - Sets the contents of this stack by making a shallow copy of - another stack \a s. Elements currently in this stack will be - deleted if autoDelete() is true. -*/ - -/*! - \fn bool Q3PtrStack::isEmpty () const - - Returns true if the stack contains no elements; otherwise returns - false. -*/ - -/*! - \fn void Q3PtrStack::push (const type* d) - - Adds an element \a d to the top of the stack. Last in, first out. -*/ - -/*! - \fn type* Q3PtrStack::pop () - - Removes the top item from the stack and returns it. The stack must - not be empty. -*/ - -/*! - \fn bool Q3PtrStack::remove () - - Removes the top item from the stack and deletes it if autoDelete() - is true. Returns true if there was an item to pop; otherwise - returns false. - - \sa clear() -*/ - -/*! - \fn void Q3PtrStack::clear() - - Removes all items from the stack, deleting them if autoDelete() is - true. - - \sa remove() -*/ - -/*! - \fn uint Q3PtrStack::count() const - - Returns the number of items in the stack. - - \sa isEmpty() -*/ - -/*! - \fn type* Q3PtrStack::top () const - - Returns a pointer to the top item on the stack (most recently - pushed). The stack is not changed. Returns 0 if the stack is - empty. -*/ - -/*! - \fn Q3PtrStack::operator type* ()const - - Returns a pointer to the top item on the stack (most recently - pushed). The stack is not changed. Returns 0 if the stack is - empty. -*/ - -/*! - \fn type* Q3PtrStack::current () const - - Returns a pointer to the top item on the stack (most recently - pushed). The stack is not changed. Returns 0 if the stack is - empty. -*/ - -/*! - \fn bool Q3PtrStack::autoDelete() const - - The same as Q3PtrCollection::autoDelete(). Returns true if - the auto-delete option is set. If the option is set, the - stack auto-deletes its contents. - - \sa setAutoDelete() -*/ - -/*! - \fn void Q3PtrStack::setAutoDelete(bool enable) - - Defines whether this stack auto-deletes its contents. The same as - Q3PtrCollection::setAutoDelete(). If \a enable is true, auto-delete - is turned on. - - If auto-deleting is turned on, all the items in the stack are - deleted when the stack itself is deleted. This is convenient if - the stack has the only pointers to the items. - - The default setting is false, for safety. If you turn it on, be - careful about copying the stack, or you might find yourself with - two stacks deleting the same items. - - Note that the auto-delete setting may also affect other functions in - subclasses. For example, a subclass that has a remove() function - will remove the item from its data structure, and if auto-delete is - enabled, will also delete the item. - - \sa autoDelete() -*/ - -/*! - \fn QDataStream& Q3PtrStack::read(QDataStream& s, Q3PtrCollection::Item& item) - - Reads a stack item, \a item, from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrStack::write(QDataStream& s, - Q3PtrCollection::Item item) const - - Writes a stack item, \a item, to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ diff --git a/doc/src/q3ptrvector.qdoc b/doc/src/q3ptrvector.qdoc deleted file mode 100644 index fa78de5..0000000 --- a/doc/src/q3ptrvector.qdoc +++ /dev/null @@ -1,427 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3PtrVector - \brief The Q3PtrVector class is a template collection class that - provides a vector (array). - \compat - - Q3ValueVector is an STL-compatible alternative to this class. - - Q3PtrVector is implemented as a template class. Defines a template - instance Q3PtrVector\ to create a vector that contains pointers - to X (X*). - - A vector is the same as an array. The main difference between - Q3PtrVector and Q3MemArray is that Q3PtrVector stores pointers to the - elements, whereas Q3MemArray stores the elements themselves (i.e. - Q3MemArray is value-based and Q3PtrVector is pointer-based). - - Items are added to the vector using insert() or fill(). Items are - removed with remove(). You can get a pointer to an item at a - particular index position using at(). - - Unless otherwise stated, all functions that remove items from the - vector will also delete the element pointed to if \link - setAutoDelete() auto-deletion\endlink is enabled. By default, - auto-deletion is disabled; see setAutoDelete(). This behavior can - be changed in a subclass by reimplementing the virtual function - deleteItem(). - - Functions that compare items (find() and sort() for example) will - do so using the virtual function compareItems(). The default - implementation of this function only compares the pointer values. - Reimplement compareItems() in a subclass to get searching and - sorting based on the item contents. You can perform a linear - search for a pointer in the vector using findRef(), or a binary - search (of a sorted vector) using bsearch(). You can count the - number of times an item appears in the vector with contains() or - containsRef(). - - \sa Q3MemArray -*/ - -/*! - \fn Q3PtrVector::Q3PtrVector() - - Constructs a null vector. - - \sa isNull() -*/ - -/*! - \fn Q3PtrVector::Q3PtrVector(uint size) - - Constructs an vector with room for \a size items. Makes a null - vector if \a size == 0. - - All \a size positions in the vector are initialized to 0. - - \sa size(), resize(), isNull() -*/ - -/*! - \fn Q3PtrVector::Q3PtrVector(const Q3PtrVector &v) - - Constructs a copy of \a v. Only the pointers are copied (i.e. - shallow copy). -*/ - -/*! - \fn Q3PtrVector::~Q3PtrVector() - - Removes all items from the vector, and destroys the vector itself. - - \sa clear() -*/ - -/*! - \fn Q3PtrVector &Q3PtrVector::operator=(const Q3PtrVector &v) - - Assigns \a v to this vector and returns a reference to this - vector. - - This vector is first cleared and then all the items from \a v are - copied into the vector. Only the pointers are copied (i.e. shallow - copy). - - \sa clear() -*/ - -/*! - \fn type **Q3PtrVector::data() const - - Returns a pointer to the actual vector data, which is an array of - type*. - - The vector is a null vector if data() == 0 (null pointer). - - \sa isNull() -*/ - -/*! - \fn uint Q3PtrVector::size() const - - Returns the size of the vector, i.e. the number of vector - positions. This is also the maximum number of items the vector can - hold. - - The vector is a null vector if size() == 0. - - \sa isNull(), resize(), count() -*/ - -/*! - \fn uint Q3PtrVector::count() const - - Returns the number of items in the vector. The vector is empty if - count() == 0. - - \sa isEmpty(), size(), isNull() -*/ - -/*! - \fn bool Q3PtrVector::isEmpty() const - - Returns true if the vector is empty; otherwise returns false. - - \sa count() -*/ - -/*! - \fn bool Q3PtrVector::isNull() const - - Returns true if the vector is null; otherwise returns false. - - A null vector has size() == 0 and data() == 0. - - \sa size() -*/ - -/*! - \fn bool Q3PtrVector::resize(uint size) - - Resizes (expands or shrinks) the vector to \a size elements. The - vector becomes a null vector if \a size == 0. - - Any items at position \a size or beyond in the vector are removed. - New positions are initialized to 0. - - Returns true if successful, i.e. if the memory was successfully - allocated; otherwise returns false. - - \sa size(), isNull() -*/ - -/*! - \fn bool Q3PtrVector::insert(uint i, const type *d) - - Sets position \a i in the vector to contain the item \a d. \a i - must be less than size(). Any previous element in position \a i is - removed. - - Returns true if \a i is within range; otherwise returns false. - - \sa at() -*/ - -/*! - \fn bool Q3PtrVector::remove(uint i) - - Removes the item at position \a i in the vector, if there is one. - \a i must be less than size(). - - Returns true if \a i is within range; otherwise returns false. - - \sa take(), at() -*/ - -/*! - \fn type* Q3PtrVector::take(uint i) - - Returns the item at position \a i in the vector, and removes that - item from the vector. \a i must be less than size(). If there is - no item at position \a i, 0 is returned. - - Unlike remove(), this function does \e not call deleteItem() for - the removed item. - - \sa remove(), at() -*/ - -/*! - \fn void Q3PtrVector::clear() - - Removes all items from the vector, and destroys the vector itself. - - The vector becomes a null vector. - - \sa isNull() -*/ - -/*! - \fn bool Q3PtrVector::fill(const type *d, int size) - - Inserts item \a d in all positions in the vector. Any existing - items are removed. If \a d is 0, the vector becomes empty. - - If \a size >= 0, the vector is first resized to \a size. By - default, \a size is -1. - - Returns true if successful, i.e. \a size is the same as the - current size, or \a size is larger and the memory has successfully - been allocated; otherwise returns false. - - \sa resize(), insert(), isEmpty() -*/ - -/*! - \fn void Q3PtrVector::sort() - - Sorts the items in ascending order. Any empty positions will be - put last. - - Compares items using the virtual function compareItems(). - - \sa bsearch() -*/ - -/*! - \fn int Q3PtrVector::bsearch(const type* d) const - - In a sorted array, finds the first occurrence of \a d using a - binary search. For a sorted array, this is generally much faster - than find(), which performs a linear search. - - Returns the position of \a d, or -1 if \a d could not be found. \a - d must not be 0. - - Compares items using the virtual function compareItems(). - - \sa sort(), find() -*/ - - -/*! - \fn int Q3PtrVector::findRef(const type *d, uint i) const - - Finds the first occurrence of the item pointer \a d in the vector - using a linear search. The search starts at position \a i, which - must be less than size(). \a i is by default 0; i.e. the search - starts at the start of the vector. - - Returns the position of \a d, or -1 if \a d could not be found. - - This function does \e not use compareItems() to compare items. - - Use the much faster bsearch() to search a sorted vector. - - \sa find(), bsearch() -*/ - -/*! - \fn int Q3PtrVector::find(const type *d, uint i) const - - Finds the first occurrence of item \a d in the vector using a - linear search. The search starts at position \a i, which must be - less than size(). \a i is by default 0; i.e. the search starts at - the start of the vector. - - Returns the position of \a d, or -1 if \a d could not be found. - - Compares items using the virtual function compareItems(). - - Use the much faster bsearch() to search a sorted vector. - - \sa findRef(), bsearch() -*/ - - -/*! - \fn uint Q3PtrVector::containsRef(const type *d) const - - Returns the number of occurrences of the item pointer \a d in the - vector. - - This function does \e not use compareItems() to compare items. - - \sa findRef() -*/ - -/*! - \fn uint Q3PtrVector::contains(const type *d) const - - Returns the number of occurrences of item \a d in the vector. - - Compares items using the virtual function compareItems(). - - \sa containsRef() -*/ - -/*! - \fn type *Q3PtrVector::operator[](int i) const - - Returns the item at position \a i, or 0 if there is no item at - that position. \a i must be less than size(). - - Equivalent to at(\a i). - - \sa at() -*/ - -/*! - \fn type *Q3PtrVector::at(uint i) const - - Returns the item at position \a i, or 0 if there is no item at - that position. \a i must be less than size(). -*/ - - -/*! - \fn void Q3PtrVector::toList(Q3GList *list) const - - \internal - - Copies all items in this vector to the list \a list. \a list is - first cleared and then all items are appended to \a list. - - \sa Q3PtrList, Q3PtrStack, Q3PtrQueue -*/ - -/*! - \fn int Q3PtrVector::compareItems(Q3PtrCollection::Item d1, - Q3PtrCollection::Item d2) - - This virtual function compares two list items. - - Returns: - \list - \i zero if \a d1 == \a d2 - \i nonzero if \a d1 != \a d2 - \endlist - - This function returns \e int rather than \e bool so that - reimplementations can return one of three values and use it to - sort by: - \list - \i 0 if \a d1 == \a d2 - \i \> 0 (positive integer) if \a d1 \> \a d2 - \i \< 0 (negative integer) if \a d1 \< \a d2 - \endlist - - The sort() and bsearch() functions require compareItems() to be - implemented as described here. - - This function should not modify the vector because some const - functions call compareItems(). -*/ - -/*! - \fn QDataStream& Q3PtrVector::read(QDataStream &s, - Q3PtrCollection::Item &item) - - Reads a vector item, \a item, from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrVector::write(QDataStream &s, - Q3PtrCollection::Item item) const - - Writes a vector item, \a item, to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ - -/*! - \fn bool Q3PtrVector::operator==(const Q3PtrVector &v) const - - Returns true if this vector and \a v are equal; otherwise returns - false. -*/ diff --git a/doc/src/q3sqlfieldinfo.qdoc b/doc/src/q3sqlfieldinfo.qdoc deleted file mode 100644 index ba064f3..0000000 --- a/doc/src/q3sqlfieldinfo.qdoc +++ /dev/null @@ -1,234 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3SqlFieldInfo - \brief The Q3SqlFieldInfo class stores meta data associated with a SQL field. - - \compat - - Q3SqlFieldInfo objects only store meta data; field values are - stored in QSqlField objects. - - All values must be set in the constructor, and may be retrieved - using isRequired(), type(), length(), precision(), defaultValue(), - name(), isGenerated() and typeID(). - - \sa Q3SqlRecordInfo -*/ - -/*! - \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QString& name, - QVariant::Type typ, - int required, - int len, - int prec, - const QVariant& defValue, - int typeID, - bool generated, - bool trim, - bool calculated) - - Constructs a Q3SqlFieldInfo with the following parameters: - \table - \row \i \a name \i the name of the field. - \row \i \a typ \i the field's type in a QVariant. - \row \i \a required \i greater than 0 if the field is required, 0 - if its value can be NULL and less than 0 if it cannot be - determined whether the field is required or not. - \row \i \a len \i the length of the field. Note that for - non-character types some databases return either the length in - bytes or the number of digits. -1 signifies that the length cannot - be determined. - \row \i \a prec \i the precision of the field, or -1 if the field - has no precision or it cannot be determined. - \row \i \a defValue \i the default value that is inserted into - the table if none is specified by the user. QVariant() if there is - no default value or it cannot be determined. - \row \i \a typeID \i the internal typeID of the database system - (only useful for low-level programming). 0 if unknown. - \row \i \a generated \i TRUE indicates that this field should be - included in auto-generated SQL statments, e.g. in Q3SqlCursor. - \row \i \a trim \i TRUE indicates that widgets should remove - trailing whitespace from character fields. This does not affect - the field value but only its representation inside widgets. - \row \i \a calculated \i TRUE indicates that the value of this - field is calculated. The value of calculated fields can by - modified by subclassing Q3SqlCursor and overriding - Q3SqlCursor::calculateField(). - \endtable -*/ - -/*! - \fn Q3SqlFieldInfo::~Q3SqlFieldInfo() - - Destroys the object and frees any allocated resources. -*/ - -/*! - \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QSqlField & other) - - Creates a Q3SqlFieldInfo object with the type and the name of the - QSqlField \a other. -*/ - -/*! - \fn bool Q3SqlFieldInfo::operator==(const Q3SqlFieldInfo& other) const - - Assigns \a other to this field info and returns a reference to it. -*/ - -/*! - \fn QSqlField Q3SqlFieldInfo::toField() const - - Returns an empty QSqlField based on the information in this - Q3SqlFieldInfo. -*/ - -/*! - \fn int Q3SqlFieldInfo::isRequired() const - - Returns a value greater than 0 if the field is required (NULL - values are not allowed), 0 if it isn't required (NULL values are - allowed) or less than 0 if it cannot be determined whether the - field is required or not. -*/ - -/*! - \fn QVariant::Type Q3SqlFieldInfo::type() const - - Returns the field's type or QVariant::Invalid if the type is - unknown. -*/ - -/*! - \fn int Q3SqlFieldInfo::length() const - - Returns the field's length. For fields storing text the return - value is the maximum number of characters the field can hold. For - non-character fields some database systems return the number of - bytes needed or the number of digits allowed. If the length cannot - be determined -1 is returned. -*/ - -/*! - \fn int Q3SqlFieldInfo::precision() const - - Returns the field's precision or -1 if the field has no precision - or it cannot be determined. -*/ - -/*! - \fn QVariant Q3SqlFieldInfo::defaultValue() const - - Returns the field's default value or an empty QVariant if the - field has no default value or the value couldn't be determined. - The default value is the value inserted in the database when it - is not explicitly specified by the user. -*/ - -/*! - \fn QString Q3SqlFieldInfo::name() const - - Returns the name of the field in the SQL table. -*/ - -/*! - \fn int Q3SqlFieldInfo::typeID() const - - Returns the internal type identifier as returned from the database - system. The return value is 0 if the type is unknown. -*/ - -/*! - \fn bool Q3SqlFieldInfo::isGenerated() const - - Returns TRUE if the field should be included in auto-generated - SQL statments, e.g. in Q3SqlCursor; otherwise returns FALSE. - - \sa setGenerated() -*/ - -/*! - \fn bool Q3SqlFieldInfo::isTrim() const - - Returns TRUE if trailing whitespace should be removed from - character fields; otherwise returns FALSE. - - \sa setTrim() -*/ - -/*! - \fn bool Q3SqlFieldInfo::isCalculated() const - - Returns TRUE if the field is calculated; otherwise returns FALSE. - - \sa setCalculated() -*/ - -/*! - \fn void Q3SqlFieldInfo::setTrim(bool trim) - - If \a trim is TRUE widgets should remove trailing whitespace from - character fields. This does not affect the field value but only - its representation inside widgets. - - \sa isTrim() -*/ - -/*! - \fn void Q3SqlFieldInfo::setGenerated(bool generated) - - \a generated set to FALSE indicates that this field should not appear - in auto-generated SQL statements (for example in Q3SqlCursor). - - \sa isGenerated() -*/ - -/*! - \fn void Q3SqlFieldInfo::setCalculated(bool calculated) - - \a calculated set to TRUE indicates that this field is a calculated - field. The value of calculated fields can by modified by subclassing - Q3SqlCursor and overriding Q3SqlCursor::calculateField(). - - \sa isCalculated() -*/ diff --git a/doc/src/q3sqlrecordinfo.qdoc b/doc/src/q3sqlrecordinfo.qdoc deleted file mode 100644 index 64236d2..0000000 --- a/doc/src/q3sqlrecordinfo.qdoc +++ /dev/null @@ -1,89 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3SqlRecordInfo - \brief The Q3SqlRecordInfo class encapsulates a set of database field meta data. - - \compat - - This class is a list that holds a set of database field meta - data. Use contains() to see if a given field name exists in the - record, and use find() to get a QSqlFieldInfo record for a named - field. - - \sa Q3SqlFieldInfo -*/ - -/*! - \fn Q3SqlRecordInfo::Q3SqlRecordInfo() - - Constructs an empty record info object. -*/ - -/*! - \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const Q3SqlFieldInfoList& other) - \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const QSqlRecord& other) - - Constructs a copy of \a other. -*/ - -/*! - \fn size_type Q3SqlRecordInfo::contains(const QString& fieldName) const - - Returns the number of times a field called \a fieldName occurs in - the record. Returns 0 if no field by that name could be found. -*/ - -/*! - \fn Q3SqlFieldInfo Q3SqlRecordInfo::find(const QString& fieldName) const - - Returns a QSqlFieldInfo object for the first field in the record - which has the field name \a fieldName. If no matching field is - found then an empty QSqlFieldInfo object is returned. -*/ - -/*! - \fn QSqlRecord Q3SqlRecordInfo::toRecord() const - - Returns an empty QSqlRecord based on the field information - in this Q3SqlRecordInfo. -*/ diff --git a/doc/src/q3valuelist.qdoc b/doc/src/q3valuelist.qdoc deleted file mode 100644 index fd73763..0000000 --- a/doc/src/q3valuelist.qdoc +++ /dev/null @@ -1,569 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3ValueList - \brief The Q3ValueList class is a value-based template class that - provides lists. - \compat - - Q3ValueList is a Qt implementation of an STL-like list container. - It can be used in your application if the standard \c list is not - available for your target platforms. - - Q3ValueList\ defines a template instance to create a list of - values that all have the class T. Note that Q3ValueList does not - store pointers to the members of the list; it holds a copy of - every member. This is why these kinds of classes are called "value - based"; Q3PtrList and Q3Dict are "pointer based". - - Q3ValueList contains and manages a collection of objects of type T - and provides iterators that allow the contained objects to be - addressed. Q3ValueList owns the contained items. For more relaxed - ownership semantics, see Q3PtrCollection and friends which are - pointer-based containers. - - Some classes cannot be used within a Q3ValueList, for example, all - classes derived from QObject and thus all classes that implement - widgets. Only values can be used in a Q3ValueList. To qualify as a - value the class must provide: - \list - \i a copy constructor; - \i an assignment operator; - \i a default constructor, i.e. a constructor that does not take any arguments. - \endlist - - Note that C++ defaults to field-by-field assignment operators and - copy constructors if no explicit version is supplied. In many - cases this is sufficient. - - In addition, some compilers (e.g. Sun CC) might require that the - class provides an equality operator (operator==()). - - Q3ValueList's function naming is consistent with the other Qt - classes (e.g. count(), isEmpty()). Q3ValueList also provides extra - functions for compatibility with STL algorithms, such as size() - and empty(). Programmers already familiar with the STL \c list may - prefer to use the STL-compatible functions. - - Example: - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 0 - - - Notice that the latest changes to Mary's salary did not affect the - value in the list because the list created a copy of Mary's entry. - - There are several ways to find items in the list. The begin() and - end() functions return iterators to the beginning and end of the - list. The advantage of getting an iterator is that you can move - forward or backward from this position by - incrementing/decrementing the iterator. The iterator returned by - end() points to the item which is one \e past the last item in the - container. The past-the-end iterator is still associated with the - list it belongs to, however it is \e not dereferenceable; - operator*() will not return a well-defined value. If the list is - empty(), the iterator returned by begin() will equal the iterator - returned by end(). - - It is safe to have multiple iterators a the list at the same - time. If some member of the list is removed, only iterators - pointing to the removed member become invalid. Inserting into the - list does not invalidate any iterator. For convenience, the - function last() returns a reference to the last item in the list, - and first() returns a reference to the first item. If the - list is empty(), both last() and first() have undefined behavior - (your application will crash or do unpredictable things). Use - last() and first() with caution, for example: - - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 1 - - Because Q3ValueList is value-based there is no need to be careful - about deleting items in the list. The list holds its own copies - and will free them if the corresponding member or the list itself - is deleted. You can force the list to free all of its items with - clear(). - - Q3ValueList is shared implicitly, which means it can be copied in - constant time, i.e. O(1). If multiple Q3ValueList instances share - the same data and one needs to modify its contents, this modifying - instance makes a copy and modifies its private copy; therefore it - does not affect the other instances; this takes O(n) time. This is - often called "copy on write". If a Q3ValueList is being used in a - multi-threaded program, you must protect all access to the list. - See \l QMutex. - - There are several ways to insert items into the list. The - prepend() and append() functions insert items at the beginning and - the end of the list respectively. The insert() function comes in - several flavors and can be used to add one or more items at - specific positions within the list. - - Items can also be removed from the list in several ways. There - are several variants of the remove() function, which removes a - specific item from the list. The remove() function will find and - remove items according to a specific item value. - - \sa Q3ValueListIterator -*/ - -/*! \typedef Q3ValueList::iterator - The list's iterator type, Q3ValueListIterator. */ -/*! \typedef Q3ValueList::const_iterator - The list's const iterator type, Q3ValueListConstIterator. */ -/*! \typedef Q3ValueList::value_type - The type of the object stored in the list, T. */ -/*! \typedef Q3ValueList::pointer - The pointer to T type. */ -/*! \typedef Q3ValueList::const_pointer - The const pointer to T type. */ -/*! \typedef Q3ValueList::reference - The reference to T type. */ -/*! \typedef Q3ValueList::const_reference - The const reference to T type. */ -/*! \typedef Q3ValueList::size_type - An unsigned integral type, used to represent various sizes. */ -/*! \typedef Q3ValueList::difference_type - \internal -*/ -/*! - \fn Q3ValueList::Q3ValueList() - - Constructs an empty list. -*/ - -/*! - \fn Q3ValueList::Q3ValueList( const Q3ValueList& l ) - \fn Q3ValueList::Q3ValueList( const QList& l ) - \fn Q3ValueList::Q3ValueList( const QLinkedList& l ) - - Constructs a copy of \a l. -*/ - -/*! - \fn Q3ValueList::Q3ValueList( const std::list& l ) - - Contructs a copy of \a l. - - This constructor is provided for compatibility with STL - containers. -*/ - -/*! - \fn Q3ValueList::~Q3ValueList() - - Destroys the list. References to the values in the list and all - iterators of this list become invalidated. Note that it is - impossible for an iterator to check whether or not it is valid: - Q3ValueList is highly tuned for performance, not for error - checking. -*/ - -/*! - \fn bool Q3ValueList::operator== ( const Q3ValueList& l ) const - - Compares both lists. - - Returns TRUE if this list and \a l are equal; otherwise returns - FALSE. -*/ - -/*! - \fn bool Q3ValueList::operator== ( const std::list& l ) const - - \overload - - Returns TRUE if this list and \a l are equal; otherwise returns - FALSE. - - This operator is provided for compatibility with STL containers. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator= ( const Q3ValueList& l ) - - Assigns \a l to this list and returns a reference to this list. - - All iterators of the current list become invalidated by this - operation. The cost of such an assignment is O(1) since Q3ValueList - is implicitly shared. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator= ( const QList& l ) - - Assigns \a l to this list and returns a reference to this list. - - All iterators of the current list become invalidated by this - operation. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator= ( const std::list& l ) - - \overload - - Assigns the contents of \a l to the list. - - All iterators of the current list become invalidated by this - operation. -*/ - -/*! - \fn bool Q3ValueList::operator!= ( const Q3ValueList& l ) const - - Compares both lists. - - Returns TRUE if this list and \a l are unequal; otherwise returns - FALSE. -*/ - -/*! - \fn iterator Q3ValueList::insert( typename Q3ValueList::Iterator it, const T& x ) - - Inserts the value \a x in front of the item pointed to by the - iterator, \a it. - - Returns an iterator pointing at the inserted item. - - \sa append(), prepend() -*/ - -/*! - \fn uint Q3ValueList::remove( const T& x ) - - \overload - - Removes all items that have value \a x and returns the number of - removed items. -*/ - -/*! - \fn QDataStream& operator>>( QDataStream& s, Q3ValueList& l ) - - \relates Q3ValueList - - Reads a list, \a l, from the stream \a s. The type T stored in the - list must implement the streaming operator. -*/ - -/*! - \fn QDataStream& operator<<( QDataStream& s, const Q3ValueList& l ) - - \overload - \relates Q3ValueList - - Writes a list, \a l, to the stream \a s. The type T stored in the - list must implement the streaming operator. -*/ - -/*! - \fn void Q3ValueList::insert( typename Q3ValueList::Iterator pos, - typename Q3ValueList::size_type n, const T& x ) - - \overload - - Inserts \a n copies of \a x before position \a pos. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator<< ( const T& x ) - - Adds the value \a x to the end of the list. - - Returns a reference to the list. -*/ - -/*! - \fn const T& Q3ValueList::operator[] ( typename Q3ValueList::size_type i ) const - - Returns a const reference to the item with index \a i in the list. - It is up to you to check whether this item really exists. You can - do that easily with the count() function. However this operator - does not check whether \a i is in range and will deliver undefined - results if it does not exist. - - \warning This function uses a linear search and can be extremely - slow for large lists. Q3ValueList is not optimized for random item - access. If you need random access use a different container, such - as Q3ValueVector. -*/ - -/*! - \fn T& Q3ValueList::operator[] ( typename Q3ValueList::size_type i ) - - \overload - - Returns a non-const reference to the item with index \a i. -*/ - -/*! - \fn const_iterator Q3ValueList::at( typename Q3ValueList::size_type i ) const - - Returns an iterator pointing to the item at position \a i in the - list, or an undefined value if the index is out of range. - - \warning This function uses a linear search and can be extremely - slow for large lists. Q3ValueList is not optimized for random item - access. If you need random access use a different container, such - as Q3ValueVector. -*/ - -/*! - \fn iterator Q3ValueList::at( typename Q3ValueList::size_type i ) - - \overload - - Returns an iterator pointing to the item at position \a i in the - list, or an undefined value if the index is out of range. - -*/ - -/*! - \fn iterator Q3ValueList::fromLast() - - \overload - - Returns an iterator to the last item in the list, or end() if - there is no last item. - - Use the end() function instead. For example: - - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 2 - -*/ - -/*! - \fn const_iterator Q3ValueList::fromLast() const - - Returns an iterator to the last item in the list, or end() if - there is no last item. - - Use the end() function instead. For example: - - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 3 - -*/ - -/*! - \fn Q3ValueList Q3ValueList::operator+( const Q3ValueList& l ) const - - Creates a new list and fills it with the items of this list. Then - the items of \a l are appended. Returns the new list. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator+= ( const Q3ValueList& l ) - - Appends the items of \a l to this list. Returns a reference to - this list. -*/ - -/*! - \fn Q3ValueList& Q3ValueList::operator+= ( const T& x ) - - \overload - - Appends the value \a x to the list. Returns a reference to the - list. -*/ - -/*! - \fn iterator Q3ValueList::append( const T& x ) - - Inserts \a x at the end of the list. - - \sa insert(), prepend() -*/ - -/*! - \fn iterator Q3ValueList::prepend( const T& x ) - - Inserts \a x at the beginning of the list. - - \sa insert(), append() -*/ - -/*! - \fn iterator Q3ValueList::remove( typename Q3ValueList::Iterator it ) - - Removes the item pointed to by \a it from the list. No iterators - other than \a it or other iterators pointing at the same item as - \a it are invalidated. Returns an iterator to the next item after - \a it, or end() if there is no such item. - - \sa clear() -*/ - -/*! - \fn uint Q3ValueList::contains( const T& x ) const - - Returns the number of occurrences of the value \a x in the list. -*/ - -/*! - \class Q3ValueListIterator - \brief The Q3ValueListIterator class provides an iterator for Q3ValueList. - \compat - - An iterator is a class for accessing the items of a container - class: a generalization of the index in an array. A pointer - into a "const char *" and an index into an "int[]" are both - iterators, and the general idea is to provide that functionality - for any data structure. - - The Q3ValueListIterator class is an iterator for Q3ValueList - instantiations. You can create the appropriate iterator type by - using the \c iterator typedef provided by Q3ValueList. - - The only way to access the items in a Q3ValueList is to use an - iterator. - - Example (see Q3ValueList for the complete code): - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 4 - - Q3ValueList is highly optimized for performance and memory usage. - This means that you must be careful: Q3ValueList does not know - about all its iterators and the iterators don't know to which list - they belong. This makes things very fast, but if you're not - careful, you can get spectacular bugs. Always make sure iterators - are valid before dereferencing them or using them as parameters to - generic algorithms in the STL. - - Using an invalid iterator is undefined (your application will - probably crash). Many Qt functions return const value lists; to - iterate over these you should make a copy and iterate over the - copy. - - For every Iterator there is a ConstIterator. When accessing a - Q3ValueList in a const environment or if the reference or pointer - to the list is itself const, then you must use the ConstIterator. - Its semantics are the same as the Iterator, but it only returns - const references. - - \sa Q3ValueList, Q3ValueListConstIterator -*/ - -/*! - \fn Q3ValueListIterator::Q3ValueListIterator() - - Constructs an unitialized iterator. -*/ - -/*! - \fn Q3ValueListIterator::Q3ValueListIterator(const Q3ValueListIterator &o) - \fn Q3ValueListIterator::Q3ValueListIterator(const typename QLinkedList::iterator &o) - - Constucts a copy of iterator \a o. -*/ - -/*! - \class Q3ValueListConstIterator - \brief The Q3ValueListConstIterator class provides a const iterator - for Q3ValueList. - \compat - - In contrast to Q3ValueListIterator, this class is used to iterate - over a const list. It does not allow modification of the values of - the list since that would break const semantics. - - You can create the appropriate const iterator type by using the \c - const_iterator typedef provided by Q3ValueList. - - For more information on Q3ValueList iterators, see - Q3ValueListIterator. - - \sa Q3ValueListIterator, Q3ValueList -*/ - -/*! - \fn Q3ValueListConstIterator::Q3ValueListConstIterator() - - Constructs an unitialized iterator. -*/ - -/*! - \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const Q3ValueListConstIterator &o) - \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList::const_iterator &o) - \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList::iterator &o) - - Constructs a copy of iterator \a o. -*/ - -/*! - \typedef Q3ValueList::Iterator - - This iterator is an instantiation of Q3ValueListIterator for the - same type as this Q3ValueList. In other words, if you instantiate - Q3ValueList, Iterator is a Q3ValueListIterator. Several - member function use it, such as Q3ValueList::begin(), which returns - an iterator pointing to the first item in the list. - - Functionally, this is almost the same as ConstIterator. The only - difference is that you cannot use ConstIterator for non-const - operations, and that the compiler can often generate better code - if you use ConstIterator. - - \sa Q3ValueListIterator ConstIterator -*/ - -/*! - \typedef Q3ValueList::ConstIterator - - This iterator is an instantiation of Q3ValueListConstIterator for - the same type as this Q3ValueList. In other words, if you - instantiate Q3ValueList, ConstIterator is a - Q3ValueListConstIterator. Several member function use it, such - as Q3ValueList::begin(), which returns an iterator pointing to the - first item in the list. - - Functionally, this is almost the same as Iterator. The only - difference is you cannot use ConstIterator for non-const - operations, and that the compiler can often generate better code - if you use ConstIterator. - - \sa Q3ValueListIterator Iterator -*/ - -/*! - \fn Q3ValueList::operator QList() const - - Automatically converts a Q3ValueList into a QList. -*/ diff --git a/doc/src/q3valuestack.qdoc b/doc/src/q3valuestack.qdoc deleted file mode 100644 index e3ae677..0000000 --- a/doc/src/q3valuestack.qdoc +++ /dev/null @@ -1,149 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3ValueStack - \brief The Q3ValueStack class is a value-based template class that provides a stack. - \compat - - Define a template instance Q3ValueStack\ to create a stack of - values that all have the class X. - - Note that Q3ValueStack does not store pointers to the members of - the stack; it holds a copy of every member. That is why these - kinds of classes are called "value based"; Q3PtrStack, Q3PtrList, - Q3Dict, etc., are "pointer based". - - A stack is a last in, first out (LIFO) structure. Items are added - to the top of the stack with push() and retrieved from the top - with pop(). The top() function provides access to the topmost item - without removing it. - - Example: - \snippet doc/src/snippets/code/doc_src_q3valuestack.qdoc 0 - - Q3ValueStack is a specialized Q3ValueList provided for convenience. - All of Q3ValueList's functionality also applies to Q3PtrStack, for - example the facility to iterate over all elements using - Q3ValueStack::Iterator. See Q3ValueListIterator for further - details. - - Some classes cannot be used within a Q3ValueStack, for example - everything derived from QObject and thus all classes that - implement widgets. Only values can be used in a Q3ValueStack. To - qualify as a value, the class must provide - \list - \i a copy constructor; - \i an assignment operator; - \i a default constructor, i.e. a constructor that does not take any arguments. - \endlist - - Note that C++ defaults to field-by-field assignment operators and - copy constructors if no explicit version is supplied. In many - cases this is sufficient. -*/ - - -/*! - \fn Q3ValueStack::Q3ValueStack() - - Constructs an empty stack. -*/ - -/*! - \fn Q3ValueStack::~Q3ValueStack() - - Destroys the stack. References to the values in the stack and all - iterators of this stack become invalidated. Because Q3ValueStack is - highly tuned for performance, you won't see warnings if you use - invalid iterators because it is impossible for an iterator to - check whether or not it is valid. -*/ - - -/*! - \fn void Q3ValueStack::push( const T& d ) - - Adds element, \a d, to the top of the stack. Last in, first out. - - This function is equivalent to append(). - - \sa pop(), top() -*/ - -/*! - \fn T& Q3ValueStack::top() - - Returns a reference to the top item of the stack or the item - referenced by end() if no such item exists. Note that you must not - change the value the end() iterator points to. - - This function is equivalent to last(). - - \sa pop(), push(), Q3ValueList::fromLast() -*/ - - -/*! - \fn const T& Q3ValueStack::top() const - - \overload - - Returns a reference to the top item of the stack or the item - referenced by end() if no such item exists. - - This function is equivalent to last(). - - \sa pop(), push(), Q3ValueList::fromLast() -*/ - -/*! - \fn T Q3ValueStack::pop() - - Removes the top item from the stack and returns it. - - \sa top() push() -*/ - - - - - diff --git a/doc/src/q3valuevector.qdoc b/doc/src/q3valuevector.qdoc deleted file mode 100644 index 353b7fa..0000000 --- a/doc/src/q3valuevector.qdoc +++ /dev/null @@ -1,274 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class Q3ValueVector - \brief The Q3ValueVector class is a value-based template class that provides a dynamic array. - \compat - - Q3ValueVector is a Qt implementation of an STL-like vector - container. It can be used in your application if the standard \c - vector is not available for your target platforms. - - Q3ValueVector\ defines a template instance to create a vector - of values that all have the class T. Q3ValueVector does not store - pointers to the members of the vector; it holds a copy of every - member. Q3ValueVector is said to be value based; in contrast, - Q3PtrList and Q3Dict are pointer based. - - Q3ValueVector contains and manages a collection of objects of type - T and provides random access iterators that allow the contained - objects to be addressed. Q3ValueVector owns the contained - elements. For more relaxed ownership semantics, see Q3PtrCollection - and friends, which are pointer-based containers. - - Q3ValueVector provides good performance if you append or remove - elements from the end of the vector. If you insert or remove - elements from anywhere but the end, performance is very bad. The - reason for this is that elements must to be copied into new - positions. - - Some classes cannot be used within a Q3ValueVector: for example, - all classes derived from QObject and thus all classes that - implement widgets. Only values can be used in a Q3ValueVector. To - qualify as a value the class must provide: - \list - \i a copy constructor; - \i an assignment operator; - \i a default constructor, i.e., a constructor that does not take any arguments. - \endlist - - Note that C++ defaults to field-by-field assignment operators and - copy constructors if no explicit version is supplied. In many - cases this is sufficient. - - Q3ValueVector uses an STL-like syntax to manipulate and address the - objects it contains. - - Example: - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 0 - - Program output: - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 1 - - As you can see, the most recent change to Joe's salary did not - affect the value in the vector because the vector created a copy - of Joe's entry. - - Many Qt functions return const value vectors; to iterate over - these you should make a copy and iterate over the copy. - - There are several ways to find items in the vector. The begin() - and end() functions return iterators to the beginning and end of - the vector. The advantage of getting an iterator is that you can - move forward or backward from this position by - incrementing/decrementing the iterator. The iterator returned by - end() points to the element which is one past the last element in - the container. The past-the-end iterator is still associated with - the vector it belongs to, however it is \e not dereferenceable; - operator*() will not return a well-defined value. If the vector is - empty(), the iterator returned by begin() will equal the iterator - returned by end(). - - The fastest way to access an element of a vector is by using - operator[]. This function provides random access and will return - a reference to the element located at the specified index. Thus, - you can access every element directly, in constant time, providing - you know the location of the element. It is undefined to access - an element that does not exist (your application will probably - crash). For example: - - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 2 - - Whenever inserting, removing or referencing elements in a vector, - always make sure you are referring to valid positions. For - example: - - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 3 - - The iterators provided by vector are random access iterators, - therefore you can use them with many generic algorithms, for - example, algorithms provided by the STL. - - It is safe to have multiple iterators on the vector at the same - time. Since Q3ValueVector manages memory dynamically, all iterators - can become invalid if a memory reallocation occurs. For example, - if some member of the vector is removed, iterators that point to - the removed element and to all following elements become - invalidated. Inserting into the middle of the vector will - invalidate all iterators. For convenience, the function back() - returns a reference to the last element in the vector, and front() - returns a reference to the first element. If the vector is - empty(), both back() and front() have undefined behavior (your - application will crash or do unpredictable things). Use back() and - front() with caution, for example: - - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 4 - - Because Q3ValueVector manages memory dynamically, it is recommended - that you contruct a vector with an initial size. Inserting and - removing elements happens fastest when: - \list - \i Inserting or removing elements happens at the end() of the - vector; - \i The vector does not need to allocate additional memory. - \endlist - - By creating a Q3ValueVector with a sufficiently large initial size, - there will be less memory allocations. Do not use an initial size - that is too big, since it will still take time to construct all - the empty entries, and the extra space will be wasted if it is - never used. - - Because Q3ValueVector is value-based there is no need to be careful - about deleting elements in the vector. The vector holds its own - copies and will free them if the corresponding member or the - vector itself is deleted. You can force the vector to free all of - its items with clear(). - - Q3ValueVector is shared implicitly, which means it can be copied in - constant time. If multiple Q3ValueVector instances share the same - data and one needs to modify its contents, this modifying instance - makes a copy and modifies its private copy; it thus does not - affect the other instances. This is often called "copy on write". - If a Q3ValueVector is being used in a multi-threaded program, you - must protect all access to the vector. See QMutex. - - There are several ways to insert elements into the vector. The - push_back() function insert elements into the end of the vector, - and is usually fastest. The insert() function can be used to add - elements at specific positions within the vector. - - Items can be also be removed from the vector in several ways. - There are several variants of the erase() function which removes a - specific element, or range of elements, from the vector. - - Q3ValueVector stores its elements in contiguous memory. This means - that you can use a Q3ValueVector in any situation that requires an - array. -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector() - - Constructs an empty vector without any elements. To create a - vector which reserves an initial amount of space for elements, use - \c Q3ValueVector(size_type n). -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector( const Q3ValueVector& v ) - - Constructs a copy of \a v. - - This operation costs O(1) time because Q3ValueVector is implicitly - shared. - - The first modification to the vector does takes O(n) time, because - the elements must be copied. -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector( const std::vector& v ) - - This operation costs O(n) time because \a v is copied. -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector( QVector::size_type n, const T& val ) - - Constructs a vector with an initial size of \a n elements. Each - element is initialized with the value of \a val. -*/ - -/*! - \fn Q3ValueVector& Q3ValueVector::operator=( const Q3ValueVector& v ) - - Assigns \a v to this vector and returns a reference to this vector. - - All iterators of the current vector become invalidated by this - operation. The cost of such an assignment is O(1) since - Q3ValueVector is implicitly shared. -*/ - -/*! - \fn Q3ValueVector& Q3ValueVector::operator=( const std::vector& v ) - - \overload - - Assigns \a v to this vector and returns a reference to this vector. - - All iterators of the current vector become invalidated by this - operation. The cost of this assignment is O(n) since \a v is - copied. -*/ - -/*! - \fn T &Q3ValueVector::at( int i , bool* ok ) - - Returns a reference to the element with index \a i. If \a ok is - non-null, and the index \a i is out of range, *\a ok is set to - FALSE and the returned reference is undefined. If the index \a i - is within the range of the vector, and \a ok is non-null, *\a ok - is set to TRUE and the returned reference is well defined. -*/ - -/*! - \fn const T &Q3ValueVector::at( int i , bool* ok ) const - - \overload - - Returns a const reference to the element with index \a i. If \a ok - is non-null, and the index \a i is out of range, *\a ok is set to - FALSE and the returned reference is undefined. If the index \a i - is within the range of the vector, and \a ok is non-null, *\a ok - is set to TRUE and the returned reference is well defined. -*/ - -/*! - \fn void Q3ValueVector::resize( int n, const T& val = T() ) - - Changes the size of the vector to \a n. If \a n is greater than - the current size(), elements are added to the end and initialized - with the value of \a val. If \a n is less than size(), elements - are removed from the end. If \a n is equal to size() nothing - happens. -*/ diff --git a/doc/src/qalgorithms.qdoc b/doc/src/qalgorithms.qdoc deleted file mode 100644 index 7634322..0000000 --- a/doc/src/qalgorithms.qdoc +++ /dev/null @@ -1,651 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \headerfile - \title Generic Algorithms - \ingroup architecture - - \brief The header provides generic template-based algorithms. - - Qt provides a number of global template functions in \c - that work on containers and perform well-know - algorithms. You can use these algorithms with any \l {container - class} that provides STL-style iterators, including Qt's QList, - QLinkedList, QVector, QMap, and QHash classes. - - These functions have taken their inspiration from similar - functions available in the STL \c header. Most of them - have a direct STL equivalent; for example, qCopyBackward() is the - same as STL's copy_backward() algorithm. - - If STL is available on all your target platforms, you can use the - STL algorithms instead of their Qt counterparts. One reason why - you might want to use the STL algorithms is that STL provides - dozens and dozens of algorithms, whereas Qt only provides the most - important ones, making no attempt to duplicate functionality that - is already provided by the C++ standard. - - Most algorithms take \l {STL-style iterators} as parameters. The - algorithms are generic in the sense that they aren't bound to a - specific iterator class; you can use them with any iterators that - meet a certain set of requirements. - - Let's take the qFill() algorithm as an example. Unlike QVector, - QList has no fill() function that can be used to fill a list with - a particular value. If you need that functionality, you can use - qFill(): - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 0 - - qFill() takes a begin iterator, an end iterator, and a value. - In the example above, we pass \c list.begin() and \c list.end() - as the begin and end iterators, but this doesn't have to be - the case: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 1 - - Different algorithms can have different requirements for the - iterators they accept. For example, qFill() accepts two - \l {forward iterators}. The iterator types required are specified - for each algorithm. If an iterator of the wrong type is passed (for - example, if QList::ConstIterator is passed as an \l {output - iterator}), you will always get a compiler error, although not - necessarily a very informative one. - - Some algorithms have special requirements on the value type - stored in the containers. For example, qEqual() requires that the - value type supports operator==(), which it uses to compare items. - Similarly, qDeleteAll() requires that the value type is a - non-const pointer type (for example, QWidget *). The value type - requirements are specified for each algorithm, and the compiler - will produce an error if a requirement isn't met. - - \target binaryFind example - - The generic algorithms can be used on other container classes - than those provided by Qt and STL. The syntax of STL-style - iterators is modeled after C++ pointers, so it's possible to use - plain arrays as containers and plain pointers as iterators. A - common idiom is to use qBinaryFind() together with two static - arrays: one that contains a list of keys, and another that - contains a list of associated values. For example, the following - code will look up an HTML entity (e.g., \c &) in the \c - name_table array and return the corresponding Unicode value from - the \c value_table if the entity is recognized: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 2 - - This kind of code is for advanced users only; for most - applications, a QMap- or QHash-based approach would work just as - well: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 3 - - \section1 Types of Iterators - - The algorithms have certain requirements on the iterator types - they accept, and these are specified individually for each - function. The compiler will produce an error if a requirement - isn't met. - - \section2 Input Iterators - - An \e{input iterator} is an iterator that can be used for reading - data sequentially from a container. It must provide the following - operators: \c{==} and \c{!=} for comparing two iterators, unary - \c{*} for retrieving the value stored in the item, and prefix - \c{++} for advancing to the next item. - - The Qt containers' iterator types (const and non-const) are all - input iterators. - - \section2 Output Iterators - - An \e{output iterator} is an iterator that can be used for - writing data sequentially to a container or to some output - stream. It must provide the following operators: unary \c{*} for - writing a value (i.e., \c{*it = val}) and prefix \c{++} for - advancing to the next item. - - The Qt containers' non-const iterator types are all output - iterators. - - \section2 Forward Iterators - - A \e{forward iterator} is an iterator that meets the requirements - of both input iterators and output iterators. - - The Qt containers' non-const iterator types are all forward - iterators. - - \section2 Bidirectional Iterators - - A \e{bidirectional iterator} is an iterator that meets the - requirements of forward iterators but that in addition supports - prefix \c{--} for iterating backward. - - The Qt containers' non-const iterator types are all bidirectional - iterators. - - \section2 Random Access Iterators - - The last category, \e{random access iterators}, is the most - powerful type of iterator. It supports all the requirements of a - bidirectional iterator, and supports the following operations: - - \table - \row \i \c{i += n} \i advances iterator \c i by \c n positions - \row \i \c{i -= n} \i moves iterator \c i back by \c n positions - \row \i \c{i + n} or \c{n + i} \i returns the iterator for the item \c - n positions ahead of iterator \c i - \row \i \c{i - n} \i returns the iterator for the item \c n positions behind of iterator \c i - \row \i \c{i - j} \i returns the number of items between iterators \c i and \c j - \row \i \c{i[n]} \i same as \c{*(i + n)} - \row \i \c{i < j} \i returns true if iterator \c j comes after iterator \c i - \endtable - - QList and QVector's non-const iterator types are random access iterators. - - \sa {container classes}, -*/ - -/*! \fn OutputIterator qCopy(InputIterator begin1, InputIterator end1, OutputIterator begin2) - \relates - - Copies the items from range [\a begin1, \a end1) to range [\a - begin2, ...), in the order in which they appear. - - The item at position \a begin1 is assigned to that at position \a - begin2; the item at position \a begin1 + 1 is assigned to that at - position \a begin2 + 1; and so on. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 4 - - \sa qCopyBackward(), {input iterators}, {output iterators} -*/ - -/*! \fn BiIterator2 qCopyBackward(BiIterator1 begin1, BiIterator1 end1, BiIterator2 end2) - \relates - - Copies the items from range [\a begin1, \a end1) to range [..., - \a end2). - - The item at position \a end1 - 1 is assigned to that at position - \a end2 - 1; the item at position \a end1 - 2 is assigned to that - at position \a end2 - 2; and so on. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 5 - - \sa qCopy(), {bidirectional iterators} -*/ - -/*! \fn bool qEqual(InputIterator1 begin1, InputIterator1 end1, InputIterator2 begin2) - \relates - - Compares the items in the range [\a begin1, \a end1) with the - items in the range [\a begin2, ...). Returns true if all the - items compare equal; otherwise returns false. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 6 - - This function requires the item type (in the example above, - QString) to implement \c operator==(). - - \sa {input iterators} -*/ - -/*! \fn void qFill(ForwardIterator begin, ForwardIterator end, const T &value) - \relates - - Fills the range [\a begin, \a end) with \a value. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 7 - - \sa qCopy(), {forward iterators} -*/ - -/*! \fn void qFill(Container &container, const T &value) - \relates - - \overload - - This is the same as qFill(\a{container}.begin(), \a{container}.end(), \a value); -*/ - -/*! \fn InputIterator qFind(InputIterator begin, InputIterator end, const T &value) - \relates - - Returns an iterator to the first occurrence of \a value in a - container in the range [\a begin, \a end). Returns \a end if \a - value isn't found. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 8 - - This function requires the item type (in the example above, - QString) to implement \c operator==(). - - If the items in the range are in ascending order, you can get - faster results by using qLowerBound() or qBinaryFind() instead of - qFind(). - - \sa qBinaryFind(), {input iterators} -*/ - -/*! \fn void qFind(const Container &container, const T &value) - \relates - - \overload - - This is the same as qFind(\a{container}.begin(), \a{container}.end(), value); -*/ - -/*! \fn void qCount(InputIterator begin, InputIterator end, const T &value, Size &n) - \relates - - Returns the number of occurrences of \a value in the range [\a begin, \a end), - which is returned in \a n. \a n is never initialized, the count is added to \a n. - It is the caller's responsibility to initialize \a n. - - Example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 9 - - This function requires the item type (in the example above, - \c int) to implement \c operator==(). - - \sa {input iterators} -*/ - -/*! \fn void qCount(const Container &container, const T &value, Size &n) -\relates - -\overload - -Instead of operating on iterators, as in the other overload, this function -operates on the specified \a container to obtain the number of instances -of \a value in the variable passed as a reference in argument \a n. -*/ - -/*! \fn void qSwap(T &var1, T &var2) - \relates - - Exchanges the values of variables \a var1 and \a var2. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 10 -*/ - -/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end) - \relates - - Sorts the items in range [\a begin, \a end) in ascending order - using the quicksort algorithm. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 11 - - The sort algorithm is efficient on large data sets. It operates - in \l {linear-logarithmic time}, O(\e{n} log \e{n}). - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - If neither of the two items is "less than" the other, the items are - taken to be equal. It is then undefined which one of the two - items will appear before the other after the sort. - - \sa qStableSort(), {random access iterators} -*/ - -/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) - \relates - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - For example, here's how to sort the strings in a QStringList - in case-insensitive alphabetical order: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 12 - - To sort values in reverse order, pass - \l{qGreater()}{qGreater()} as the \a lessThan parameter. For - example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 13 - - If neither of the two items is "less than" the other, the items are - taken to be equal. It is then undefined which one of the two - items will appear before the other after the sort. - - An alternative to using qSort() is to put the items to sort in a - QMap, using the sort key as the QMap key. This is often more - convenient than defining a \a lessThan function. For example, the - following code shows how to sort a list of strings case - insensitively using QMap: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 14 - - \sa QMap -*/ - -/*! \fn void qSort(Container &container) - \relates - - \overload - - This is the same as qSort(\a{container}.begin(), \a{container}.end()); -*/ - -/*! - \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end) - \relates - - Sorts the items in range [\a begin, \a end) in ascending order - using a stable sorting algorithm. - - If neither of the two items is "less than" the other, the items are - taken to be equal. The item that appeared before the other in the - original container will still appear first after the sort. This - property is often useful when sorting user-visible data. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 15 - - The sort algorithm is efficient on large data sets. It operates - in \l {linear-logarithmic time}, O(\e{n} log \e{n}). - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - \sa qSort(), {random access iterators} -*/ - -/*! - \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) - \relates - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - For example, here's how to sort the strings in a QStringList - in case-insensitive alphabetical order: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 16 - - Note that earlier versions of Qt allowed using a lessThan function that took its - arguments by non-const reference. From 4.3 and on this is no longer possible, - the arguments has to be passed by const reference or value. - - To sort values in reverse order, pass - \l{qGreater()}{qGreater()} as the \a lessThan parameter. For - example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 17 - - If neither of the two items is "less than" the other, the items are - taken to be equal. The item that appeared before the other in the - original container will still appear first after the sort. This - property is often useful when sorting user-visible data. -*/ - -/*! - \fn void qStableSort(Container &container) - \relates - - \overload - - This is the same as qStableSort(\a{container}.begin(), \a{container}.end()); -*/ - -/*! \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) - \relates - - Performs a binary search of the range [\a begin, \a end) and - returns the position of the first ocurrence of \a value. If no - such item is found, returns the position where it should be - inserted. - - The items in the range [\a begin, \e end) must be sorted in - ascending order; see qSort(). - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 18 - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - qLowerBound() can be used in conjunction with qUpperBound() to - iterate over all occurrences of the same value: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 19 - - \sa qUpperBound(), qBinaryFind() -*/ - -/*! - \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) - \relates - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - Note that the items in the range must be sorted according to the order - specified by the \a lessThan object. -*/ - -/*! - \fn void qLowerBound(const Container &container, const T &value) - \relates - - \overload - - For read-only iteration over containers, this function is broadly equivalent to - qLowerBound(\a{container}.begin(), \a{container}.end(), value). However, since it - returns a const iterator, you cannot use it to modify the container; for example, - to insert items. -*/ - -/*! \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) - \relates - - Performs a binary search of the range [\a begin, \a end) and - returns the position of the one-past-the-last occurrence of \a - value. If no such item is found, returns the position where the - item should be inserted. - - The items in the range [\a begin, \e end) must be sorted in - ascending order; see qSort(). - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 20 - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - qUpperBound() can be used in conjunction with qLowerBound() to - iterate over all occurrences of the same value: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 21 - - \sa qLowerBound(), qBinaryFind() -*/ - -/*! - \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) - \relates - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - Note that the items in the range must be sorted according to the order - specified by the \a lessThan object. -*/ - -/*! - \fn void qUpperBound(const Container &container, const T &value) - \relates - - \overload - - This is the same as qUpperBound(\a{container}.begin(), \a{container}.end(), value); -*/ - - -/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value) - \relates - - Performs a binary search of the range [\a begin, \a end) and - returns the position of an occurrence of \a value. If there are - no occurrences of \a value, returns \a end. - - The items in the range [\a begin, \a end) must be sorted in - ascending order; see qSort(). - - If there are many occurrences of the same value, any one of them - could be returned. Use qLowerBound() or qUpperBound() if you need - finer control. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 22 - - This function requires the item type (in the example above, - QString) to implement \c operator<(). - - See the \l{#binaryFind example}{detailed - description} for an example usage. - - \sa qLowerBound(), qUpperBound(), {random access iterators} -*/ - -/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) - \relates - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - Note that the items in the range must be sorted according to the order - specified by the \a lessThan object. -*/ - -/*! - \fn void qBinaryFind(const Container &container, const T &value) - \relates - - \overload - - This is the same as qBinaryFind(\a{container}.begin(), \a{container}.end(), value); -*/ - - -/*! - \fn void qDeleteAll(ForwardIterator begin, ForwardIterator end) - \relates - - Deletes all the items in the range [\a begin, \a end) using the - C++ \c delete operator. The item type must be a pointer type (for - example, \c{QWidget *}). - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 23 - - Notice that qDeleteAll() doesn't remove the items from the - container; it merely calls \c delete on them. In the example - above, we call clear() on the container to remove the items. - - This function can also be used to delete items stored in - associative containers, such as QMap and QHash. Only the objects - stored in each container will be deleted by this function; objects - used as keys will not be deleted. - - \sa {forward iterators} -*/ - -/*! - \fn void qDeleteAll(const Container &c) - \relates - - \overload - - This is the same as qDeleteAll(\a{c}.begin(), \a{c}.end()). -*/ - -/*! \fn LessThan qLess() - \relates - - Returns a functional object, or functor, that can be passed to qSort() - or qStableSort(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 24 - - \sa {qGreater()}{qGreater()} -*/ - -/*! \fn LessThan qGreater() - \relates - - Returns a functional object, or functor, that can be passed to qSort() - or qStableSort(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 25 - - \sa {qLess()}{qLess()} -*/ diff --git a/doc/src/qcache.qdoc b/doc/src/qcache.qdoc deleted file mode 100644 index 6c88ede..0000000 --- a/doc/src/qcache.qdoc +++ /dev/null @@ -1,244 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QCache - \brief The QCache class is a template class that provides a cache. - - \ingroup tools - \ingroup shared - \mainclass - \reentrant - - QCache\ defines a cache that stores objects of type T - associated with keys of type Key. For example, here's the - definition of a cache that stores objects of type Employee - associated with an integer key: - - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 0 - - Here's how to insert an object in the cache: - - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 1 - - The advantage of using QCache over some other key-based data - structure (such as QMap or QHash) is that QCache automatically - takes ownership of the objects that are inserted into the cache and - deletes them to make room for new objects, if necessary. When - inserting an object into the cache, you can specify a \e{cost}, - which should bear some approximate relationship to the amount of - memory taken by the object. When the sum of all objects' costs - (totalCost()) exceeds the cache's limit (maxCost()), QCache starts - deleting objects in the cache to keep under the limit, starting with - less recently accessed objects. - - By default, QCache's maxCost() is 100. You can specify a - different value in the QCache constructor: - - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 2 - - Each time you call insert(), you can specify a cost as third - argument (after the key and a pointer to the object to insert). - After the call, the inserted object is owned by the QCache, which - may delete it at any time to make room for other objects. - - To look up objects in the cache, use object() or - operator[](). This function looks up an object by its key, and - returns either a pointer to the cached object (which is owned by - the cache) or 0. - - If you want to remove an object from the cache for a particular key, - call remove(). This will also delete the object. If you want to - remove an object from the cache without the QCache deleting it, use - take(). - - \sa QPixmapCache, QHash, QMap -*/ - -/*! \fn QCache::QCache(int maxCost = 100) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost. -*/ - -/*! \fn QCache::~QCache() - - Destroys the cache. Deletes all the objects in the cache. -*/ - -/*! \fn int QCache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost(), totalCost() -*/ - -/*! \fn void QCache::setMaxCost(int cost) - - Sets the maximum allowed total cost of the cache to \a cost. If - the current total cost is greater than \a cost, some objects are - deleted immediately. - - \sa maxCost(), totalCost() -*/ - -/*! \fn int QCache::totalCost() const - - Returns the total cost of the objects in the cache. - - This value is normally below maxCost(), but QCache makes an - exception for Qt's \l{implicitly shared} classes. If a cached - object shares its internal data with another instance, QCache may - keep the object lying around, possibly contributing to making - totalCost() larger than maxCost(). - - \sa setMaxCost() -*/ - -/*! \fn int QCache::size() const - - Returns the number of objects in the cache. - - \sa isEmpty() -*/ - -/*! \fn int QCache::count() const - - Same as size(). -*/ - -/*! \fn bool QCache::isEmpty() const - - Returns true if the cache contains no objects; otherwise - returns false. - - \sa size() -*/ - -/*! \fn QList QCache::keys() const - - Returns a list of the keys in the cache. -*/ - -/*! \fn void QCache::clear(); - - Deletes all the objects in the cache. - - \sa remove(), take() -*/ - - -/*! \fn bool QCache::insert(const Key &key, T *object, int cost = 1) - - Inserts \a object into the cache with key \a key and - associated cost \a cost. Any object with the same key already in - the cache will be removed. - - After this call, \a object is owned by the QCache and may be - deleted at any time. In particular, if \a cost is greater than - maxCost(), the object will be deleted immediately. - - The function returns true if the object was inserted into the - cache; otherwise it returns false. - - \sa take(), remove() -*/ - -/*! \fn T *QCache::object(const Key &key) const - - Returns the object associated with key \a key, or 0 if the key does - not exist in the cache. - - \warning The returned object is owned by QCache and may be - deleted at any time. - - \sa take(), remove() -*/ - -/*! \fn bool QCache::contains(const Key &key) const - - Returns true if the cache contains an object associated with key \a - key; otherwise returns false. - - \sa take(), remove() -*/ - -/*! \fn T *QCache::operator[](const Key &key) const - - Returns the object associated with key \a key, or 0 if the key does - not exist in the cache. - - This is the same as object(). - - \warning The returned object is owned by QCache and may be - deleted at any time. -*/ - -/*! \fn bool QCache::remove(const Key &key) - - Deletes the object associated with key \a key. Returns true if the - object was found in the cache; otherwise returns false. - - \sa take(), clear() -*/ - -/*! \fn T *QCache::take(const Key &key) - - Takes the object associated with key \a key out of the cache - without deleting it. Returns a pointer to the object taken out, or - 0 if the key does not exist in the cache. - - The ownership of the returned object is passed to the caller. - - \sa remove() -*/ - -/*! - \fn QCache::QCache(int maxCost, int dummy) - - Use QCache(int) instead. -*/ - -/*! - \fn T *QCache::find(const Key &key) const - - Use object() instead. -*/ diff --git a/doc/src/qcolormap.qdoc b/doc/src/qcolormap.qdoc deleted file mode 100644 index 95f7dc0..0000000 --- a/doc/src/qcolormap.qdoc +++ /dev/null @@ -1,152 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QColormap - \ingroup multimedia - - \brief The QColormap class maps device independent QColors to device - dependent pixel values. -*/ - -/*! \enum QColormap::Mode - - This enum describes how QColormap maps device independent RGB - values to device dependent pixel values. - - \value Direct Pixel values are derived directly from the RGB - values, also known as "True Color." - - \value Indexed Pixel values represent indexes into a vector of - available colors, i.e. QColormap uses the index of the color that - most closely matches an RGB value. - - \value Gray Similar to \c Indexed, pixel values represent a vector - of available gray tones. QColormap uses the index of the gray - tone that most closely matches the computed gray tone of an RGB - value. -*/ - -/*! - \fn QColormap QColormap::instance(int screen) - - Returns the colormap for the specified \a screen. If \a screen is - -1, this function returns the colormap for the default screen. -*/ - -/*! - \fn QColormap::QColormap(const QColormap &colormap) - - Constructs a copy of another \a colormap. -*/ - -/*! - \fn QColormap::~QColormap() - - Destroys the colormap. -*/ - -/*! - \fn int QColormap::size() const - - Returns the size of the colormap for \c Indexed and \c Gray modes; - Returns -1 for \c Direct mode. - - \sa colormap() -*/ - -/*! - \fn uint QColormap::pixel(const QColor &color) const - - Returns a device dependent pixel value for the \a color. - - \sa colorAt() -*/ - -/*! - \fn int QColormap::depth() const - - Returns the depth of the device. - - \sa size() -*/ - -/*! - \fn QColormap::Mode QColormap::mode() const - - Returns the mode of this colormap. - - \sa QColormap::Mode -*/ - -/*! - \fn const QColor QColormap::colorAt(uint pixel) const - - Returns a QColor for the \a pixel. - - \sa pixel() -*/ - -/*! - \fn const QVector QColormap::colormap() const - - Returns a vector of colors which represents the devices colormap - for \c Indexed and \c Gray modes. This function returns an empty - vector for \c Direct mode. - - \sa size() -*/ - -/*! \fn HPALETTE QColormap::hPal() - - This function is only available on Windows. - - Returns an handle to the HPALETTE used by this colormap. If no - HPALETTE is being used, this function returns zero. -*/ - -/*! \since 4.2 - - \fn QColormap &QColormap::operator=(const QColormap &colormap) - - Assigns the given \a colormap to \e this color map and returns - a reference to \e this color map. -*/ diff --git a/doc/src/qdesktopwidget.qdoc b/doc/src/qdesktopwidget.qdoc deleted file mode 100644 index 56a882d..0000000 --- a/doc/src/qdesktopwidget.qdoc +++ /dev/null @@ -1,266 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QDesktopWidget - \brief The QDesktopWidget class provides access to screen information on multi-head systems. - - \ingroup advanced - \ingroup desktop - \ingroup environment - \mainclass - - QApplication::desktop() function should be used to get an instance - of the QDesktopWidget. - - Systems with more than one graphics card and monitor can manage the - physical screen space available either as multiple desktops, or as a - large virtual desktop, which usually has the size of the bounding - rectangle of all the screens (see virtualDesktop). For an - application, one of the available screens is the primary screen, i.e. - the screen where the main widget resides (see primaryScreen). All - windows opened in the context of the application should be - constrained to the boundaries of the primary screen; for example, - it would be inconvenient if a dialog box popped up on a different - screen, or split over two screens. - - The QDesktopWidget provides information about the geometry of the - available screens with screenGeometry(). The number of screens - available is returned by screenCount, and the screenCountChanged - signal is emitted when screens are added or removed during runtime. - The screen number that a particular point or widget is located in - is returned by screenNumber(). - - Widgets provided by Qt use this class, for example, to place - tooltips, menus and dialog boxes according to the parent or - application widget. Applications can use this class to save window - positions, or to place child widgets and dialogs on one particular - screen. - - \img qdesktopwidget.png Managing Multiple Screens - - In the illustration above, Application One's primary screen is - screen 0, and App Two's primary screen is screen 1. - - \target multiple screens note - \note QDesktopWidget inherits the QWidget properties, width() and - height(), which specify the size of the desktop. However, for - desktops with multiple screens, the size of the desktop is the union - of all the screen sizes, so width() and height() should \e not be - used for computing the size of a widget to be placed on one of the - screens. The correct width and height values are obtained using - availableGeometry() or screenGeometry() for a particular screen. - - \sa QApplication, QApplication::desktop(), QX11Info::appRootWindow() -*/ - -/*! - \fn QDesktopWidget::QDesktopWidget() - - \internal - - Creates the desktop widget. - - If the system supports a virtual desktop, this widget will have - the size of the virtual desktop; otherwise this widget will have - the size of the primary screen. - - Instead of using QDesktopWidget directly, use QApplication::desktop(). -*/ - -/*! - \fn QDesktopWidget::~QDesktopWidget() - - \internal - - Destroys the desktop widget and frees any allocated resources. -*/ - -/*! - \fn int QDesktopWidget::numScreens() const - - Returns the number of available screens. - - \obsolete - - This function is deprecated. Use screenCount instead. - - \sa primaryScreen -*/ - -/*! - \fn QWidget *QDesktopWidget::screen(int screen) - - Returns a widget that represents the screen with index \a screen - (a value of -1 means the default screen). - - If the system uses a virtual desktop, the returned widget will - have the geometry of the entire virtual desktop; i.e., bounding - every \a screen. - - \sa primaryScreen, screenCount, virtualDesktop -*/ - -/*! - \fn const QRect QDesktopWidget::availableGeometry(int screen) const - - Returns the available geometry of the screen with index \a screen. What - is available will be subrect of screenGeometry() based on what the - platform decides is available (for example excludes the dock and menu bar - on Mac OS X, or the task bar on Windows). The default screen is used if - \a screen is -1. - - \sa screenNumber(), screenGeometry() -*/ - -/*! - \fn const QRect QDesktopWidget::availableGeometry(const QWidget *widget) const - \overload - - Returns the available geometry of the screen which contains \a widget. - - \sa screenGeometry() -*/ - -/*! - \fn const QRect QDesktopWidget::availableGeometry(const QPoint &p) const - \overload - - Returns the available geometry of the screen which contains \a p. - - \sa screenGeometry() -*/ - - -/*! - \fn const QRect QDesktopWidget::screenGeometry(int screen) const - - Returns the geometry of the screen with index \a screen. The default - screen is used if \a screen is -1. - - \sa screenNumber() -*/ - -/*! - \fn const QRect QDesktopWidget::screenGeometry(const QWidget *widget) const - \overload - - Returns the geometry of the screen which contains \a widget. -*/ - -/*! - \fn const QRect QDesktopWidget::screenGeometry(const QPoint &p) const - \overload - - Returns the geometry of the screen which contains \a p. -*/ - - -/*! - \fn int QDesktopWidget::screenNumber(const QWidget *widget) const - - Returns the index of the screen that contains the largest - part of \a widget, or -1 if the widget not on a screen. - - \sa primaryScreen -*/ - -/*! - \fn int QDesktopWidget::screenNumber(const QPoint &point) const - - \overload - Returns the index of the screen that contains the \a point, or the - screen which is the shortest distance from the \a point. - - \sa primaryScreen -*/ - -/*! - \fn void QDesktopWidget::resizeEvent(QResizeEvent *event) - \reimp -*/ - -/*! - \fn void QDesktopWidget::resized(int screen) - - This signal is emitted when the size of \a screen changes. -*/ - -/*! - \fn void QDesktopWidget::workAreaResized(int screen) - - This signal is emitted when the work area available on \a screen changes. -*/ - -/*! - \property QDesktopWidget::screenCount - \brief the number of screens currently available on the system. - - \since 4.6 - - \sa screenCountChanged() -*/ - -/*! - \property QDesktopWidget::primaryScreen - \brief the index of the screen that is configured to be the primary screen - on the system. -*/ - -/*! - \property QDesktopWidget::virtualDesktop - - \brief if the system manages the available screens in a virtual desktop. - - For virtual desktops, screen() will always return the same widget. - The size of the virtual desktop is the size of this desktop - widget. -*/ - -/*! - \fn void QDesktopWidget::screenCountChanged(int newCount) - - \since 4.6 - - This signal is emitted when the number of screens changes to \a newCount. - - \sa screenCount -*/ diff --git a/doc/src/qiterator.qdoc b/doc/src/qiterator.qdoc deleted file mode 100644 index 416b4bc..0000000 --- a/doc/src/qiterator.qdoc +++ /dev/null @@ -1,1431 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QListIterator - \inmodule QtCore - - \brief The QListIterator class provides a Java-style const iterator for QList and QQueue. - - QList has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QList member functions take an index as their first parameter, - making it possible to access, modify, and remove items without - using iterators. - - QListIterator\ allows you to iterate over a QList\ (or a - QQueue\). If you want to modify the list as you iterate over - it, use QMutableListIterator\ instead. - - The QListIterator constructor takes a QList as argument. After - construction, the iterator is located at the very beginning of - the list (before the first item). Here's how to iterate over all - the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 0 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, and returns the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 1 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same list. If the list is - modified while a QListIterator is active, the QListIterator will - continue iterating over the original list, ignoring the modified - copy. - - \sa QMutableListIterator, QList::const_iterator -*/ - -/*! - \class QLinkedListIterator - \inmodule QtCore - - \brief The QLinkedListIterator class provides a Java-style const iterator for QLinkedList. - - QLinkedList has both \l{Java-style iterators} and - \l{STL-style iterators}. The Java-style iterators are more - high-level and easier to use than the STL-style iterators; on the - other hand, they are slightly less efficient. - - QLinkedListIterator\ allows you to iterate over a - QLinkedList\. If you want to modify the list as you iterate - over it, use QMutableLinkedListIterator\ instead. - - The QLinkedListIterator constructor takes a QLinkedList as - argument. After construction, the iterator is located at the very - beginning of the list (before the first item). Here's how to - iterate over all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 2 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, and returns the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 3 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same list. If the list is - modified while a QLinkedListIterator is active, the - QLinkedListIterator will continue iterating over the original - list, ignoring the modified copy. - - \sa QMutableLinkedListIterator, QLinkedList::const_iterator -*/ - -/*! - \class QVectorIterator - \inmodule QtCore - \brief The QVectorIterator class provides a Java-style const iterator for QVector and QStack. - - QVector has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QVector member functions take an index as their first parameter, - making it possible to access, insert, and remove items without - using iterators. - - QVectorIterator\ allows you to iterate over a QVector\ - (or a QStack\). If you want to modify the vector as you - iterate over it, use QMutableVectorIterator\ instead. - - The QVectorIterator constructor takes a QVector as argument. - After construction, the iterator is located at the very beginning - of the vector (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 4 - - The next() function returns the next item in the vector and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 5 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same vector. If the vector - is modified while a QVectorIterator is active, the QVectorIterator - will continue iterating over the original vector, ignoring the - modified copy. - - \sa QMutableVectorIterator, QVector::const_iterator -*/ - -/*! - \class QSetIterator - \inmodule QtCore - \brief The QSetIterator class provides a Java-style const iterator for QSet. - - QSet supports both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QSetIterator\ allows you to iterate over a QSet\. If you - want to modify the set as you iterate over it, use - QMutableSetIterator\ instead. - - The constructor takes a QSet as argument. After construction, the - iterator is located at the very beginning of the set (before - the first item). Here's how to iterate over all the elements - sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 6 - - The next() function returns the next item in the set and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 7 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same set. If the set - is modified while a QSetIterator is active, the QSetIterator - will continue iterating over the original set, ignoring the - modified copy. - - \sa QMutableSetIterator, QSet::const_iterator -*/ - -/*! - \class QMutableListIterator - \inmodule QtCore - - \brief The QMutableListIterator class provides a Java-style non-const iterator for QList and QQueue. - - QList has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QList member functions take an index as their first parameter, - making it possible to access, insert, and remove items without - using iterators. - - QMutableListIterator\ allows you to iterate over a QList\ - (or a QQueue\) and modify the list. If you don't want to - modify the list (or have a const QList), use the slightly faster - QListIterator\ instead. - - The QMutableListIterator constructor takes a QList as argument. - After construction, the iterator is located at the very beginning - of the list (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 8 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 9 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - If you want to remove items as you iterate over the list, use - remove(). If you want to modify the value of an item, use - setValue(). If you want to insert a new item in the list, use - insert(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 10 - - The example traverses a list, replacing negative numbers with - their absolute values, and eliminating zeroes. - - Only one mutable iterator can be active on a given list at any - time. Furthermore, no changes should be done directly to the list - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QListIterator, QList::iterator -*/ - -/*! - \class QMutableLinkedListIterator - \inmodule QtCore - - \brief The QMutableLinkedListIterator class provides a Java-style non-const iterator for QLinkedList. - - QLinkedList has both \l{Java-style iterators} and - \l{STL-style iterators}. The Java-style iterators are more - high-level and easier to use than the STL-style iterators; on the - other hand, they are slightly less efficient. - - QMutableLinkedListIterator\ allows you to iterate over a - QLinkedList\ and modify the list. If you don't want to modify - the list (or have a const QLinkedList), use the slightly faster - QLinkedListIterator\ instead. - - The QMutableLinkedListIterator constructor takes a QLinkedList as - argument. After construction, the iterator is located at the very - beginning of the list (before the first item). Here's how to - iterate over all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 11 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 12 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - If you want to remove items as you iterate over the list, use - remove(). If you want to modify the value of an item, use - setValue(). If you want to insert a new item in the list, use - insert(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 13 - - The example traverses a list, replacing negative numbers with - their absolute values, and eliminating zeroes. - - Only one mutable iterator can be active on a given list at any - time. Furthermore, no changes should be done directly to the list - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QLinkedListIterator, QLinkedList::iterator -*/ - -/*! - \class QMutableVectorIterator - \inmodule QtCore - - \brief The QMutableVectorIterator class provides a Java-style non-const iterator for QVector and QStack. - - QVector has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QVector member functions take an index as their first parameter, - making it possible to access, insert, and remove items without - using iterators. - - QMutableVectorIterator\ allows you to iterate over a - QVector\ and modify the vector. If you don't want to modify - the vector (or have a const QVector), use the slightly faster - QVectorIterator\ instead. - - The QMutableVectorIterator constructor takes a QVector as - argument. After construction, the iterator is located at the very - beginning of the list (before the first item). Here's how to - iterate over all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 14 - - The next() function returns the next item in the vector and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 15 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - If you want to remove items as you iterate over the vector, use - remove(). If you want to modify the value of an item, use - setValue(). If you want to insert a new item in the vector, use - insert(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 16 - - The example traverses a vector, replacing negative numbers with - their absolute values, and eliminating zeroes. - - Only one mutable iterator can be active on a given vector at any - time. Furthermore, no changes should be done directly to the - vector while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QVectorIterator, QVector::iterator -*/ - -/*! - \class QMutableSetIterator - \inmodule QtCore - \since 4.2 - - \brief The QMutableSetIterator class provides a Java-style non-const iterator for QSet. - - QSet has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMutableSetIterator\ allows you to iterate over a QSet\ - and remove items from the set as you iterate. If you don't want - to modify the set (or have a const QSet), use the slightly faster - QSetIterator\ instead. - - The QMutableSetIterator constructor takes a QSet as argument. - After construction, the iterator is located at the very beginning - of the set (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 17 - - The next() function returns the next item in the set and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 18 - - If you want to remove items as you iterate over the set, use - remove(). - - Only one mutable iterator can be active on a given set at any - time. Furthermore, no changes should be done directly to the set - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QSetIterator, QSet::iterator -*/ - -/*! - \fn QListIterator::QListIterator(const QList &list) - \fn QLinkedListIterator::QLinkedListIterator(const QLinkedList &list) - \fn QMutableListIterator::QMutableListIterator(QList &list) - \fn QMutableLinkedListIterator::QMutableLinkedListIterator(QLinkedList &list) - - Constructs an iterator for traversing \a list. The iterator is - set to be at the front of the list (before the first item). - - \sa operator=() -*/ - -/*! - \fn QVectorIterator::QVectorIterator(const QVector &vector) - \fn QMutableVectorIterator::QMutableVectorIterator(QVector &vector) - - Constructs an iterator for traversing \a vector. The iterator is - set to be at the front of the vector (before the first item). - - \sa operator=() -*/ - -/*! - \fn QSetIterator::QSetIterator(const QSet &set) - \fn QMutableSetIterator::QMutableSetIterator(QSet &set) - - Constructs an iterator for traversing \a set. The iterator is - set to be at the front of the set (before the first item). - - \sa operator=() -*/ - -/*! - \fn QMutableListIterator::~QMutableListIterator() - \fn QMutableLinkedListIterator::~QMutableLinkedListIterator() - \fn QMutableVectorIterator::~QMutableVectorIterator() - \fn QMutableSetIterator::~QMutableSetIterator() - - Destroys the iterator. - - \sa operator=() -*/ - -/*! \fn QMutableListIterator &QMutableListIterator::operator=(QList &list) - \fn QMutableLinkedListIterator &QMutableLinkedListIterator::operator=(QLinkedList &list) - \fn QListIterator &QListIterator::operator=(const QList &list) - \fn QLinkedListIterator &QLinkedListIterator::operator=(const QLinkedList &list) - - Makes the iterator operate on \a list. The iterator is set to be - at the front of the list (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn QVectorIterator &QVectorIterator::operator=(const QVector &vector) - \fn QMutableVectorIterator &QMutableVectorIterator::operator=(QVector &vector) - - Makes the iterator operate on \a vector. The iterator is set to be - at the front of the vector (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn QSetIterator &QSetIterator::operator=(const QSet &set) - \fn QMutableSetIterator &QMutableSetIterator::operator=(QSet &set) - - Makes the iterator operate on \a set. The iterator is set to be - at the front of the set (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn void QListIterator::toFront() - \fn void QLinkedListIterator::toFront() - \fn void QVectorIterator::toFront() - \fn void QSetIterator::toFront() - \fn void QMutableListIterator::toFront() - \fn void QMutableLinkedListIterator::toFront() - \fn void QMutableVectorIterator::toFront() - \fn void QMutableSetIterator::toFront() - - Moves the iterator to the front of the container (before the - first item). - - \sa toBack(), next() -*/ - -/*! \fn void QListIterator::toBack() - \fn void QLinkedListIterator::toBack() - \fn void QVectorIterator::toBack() - \fn void QSetIterator::toBack() - \fn void QMutableListIterator::toBack() - \fn void QMutableLinkedListIterator::toBack() - \fn void QMutableVectorIterator::toBack() - \fn void QMutableSetIterator::toBack() - - Moves the iterator to the back of the container (after the last - item). - - \sa toFront(), previous() -*/ - -/*! \fn bool QListIterator::hasNext() const - \fn bool QLinkedListIterator::hasNext() const - \fn bool QVectorIterator::hasNext() const - \fn bool QSetIterator::hasNext() const - \fn bool QMutableListIterator::hasNext() const - \fn bool QMutableLinkedListIterator::hasNext() const - \fn bool QMutableVectorIterator::hasNext() const - \fn bool QMutableSetIterator::hasNext() const - - Returns true if there is at least one item ahead of the iterator, - i.e. the iterator is \e not at the back of the container; - otherwise returns false. - - \sa hasPrevious(), next() -*/ - -/*! \fn const T &QListIterator::next() - \fn const T &QLinkedListIterator::next() - \fn const T &QVectorIterator::next() - \fn const T &QSetIterator::next() - \fn const T &QMutableSetIterator::next() - - Returns the next item and advances the iterator by one position. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn T &QMutableListIterator::next() - \fn T &QMutableLinkedListIterator::next() - \fn T &QMutableVectorIterator::next() - - Returns a reference to the next item, and advances the iterator - by one position. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn const T &QListIterator::peekNext() const - \fn const T &QLinkedListIterator::peekNext() const - \fn const T &QVectorIterator::peekNext() const - \fn const T &QSetIterator::peekNext() const - \fn const T &QMutableSetIterator::peekNext() const - - Returns the next item without moving the iterator. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn T &QMutableListIterator::peekNext() const - \fn T &QMutableLinkedListIterator::peekNext() const - \fn T &QMutableVectorIterator::peekNext() const - - Returns a reference to the next item, without moving the iterator. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn bool QListIterator::hasPrevious() const - \fn bool QLinkedListIterator::hasPrevious() const - \fn bool QVectorIterator::hasPrevious() const - \fn bool QSetIterator::hasPrevious() const - \fn bool QMutableListIterator::hasPrevious() const - \fn bool QMutableLinkedListIterator::hasPrevious() const - \fn bool QMutableVectorIterator::hasPrevious() const - \fn bool QMutableSetIterator::hasPrevious() const - - Returns true if there is at least one item behind the iterator, - i.e. the iterator is \e not at the front of the container; - otherwise returns false. - - \sa hasNext(), previous() -*/ - -/*! \fn const T &QListIterator::previous() - \fn const T &QLinkedListIterator::previous() - \fn const T &QVectorIterator::previous() - \fn const T &QSetIterator::previous() - \fn const T &QMutableSetIterator::previous() - - Returns the previous item and moves the iterator back by one - position. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn T &QMutableListIterator::previous() - \fn T &QMutableLinkedListIterator::previous() - \fn T &QMutableVectorIterator::previous() - - Returns a reference to the previous item and moves the iterator - back by one position. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn const T &QListIterator::peekPrevious() const - \fn const T &QLinkedListIterator::peekPrevious() const - \fn const T &QVectorIterator::peekPrevious() const - \fn const T &QSetIterator::peekPrevious() const - \fn const T &QMutableSetIterator::peekPrevious() const - - Returns the previous item without moving the iterator. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn T &QMutableListIterator::peekPrevious() const - \fn T &QMutableLinkedListIterator::peekPrevious() const - \fn T &QMutableVectorIterator::peekPrevious() const - - Returns a reference to the previous item, without moving the iterator. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn bool QListIterator::findNext(const T &value) - \fn bool QLinkedListIterator::findNext(const T &value) - \fn bool QVectorIterator::findNext(const T &value) - \fn bool QSetIterator::findNext(const T &value) - \fn bool QMutableListIterator::findNext(const T &value) - \fn bool QMutableLinkedListIterator::findNext(const T &value) - \fn bool QMutableVectorIterator::findNext(const T &value) - \fn bool QMutableSetIterator::findNext(const T &value) - - Searches for \a value starting from the current iterator position - forward. Returns true if \a value is found; otherwise returns false. - - After the call, if \a value was found, the iterator is positioned - just after the matching item; otherwise, the iterator is - positioned at the back of the container. - - \sa findPrevious() -*/ - -/*! \fn bool QListIterator::findPrevious(const T &value) - \fn bool QLinkedListIterator::findPrevious(const T &value) - \fn bool QVectorIterator::findPrevious(const T &value) - \fn bool QSetIterator::findPrevious(const T &value) - \fn bool QMutableListIterator::findPrevious(const T &value) - \fn bool QMutableLinkedListIterator::findPrevious(const T &value) - \fn bool QMutableVectorIterator::findPrevious(const T &value) - \fn bool QMutableSetIterator::findPrevious(const T &value) - - Searches for \a value starting from the current iterator position - backward. Returns true if \a value is found; otherwise returns - false. - - After the call, if \a value was found, the iterator is positioned - just before the matching item; otherwise, the iterator is - positioned at the front of the container. - - \sa findNext() -*/ - -/*! \fn void QMutableListIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 19 - - \sa insert(), setValue() -*/ - -/*! \fn void QMutableLinkedListIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 20 - - \sa insert(), setValue() -*/ - -/*! \fn void QMutableVectorIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 21 - - \sa insert(), setValue() -*/ - -/*! \fn void QMutableSetIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 22 - - \sa value() -*/ - -/*! \fn void QMutableListIterator::setValue(const T &value) const - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 23 - - \sa value(), remove(), insert() -*/ - -/*! \fn void QMutableLinkedListIterator::setValue(const T &value) const - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 24 - - \sa value(), remove(), insert() -*/ - -/*! \fn void QMutableVectorIterator::setValue(const T &value) const - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 25 - - \sa value(), remove(), insert() -*/ - -/*! \fn const T &QMutableListIterator::value() const - \fn const T &QMutableLinkedListIterator::value() const - \fn const T &QMutableVectorIterator::value() const - \fn const T &QMutableSetIterator::value() const - - Returns the value of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), value() is equivalent to - peekPrevious(). After a call to previous() or findPrevious(), value() is - equivalent to peekNext(). -*/ - -/*! - \fn T &QMutableListIterator::value() - \fn T &QMutableLinkedListIterator::value() - \fn T &QMutableVectorIterator::value() - \overload - - Returns a non-const reference to the value of the last item that - was jumped over using one of the traversal functions. -*/ - -/*! \fn void QMutableListIterator::insert(const T &value) - \fn void QMutableLinkedListIterator::insert(const T &value) - \fn void QMutableVectorIterator::insert(const T &value) - - Inserts \a value at the current iterator position. After the - call, the iterator is located just after the inserted item. - - \sa remove(), setValue() -*/ - -/*! - \class QMapIterator - \inmodule QtCore - - \brief The QMapIterator class provides a Java-style const iterator for QMap and QMultiMap. - - QMap has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMapIterator\ allows you to iterate over a QMap (or a - QMultiMap). If you want to modify the map as you iterate over - it, use QMutableMapIterator instead. - - The QMapIterator constructor takes a QMap as argument. After - construction, the iterator is located at the very beginning of - the map (before the first item). Here's how to iterate over all - the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 26 - - The next() function returns the next item in the map and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 27 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 28 - - Multiple iterators can be used on the same map. If the map is - modified while a QMapIterator is active, the QMapIterator will - continue iterating over the original map, ignoring the modified - copy. - - \sa QMutableMapIterator, QMap::const_iterator -*/ - -/*! - \class QHashIterator - \inmodule QtCore - - \brief The QHashIterator class provides a Java-style const iterator for QHash and QMultiHash. - - QHash has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QHashIterator\ allows you to iterate over a QHash (or a - QMultiHash). If you want to modify the hash as you iterate over - it, use QMutableHashIterator instead. - - The QHashIterator constructor takes a QHash as argument. After - construction, the iterator is located at the very beginning of - the hash (before the first item). Here's how to iterate over all - the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 29 - - The next() function returns the next item in the hash and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 30 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 31 - - Multiple iterators can be used on the same hash. If the hash is - modified while a QHashIterator is active, the QHashIterator will - continue iterating over the original hash, ignoring the modified - copy. - - \sa QMutableHashIterator, QHash::const_iterator -*/ - -/*! - \class QMutableMapIterator - \inmodule QtCore - - \brief The QMutableMapIterator class provides a Java-style non-const iterator for QMap and QMultiMap. - - QMap has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMutableMapIterator\ allows you to iterate over a QMap - (or a QMultiMap) and modify the map. If you don't want to modify - the map (or have a const QMap), use the slightly faster - QMapIterator instead. - - The QMutableMapIterator constructor takes a QMap as argument. - After construction, the iterator is located at the very beginning - of the map (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 32 - - The next() function returns the next item in the map and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 33 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 34 - - If you want to remove items as you iterate over the map, use - remove(). If you want to modify the value of an item, use - setValue(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 35 - - The example removes all (key, value) pairs where the key and the - value are the same. - - Only one mutable iterator can be active on a given map at any - time. Furthermore, no changes should be done directly to the map - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QMapIterator, QMap::iterator -*/ - -/*! - \class QMutableHashIterator - \inmodule QtCore - - \brief The QMutableHashIterator class provides a Java-style non-const iterator for QHash and QMultiHash. - - QHash has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMutableHashIterator\ allows you to iterate over a QHash - (or a QMultiHash) and modify the hash. If you don't want to modify - the hash (or have a const QHash), use the slightly faster - QHashIterator instead. - - The QMutableHashIterator constructor takes a QHash as argument. - After construction, the iterator is located at the very beginning - of the hash (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 36 - - The next() function returns the next item in the hash and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 37 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 38 - - If you want to remove items as you iterate over the hash, use - remove(). If you want to modify the value of an item, use - setValue(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 39 - - The example removes all (key, value) pairs where the key and the - value are the same. - - Only one mutable iterator can be active on a given hash at any - time. Furthermore, no changes should be done directly to the hash - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QHashIterator, QHash::iterator -*/ - -/*! \fn QMapIterator::QMapIterator(const QMap &map) - \fn QMutableMapIterator::QMutableMapIterator(QMap &map) - - Constructs an iterator for traversing \a map. The iterator is set - to be at the front of the map (before the first item). - - \sa operator=() -*/ - -/*! \fn QHashIterator::QHashIterator(const QHash &hash) - \fn QMutableHashIterator::QMutableHashIterator(QHash &hash) - - Constructs an iterator for traversing \a hash. The iterator is - set to be at the front of the hash (before the first item). - - \sa operator=() -*/ - -/*! - \fn QMutableMapIterator::~QMutableMapIterator() - \fn QMutableHashIterator::~QMutableHashIterator() - - Destroys the iterator. - - \sa operator=() -*/ - -/*! \fn QMapIterator &QMapIterator::operator=(const QMap &map) - \fn QMutableMapIterator &QMutableMapIterator::operator=(QMap &map) - - Makes the iterator operate on \a map. The iterator is set to be - at the front of the map (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn QHashIterator &QHashIterator::operator=(const QHash &hash) - \fn QMutableHashIterator &QMutableHashIterator::operator=(QHash &hash) - - Makes the iterator operate on \a hash. The iterator is set to be - at the front of the hash (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn void QMapIterator::toFront() - \fn void QHashIterator::toFront() - \fn void QMutableMapIterator::toFront() - \fn void QMutableHashIterator::toFront() - - Moves the iterator to the front of the container (before the - first item). - - \sa toBack(), next() -*/ - -/*! \fn void QMapIterator::toBack() - \fn void QHashIterator::toBack() - \fn void QMutableMapIterator::toBack() - \fn void QMutableHashIterator::toBack() - - Moves the iterator to the back of the container (after the last - item). - - \sa toFront(), previous() -*/ - -/*! \fn bool QMapIterator::hasNext() const - \fn bool QHashIterator::hasNext() const - \fn bool QMutableMapIterator::hasNext() const - \fn bool QMutableHashIterator::hasNext() const - - Returns true if there is at least one item ahead of the iterator, - i.e. the iterator is \e not at the back of the container; - otherwise returns false. - - \sa hasPrevious(), next() -*/ - -/*! \fn QMapIterator::Item QMapIterator::next() - \fn QHashIterator::Item QHashIterator::next() - - Returns the next item and advances the iterator by one position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::next() - \fn QMutableHashIterator::Item QMutableHashIterator::next() - - Returns the next item and advances the iterator by one position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn QMapIterator::Item QMapIterator::peekNext() const - \fn QHashIterator::Item QHashIterator::peekNext() const - - Returns the next item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekNext() const - \fn QMutableHashIterator::Item QMutableHashIterator::peekNext() const - - Returns a reference to the next item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn bool QMapIterator::hasPrevious() const - \fn bool QHashIterator::hasPrevious() const - \fn bool QMutableMapIterator::hasPrevious() const - \fn bool QMutableHashIterator::hasPrevious() const - - Returns true if there is at least one item behind the iterator, - i.e. the iterator is \e not at the front of the container; - otherwise returns false. - - \sa hasNext(), previous() -*/ - -/*! \fn QMapIterator::Item QMapIterator::previous() - \fn QHashIterator::Item QHashIterator::previous() - - Returns the previous item and moves the iterator back by one - position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::previous() - \fn QMutableHashIterator::Item QMutableHashIterator::previous() - - Returns the previous item and moves the iterator back by one - position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn QMapIterator::Item QMapIterator::peekPrevious() const - \fn QHashIterator::Item QHashIterator::peekPrevious() const - - Returns the previous item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekPrevious() const - \fn QMutableHashIterator::Item QMutableHashIterator::peekPrevious() const - - Returns the previous item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn const T &QMapIterator::value() const - \fn const T &QHashIterator::value() const - - Returns the value of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), value() is - equivalent to peekPrevious().value(). After a call to previous() - or findPrevious(), value() is equivalent to peekNext().value(). - - \sa key() -*/ - -/*! - \fn const T &QMutableMapIterator::value() const - \fn const T &QMutableHashIterator::value() const - - Returns the value of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), value() is - equivalent to peekPrevious().value(). After a call to previous() - or findPrevious(), value() is equivalent to peekNext().value(). - - \sa key(), setValue() -*/ - -/*! - \fn T &QMutableMapIterator::value() - \fn T &QMutableHashIterator::value() - \overload - - Returns a non-const reference to the value of - the last item that was jumped over using one - of the traversal functions. -*/ - -/*! \fn const Key &QMapIterator::key() const - \fn const Key &QHashIterator::key() const - \fn const Key &QMutableMapIterator::key() const - \fn const Key &QMutableHashIterator::key() const - - Returns the key of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), key() is - equivalent to peekPrevious().key(). After a call to previous() or - findPrevious(), key() is equivalent to peekNext().key(). - - \sa value() -*/ - -/*! \fn bool QMapIterator::findNext(const T &value) - \fn bool QHashIterator::findNext(const T &value) - \fn bool QMutableMapIterator::findNext(const T &value) - \fn bool QMutableHashIterator::findNext(const T &value) - - Searches for \a value starting from the current iterator position - forward. Returns true if a (key, value) pair with value \a value - is found; otherwise returns false. - - After the call, if \a value was found, the iterator is positioned - just after the matching item; otherwise, the iterator is - positioned at the back of the container. - - \sa findPrevious() -*/ - -/*! \fn bool QMapIterator::findPrevious(const T &value) - \fn bool QHashIterator::findPrevious(const T &value) - \fn bool QMutableMapIterator::findPrevious(const T &value) - \fn bool QMutableHashIterator::findPrevious(const T &value) - - Searches for \a value starting from the current iterator position - backward. Returns true if a (key, value) pair with value \a value - is found; otherwise returns false. - - After the call, if \a value was found, the iterator is positioned - just before the matching item; otherwise, the iterator is - positioned at the front of the container. - - \sa findNext() -*/ - -/*! \fn void QMutableMapIterator::remove() - \fn void QMutableHashIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - \sa setValue() -*/ - -/*! \fn void QMutableMapIterator::setValue(const T &value) - \fn void QMutableHashIterator::setValue(const T &value) - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - \sa key(), value(), remove() -*/ diff --git a/doc/src/qpagesetupdialog.qdoc b/doc/src/qpagesetupdialog.qdoc deleted file mode 100644 index 7f0b09e..0000000 --- a/doc/src/qpagesetupdialog.qdoc +++ /dev/null @@ -1,84 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QPageSetupDialog - - \brief The QPageSetupDialog class provides a configuration dialog - for the page-related options on a printer. - - On Windows and Mac OS X the page setup dialog is implemented using - the native page setup dialogs. - - Note that on Windows and Mac OS X custom paper sizes won't be - reflected in the native page setup dialogs. Additionally, custom - page margins set on a QPrinter won't show in the native Mac OS X - page setup dialog. - - \sa QPrinter, QPrintDialog -*/ - - -/*! - \fn QPageSetupDialog::QPageSetupDialog(QPrinter *printer, QWidget *parent) - - Constructs a page setup dialog that configures \a printer with \a - parent as the parent widget. -*/ - -/*! - \since 4.5 - - \fn QPageSetupDialog::QPageSetupDialog(QWidget *parent) - - Constructs a page setup dialog that configures a default-constructed - QPrinter with \a parent as the parent widget. - - \sa printer() -*/ - -/*! - \fn QPrinter *QPageSetupDialog::printer() - - Returns the printer that was passed to the QPageSetupDialog - constructor. -*/ - diff --git a/doc/src/qpaintdevice.qdoc b/doc/src/qpaintdevice.qdoc deleted file mode 100644 index 0f4e9a0..0000000 --- a/doc/src/qpaintdevice.qdoc +++ /dev/null @@ -1,289 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QPaintDevice - \brief The QPaintDevice class is the base class of objects that - can be painted. - - \ingroup multimedia - - A paint device is an abstraction of a two-dimensional space that - can be drawn using a QPainter. Its default coordinate system has - its origin located at the top-left position. X increases to the - right and Y increases downwards. The unit is one pixel. - - The drawing capabilities of QPaintDevice are currently implemented - by the QWidget, QImage, QPixmap, QGLPixelBuffer, QPicture, and - QPrinter subclasses. - - To implement support for a new backend, you must derive from - QPaintDevice and reimplement the virtual paintEngine() function to - tell QPainter which paint engine should be used to draw on this - particular device. Note that you also must create a corresponding - paint engine to be able to draw on the device, i.e derive from - QPaintEngine and reimplement its virtual functions. - - \warning Qt requires that a QApplication object exists before - any paint devices can be created. Paint devices access window - system resources, and these resources are not initialized before - an application object is created. - - The QPaintDevice class provides several functions returning the - various device metrics: The depth() function returns its bit depth - (number of bit planes). The height() function returns its height - in default coordinate system units (e.g. pixels for QPixmap and - QWidget) while heightMM() returns the height of the device in - millimeters. Similiarily, the width() and widthMM() functions - return the width of the device in default coordinate system units - and in millimeters, respectively. Alternatively, the protected - metric() function can be used to retrieve the metric information - by specifying the desired PaintDeviceMetric as argument. - - The logicalDpiX() and logicalDpiY() functions return the - horizontal and vertical resolution of the device in dots per - inch. The physicalDpiX() and physicalDpiY() functions also return - the resolution of the device in dots per inch, but note that if - the logical and vertical resolution differ, the corresponding - QPaintEngine must handle the mapping. Finally, the numColors() - function returns the number of different colors available for the - paint device. - - \sa QPaintEngine, QPainter, {The Coordinate System}, {The Paint - System} -*/ - -/*! - \enum QPaintDevice::PaintDeviceMetric - - Describes the various metrics of a paint device. - - \value PdmWidth The width of the paint device in default - coordinate system units (e.g. pixels for QPixmap and QWidget). See - also width(). - - \value PdmHeight The height of the paint device in default - coordinate system units (e.g. pixels for QPixmap and QWidget). See - also height(). - - \value PdmWidthMM The width of the paint device in millimeters. See - also widthMM(). - - \value PdmHeightMM The height of the paint device in millimeters. See - also heightMM(). - - \value PdmNumColors The number of different colors available for - the paint device. See also numColors(). - - \value PdmDepth The bit depth (number of bit planes) of the paint - device. See also depth(). - - \value PdmDpiX The horizontal resolution of the device in dots per - inch. See also logicalDpiX(). - - \value PdmDpiY The vertical resolution of the device in dots per inch. See - also logicalDpiY(). - - \value PdmPhysicalDpiX The horizontal resolution of the device in - dots per inch. See also physicalDpiX(). - - \value PdmPhysicalDpiY The vertical resolution of the device in - dots per inch. See also physicalDpiY(). - - \sa metric() -*/ - -/*! - \fn QPaintDevice::QPaintDevice() - - Constructs a paint device. This constructor can be invoked only from - subclasses of QPaintDevice. -*/ - -/*! - \fn QPaintDevice::~QPaintDevice() - - Destroys the paint device and frees window system resources. -*/ - -/*! - \fn int QPaintDevice::devType() const - - \internal - - Returns the device type identifier, which is QInternal::Widget - if the device is a QWidget, QInternal::Pixmap if it's a - QPixmap, QInternal::Printer if it's a QPrinter, - QInternal::Picture if it's a QPicture, or - QInternal::UnknownDevice in other cases. -*/ - -/*! - \fn bool QPaintDevice::paintingActive() const - - Returns true if the device is currently being painted on, i.e. someone has - called QPainter::begin() but not yet called QPainter::end() for - this device; otherwise returns false. - - \sa QPainter::isActive() -*/ - -/*! - \fn QPaintEngine *QPaintDevice::paintEngine() const - - Returns a pointer to the paint engine used for drawing on the - device. -*/ - -/*! - \fn int QPaintDevice::metric(PaintDeviceMetric metric) const - - Returns the metric information for the given paint device \a metric. - - \sa PaintDeviceMetric -*/ - -/*! - \fn int QPaintDevice::width() const - - Returns the width of the paint device in default coordinate system - units (e.g. pixels for QPixmap and QWidget). - - \sa widthMM() -*/ - -/*! - \fn int QPaintDevice::height() const - - Returns the height of the paint device in default coordinate - system units (e.g. pixels for QPixmap and QWidget). - - \sa heightMM() -*/ - -/*! - \fn int QPaintDevice::widthMM() const - - Returns the width of the paint device in millimeters. Due to platform - limitations it may not be possible to use this function to determine - the actual physical size of a widget on the screen. - - \sa width() -*/ - -/*! - \fn int QPaintDevice::heightMM() const - - Returns the height of the paint device in millimeters. Due to platform - limitations it may not be possible to use this function to determine - the actual physical size of a widget on the screen. - - \sa height() -*/ - -/*! - \fn int QPaintDevice::numColors() const - - Returns the number of different colors available for the paint - device. Since this value is an int, it will not be sufficient to represent - the number of colors on 32 bit displays, in this case INT_MAX is - returned instead. -*/ - -/*! - \fn int QPaintDevice::depth() const - - Returns the bit depth (number of bit planes) of the paint device. -*/ - -/*! - \fn int QPaintDevice::logicalDpiX() const - - Returns the horizontal resolution of the device in dots per inch, - which is used when computing font sizes. For X11, this is usually - the same as could be computed from widthMM(). - - Note that if the logicalDpiX() doesn't equal the physicalDpiX(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa logicalDpiY(), physicalDpiX() -*/ - -/*! - \fn int QPaintDevice::logicalDpiY() const - - Returns the vertical resolution of the device in dots per inch, - which is used when computing font sizes. For X11, this is usually - the same as could be computed from heightMM(). - - Note that if the logicalDpiY() doesn't equal the physicalDpiY(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa logicalDpiX(), physicalDpiY() -*/ - -/*! - \fn int QPaintDevice::physicalDpiX() const - - Returns the horizontal resolution of the device in dots per inch. - For example, when printing, this resolution refers to the physical - printer's resolution. The logical DPI on the other hand, refers to - the resolution used by the actual paint engine. - - Note that if the physicalDpiX() doesn't equal the logicalDpiX(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa physicalDpiY(), logicalDpiX() -*/ - -/*! - \fn int QPaintDevice::physicalDpiY() const - - Returns the horizontal resolution of the device in dots per inch. - For example, when printing, this resolution refers to the physical - printer's resolution. The logical DPI on the other hand, refers to - the resolution used by the actual paint engine. - - Note that if the physicalDpiY() doesn't equal the logicalDpiY(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa physicalDpiX(), logicalDpiY() -*/ diff --git a/doc/src/qpair.qdoc b/doc/src/qpair.qdoc deleted file mode 100644 index 6d8a0f9..0000000 --- a/doc/src/qpair.qdoc +++ /dev/null @@ -1,229 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QPair - \brief The QPair class is a template class that stores a pair of items. - - \ingroup tools - - QPair\ can be used in your application if the STL \c - pair type is not available. It stores one value of type T1 and - one value of type T2. It can be used as a return value for a - function that needs to return two values, or as the value type of - a \l{generic container}. - - Here's an example of a QPair that stores one QString and one \c - double value: - - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 0 - - The components are accessible as public data members called \l - first and \l second. For example: - - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 1 - - QPair's template data types (T1 and T2) must be \l{assignable - data types}. You cannot, for example, store a QWidget as a value; - instead, store a QWidget *. A few functions have additional - requirements; these requirements are documented on a per-function - basis. - - \sa {Generic Containers} -*/ - -/*! \typedef QPair::first_type - - The type of the first element in the pair (T1). - - \sa first -*/ - -/*! \typedef QPair::second_type - - The type of the second element in the pair (T2). - - \sa second -*/ - -/*! \variable QPair::first - - The first element in the pair. -*/ - -/*! \variable QPair::second - - The second element in the pair. -*/ - -/*! \fn QPair::QPair() - - Constructs an empty pair. The \c first and \c second elements are - initialized with \l{default-constructed values}. -*/ - -/*! - \fn QPair::QPair(const T1 &value1, const T2 &value2) - - Constructs a pair and initializes the \c first element with \a - value1 and the \c second element with \a value2. - - \sa qMakePair() -*/ - -/*! - \fn QPair &QPair::operator=(const QPair &other) - - Assigns \a other to this pair. -*/ - -/*! \fn bool operator==(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is equal to \a p2; otherwise returns false. - Two pairs compare equal if their \c first data members compare - equal and if their \c second data members compare equal. - - This function requires the T1 and T2 types to have an - implementation of \c operator==(). -*/ - -/*! \fn bool operator!=(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is not equal to \a p2; otherwise returns - false. Two pairs compare as not equal if their \c first data - members are not equal or if their \c second data members are not - equal. - - This function requires the T1 and T2 types to have an - implementation of \c operator==(). -*/ - -/*! \fn bool operator<(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is less than \a p2; otherwise returns - false. The comparison is done on the \c first members of \a p1 - and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn bool operator>(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is greater than \a p2; otherwise returns - false. The comparison is done on the \c first members of \a p1 - and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn bool operator<=(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is less than or equal to \a p2; otherwise - returns false. The comparison is done on the \c first members of - \a p1 and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn bool operator>=(const QPair &p1, const QPair &p2) - - \relates QPair - - Returns true if \a p1 is greater than or equal to \a p2; - otherwise returns false. The comparison is done on the \c first - members of \a p1 and \a p2; if they compare equal, the \c second - members are compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! - \fn QPair qMakePair(const T1 &value1, const T2 &value2) - - \relates QPair - - Returns a QPair\ that contains \a value1 and \a value2. - Example: - - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 2 - - This is equivalent to QPair(\a value1, \a value2), but - usually requires less typing. -*/ - -/*! \fn QDataStream &operator>>(QDataStream &in, QPair &pair) - - \relates QPair - - Reads a pair from stream \a in into \a pair. - - This function requires the T1 and T2 types to implement \c operator>>(). - - \sa {Format of the QDataStream operators} -*/ - -/*! \fn QDataStream &operator<<(QDataStream &out, const QPair &pair) - - \relates QPair - - Writes the pair \a pair to stream \a out. - - This function requires the T1 and T2 types to implement \c operator<<(). - - \sa {Format of the QDataStream operators} -*/ diff --git a/doc/src/qpatternistdummy.cpp b/doc/src/qpatternistdummy.cpp deleted file mode 100644 index a690184..0000000 --- a/doc/src/qpatternistdummy.cpp +++ /dev/null @@ -1,1010 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - - This file exists only to make internal all the classes you see - below. they are all in the QPatternist namespace, but they don't - have qdoc documentation because they are all declared in xxx_p.h files. Without these \internal declarations, the class names - appear on the Inheritance Hierarchy page, which is bad because - clicking on them brings up the "File not found" page. - */ - -#include "qitem_p.h" -#include "qbuiltintypes_p.h" -#include "qitem_p.h" -#include "qschematypefactory_p.h" -#include "qxmlname.h" -#include "qatomictype_p.h" - -QT_BEGIN_NAMESPACE - -using namespace QPatternist; - -/*! - \class AtomicCaster - \internal - */ - -/*! - \class AtomicComparator - \internal - */ - -/*! - \class AtomicMathematician - \internal - */ - -/*! - \class AtomicValue - \internal - */ - -/*! - \class AbstractDateTime - \internal - */ - -/*! - \class AbstractDuration - \internal - */ - -/*! - \class AbstractFloatComparator - \internal - */ - -/*! - \class AtomicString - \internal - */ - -/*! - \class Base64Binary - \internal - */ - -/*! - \class FunctionCall - \internal - */ - -/*! - \class AddingAggregate - \internal - */ - -/*! - \class AdjustTimezone - \internal - */ - -/*! - \class Aggregator - \internal - */ - -/*! - \class ComparesCaseAware - \internal - */ - -/*! - \class EncodeString - \internal - */ - -/*! - \class ExtractFromDateTimeFN - \internal - */ - -/*! - \class ExtractFromDurationFN - \internal - */ - -/*! - \class FunctionFactory - \internal - */ - -/*! - \class Numeric - \internal - */ - -/*! - \class ReportContext - \internal - */ - -/*! - \class AbstractFunctionFactory - \internal - */ - -/*! - \class DynamicContext - \internal - */ - -/*! - \class IdFN - \internal - */ - -/*! - \class IntegerType - \internal - */ - -/*! - \class NamespaceResolver - \internal - */ - -/*! - \class PatternPlatform - \internal - */ - -/*! \class DocumentProjector - \internal */ -/*! \class NodeBuilder - \internal */ -/*! \class AccelTreeBuilder - \internal */ -/*! \class OutputValidator - \internal */ -/*! \class NetworkLoop - \internal */ -/*! \class QIODeviceDelegate - \internal */ -/*! \class URILoader - \internal */ -/*! \class AbsFN - \internal */ -/*! \class AbstractDateTimeComparator - \internal */ -/*! \class AbstractDateTimeMathematician - \internal */ -/*! \class AbstractDateTimeToDateCaster - \internal */ -/*! \class AbstractDateTimeToDateTimeCaster - \internal */ -/*! \class AbstractDateTimeToGDayCaster - \internal */ -/*! \class AbstractDateTimeToGMonthCaster - \internal */ -/*! \class AbstractDateTimeToGMonthDayCaster - \internal */ -/*! \class AbstractDateTimeToGYearCaster - \internal */ -/*! \class AbstractDateTimeToGYearMonthCaster - \internal */ -/*! \class AbstractDateTimeToTimeCaster - \internal */ -/*! \class AbstractDurationComparator - \internal */ -/*! \class AbstractDurationToDayTimeDurationCaster - \internal */ -/*! \class AbstractDurationToDurationCaster - \internal */ -/*! \class AbstractDurationToYearMonthDurationCaster - \internal */ -/*! \class AbstractFloat - \internal */ -/*! \class AbstractFloatMathematician - \internal */ -/*! \class AbstractFloatSortComparator - \internal */ -/*! \class ConstructorFunctionsFactory - \internal */ -/*! \class XPath10CoreFunctions - \internal */ -/*! \class XPath20CoreFunctions - \internal */ -/*! \class AdjustDateTimeToTimezoneFN - \internal */ -/*! \class AdjustDateToTimezoneFN - \internal */ -/*! \class AdjustTimeToTimezoneFN - \internal */ -/*! \class AnyToDerivedStringCaster - \internal */ -/*! \class AnyURI - \internal */ -/*! \class Atomizer - \internal */ -/*! \class AvgFN - \internal */ -/*! \class Base64BinaryComparatorLocator - \internal */ -/*! \class Base64BinaryToHexBinaryCaster - \internal */ -/*! \class Base64BinaryType - \internal */ -/*! \class BaseURIFN - \internal */ -/*! \class BinaryDataComparator - \internal */ -/*! \class Boolean - \internal */ -/*! \class BooleanComparator - \internal */ -/*! \class BooleanComparatorLocator - \internal */ -/*! \class BooleanFN - \internal */ -/*! \class BooleanToAbstractFloatCaster - \internal */ -/*! \class BooleanToDecimalCaster - \internal */ -/*! \class BooleanToDerivedIntegerCaster - \internal */ -/*! \class BooleanToIntegerCaster - \internal */ -/*! \class BooleanType - \internal */ -/*! \class BuiltinNodeType - \internal */ -/*! \class CardinalityVerifier - \internal */ -/*! \class CaseInsensitiveStringComparator - \internal */ -/*! \class CeilingFN - \internal */ -/*! \class CodepointEqualFN - \internal */ -/*! \class CodepointsToStringFN - \internal */ -/*! \class CollectionFN - \internal */ -/*! \class CompareFN - \internal */ -/*! \class ComparingAggregator - \internal */ -/*! \class ConcatFN - \internal */ -/*! \class ContainsFN - \internal */ -/*! \class CountFN - \internal */ -/*! \class CurrentDateFN - \internal */ -/*! \class CurrentDateTimeFN - \internal */ -/*! \class CurrentTimeFN - \internal */ -/*! \class Date - \internal */ -/*! \class DateComparatorLocator - \internal */ -/*! \class DateMathematicianLocator - \internal */ -/*! \class DateTime - \internal */ -/*! \class DateTimeComparatorLocator - \internal */ -/*! \class DateTimeDurationMathematician - \internal */ -/*! \class DateTimeFN - \internal */ -/*! \class DateTimeMathematicianLocator - \internal */ -/*! \class DateTimeType - \internal */ -/*! \class DateType - \internal */ -/*! \class DayFromAbstractDateTimeFN - \internal */ -/*! \class DayTimeDuration - \internal */ -/*! \class DayTimeDurationComparatorLocator - \internal */ -/*! \class DayTimeDurationMathematicianLocator - \internal */ -/*! \class DayTimeDurationType - \internal */ -/*! \class DaysFromDurationFN - \internal */ -/*! \class Decimal - \internal */ -/*! \class DecimalComparator - \internal */ -/*! \class DecimalComparatorLocator - \internal */ -/*! \class DecimalMathematician - \internal */ -/*! \class DecimalMathematicianLocator - \internal */ -/*! \class DecimalType - \internal */ -/*! \class DeduplicateIterator - \internal */ -/*! \class DeepEqualFN - \internal */ -/*! \class DefaultCollationFN - \internal */ -/*! \class DerivedInteger - \internal */ -/*! \class DerivedString - \internal */ -/*! \class DistinctValuesFN - \internal */ -/*! \class DocAvailableFN - \internal */ -/*! \class DocFN - \internal */ -/*! \class DocumentURIFN - \internal */ -/*! \class DoubleComparatorLocator - \internal */ -/*! \class DoubleMathematicianLocator - \internal */ -/*! \class DoubleType - \internal */ -/*! \class Duration - \internal */ -/*! \class DurationComparatorLocator - \internal */ -/*! \class DurationDurationDivisor - \internal */ -/*! \class DurationDurationMathematician - \internal */ -/*! \class DurationNumericMathematician - \internal */ -/*! \class DurationType - \internal */ -/*! \class DelegatingDynamicContext - \internal */ -/*! \class Focus - \internal */ -/*! \class ReceiverDynamicContext - \internal */ -/*! \class EmptyIterator - \internal */ -/*! \class EncodeForURIFN - \internal */ -/*! \class EndsWithFN - \internal */ -/*! \class ErrorFN - \internal */ -/*! \class EscapeHtmlURIFN - \internal */ -/*! \class EvaluationCache - \internal */ -/*! \class Existence - \internal */ -/*! \class ExpressionVisitor - \internal */ -/*! \class ExpressionVisitorResult - \internal */ -/*! \class FalseFN - \internal */ -/*! \class FloatComparatorLocator - \internal */ -/*! \class FloatMathematicianLocator - \internal */ -/*! \class FloatType - \internal */ -/*! \class FloorFN - \internal */ -/*! \class FunctionArgument - \internal */ -/*! \class FunctionAvailableFN - \internal */ -/*! \class FunctionFactoryCollection - \internal */ -/*! \class FunctionSignature - \internal */ -/*! \class GDay - \internal */ -/*! \class GDayComparatorLocator - \internal */ -/*! \class GDayType - \internal */ -/*! \class GMonth - \internal */ -/*! \class GMonthComparatorLocator - \internal */ -/*! \class GMonthDay - \internal */ -/*! \class GMonthDayComparatorLocator - \internal */ -/*! \class GMonthDayType - \internal */ -/*! \class GMonthType - \internal */ -/*! \class GYear - \internal */ -/*! \class GYearComparatorLocator - \internal */ -/*! \class GYearMonth - \internal */ -/*! \class GYearMonthComparatorLocator - \internal */ -/*! \class GYearMonthType - \internal */ -/*! \class GYearType - \internal */ -/*! \class HexBinary - \internal */ -/*! \class HexBinaryComparatorLocator - \internal */ -/*! \class HexBinaryToBase64BinaryCaster - \internal */ -/*! \class HexBinaryType - \internal */ -/*! \class HoursFromAbstractDateTimeFN - \internal */ -/*! \class HoursFromDurationFN - \internal */ -/*! \class IdrefFN - \internal */ -/*! \class ImplicitTimezoneFN - \internal */ -/*! \class InScopePrefixesFN - \internal */ -/*! \class IndexOfFN - \internal */ -/*! \class InsertBeforeFN - \internal */ -/*! \class Integer - \internal */ -/*! \class IntegerComparator - \internal */ -/*! \class IntegerComparatorLocator - \internal */ -/*! \class IntegerMathematician - \internal */ -/*! \class IntegerMathematicianLocator - \internal */ -/*! \class DerivedIntegerType - \internal */ -/*! \class IriToURIFN - \internal */ -/*! \class ItemMappingIterator - \internal */ -/*! \class ItemVerifier - \internal */ -/*! \class LangFN - \internal */ -/*! \class LastFN - \internal */ -/*! \class LocalNameFN - \internal */ -/*! \class LocalNameFromQNameFN - \internal */ -/*! \class LowerCaseFN - \internal */ -/*! \class MinutesFromAbstractDateTimeFN - \internal */ -/*! \class MinutesFromDurationFN - \internal */ -/*! \class MonthFromAbstractDateTimeFN - \internal */ -/*! \class MonthsFromDurationFN - \internal */ -/*! \class NOTATIONType - \internal */ -/*! \class NameFN - \internal */ -/*! \class NamePool - \internal */ -/*! \class DelegatingNamespaceResolver - \internal */ -/*! \class GenericNamespaceResolver - \internal */ -/*! \class NodeNamespaceResolver - \internal */ -/*! \class NamespaceURIFN - \internal */ -/*! \class NamespaceURIForPrefixFN - \internal */ -/*! \class NamespaceURIFromQNameFN - \internal */ -/*! \class NilledFN - \internal */ -/*! \class NodeNameFN - \internal */ -/*! \class NormalizeSpaceFN - \internal */ -/*! \class NormalizeUnicodeFN - \internal */ -/*! \class NotFN - \internal */ -/*! \class NumberFN - \internal */ -/*! \class NumericToAbstractFloatCaster - \internal */ -/*! \class NumericToBooleanCaster - \internal */ -/*! \class NumericToDecimalCaster - \internal */ -/*! \class NumericToDerivedIntegerCaster - \internal */ -/*! \class OperandSwitcherMathematician - \internal */ -/*! \class ParserContext - \internal */ -/*! \class MatchesFN - \internal */ -/*! \class ReplaceFN - \internal */ -/*! \class TokenizeFN - \internal */ -/*! \class PositionFN - \internal */ -/*! \class PrefixFromQNameFN - \internal */ -/*! \class AccelTree - \internal */ -/*! \class QNameComparator - \internal */ -/*! \class QNameComparatorLocator - \internal */ -/*! \class QNameFN - \internal */ -/*! \class QNameType - \internal */ -/*! \class QNameValue - \internal */ -/*! \class RemoveFN - \internal */ -/*! \class ResolveQNameFN - \internal */ -/*! \class ResolveURIFN - \internal */ -/*! \class ResourceLoader - \internal */ -/*! \class AccelTreeResourceLoader - \internal */ -/*! \class ReverseFN - \internal */ -/*! \class RootFN - \internal */ -/*! \class RoundFN - \internal */ -/*! \class RoundHalfToEvenFN - \internal */ -/*! \class SchemaTime - \internal */ -/*! \class SchemaTimeComparatorLocator - \internal */ -/*! \class SchemaTimeMathematicianLocator - \internal */ -/*! \class SchemaTimeType - \internal */ -/*! \class SecondsFromAbstractDateTimeFN - \internal */ -/*! \class SecondsFromDurationFN - \internal */ -/*! \class SelfToSelfCaster - \internal */ -/*! \class SequenceMappingIterator - \internal */ -/*! \class SingletonIterator - \internal */ -/*! \class SortTuple - \internal */ -/*! \class StartsWithFN - \internal */ -/*! \class StaticBaseURIFN - \internal */ -/*! \class StaticContext - \internal */ -/*! \class DelegatingStaticContext - \internal */ -/*! \class StaticFocusContext - \internal */ -/*! \class StaticNamespaceContext - \internal */ -/*! \class GenericStaticContext - \internal */ -/*! \class StringComparator - \internal */ -/*! \class StringComparatorLocator - \internal */ -/*! \class StringFN - \internal */ -/*! \class StringJoinFN - \internal */ -/*! \class StringLengthFN - \internal */ -/*! \class StringToAbstractFloatCaster - \internal */ -/*! \class StringToBase64BinaryCaster - \internal */ -/*! \class StringToBooleanCaster - \internal */ -/*! \class StringToCodepointsFN - \internal */ -/*! \class StringToDateCaster - \internal */ -/*! \class StringToDateTimeCaster - \internal */ -/*! \class StringToDayTimeDurationCaster - \internal */ -/*! \class StringToDecimalCaster - \internal */ -/*! \class StringToDerivedIntegerCaster - \internal */ -/*! \class StringToDurationCaster - \internal */ -/*! \class StringToGDayCaster - \internal */ -/*! \class StringToGMonthCaster - \internal */ -/*! \class StringToGMonthDayCaster - \internal */ -/*! \class StringToGYearCaster - \internal */ -/*! \class StringToGYearMonthCaster - \internal */ -/*! \class StringToHexBinaryCaster - \internal */ -/*! \class StringToIntegerCaster - \internal */ -/*! \class StringToTimeCaster - \internal */ -/*! \class StringToYearMonthDurationCaster - \internal */ -/*! \class StringType - \internal */ -/*! \class DerivedStringType - \internal */ -/*! \class SubsequenceFN - \internal */ -/*! \class SubstringAfterFN - \internal */ -/*! \class SubstringBeforeFN - \internal */ -/*! \class SubstringFN - \internal */ -/*! \class SumFN - \internal */ -/*! \class SystemPropertyFN - \internal */ -/*! \class TimezoneFromAbstractDateTimeFN - \internal */ -/*! \class ToAnyURICaster - \internal */ -/*! \class ToAnyURICasterLocator - \internal */ -/*! \class ToBase64BinaryCasterLocator - \internal */ -/*! \class ToBooleanCasterLocator - \internal */ -/*! \class ToDateCasterLocator - \internal */ -/*! \class ToDateTimeCasterLocator - \internal */ -/*! \class ToDayTimeDurationCasterLocator - \internal */ -/*! \class ToDecimalCasterLocator - \internal */ -/*! \class ToDoubleCasterLocator - \internal */ -/*! \class ToDurationCasterLocator - \internal */ -/*! \class ToFloatCasterLocator - \internal */ -/*! \class ToGDayCasterLocator - \internal */ -/*! \class ToGMonthCasterLocator - \internal */ -/*! \class ToGMonthDayCasterLocator - \internal */ -/*! \class ToGYearCasterLocator - \internal */ -/*! \class ToGYearMonthCasterLocator - \internal */ -/*! \class ToHexBinaryCasterLocator - \internal */ -/*! \class ToIntegerCasterLocator - \internal */ -/*! \class ToDerivedIntegerCasterLocator - \internal */ -/*! \class ToQNameCasterLocator - \internal */ -/*! \class ToSchemaTimeCasterLocator - \internal */ -/*! \class ToStringCaster - \internal */ -/*! \class ToStringCasterLocator - \internal */ -/*! \class ToDerivedStringCasterLocator - \internal */ -/*! \class ToUntypedAtomicCaster - \internal */ -/*! \class ToUntypedAtomicCasterLocator - \internal */ -/*! \class ToYearMonthDurationCasterLocator - \internal */ -/*! \class Tokenizer - \internal */ -/*! \class XQueryTokenizer - \internal */ -/*! \class TraceFN - \internal */ -/*! \class TranslateFN - \internal */ -/*! \class TrueFN - \internal */ -/*! \class UntypedAtomic - \internal */ -/*! \class UntypedAtomicConverter - \internal */ -/*! \class ArgumentConverter - \internal */ -/*! \class UntypedAtomicType - \internal */ -/*! \class UpperCaseFN - \internal */ -/*! \class ValidationError - \internal */ -/*! \class VariableDeclaration - \internal */ -/*! \class VariableLoader - \internal */ -/*! \class YearFromAbstractDateTimeFN - \internal */ -/*! \class YearMonthDuration - \internal */ -/*! \class YearMonthDurationComparatorLocator - \internal */ -/*! \class YearMonthDurationMathematicianLocator - \internal */ -/*! \class YearMonthDurationType - \internal */ -/*! \class YearsFromDurationFN - \internal - */ -/*! \class DocumentContentValidator - \internal */ -/*! \class AtomicTypeVisitor - \internal */ -/*! \class AtomicCasterLocator - \internal */ -/*! \class AtomicTypeVisitorResult - \internal */ -/*! \class Expression - \internal */ -/*! \class EmptyContainer - \internal */ -/*! \class AxisStep - \internal */ -/*! \class ContextItem - \internal */ -/*! \class EmptySequence - \internal */ -/*! \class ExternalVariableReference - \internal */ -/*! \class Literal - \internal */ -/*! \class LiteralSequence - \internal */ -/*! \class NamespaceConstructor - \internal */ -/*! \class ParentNodeAxis - \internal */ -/*! \class VariableReference - \internal */ -/*! \class ArgumentReference - \internal */ -/*! \class ExpressionVariableReference - \internal */ -/*! \class PositionalVariableReference - \internal */ -/*! \class RangeVariableReference - \internal */ -/*! \class PairContainer - \internal */ -/*! \class AndExpression - \internal */ -/*! \class OrExpression - \internal */ -/*! \class ArithmeticExpression - \internal */ -/*! \class UnaryExpression - \internal */ -/*! \class AttributeConstructor - \internal */ -/*! \class CombineNodes - \internal */ -/*! \class ElementConstructor - \internal */ -/*! \class ForClause - \internal */ -/*! \class GeneralComparison - \internal */ -/*! \class GenericPredicate - \internal */ -/*! \class TruthPredicate - \internal */ -/*! \class LetClause - \internal */ -/*! \class NodeComparison - \internal */ -/*! \class Path - \internal */ -/*! \class ProcessingInstructionConstructor - \internal */ -/*! \class QuantifiedExpression - \internal */ -/*! \class RangeExpression - \internal */ -/*! \class ValueComparison - \internal */ -/*! \class SingleContainer - \internal */ -/*! \class AttributeNameValidator - \internal */ -/*! \class CastAs - \internal */ -/*! \class CastableAs - \internal */ -/*! \class CollationChecker - \internal */ -/*! \class CommentConstructor - \internal */ -/*! \class CopyOf - \internal */ -/*! \class DocumentConstructor - \internal */ -/*! \class DynamicContextStore - \internal */ -/*! \class FirstItemPredicate - \internal */ -/*! \class InstanceOf - \internal */ -/*! \class NCNameConstructor - \internal */ -/*! \class NodeSortExpression - \internal */ -/*! \class OrderBy - \internal */ -/*! \class QNameConstructor - \internal */ -/*! \class SimpleContentConstructor - \internal */ -/*! \class TextNodeConstructor - \internal */ -/*! \class TreatAs - \internal */ -/*! \class TripleContainer - \internal */ -/*! \class IfThenClause - \internal */ -/*! \class UnlimitedContainer - \internal */ -/*! \class ExpressionSequence - \internal */ -/*! \class ReturnOrderBy - \internal */ -/*! \class UserFunctionCallsite - \internal */ -/*! \class ExpressionCreator - \internal */ -/*! \class ByIDCreator - \internal */ -/*! \class ExpressionFactory - \internal */ -/*! \class ExpressionIdentifier - \internal */ -/*! \class BooleanIdentifier - \internal */ -/*! \class ByIDIdentifier - \internal */ -/*! \class BySequenceTypeIdentifier - \internal */ -/*! \class ComparisonIdentifier - \internal */ -/*! \class IntegerIdentifier - \internal */ -/*! \class ExternalVariableLoader - \internal */ -/*! \class ItemType - \internal */ -/*! \class AnyItemType - \internal */ -/*! \class AnyNodeType - \internal */ -/*! \class AbstractNodeTest - \internal */ -/*! \class LocalNameTest - \internal */ -/*! \class NamespaceNameTest - \internal */ -/*! \class QNameTest - \internal */ -/*! \class AtomicType - \internal */ -/*! \class BuiltinAtomicType - \internal */ -/*! \class AnyAtomicType - \internal */ -/*! \class AnyURIType - \internal */ -/*! \class NumericType - \internal */ -/*! \class EBVType - \internal */ -/*! \class EmptySequenceType - \internal */ -/*! \class MultiItemType - \internal */ -/*! \class NoneType - \internal */ -/*! \class OptimizationPass - \internal */ -/*! \class ParameterizedAtomicTypeVisitor - \internal */ -/*! \class AtomicComparatorLocator - \internal */ -/*! \class AtomicMathematicianLocator - \internal */ -/*! \class SchemaComponent - \internal */ -/*! \class SchemaType - \internal */ -/*! \class AnyType - \internal */ -/*! \class AnySimpleType - \internal */ -/*! \class Untyped - \internal */ -/*! \class SchemaTypeFactory - \internal */ -/*! \class BasicTypesFactory - \internal */ -/*! \class SequenceType - \internal */ -/*! \class GenericSequenceType - \internal */ -/*! \class UserFunction - \internal -*/ -QT_END_NAMESPACE diff --git a/doc/src/qplugin.qdoc b/doc/src/qplugin.qdoc deleted file mode 100644 index 4fbd198..0000000 --- a/doc/src/qplugin.qdoc +++ /dev/null @@ -1,135 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \headerfile - \title Macros for Defining Plugins - - \brief The header files defines macros for defining plugins. - - \sa {How to Create Qt Plugins} -*/ - -/*! - \macro Q_DECLARE_INTERFACE(ClassName, Identifier) - \relates - - This macro associates the given \a Identifier (a string literal) - to the interface class called \a ClassName. The \a Identifier must - be unique. For example: - - \snippet examples/tools/plugandpaint/interfaces.h 3 - - This macro is normally used right after the class definition for - \a ClassName, in a header file. See the - \l{tools/plugandpaint}{Plug & Paint} example for details. - - If you want to use Q_DECLARE_INTERFACE with interface classes - declared in a namespace then you have to make sure the Q_DECLARE_INTERFACE - is not inside a namespace though. For example: - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 0 - - \sa Q_INTERFACES(), Q_EXPORT_PLUGIN2(), {How to Create Qt Plugins} -*/ - -/*! - \macro Q_EXPORT_PLUGIN(ClassName) - \relates - \obsolete - - Use Q_EXPORT_PLUGIN2() instead. This macro is equivalent to - Q_EXPORT_PLUGIN2(\a ClassName, \a ClassName). -*/ - -/*! - \macro Q_EXPORT_PLUGIN2(PluginName, ClassName) - \relates - \since 4.1 - \keyword Q_EXPORT_PLUGIN2 - - This macro exports the plugin class \a ClassName for the plugin specified - by \a PluginName. The value of \a PluginName should correspond to the - \l{qmake Variable Reference#TARGET}{TARGET} specified in the plugin's - project file. - - There should be exactly one occurrence of this macro in the source code - for a Qt plugin, and it should be used where the implementation is written - rather than in a header file. - - Example: - - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 1 - - See the \l{tools/plugandpaint}{Plug & Paint} example for details. - - \sa Q_DECLARE_INTERFACE(), {How to Create Qt Plugins} -*/ - -/*! - \macro Q_IMPORT_PLUGIN(PluginName) - \relates - - This macro imports the plugin named \a PluginName, corresponding - to the \l{qmake Variable Reference#TARGET}{TARGET} specified in the - plugin's project file. - - Inserting this macro into your application's source code will allow - you to make use of a static plugin. - - Example: - - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 2 - - Static plugins must also be included by the linker when your - application is built. For Qt's predefined plugins, - you can use the \c QTPLUGIN to add - the required plugins to your build. For example: - - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 3 - - \sa {Static Plugins}, {How to Create Qt Plugins}, {Using qmake} -*/ - -/*! - \macro Q_EXPORT_STATIC_PLUGIN(ClassName) - \relates - \internal -*/ diff --git a/doc/src/qprintdialog.qdoc b/doc/src/qprintdialog.qdoc deleted file mode 100644 index 8011f62..0000000 --- a/doc/src/qprintdialog.qdoc +++ /dev/null @@ -1,72 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#ifdef QT3_SUPPORT -/*! - \fn QPrinter *QPrintDialog::printer() const - - Returns a pointer to the printer this dialog configures, or 0 if - this dialog does not operate on any printer. - - This function is available for Unix platforms only. -*/ - -/*! - \fn void QPrintDialog::setPrinter(QPrinter *printer, bool pickupSettings) - - Sets this dialog to configure printer \a printer, or no printer if \a printer - is null. If \a pickupSettings is true, the dialog reads most of - its settings from \a printer. If \a pickupSettings is false (the - default) the dialog keeps its old settings. - - This function is available for Unix platforms only. -*/ - -/*! - \fn void QPrintDialog::addButton(QPushButton *button) - - Adds the \a button to the layout of the print dialog. The added - buttons are arranged from the left to the right below the - last groupbox of the printdialog. - - This function is available for Unix platforms only. -*/ -#endif diff --git a/doc/src/qprinterinfo.qdoc b/doc/src/qprinterinfo.qdoc deleted file mode 100644 index a4ffeb2..0000000 --- a/doc/src/qprinterinfo.qdoc +++ /dev/null @@ -1,137 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QPrinterInfo - - \brief The QPrinterInfo class gives access to information about - existing printers. - - Use the static functions to generate a list of QPrinterInfo - objects. Each QPrinterInfo object in the list represents a single - printer and can be queried for name, supported paper sizes, and - whether or not it is the default printer. - - \since 4.4 -*/ - -/*! - \fn QList QPrinterInfo::availablePrinters() - - Returns a list of available printers on the system. -*/ - -/*! - \fn QPrinterInfo QPrinterInfo::defaultPrinter() - - Returns the default printer on the system. - - The return value should be checked using isNull() before being - used, in case there is no default printer. - - \sa isNull() -*/ - -/*! - \fn QPrinterInfo::QPrinterInfo() - - Constructs an empty QPrinterInfo object. - - \sa isNull() -*/ - -/*! - \fn QPrinterInfo::QPrinterInfo(const QPrinterInfo& src) - - Constructs a copy of \a src. -*/ - -/*! - \fn QPrinterInfo::QPrinterInfo(const QPrinter& printer) - - Constructs a QPrinterInfo object from \a printer. -*/ - -/*! - \fn QPrinterInfo::~QPrinterInfo() - - Destroys the QPrinterInfo object. References to the values in the - object become invalid. -*/ - -/*! - \fn QPrinterInfo& QPrinterInfo::operator=(const QPrinterInfo& src) - - Sets the QPrinterInfo object to be equal to \a src. -*/ - -/*! - \fn QString QPrinterInfo::printerName() const - - Returns the name of the printer. - - \sa QPrinter::setPrinterName() -*/ - -/*! - \fn bool QPrinterInfo::isNull() const - - Returns whether this QPrinterInfo object holds a printer definition. - - An empty QPrinterInfo object could result for example from calling - defaultPrinter() when there are no printers on the system. -*/ - -/*! - \fn bool QPrinterInfo::isDefault() const - - Returns whether this printer is the default printer. -*/ - -/*! - \fn QList< QPrinter::PaperSize> QPrinterInfo::supportedPaperSizes() const - \since 4.4 - - Returns a list of supported paper sizes by the printer. - - Not all printer drivers support this query, so the list may be empty. - On Mac OS X 10.3, this function always returns an empty list. -*/ diff --git a/doc/src/qset.qdoc b/doc/src/qset.qdoc deleted file mode 100644 index 0db3775..0000000 --- a/doc/src/qset.qdoc +++ /dev/null @@ -1,953 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QSet - \brief The QSet class is a template class that provides a hash-table-based set. - - \ingroup tools - \ingroup shared - \reentrant - \mainclass - - QSet is one of Qt's generic \l{container classes}. It stores - values in an unspecified order and provides very fast lookup of - the values. Internally, QSet is implemented as a QHash. - - Here's an example QSet with QString values: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 0 - - To insert a value into the set, use insert(): - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 1 - - Another way to insert items into the set is to use operator<<(): - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 2 - - To test whether an item belongs to the set or not, use contains(): - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 3 - - If you want to navigate through all the values stored in a QSet, - you can use an iterator. QSet supports both \l{Java-style - iterators} (QSetIterator and QMutableSetIterator) and \l{STL-style - iterators} (QSet::iterator and QSet::const_iterator). Here's how - to iterate over a QSet using a Java-style iterator: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 4 - - Here's the same code, but using an STL-style iterator: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 5 - - QSet is unordered, so an iterator's sequence cannot be assumed to - be predictable. If ordering by key is required, use a QMap. - - To navigate through a QSet, you can also use \l{foreach}: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 6 - - Items can be removed from the set using remove(). There is also a - clear() function that removes all items. - - QSet's value data type must be an \l{assignable data type}. You - cannot, for example, store a QWidget as a value; instead, store a - QWidget *. In addition, the type must provide \c operator==(), and - there must also be a global qHash() function that returns a hash - value for an argument of the key's type. See the QHash - documentation for a list of types supported by qHash(). - - Internally, QSet uses a hash table to perform lookups. The hash - table automatically grows and shrinks to provide fast lookups - without wasting memory. You can still control the size of the hash - table by calling reserve(), if you already know approximately how - many elements the QSet will contain, but this isn't necessary to - obtain good performance. You can also call capacity() to retrieve - the hash table's size. - - \sa QSetIterator, QMutableSetIterator, QHash, QMap -*/ - -/*! - \fn QSet::QSet() - - Constructs an empty set. - - \sa clear() -*/ - -/*! - \fn QSet::QSet(const QSet &other) - - Constructs a copy of \a other. - - This operation occurs in \l{constant time}, because QSet is - \l{implicitly shared}. This makes returning a QSet from a - function very fast. If a shared instance is modified, it will be - copied (copy-on-write), and this takes \l{linear time}. - - \sa operator=() -*/ - -/*! - \fn QSet &QSet::operator=(const QSet &other) - - Assigns the \a other set to this set and returns a reference to - this set. -*/ - -/*! - \fn bool QSet::operator==(const QSet &other) const - - Returns true if the \a other set is equal to this set; otherwise - returns false. - - Two sets are considered equal if they contain the same elements. - - This function requires the value type to implement \c operator==(). - - \sa operator!=() -*/ - -/*! - \fn bool QSet::operator!=(const QSet &other) const - - Returns true if the \a other set is not equal to this set; otherwise - returns false. - - Two sets are considered equal if they contain the same elements. - - This function requires the value type to implement \c operator==(). - - \sa operator==() -*/ - -/*! - \fn int QSet::size() const - - Returns the number of items in the set. - - \sa isEmpty(), count() -*/ - -/*! - \fn bool QSet::isEmpty() const - - Returns true if the set contains no elements; otherwise returns - false. - - \sa size() -*/ - -/*! - \fn int QSet::capacity() const - - Returns the number of buckets in the set's internal hash - table. - - The sole purpose of this function is to provide a means of fine - tuning QSet's memory usage. In general, you will rarely ever need - to call this function. If you want to know how many items are in - the set, call size(). - - \sa reserve(), squeeze() -*/ - -/*! \fn void QSet::reserve(int size) - - Ensures that the set's internal hash table consists of at - least \a size buckets. - - This function is useful for code that needs to build a huge set - and wants to avoid repeated reallocation. For example: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 7 - - Ideally, \a size should be slightly more than the maximum number - of elements expected in the set. \a size doesn't have to be prime, - because QSet will use a prime number internally anyway. If \a size - is an underestimate, the worst that will happen is that the QSet - will be a bit slower. - - In general, you will rarely ever need to call this function. - QSet's internal hash table automatically shrinks or grows to - provide good performance without wasting too much memory. - - \sa squeeze(), capacity() -*/ - -/*! - \fn void QSet::squeeze() - - Reduces the size of the set's internal hash table to save - memory. - - The sole purpose of this function is to provide a means of fine - tuning QSet's memory usage. In general, you will rarely ever - need to call this function. - - \sa reserve(), capacity() -*/ - -/*! - \fn void QSet::detach() - - \internal - - Detaches this set from any other sets with which it may share - data. - - \sa isDetached() -*/ - -/*! \fn bool QSet::isDetached() const - - \internal - - Returns true if the set's internal data isn't shared with any - other set object; otherwise returns false. - - \sa detach() -*/ - -/*! - \fn void QSet::setSharable(bool sharable) - \internal -*/ - -/*! - \fn void QSet::clear() - - Removes all elements from the set. - - \sa remove() -*/ - -/*! - \fn bool QSet::remove(const T &value) - - Removes any occurrence of item \a value from the set. Returns - true if an item was actually removed; otherwise returns false. - - \sa contains(), insert() -*/ - -/*! - \fn QSet::iterator QSet::erase(iterator pos) - \since 4.2 - - Removes the item at the iterator position \a pos from the set, and - returns an iterator positioned at the next item in the set. - - Unlike remove(), this function never causes QSet to rehash its - internal data structure. This means that it can safely be called - while iterating, and won't affect the order of items in the set. - - \sa remove(), find() -*/ - -/*! \fn QSet::const_iterator QSet::find(const T &value) const - \since 4.2 - - Returns a const iterator positioned at the item \a value in the - set. If the set contains no item \a value, the function returns - constEnd(). - - \sa constFind(), contains() -*/ - -/*! \fn QSet::iterator QSet::find(const T &value) - \since 4.2 - \overload - - Returns a non-const iterator positioned at the item \a value in - the set. If the set contains no item \a value, the function - returns end(). -*/ - -/*! \fn QSet::const_iterator QSet::constFind(const T &value) const - \since 4.2 - - Returns a const iterator positioned at the item \a value in the - set. If the set contains no item \a value, the function returns - constEnd(). - - \sa find(), contains() -*/ - -/*! - \fn bool QSet::contains(const T &value) const - - Returns true if the set contains item \a value; otherwise returns - false. - - \sa insert(), remove(), find() -*/ - -/*! - \fn bool QSet::contains(const QSet &other) const - \since 4.6 - - Returns true if the set contains all items from the \a other set; - otherwise returns false. - - \sa insert(), remove(), find() -*/ - -/*! \fn QSet::const_iterator QSet::begin() const - - Returns a const \l{STL-style iterator} positioned at the first - item in the set. - - \sa constBegin(), end() -*/ - -/*! \fn QSet::iterator QSet::begin() - \since 4.2 - \overload - - Returns a non-const \l{STL-style iterator} positioned at the first - item in the set. -*/ - -/*! \fn QSet::const_iterator QSet::constBegin() const - - Returns a const \l{STL-style iterator} positioned at the first - item in the set. - - \sa begin(), constEnd() -*/ - -/*! \fn QSet::const_iterator QSet::end() const - - Returns a const \l{STL-style iterator} positioned at the imaginary - item after the last item in the set. - - \sa constEnd(), begin() -*/ - -/*! \fn QSet::iterator QSet::end() - \since 4.2 - \overload - - Returns a non-const \l{STL-style iterator} pointing to the - imaginary item after the last item in the set. -*/ - -/*! \fn QSet::const_iterator QSet::constEnd() const - - Returns a const \l{STL-style iterator} pointing to the imaginary - item after the last item in the set. - - \sa constBegin(), end() -*/ - -/*! - \typedef QSet::Iterator - \since 4.2 - - Qt-style synonym for QSet::iterator. -*/ - -/*! - \typedef QSet::ConstIterator - - Qt-style synonym for QSet::const_iterator. -*/ - -/*! - \typedef QSet::const_pointer - - Typedef for const T *. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::const_reference - - Typedef for const T &. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::difference_type - - Typedef for const ptrdiff_t. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::key_type - - Typedef for T. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::pointer - - Typedef for T *. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::reference - - Typedef for T &. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::size_type - - Typedef for int. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::value_type - - Typedef for T. Provided for STL compatibility. -*/ - -/*! - \fn QSet::const_iterator QSet::insert(const T &value) - - Inserts item \a value into the set, if \a value isn't already - in the set, and returns an iterator pointing at the inserted - item. - - \sa operator<<(), remove(), contains() -*/ - -/*! - \fn QSet &QSet::unite(const QSet &other) - - Each item in the \a other set that isn't already in this set is - inserted into this set. A reference to this set is returned. - - \sa operator|=(), intersect(), subtract() -*/ - -/*! - \fn QSet &QSet::intersect(const QSet &other) - - Removes all items from this set that are not contained in the - \a other set. A reference to this set is returned. - - \sa operator&=(), unite(), subtract() -*/ - -/*! - \fn QSet &QSet::subtract(const QSet &other) - - Removes all items from this set that are contained in the - \a other set. Returns a reference to this set. - - \sa operator-=(), unite(), intersect() -*/ - -/*! - \fn bool QSet::empty() const - - Returns true if the set is empty. This function is provided - for STL compatibility. It is equivalent to isEmpty(). -*/ - -/*! - \fn bool QSet::count() const - - Same as size(). -*/ - -/*! - \fn QSet &QSet::operator<<(const T &value) - \fn QSet &QSet::operator+=(const T &value) - \fn QSet &QSet::operator|=(const T &value) - - Inserts a new item \a value and returns a reference to the set. - If \a value already exists in the set, the set is left unchanged. - - \sa insert() -*/ - -/*! - \fn QSet &QSet::operator-=(const T &value) - - Removes the occurrence of item \a value from the set, if - it is found, and returns a reference to the set. If the - \a value is not contained the set, nothing is removed. - - \sa remove() -*/ - -/*! - \fn QSet &QSet::operator|=(const QSet &other) - \fn QSet &QSet::operator+=(const QSet &other) - - Same as unite(\a other). - - \sa operator|(), operator&=(), operator-=() -*/ - -/*! - \fn QSet &QSet::operator&=(const QSet &other) - - Same as intersect(\a other). - - \sa operator&(), operator|=(), operator-=() -*/ - -/*! - \fn QSet &QSet::operator&=(const T &value) - - \overload - - Same as intersect(\e{other}), if we consider \e{other} to be a set - that contains the singleton \a value. -*/ - - -/*! - \fn QSet &QSet::operator-=(const QSet &other) - - Same as subtract(\a{other}). - - \sa operator-(), operator|=(), operator&=() -*/ - -/*! - \fn QSet QSet::operator|(const QSet &other) const - \fn QSet QSet::operator+(const QSet &other) const - - Returns a new QSet that is the union of this set and the - \a other set. - - \sa unite(), operator|=(), operator&(), operator-() -*/ - -/*! - \fn QSet QSet::operator&(const QSet &other) const - - Returns a new QSet that is the intersection of this set and the - \a other set. - - \sa intersect(), operator&=(), operator|(), operator-() -*/ - -/*! - \fn QSet QSet::operator-(const QSet &other) const - - Returns a new QSet that is the set difference of this set and - the \a other set, i.e., this set - \a other set. - - \sa subtract(), operator-=(), operator|(), operator&() -*/ - -/*! - \fn QSet QSet::operator-(const QSet &other) - \fn QSet QSet::operator|(const QSet &other) - \fn QSet QSet::operator+(const QSet &other) - \fn QSet QSet::operator&(const QSet &other) - \internal - - These will go away in Qt 5. -*/ - -/*! - \class QSet::iterator - \since 4.2 - \brief The QSet::iterator class provides an STL-style non-const iterator for QSet. - - QSet features both \l{STL-style iterators} and - \l{Java-style iterators}. The STL-style iterators are more - low-level and more cumbersome to use; on the other hand, they are - slightly faster and, for developers who already know STL, have - the advantage of familiarity. - - QSet::iterator allows you to iterate over a QSet and to remove - items (using QSet::erase()) while you iterate. (QSet doesn't let - you \e modify a value through an iterator, because that - would potentially require moving the value in the internal hash - table used by QSet.) If you want to iterate over a const QSet, - you should use QSet::const_iterator. It is generally good - practice to use QSet::const_iterator on a non-const QSet as well, - unless you need to change the QSet through the iterator. Const - iterators are slightly faster, and can improve code readability. - - QSet\::iterator allows you to iterate over a QSet\ and - modify it as you go (using QSet::erase()). However, - - The default QSet::iterator constructor creates an uninitialized - iterator. You must initialize it using a function like - QSet::begin(), QSet::end(), or QSet::insert() before you can - start iterating. Here's a typical loop that prints all the items - stored in a set: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 8 - - Here's a loop that removes certain items (all those that start - with 'J') from a set while iterating: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 9 - - STL-style iterators can be used as arguments to \l{generic - algorithms}. For example, here's how to find an item in the set - using the qFind() algorithm: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 10 - - Multiple iterators can be used on the same set. However, you may - not attempt to modify the container while iterating on it. - - \sa QSet::const_iterator, QMutableSetIterator -*/ - -/*! - \class QSet::const_iterator - \brief The QSet::const_iterator class provides an STL-style const iterator for QSet. - \since 4.2 - - QSet features both \l{STL-style iterators} and - \l{Java-style iterators}. The STL-style iterators are more - low-level and more cumbersome to use; on the other hand, they are - slightly faster and, for developers who already know STL, have - the advantage of familiarity. - - QSet\::const_iterator allows you to iterate over a QSet. - If you want to modify the QSet as you iterate over it, you must - use QSet::iterator instead. It is generally good practice to use - QSet::const_iterator on a non-const QSet as well, unless you need - to change the QSet through the iterator. Const iterators are - slightly faster, and can improve code readability. - - The default QSet::const_iterator constructor creates an - uninitialized iterator. You must initialize it using a function - like QSet::begin(), QSet::end(), or QSet::insert() before you can - start iterating. Here's a typical loop that prints all the items - stored in a set: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 11 - - STL-style iterators can be used as arguments to \l{generic - algorithms}. For example, here's how to find an item in the set - using the qFind() algorithm: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 12 - - Multiple iterators can be used on the same set. However, you may - not attempt to modify the container while iterating on it. - - \sa QSet::iterator, QSetIterator -*/ - -/*! - \fn QSet::iterator::iterator() - \fn QSet::const_iterator::const_iterator() - - Constructs an uninitialized iterator. - - Functions like operator*() and operator++() should not be called - on an uninitialized iterator. Use operator=() to assign a value - to it before using it. - - \sa QSet::begin(), QSet::end() -*/ - -/*! - \fn QSet::iterator::iterator(typename Hash::iterator i) - \fn QSet::const_iterator::const_iterator(typename Hash::const_iterator i) - - \internal -*/ - -/*! - \typedef QSet::iterator::iterator_category - \typedef QSet::const_iterator::iterator_category - - Synonyms for \e {std::bidirectional_iterator_tag} indicating - these iterators are bidirectional iterators. - */ - -/*! - \typedef QSet::iterator::difference_type - \typedef QSet::const_iterator::difference_type - - \internal -*/ - -/*! - \typedef QSet::iterator::value_type - \typedef QSet::const_iterator::value_type - - \internal -*/ - -/*! - \typedef QSet::iterator::pointer - \typedef QSet::const_iterator::pointer - - \internal -*/ - -/*! - \typedef QSet::iterator::reference - \typedef QSet::const_iterator::reference - - \internal -*/ - -/*! - \fn QSet::iterator::iterator(const iterator &other) - \fn QSet::const_iterator::const_iterator(const const_iterator &other) - - Constructs a copy of \a other. -*/ - -/*! - \fn QSet::const_iterator::const_iterator(const iterator &other) - \since 4.2 - \overload - - Constructs a copy of \a other. -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator=(const iterator &other) - \fn QSet::const_iterator &QSet::const_iterator::operator=(const const_iterator &other) - - Assigns \a other to this iterator. -*/ - -/*! - \fn const T &QSet::iterator::operator*() const - \fn const T &QSet::const_iterator::operator*() const - - Returns a reference to the current item. - - \sa operator->() -*/ - -/*! - \fn const T *QSet::iterator::operator->() const - \fn const T *QSet::const_iterator::operator->() const - - Returns a pointer to the current item. - - \sa operator*() -*/ - -/*! - \fn bool QSet::iterator::operator==(const iterator &other) const - \fn bool QSet::const_iterator::operator==(const const_iterator &other) const - - Returns true if \a other points to the same item as this - iterator; otherwise returns false. - - \sa operator!=() -*/ - -/*! - \fn bool QSet::iterator::operator==(const const_iterator &other) const - \fn bool QSet::iterator::operator!=(const const_iterator &other) const - - \overload -*/ - -/*! - \fn bool QSet::iterator::operator!=(const iterator &other) const - \fn bool QSet::const_iterator::operator!=(const const_iterator &other) const - - Returns true if \a other points to a different item than this - iterator; otherwise returns false. - - \sa operator==() -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator++() - \fn QSet::const_iterator &QSet::const_iterator::operator++() - - The prefix ++ operator (\c{++it}) advances the iterator to the - next item in the set and returns an iterator to the new current - item. - - Calling this function on QSet::constEnd() leads to - undefined results. - - \sa operator--() -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator++(int) - \fn QSet::const_iterator QSet::const_iterator::operator++(int) - - \overload - - The postfix ++ operator (\c{it++}) advances the iterator to the - next item in the set and returns an iterator to the previously - current item. -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator--() - \fn QSet::const_iterator &QSet::const_iterator::operator--() - - The prefix -- operator (\c{--it}) makes the preceding item - current and returns an iterator to the new current item. - - Calling this function on QSet::begin() leads to undefined - results. - - \sa operator++() -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator--(int) - \fn QSet::const_iterator QSet::const_iterator::operator--(int) - - \overload - - The postfix -- operator (\c{it--}) makes the preceding item - current and returns an iterator to the previously current item. -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator+(int j) const - \fn QSet::const_iterator QSet::const_iterator::operator+(int j) const - - Returns an iterator to the item at \a j positions forward from - this iterator. (If \a j is negative, the iterator goes backward.) - - This operation can be slow for large \a j values. - - \sa operator-() -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator-(int j) const - \fn QSet::const_iterator QSet::const_iterator::operator-(int j) const - - Returns an iterator to the item at \a j positions backward from - this iterator. (If \a j is negative, the iterator goes forward.) - - This operation can be slow for large \a j values. - - \sa operator+() -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator+=(int j) - \fn QSet::const_iterator &QSet::const_iterator::operator+=(int j) - - Advances the iterator by \a j items. (If \a j is negative, the - iterator goes backward.) - - This operation can be slow for large \a j values. - - \sa operator-=(), operator+() -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator-=(int j) - \fn QSet::const_iterator &QSet::const_iterator::operator-=(int j) - - Makes the iterator go back by \a j items. (If \a j is negative, - the iterator goes forward.) - - This operation can be slow for large \a j values. - - \sa operator+=(), operator-() -*/ - -/*! \fn QList QSet::toList() const - - Returns a new QList containing the elements in the set. The - order of the elements in the QList is undefined. - - Example: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 13 - - \sa fromList(), QList::fromSet(), qSort() -*/ - -/*! \fn QList QSet::values() const - - Returns a new QList containing the elements in the set. The - order of the elements in the QList is undefined. - - This is the same as toList(). - - \sa fromList(), QList::fromSet(), qSort() -*/ - - -/*! \fn QSet QSet::fromList(const QList &list) - - Returns a new QSet object containing the data contained in \a - list. Since QSet doesn't allow duplicates, the resulting QSet - might be smaller than the \a list, because QList can contain - duplicates. - - Example: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 14 - - \sa toList(), QList::toSet() -*/ - -/*! - \fn QDataStream &operator<<(QDataStream &out, const QSet &set) - \relates QSet - - Writes the \a set to stream \a out. - - This function requires the value type to implement \c operator<<(). - - \sa \link datastreamformat.html Format of the QDataStream operators \endlink -*/ - -/*! - \fn QDataStream &operator>>(QDataStream &in, QSet &set) - \relates QSet - - Reads a set from stream \a in into \a set. - - This function requires the value type to implement \c operator>>(). - - \sa \link datastreamformat.html Format of the QDataStream operators \endlink -*/ diff --git a/doc/src/qsignalspy.qdoc b/doc/src/qsignalspy.qdoc deleted file mode 100644 index 4ee7590..0000000 --- a/doc/src/qsignalspy.qdoc +++ /dev/null @@ -1,98 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QSignalSpy - \inmodule QtTest - - \brief The QSignalSpy class enables introspection of signal emission. - - QSignalSpy can connect to any signal of any object and records its emission. - QSignalSpy itself is a list of QVariant lists. Each emission of the signal - will append one item to the list, containing the arguments of the signal. - - The following example records all signal emissions for the \c clicked() signal - of a QCheckBox: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 0 - - \c{spy.takeFirst()} returns the arguments for the first emitted signal, as a - list of QVariant objects. The \c clicked() signal has a single bool argument, - which is stored as the first entry in the list of arguments. - - The example below catches a signal from a custom object: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 1 - - \bold {Note:} Non-standard data types need to be registered, using - the qRegisterMetaType() function, before you can create a - QSignalSpy. For example: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 2 - - To retrieve the \c QModelIndex, you can use qvariant_cast: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 3 - */ - -/*! \fn QSignalSpy::QSignalSpy(QObject *object, const char *signal) - - Constructs a new QSignalSpy that listens for emissions of the \a signal - from the QObject \a object. Neither \a signal nor \a object can be null. - - Example: - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 4 -*/ - -/*! \fn QSignalSpy::isValid() const - - Returns true if the signal spy listens to a valid signal, otherwise false. -*/ - -/*! \fn QSignalSpy::signal() const - - Returns the normalized signal the spy is currently listening to. -*/ - -/*! \fn int QSignalSpy::qt_metacall(QMetaObject::Call call, int id, void **a) - \internal -*/ - diff --git a/doc/src/qsizepolicy.qdoc b/doc/src/qsizepolicy.qdoc deleted file mode 100644 index c74beb8..0000000 --- a/doc/src/qsizepolicy.qdoc +++ /dev/null @@ -1,522 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QSizePolicy - \brief The QSizePolicy class is a layout attribute describing horizontal - and vertical resizing policy. - - \ingroup appearance - \ingroup geomanagement - - The size policy of a widget is an expression of its willingness to - be resized in various ways, and affects how the widget is treated - by the \l{Layout Management}{layout engine}. Each widget returns a - QSizePolicy that describes the horizontal and vertical resizing - policy it prefers when being laid out. You can change this for - a specific widget by changing its QWidget::sizePolicy property. - - QSizePolicy contains two independent QSizePolicy::Policy values - and two stretch factors; one describes the widgets's horizontal - size policy, and the other describes its vertical size policy. It - also contains a flag to indicate whether the height and width of - its preferred size are related. - - The horizontal and vertical policies can be set in the - constructor, and altered using the setHorizontalPolicy() and - setVerticalPolicy() functions. The stretch factors can be set - using the setHorizontalStretch() and setVerticalStretch() - functions. The flag indicating whether the widget's - \l{QWidget::sizeHint()}{sizeHint()} is width-dependent (such as a - menu bar or a word-wrapping label) can be set using the - setHeightForWidth() function. - - The current size policies and stretch factors be retrieved using - the horizontalPolicy(), verticalPolicy(), horizontalStretch() and - verticalStretch() functions. Alternatively, use the transpose() - function to swap the horizontal and vertical policies and - stretches. The hasHeightForWidth() function returns the current - status of the flag indicating the size hint dependencies. - - Use the expandingDirections() function to determine whether the - associated widget can make use of more space than its - \l{QWidget::sizeHint()}{sizeHint()} function indicates, as well as - find out in which directions it can expand. - - Finally, the QSizePolicy class provides operators comparing this - size policy to a given policy, as well as a QVariant operator - storing this QSizePolicy as a QVariant object. - - \sa QSize, QWidget::sizeHint(), QWidget::sizePolicy, - QLayoutItem::sizeHint() -*/ - -/*! - \enum QSizePolicy::PolicyFlag - - These flags are combined together to form the various \l{Policy} - values: - - \value GrowFlag The widget can grow beyond its size hint if necessary. - \value ExpandFlag The widget should get as much space as possible. - \value ShrinkFlag The widget can shrink below its size hint if necessary. - \value IgnoreFlag The widget's size hint is ignored. The widget will get - as much space as possible. - - \sa Policy -*/ - -/*! - \enum QSizePolicy::Policy - - This enum describes the various per-dimension sizing types used - when constructing a QSizePolicy. - - \value Fixed The QWidget::sizeHint() is the only acceptable - alternative, so the widget can never grow or shrink (e.g. the - vertical direction of a push button). - - \value Minimum The sizeHint() is minimal, and sufficient. The - widget can be expanded, but there is no advantage to it being - larger (e.g. the horizontal direction of a push button). - It cannot be smaller than the size provided by sizeHint(). - - \value Maximum The sizeHint() is a maximum. The widget can be - shrunk any amount without detriment if other widgets need the - space (e.g. a separator line). - It cannot be larger than the size provided by sizeHint(). - - \value Preferred The sizeHint() is best, but the widget can be - shrunk and still be useful. The widget can be expanded, but there - is no advantage to it being larger than sizeHint() (the default - QWidget policy). - - \value Expanding The sizeHint() is a sensible size, but the - widget can be shrunk and still be useful. The widget can make use - of extra space, so it should get as much space as possible (e.g. - the horizontal direction of a horizontal slider). - - \value MinimumExpanding The sizeHint() is minimal, and sufficient. - The widget can make use of extra space, so it should get as much - space as possible (e.g. the horizontal direction of a horizontal - slider). - - \value Ignored The sizeHint() is ignored. The widget will get as - much space as possible. - - \sa PolicyFlag, setHorizontalPolicy(), setVerticalPolicy() -*/ - -/*! - \fn QSizePolicy::QSizePolicy() - - Constructs a QSizePolicy object with \l Fixed as its horizontal - and vertical policies. - - The policies can be altered using the setHorizontalPolicy() and - setVerticalPolicy() functions. Use the setHeightForWidth() - function if the preferred height of the widget is dependent on the - width of the widget (for example, a QLabel with line wrapping). - - \sa setHorizontalStretch(), setVerticalStretch() -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical) - - Constructs a QSizePolicy object with the given \a horizontal and - \a vertical policies, and DefaultType as the control type. - - Use setHeightForWidth() if the preferred height of the widget is - dependent on the width of the widget (for example, a QLabel with - line wrapping). - - \sa setHorizontalStretch(), setVerticalStretch() -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, ControlType type) - \since 4.3 - - Constructs a QSizePolicy object with the given \a horizontal and - \a vertical policies, and the specified control \a type. - - Use setHeightForWidth() if the preferred height of the widget is - dependent on the width of the widget (for example, a QLabel with - line wrapping). - - \sa setHorizontalStretch(), setVerticalStretch(), controlType() -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::horizontalPolicy() const - - Returns the horizontal component of the size policy. - - \sa setHorizontalPolicy(), verticalPolicy(), horizontalStretch() -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::verticalPolicy() const - - Returns the vertical component of the size policy. - - \sa setVerticalPolicy(), horizontalPolicy(), verticalStretch() -*/ - -/*! - \fn void QSizePolicy::setHorizontalPolicy(Policy policy) - - Sets the horizontal component to the given \a policy. - - \sa horizontalPolicy(), setVerticalPolicy(), setHorizontalStretch() -*/ - -/*! - \fn void QSizePolicy::setVerticalPolicy(Policy policy) - - Sets the vertical component to the given \a policy. - - \sa verticalPolicy(), setHorizontalPolicy(), setVerticalStretch() -*/ - -/*! - \fn Qt::Orientations QSizePolicy::expandingDirections() const - - Returns whether a widget can make use of more space than the - QWidget::sizeHint() function indicates. - - A value of Qt::Horizontal or Qt::Vertical means that the widget - can grow horizontally or vertically (i.e., the horizontal or - vertical policy is \l Expanding or \l MinimumExpanding), whereas - Qt::Horizontal | Qt::Vertical means that it can grow in both - dimensions. - - \sa horizontalPolicy(), verticalPolicy() -*/ - -/*! - \fn ControlType QSizePolicy::controlType() const - \since 4.3 - - Returns the control type associated with the widget for which - this size policy applies. -*/ - -/*! - \fn void QSizePolicy::setControlType(ControlType type) - \since 4.3 - - Sets the control type associated with the widget for which this - size policy applies to \a type. - - The control type specifies the type of the widget for which this - size policy applies. It is used by some styles, notably - QMacStyle, to insert proper spacing between widgets. For example, - the Mac OS X Aqua guidelines specify that push buttons should be - separated by 12 pixels, whereas vertically stacked radio buttons - only require 6 pixels. - - \sa QStyle::layoutSpacing() -*/ - -/*! - \fn void QSizePolicy::setHeightForWidth(bool dependent) - - Sets the flag determining whether the widget's preferred height - depends on its width, to \a dependent. - - \sa hasHeightForWidth() -*/ - -/*! - \fn bool QSizePolicy::hasHeightForWidth() const - - Returns true if the widget's preferred height depends on its - width; otherwise returns false. - - \sa setHeightForWidth() -*/ - -/*! - \fn bool QSizePolicy::operator==(const QSizePolicy &other) const - - Returns true if this policy is equal to \a other; otherwise - returns false. - - \sa operator!=() -*/ - -/*! - \fn bool QSizePolicy::operator!=(const QSizePolicy &other) const - - Returns true if this policy is different from \a other; otherwise - returns false. - - \sa operator==() -*/ - -/*! - \fn int QSizePolicy::horizontalStretch() const - - Returns the horizontal stretch factor of the size policy. - - \sa setHorizontalStretch(), verticalStretch(), horizontalPolicy() -*/ - -/*! - \fn int QSizePolicy::verticalStretch() const - - Returns the vertical stretch factor of the size policy. - - \sa setVerticalStretch(), horizontalStretch(), verticalPolicy() -*/ - -/*! - \fn void QSizePolicy::setHorizontalStretch(uchar stretchFactor) - - Sets the horizontal stretch factor of the size policy to the given \a - stretchFactor. - - \sa horizontalStretch(), setVerticalStretch(), setHorizontalPolicy() -*/ - -/*! - \fn void QSizePolicy::setVerticalStretch(uchar stretchFactor) - - Sets the vertical stretch factor of the size policy to the given - \a stretchFactor. - - \sa verticalStretch(), setHorizontalStretch(), setVerticalPolicy() -*/ - -/*! - \fn void QSizePolicy::transpose() - - Swaps the horizontal and vertical policies and stretches. -*/ - -/*! - \enum QSizePolicy::ControlType - \since 4.3 - - This enum specifies the different types of widgets in terms of - layout interaction: - - \value DefaultType The default type, when none is specified. - \value ButtonBox A QDialogButtonBox instance. - \value CheckBox A QCheckBox instance. - \value ComboBox A QComboBox instance. - \value Frame A QFrame instance. - \value GroupBox A QGroupBox instance. - \value Label A QLabel instance. - \value Line A QFrame instance with QFrame::HLine or QFrame::VLine. - \value LineEdit A QLineEdit instance. - \value PushButton A QPushButton instance. - \value RadioButton A QRadioButton instance. - \value Slider A QAbstractSlider instance. - \value SpinBox A QAbstractSpinBox instance. - \value TabWidget A QTabWidget instance. - \value ToolButton A QToolButton instance. - - \sa setControlType(), controlType() -*/ - -#ifdef QT3_SUPPORT -/*! - \typedef QSizePolicy::SizeType - \compat - - Use the QSizePolicy::Policy enum instead. -*/ - -/*! - \enum QSizePolicy::ExpandData - \compat - - Use the Qt::Orientations enum instead. - - \value NoDirection Use 0 instead. - \value Horizontally Use Qt::Horizontal instead. - \value Vertically Use Qt::Vertical instead. - \value BothDirections Use Qt::Horizontal | Qt::Vertical instead. -*/ - -/*! - \fn bool QSizePolicy::mayShrinkHorizontally() const - - Use the horizontalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayShrinkHorizontally(); - \newcode - bool policy = horizontalPolicy() & QSizePolicy::ShrinkFlag; - \endcode -*/ - -/*! - \fn bool QSizePolicy::mayShrinkVertically() const - - Use the verticalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayShrinkVertically(); - \newcode - bool policy = verticalPolicy() & QSizePolicy::ShrinkFlag; - \endcode -*/ - -/*! - \fn bool QSizePolicy::mayGrowHorizontally() const - - Use the horizontalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayGrowHorizontally(); - \newcode - bool policy = horizontalPolicy() & QSizePolicy::GrowFlag; - \endcode -*/ - -/*! - \fn bool QSizePolicy::mayGrowVertically() const - - Use the verticalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayGrowVertically(); - \newcode - bool policy = verticalPolicy() & QSizePolicy::GrowFlag; - \endcode -*/ - -/*! - \fn Qt::QSizePolicy::Orientations QSizePolicy::expanding() const - - Use expandingDirections() instead. -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, bool dependent) - - Use the QSizePolicy() constructor and the setHeightForWidth() - function instead. - - \oldcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical, dependent); - \newcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical); - policy->setHeightForWidth(dependent); - \endcode -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, uchar horizontalStretch, - uchar verticalStretch, bool dependent) - - Use the QSizePolicy() constructor and call the - setHorizontalStretch(), setVerticalStretch(), and - setHeightForWidth() functions instead. - - \oldcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical, - horizontalStretch, verticalStretch, - dependent); - \newcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical); - policy->setHorizontalStretch(horizontalStretch); - policy->setVerticalStretch(verticalStretch); - policy->setHeightForWidth(dependent); - \endcode -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::horData() const - - Use horizontalPolicy() instead. -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::verData() const - - Use verticalPolicy() instead. -*/ - -/*! - \fn void QSizePolicy::setHorData(Policy policy) - - Use setHorizontalPolicy() instead. -*/ - -/*! - \fn void QSizePolicy::setVerData(Policy policy) - - Use setVerticalPolicy() instead. -*/ - -/*! - \fn uint QSizePolicy::horStretch() const - - Use horizontalStretch() instead. -*/ - -/*! - \fn uint QSizePolicy::verStretch() const - - Use verticalStretch() instead. -*/ - -/*! - \fn void QSizePolicy::setHorStretch(uchar stretch) - - Use setHorizontalStretch() instead. -*/ - -/*! - \fn void QSizePolicy::setVerStretch(uchar stretch) - - Use setVerticalStretch() instead. -*/ -#endif diff --git a/doc/src/qstyles.qdoc b/doc/src/qstyles.qdoc deleted file mode 100644 index ae2d95b..0000000 --- a/doc/src/qstyles.qdoc +++ /dev/null @@ -1,261 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - - -/*! - \class QMacStyle - \brief The QMacStyle class provides a Mac OS X style using the Apple Appearance Manager. - - \ingroup appearance - - This class is implemented as a wrapper to the HITheme - APIs, allowing applications to be styled according to the current - theme in use on Mac OS X. This is done by having primitives - in QStyle implemented in terms of what Mac OS X would normally theme. - - \warning This style is only available on Mac OS X because it relies on the - HITheme APIs. - - There are additional issues that should be taken - into consideration to make an application compatible with the - \link http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html - Apple Human Interface Guidelines \endlink. Some of these issues are outlined - below. - - \list - - \i Layout - The restrictions on window layout are such that some - aspects of layout that are style-dependent cannot be achieved - using QLayout. Changes are being considered (and feedback would be - appreciated) to make layouts QStyle-able. Some of the restrictions - involve horizontal and vertical widget alignment and widget size - (covered below). - - \i Widget size - Mac OS X allows widgets to have specific fixed sizes. Qt - does not fully implement this behavior so as to maintain cross-platform - compatibility. As a result some widgets sizes may be inappropriate (and - subsequently not rendered correctly by the HITheme APIs).The - QWidget::sizeHint() will return the appropriate size for many - managed widgets (widgets enumerated in \l QStyle::ContentsType). - - \i Effects - QMacStyle uses HITheme for performing most of the drawing, but - also uses emulation in a few cases where HITheme does not provide the - required functionality (for example, tab bars on Panther, the toolbar - separator, etc). We tried to make the emulation as close to the original as - possible. Please report any issues you see in effects or non-standard - widgets. - - \endlist - - There are other issues that need to be considered in the feel of - your application (including the general color scheme to match the - Aqua colors). The Guidelines mentioned above will remain current - with new advances and design suggestions for Mac OS X. - - Note that the functions provided by QMacStyle are - reimplementations of QStyle functions; see QStyle for their - documentation. - - \img qmacstyle.png - \sa QWindowsXPStyle, QWindowsStyle, QPlastiqueStyle, QCDEStyle, QMotifStyle -*/ - - -/*! - \enum QMacStyle::WidgetSizePolicy - - \value SizeSmall - \value SizeLarge - \value SizeMini - \value SizeDefault - \omitvalue SizeNone -*/ - -/*! \fn QMacStyle::QMacStyle() - Constructs a QMacStyle object. -*/ - -/*! \fn QMacStyle::~QMacStyle() - Destructs a QMacStyle object. -*/ - -/*! \fn void QMacStyle::polish(QPalette &pal) - \reimp -*/ - -/*! \fn void QMacStyle::polish(QApplication *) - \reimp -*/ - -/*! \fn void QMacStyle::unpolish(QApplication *) - \reimp -*/ - -/*! \fn void QMacStyle::polish(QWidget* w) - \reimp -*/ - -/*! \fn void QMacStyle::unpolish(QWidget* w) - \reimp -*/ - -/*! \fn int QMacStyle::pixelMetric(PixelMetric metric, const QStyleOption *opt, const QWidget *widget) const - \reimp -*/ - -/*! \fn QPalette QMacStyle::standardPalette() const - \reimp -*/ - -/*! \fn int QMacStyle::styleHint(StyleHint sh, const QStyleOption *opt, const QWidget *w, QStyleHintReturn *hret) const - \reimp -*/ - -/*! \fn QPixmap QMacStyle::generatedIconPixmap(QIcon::Mode iconMode, const QPixmap &pixmap, const QStyleOption *opt) const - \reimp -*/ - -/*! \fn QPixmap QMacStyle::standardPixmap(StandardPixmap standardPixmap, const QStyleOption *opt, const QWidget *widget) const - \reimp -*/ - -/*! - \enum QMacStyle::FocusRectPolicy - - This type is used to signify a widget's focus rectangle policy. - - \value FocusEnabled show a focus rectangle when the widget has focus. - \value FocusDisabled never show a focus rectangle for the widget. - \value FocusDefault show a focus rectangle when the widget has - focus and the widget is a QSpinWidget, QDateTimeEdit, QLineEdit, - QListBox, QListView, editable QTextEdit, or one of their - subclasses. -*/ - -/*! \fn void QMacStyle::setFocusRectPolicy(QWidget *w, FocusRectPolicy policy) - \obsolete - Sets the focus rectangle policy of \a w. The \a policy can be one of - \l{QMacStyle::FocusRectPolicy}. - - This is now simply an interface to the Qt::WA_MacShowFocusRect attribute and the - FocusDefault value does nothing anymore. If you want to set a widget back - to its default value, you must save the old value of the attribute before - you change it. - - \sa focusRectPolicy() QWidget::setAttribute() -*/ - -/*! \fn QMacStyle::FocusRectPolicy QMacStyle::focusRectPolicy(const QWidget *w) - \obsolete - Returns the focus rectangle policy for the widget \a w. - - The focus rectangle policy can be one of \l{QMacStyle::FocusRectPolicy}. - - In 4.3 and up this function will simply test for the - Qt::WA_MacShowFocusRect attribute and will never return - QMacStyle::FocusDefault. - - \sa setFocusRectPolicy(), QWidget::testAttribute() -*/ - -/*! \fn void QMacStyle::setWidgetSizePolicy(const QWidget *widget, WidgetSizePolicy policy) - - \obsolete - - Call QWidget::setAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, - or Qt::WA_MacNormalSize instead. -*/ - -/*! \fn QMacStyle::WidgetSizePolicy QMacStyle::widgetSizePolicy(const QWidget *widget) - \obsolete - - Call QWidget::testAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, - or Qt::WA_MacNormalSize instead. -*/ - -/*! \fn void QMacStyle::drawPrimitive(PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w) const - - \reimp -*/ - -/*! \fn void QMacStyle::drawControl(ControlElement ce, const QStyleOption *opt, QPainter *p, const QWidget *w) const - - \reimp -*/ - -/*! \fn QRect QMacStyle::subElementRect(SubElement sr, const QStyleOption *opt, const QWidget *widget) const - - \reimp -*/ - -/*! \fn void QMacStyle::drawComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *widget) const - \reimp -*/ - -/*! \fn QStyle::SubControl QMacStyle::hitTestComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *widget) const - \reimp -*/ - -/*! \fn QRect QMacStyle::subControlRect(ComplexControl cc, const QStyleOptionComplex *opt, SubControl sc, const QWidget *widget) const - \reimp -*/ - -/*! \fn QSize QMacStyle::sizeFromContents(ContentsType ct, const QStyleOption *opt, const QSize &csz, const QWidget *widget) const - \reimp -*/ - -/*! \fn void QMacStyle::drawItemText(QPainter *p, const QRect &r, int flags, const QPalette &pal, bool enabled, const QString &text, QPalette::ColorRole textRole) const - \reimp -*/ - -/*! \fn bool QMacStyle::event(QEvent *e) - \reimp -*/ - -/*! \fn QIcon QMacStyle::standardIconImplementation(StandardPixmap standardIcon, const QStyleOption *opt, const QWidget *widget) const - \internal -*/ - -/*! \fn int QMacStyle::layoutSpacingImplementation(QSizePolicy::ControlType control1, QSizePolicy::ControlType control2, Qt::Orientation orientation, const QStyleOption *option, const QWidget *widget) const - - \internal -*/ - diff --git a/doc/src/qtdesigner.qdoc b/doc/src/qtdesigner.qdoc index d913b32..0959bd9 100644 --- a/doc/src/qtdesigner.qdoc +++ b/doc/src/qtdesigner.qdoc @@ -166,1376 +166,3 @@ \sa {Qt Designer Manual}, {QtUiTools Module} */ - -/*! - \class QDesignerMemberSheetExtension - - \brief The QDesignerMemberSheetExtension class 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. - - \inmodule QtDesigner - - QDesignerMemberSheetExtension is a collection of functions that is - typically used to query a widget's member functions, and to - manipulate the member functions' appearance in \QD's signals and - slots editing mode. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 2 - - When implementing a custom widget plugin, a pointer to \QD's - current QDesignerFormEditorInterface object (\c formEditor in the - example above) is provided by the - QDesignerCustomWidgetInterface::initialize() function's parameter. - - The member sheet (and any other extension), can be retrieved by - querying \QD's extension manager using the qt_extension() - function. When you want to release the extension, you only need to - delete the pointer. - - All widgets have a default member sheet used in \QD's signals and - slots editing mode with the widget's member functions. But - QDesignerMemberSheetExtension also provides an interface for - creating custom member sheet extensions. - - \warning \QD uses the QDesignerMemberSheetExtension to facilitate - the signal and slot editing mode. Whenever a connection between - two widgets is requested, \QD will query for the widgets' member - sheet extensions. If a widget has an implemented member sheet - extension, this extension will override the default member sheet. - - To create a member sheet extension, your extension class must - inherit from both QObject and QDesignerMemberSheetExtension. Then, - since we are implementing an interface, we must ensure that it's - made known to the meta object system using the Q_INTERFACES() - macro: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 3 - - This enables \QD to use qobject_cast() to query for - supported interfaces using nothing but a QObject pointer. - - In \QD the extensions are not created until they are - required. For that reason, when implementing a member sheet - extension, you must also create a QExtensionFactory, i.e a class - that is able to make an instance of your extension, and register - it using \QD's \l {QExtensionManager}{extension manager}. - - When a widget's member sheet extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until the first one that is able to create a member sheet - extension for that widget, is found. This factory will then make - an instance of the extension. If no such factory is found, \QD - will use the default member sheet. - - There are four available types of extensions in \QD: - QDesignerContainerExtension, QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension and - QDesignerTaskMenuExtension. \QD's behavior is the same whether the - requested extension is associated with a multi page container, a - member sheet, a property sheet or a task menu. - - The QExtensionFactory class provides a standard extension - factory, and can also be used as an interface for custom - extension factories. You can either create a new - QExtensionFactory and reimplement the - QExtensionFactory::createExtension() function. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 4 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a member sheet extension as well. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 5 - - For a complete example using an extension class, see \l - {designer/taskmenuextension}{Task Menu Extension example}. The - example shows how to create a custom widget plugin for Qt - Designer, and how to to use the QDesignerTaskMenuExtension class - to add custom items to \QD's task menu. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerMemberSheetExtension::~QDesignerMemberSheetExtension() - - Destroys the member sheet extension. -*/ - -/*! - \fn int QDesignerMemberSheetExtension::count() const - - Returns the extension's number of member functions. -*/ - -/*! - \fn int QDesignerMemberSheetExtension::indexOf(const QString &name) const - - Returns the index of the member function specified by the given \a - name. - - \sa memberName() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::memberName(int index) const - - Returns the name of the member function with the given \a index. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::memberGroup(int index) const - - Returns the name of the member group specified for the function - with the given \a index. - - \sa indexOf(), setMemberGroup() -*/ - -/*! - \fn void QDesignerMemberSheetExtension::setMemberGroup(int index, const QString &group) - - Sets the member group of the member function with the given \a - index, to \a group. - - \sa indexOf(), memberGroup() -*/ - -/*! - \fn bool QDesignerMemberSheetExtension::isVisible(int index) const - - Returns true if the member function with the given \a index is - visible in \QD's signal and slot editor, otherwise false. - - \sa indexOf(), setVisible() -*/ - -/*! - \fn void QDesignerMemberSheetExtension::setVisible(int index, bool visible) - - If \a visible is true, the member function with the given \a index - is visible in \QD's signals and slots editing mode; otherwise the - member function is hidden. - - \sa indexOf(), isVisible() -*/ - -/*! - \fn virtual bool QDesignerMemberSheetExtension::isSignal(int index) const - - Returns true if the member function with the given \a index is a - signal, otherwise false. - - \sa indexOf() -*/ - -/*! - \fn bool QDesignerMemberSheetExtension::isSlot(int index) const - - Returns true if the member function with the given \a index is a - slot, otherwise false. - - \sa indexOf() -*/ - -/*! - \fn bool QDesignerMemberSheetExtension::inheritedFromWidget(int index) const - - Returns true if the member function with the given \a index is - inherited from QWidget, otherwise false. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::declaredInClass(int index) const - - Returns the name of the class in which the member function with - the given \a index is declared. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::signature(int index) const - - Returns the signature of the member function with the given \a - index. - - \sa indexOf() -*/ - -/*! - \fn QList QDesignerMemberSheetExtension::parameterTypes(int index) const - - Returns the parameter types of the member function with the given - \a index, as a QByteArray list. - - \sa indexOf(), parameterNames() -*/ - -/*! - \fn QList QDesignerMemberSheetExtension::parameterNames(int index) const - - Returns the parameter names of the member function with the given - \a index, as a QByteArray list. - - \sa indexOf(), parameterTypes() -*/ - - -// Doc: Interface only - -/*! - \class QDesignerLayoutDecorationExtension - \brief The QDesignerLayoutDecorationExtension class provides an extension to a layout in \QD. - \inmodule QtDesigner - \internal -*/ - -/*! - \enum QDesignerLayoutDecorationExtension::InsertMode - - This enum describes the modes that are used to insert items into a layout. - - \value InsertWidgetMode Widgets are inserted into empty cells in a layout. - \value InsertRowMode Whole rows are inserted into a vertical or grid layout. - \value InsertColumnMode Whole columns are inserted into a horizontal or grid layout. -*/ - -/*! - \fn virtual QDesignerLayoutDecorationExtension::~QDesignerLayoutDecorationExtension() - - Destroys the extension. -*/ - -/*! - \fn virtual QList QDesignerLayoutDecorationExtension::widgets(QLayout *layout) const - - Returns the widgets that are managed by the given \a layout. - - \sa insertWidget(), removeWidget() -*/ - -/*! - \fn QRect QDesignerLayoutDecorationExtension::itemInfo(int index) const - - Returns the rectangle covered by the item at the given \a index in the layout. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::indexOf(QWidget *widget) const - - Returns the index of the specified \a widget in the layout. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::indexOf(QLayoutItem *item) const - - Returns the index of the specified layout \a item. -*/ - -/*! - \fn QDesignerLayoutDecorationExtension::InsertMode QDesignerLayoutDecorationExtension::currentInsertMode() const - - Returns the current insertion mode. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::currentIndex() const - - Returns the current index in the layout. -*/ - -/*! - \fn QPair QDesignerLayoutDecorationExtension::currentCell() const - - Returns a pair containing the row and column of the current cell in the layout. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::insertWidget(QWidget *widget, const QPair &cell) - - Inserts the given \a widget into the specified \a cell in the layout. - - \sa removeWidget() -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::removeWidget(QWidget *widget) - - Removes the specified \a widget from the layout. - - \sa insertWidget() -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::insertRow(int row) - - Inserts a new row into the form at the position specified by \a row. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::insertColumn(int column) - - Inserts a new column into the form at the position specified by \a column. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::simplify() - - Simplifies the layout by removing unnecessary empty rows and columns, and by changing the - number of rows or columns spanned by widgets. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::findItemAt(const QPoint &position) const - - Returns the index of the item in the layout that covers the given \a position. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::findItemAt(int row, int column) const - - Returns the item in the layout that occupies the specified \a row and \a column in the layout. - - Currently, this only applies to grid layouts. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::adjustIndicator(const QPoint &position, int index) - - Adjusts the indicator for the item specified by \a index so that - it lies at the given \a position on the form. -*/ - - -// Doc: Interface only - -/*! - \class QDesignerContainerExtension - \brief The QDesignerContainerExtension class allows you to add pages to - a custom multi-page container in Qt Designer's workspace. - \inmodule QtDesigner - - QDesignerContainerExtension provide an interface for creating - custom container extensions. A container extension consists of a - collection of functions that \QD needs to manage a multi-page - container plugin, and a list of the container's pages. - - \image containerextension-example.png - - \warning This is \e not an extension for container plugins in - general, only custom \e multi-page containers. - - To create a container extension, your extension class must inherit - from both QObject and QDesignerContainerExtension. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 6 - - Since we are implementing an interface, we must ensure that it's - made known to the meta object system using the Q_INTERFACES() - macro. This enables \QD to use the qobject_cast() function to - query for supported interfaces using nothing but a QObject - pointer. - - You must reimplement several functions to enable \QD to manage a - custom multi-page container widget: \QD uses count() to keep track - of the number pages in your container, widget() to return the page - at a given index in the list of the container's pages, and - currentIndex() to return the list index of the selected page. \QD - uses the addWidget() function to add a given page to the - container, expecting it to be appended to the list of pages, while - it expects the insertWidget() function to add a given page to the - container by inserting it at a given index. - - In \QD the extensions are not created until they are - required. For that reason you must also create a - QExtensionFactory, i.e a class that is able to make an instance of - your extension, and register it using \QD's \l - {QExtensionManager}{extension manager}. - - When a container extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until the first one that is able to create a container - extension, is found. This factory will then create the extension - for the plugin. - - There are four available types of extensions in \QD: - QDesignerContainerExtension , QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. - \QD's behavior is the same whether the requested extension is - associated with a multi page container, a member sheet, a property - sheet or a task menu. - - The QExtensionFactory class provides a standard extension factory, - and can also be used as an interface for custom extension - factories. You can either create a new QExtensionFactory and - reimplement the QExtensionFactory::createExtension() function. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 7 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a container extension as well. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 8 - - For a complete example using the QDesignerContainerExtension - class, see the \l {designer/containerextension}{Container - Extension example}. The example shows how to create a custom - multi-page plugin for \QD. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerContainerExtension::~QDesignerContainerExtension() - - Destroys the extension. -*/ - -/*! - \fn int QDesignerContainerExtension::count() const - - Returns the number of pages in the container. -*/ - -/*! - \fn QWidget *QDesignerContainerExtension::widget(int index) const - - Returns the page at the given \a index in the extension's list of - pages. - - \sa addWidget(), insertWidget() -*/ - -/*! - \fn int QDesignerContainerExtension::currentIndex() const - - Returns the index of the currently selected page in the - container. - - \sa setCurrentIndex() -*/ - -/*! - \fn void QDesignerContainerExtension::setCurrentIndex(int index) - - Sets the currently selected page in the container to be the - page at the given \a index in the extension's list of pages. - - \sa currentIndex() -*/ - -/*! - \fn void QDesignerContainerExtension::addWidget(QWidget *page) - - Adds the given \a page to the container by appending it to the - extension's list of pages. - - \sa insertWidget(), remove(), widget() -*/ - -/*! - \fn void QDesignerContainerExtension::insertWidget(int index, QWidget *page) - - Adds the given \a page to the container by inserting it at the - given \a index in the extension's list of pages. - - \sa addWidget(), remove(), widget() -*/ - -/*! - \fn void QDesignerContainerExtension::remove(int index) - - Removes the page at the given \a index from the extension's list - of pages. - - \sa addWidget(), insertWidget() -*/ - - -// Doc: Interface only - -/*! - \class QDesignerTaskMenuExtension - \brief The QDesignerTaskMenuExtension class allows you to add custom - menu entries to Qt Designer's task menu. - \inmodule QtDesigner - - QDesignerTaskMenuExtension provides an interface for creating - custom task menu extensions. It is typically used to create task - menu entries that are specific to a plugin in \QD. - - \QD uses the QDesignerTaskMenuExtension to feed its task - menu. Whenever a task menu is requested, \QD will query - for the selected widget's task menu extension. - - \image taskmenuextension-example-faded.png - - A task menu extension is a collection of QActions. The actions - appear as entries in the task menu when the plugin with the - specified extension is selected. The image above shows the custom - \gui {Edit State...} action which appears in addition to \QD's - default task menu entries: \gui Cut, \gui Copy, \gui Paste etc. - - To create a custom task menu extension, your extension class must - inherit from both QObject and QDesignerTaskMenuExtension. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 9 - - Since we are implementing an interface, we must ensure that it - is made known to the meta-object system using the Q_INTERFACES() - macro. This enables \QD to use the qobject_cast() function to - query for supported interfaces using nothing but a QObject - pointer. - - You must reimplement the taskActions() function to return a list - of actions that will be included in \QD task menu. Optionally, you - can reimplement the preferredEditAction() function to set the - action that is invoked when selecting your plugin and pressing - \key F2. The preferred edit action must be one of the actions - returned by taskActions() and, if it's not defined, pressing the - \key F2 key will simply be ignored. - - In \QD, extensions are not created until they are required. A - task menu extension, for example, is created when you click the - right mouse button over a widget in \QD's workspace. For that - reason you must also construct an extension factory, using either - QExtensionFactory or a subclass, and register it using \QD's - \l {QExtensionManager}{extension manager}. - - When a task menu extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until it finds one that is able to create a task menu - extension for the selected widget. This factory will then make an - instance of the extension. - - There are four available types of extensions in \QD: - QDesignerContainerExtension, QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension, and QDesignerTaskMenuExtension. - \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. - - The QExtensionFactory class provides a standard extension factory, - and can also be used as an interface for custom extension - factories. You can either create a new QExtensionFactory and - reimplement the QExtensionFactory::createExtension() function. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 10 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a task menu extension as well. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 11 - - For a complete example using the QDesignerTaskMenuExtension class, - see the \l {designer/taskmenuextension}{Task Menu Extension - example}. The example shows how to create a custom widget plugin - for \QD, and how to to use the QDesignerTaskMenuExtension - class to add custom items to \QD's task menu. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerTaskMenuExtension::~QDesignerTaskMenuExtension() - - Destroys the task menu extension. -*/ - -/*! - \fn QAction *QDesignerTaskMenuExtension::preferredEditAction() const - - Returns the action that is invoked when selecting a plugin with - the specified extension and pressing \key F2. - - The action must be one of the actions returned by taskActions(). -*/ - -/*! - \fn QList QDesignerTaskMenuExtension::taskActions() const - - Returns the task menu extension as a list of actions which will be - included in \QD's task menu when a plugin with the specified - extension is selected. - - The function must be reimplemented to add actions to the list. -*/ - - -// Doc: Interface only - -/*! - \class QDesignerCustomWidgetCollectionInterface - - \brief The QDesignerCustomWidgetCollectionInterface class allows - you to include several custom widgets in one single library. - - \inmodule QtDesigner - - When implementing a custom widget plugin, you build it as a - separate library. If you want to include several custom widget - plugins in the same library, you must in addition subclass - QDesignerCustomWidgetCollectionInterface. - - QDesignerCustomWidgetCollectionInterface contains one single - function returning a list of the collection's - QDesignerCustomWidgetInterface objects. For example, if you have - several custom widgets \c CustomWidgetOne, \c CustomWidgetTwo and - \c CustomWidgetThree, the class definition may look like this: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 12 - - In the class constructor you add the interfaces to your custom - widgets to the list which you return in the customWidgets() - function: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 13 - - Note that instead of exporting each custom widget plugin using the - Q_EXPORT_PLUGIN2() macro, you export the entire collection. The - Q_EXPORT_PLUGIN2() macro ensures that \QD can access and construct - the custom widgets. Without this macro, there is no way for \QD to - use them. - - \sa QDesignerCustomWidgetInterface, {Creating Custom Widgets for - Qt Designer} -*/ - -/*! - \fn QDesignerCustomWidgetCollectionInterface::~QDesignerCustomWidgetCollectionInterface() { - - Destroys the custom widget collection interface. -*/ - -/*! - \fn QList QDesignerCustomWidgetCollectionInterface::customWidgets() const - - Returns a list of interfaces to the collection's custom widgets. -*/ - - -// Doc: Interface only - -/*! - \class QDesignerCustomWidgetInterface - - \brief The QDesignerCustomWidgetInterface class enables Qt Designer - to access and construct custom widgets. - - \inmodule QtDesigner - - QDesignerCustomWidgetInterface provides a custom widget with an - interface. The class contains a set of functions that must be subclassed - to return basic information about the widget, such as its class name and - the name of its header file. Other functions must be implemented to - initialize the plugin when it is loaded, and to construct instances of - the custom widget for \QD to use. - - When implementing a custom widget you must subclass - QDesignerCustomWidgetInterface to expose your widget to \QD. For - example, this is the declaration for the plugin used in the - \l{Custom Widget Plugin Example}{Custom Widget Plugin example} that - enables an analog clock custom widget to be used by \QD: - - \snippet examples/designer/customwidgetplugin/customwidgetplugin.h 0 - - Note that the only part of the class definition that is specific - to this particular custom widget is the class name. In addition, - since we are implementing an interface, we must ensure that it's - made known to the meta object system using the Q_INTERFACES() - macro. This enables \QD to use the qobject_cast() function to - query for supported interfaces using nothing but a QObject - pointer. - - After \QD loads a custom widget plugin, it calls the interface's - initialize() function to enable it to set up any resources that it - may need. This function is called with a QDesignerFormEditorInterface - parameter that provides the plugin with a gateway to all of \QD's API. - - \QD constructs instances of the custom widget by calling the plugin's - createWidget() function with a suitable parent widget. Plugins must - construct and return an instance of a custom widget with the specified - parent widget. - - In the implementation of the class you must remember to export - your custom widget plugin to \QD using the Q_EXPORT_PLUGIN2() - macro. For example, if a library called \c libcustomwidgetplugin.so - (on Unix) or \c libcustomwidget.dll (on Windows) contains a widget - class called \c MyCustomWidget, we can export it by adding the - following line to the file containing the plugin implementation: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 14 - - This macro ensures that \QD can access and construct the custom widget. - Without this macro, there is no way for \QD to use it. - - When implementing a custom widget plugin, you build it as a - separate library. If you want to include several custom widget - plugins in the same library, you must in addition subclass - QDesignerCustomWidgetCollectionInterface. - - \warning If your custom widget plugin contains QVariant - properties, be aware that only the following \l - {QVariant::Type}{types} are supported: - - \list - \o QVariant::ByteArray - \o QVariant::Bool - \o QVariant::Color - \o QVariant::Cursor - \o QVariant::Date - \o QVariant::DateTime - \o QVariant::Double - \o QVariant::Int - \o QVariant::Point - \o QVariant::Rect - \o QVariant::Size - \o QVariant::SizePolicy - \o QVariant::String - \o QVariant::Time - \o QVariant::UInt - \endlist - - For a complete example using the QDesignerCustomWidgetInterface - class, see the \l {designer/customwidgetplugin}{Custom Widget - Example}. The example shows how to create a custom widget plugin - for \QD. - - \sa QDesignerCustomWidgetCollectionInterface {Creating Custom - Widgets for Qt Designer} -*/ - -/*! - \fn QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface() - - Destroys the custom widget interface. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::name() const - - Returns the class name of the custom widget supplied by the interface. - - The name returned \e must be identical to the class name used for the - custom widget. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::group() const - - Returns the name of the group to which the custom widget belongs. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::toolTip() const - - Returns a short description of the widget that can be used by \QD - in a tool tip. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::whatsThis() const - - Returns a description of the widget that can be used by \QD in - "What's This?" help for the widget. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::includeFile() const - - Returns the path to the include file that \l uic uses when - creating code for the custom widget. -*/ - -/*! - \fn QIcon QDesignerCustomWidgetInterface::icon() const - - Returns the icon used to represent the custom widget in \QD's - widget box. -*/ - -/*! - \fn bool QDesignerCustomWidgetInterface::isContainer() const - - Returns true if the custom widget is intended to be used as a - container; otherwise returns false. - - Most custom widgets are not used to hold other widgets, so their - implementations of this function will return false, but custom - containers will return true to ensure that they behave correctly - in \QD. -*/ - -/*! - \fn QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent) - - Returns a new instance of the custom widget, with the given \a - parent. -*/ - -/*! - \fn bool QDesignerCustomWidgetInterface::isInitialized() const - - Returns true if the widget has been initialized; otherwise returns - false. - - \sa initialize() -*/ - -/*! - \fn void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor) - - Initializes the widget for use with the specified \a formEditor - interface. - - \sa isInitialized() -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::domXml() const - - Returns the XML that is used to describe the custom widget's - properties to \QD. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::codeTemplate() const - - This function is reserved for future use by \QD. - - \omit - Returns the code template that \QD includes in forms that contain - the custom widget when they are saved. - \endomit -*/ - -/*! - \macro QDESIGNER_WIDGET_EXPORT - \relates QDesignerCustomWidgetInterface - \since 4.1 - - This macro is used when defining custom widgets to ensure that they are - correctly exported from plugins for use with \QD. - - On some platforms, the symbols required by \QD to create new widgets - are removed from plugins by the build system, making them unusable. - Using this macro ensures that the symbols are retained on those platforms, - and has no side effects on other platforms. - - For example, the \l{designer/worldtimeclockplugin}{World Time Clock Plugin} - example exports a custom widget class with the following declaration: - - \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 0 - \dots - \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 2 - - \sa {Creating Custom Widgets for Qt Designer} -*/ - - -// Doc: Abstract class - -/*! - \class QDesignerDnDItemInterface - \brief The QDesignerDnDItemInterface class provides an interface that is used to manage items - during a drag and drop operation. - \inmodule QtDesigner - \internal -*/ - -/*! - \enum QDesignerDnDItemInterface::DropType - - This enum describes the result of a drag and drop operation. - - \value MoveDrop The item was moved. - \value CopyDrop The item was copied. -*/ - -/*! - \fn QDesignerDnDItemInterface::QDesignerDnDItemInterface() - - Constructs a new interface to a drag and drop item. -*/ - -/*! - \fn QDesignerDnDItemInterface::~QDesignerDnDItemInterface() - - Destroys the interface to the item. -*/ - -/*! - \fn DomUI *QDesignerDnDItemInterface::domUi() const - - Returns a user interface object for the item. -*/ - -/*! - \fn QWidget *QDesignerDnDItemInterface::widget() const - - Returns the widget being copied or moved in the drag and drop operation. - - \sa source() -*/ - -/*! - \fn QWidget *QDesignerDnDItemInterface::decoration() const - - Returns the widget used to represent the item. -*/ - -/*! - \fn QPoint QDesignerDnDItemInterface::hotSpot() const - - Returns the cursor's hotspot. - - \sa QDrag::hotSpot() -*/ - -/*! - \fn DropType QDesignerDnDItemInterface::type() const - - Returns the type of drag and drop operation in progress. -*/ - -/*! - \fn QWidget *QDesignerDnDItemInterface::source() const - - Returns the widget that is the source of the drag and drop operation; i.e. the original - container of the widget being dragged. - - \sa widget() -*/ - - -// Doc: Abstract class - -/*! - \class QDesignerIconCacheInterface - \brief The QDesignerIconCacheInterface class provides an interface to \QD's icon cache. - \inmodule QtDesigner - \internal -*/ - -/*! - \fn QDesignerIconCacheInterface::QDesignerIconCacheInterface(QObject *parent) - - Constructs a new interface with the given \a parent. -*/ - -/*! - \fn QIcon QDesignerIconCacheInterface::nameToIcon(const QString &filePath, const QString &qrcPath) - - Returns the icon associated with the name specified by \a filePath in the resource - file specified by \a qrcPath. - - If \a qrcPath refers to a valid resource file, the name used for the file path is a path - within those resources; otherwise the file path refers to a local file. - - \sa {The Qt Resource System}, nameToPixmap() -*/ - -/*! - \fn QPixmap QDesignerIconCacheInterface::nameToPixmap(const QString &filePath, const QString &qrcPath) - - Returns the pixmap associated with the name specified by \a filePath in the resource - file specified by \a qrcPath. - - If \a qrcPath refers to a valid resource file, the name used for the file path is a path - within those resources; otherwise the file path refers to a local file. - - \sa {The Qt Resource System}, nameToIcon() -*/ - -/*! - \fn QString QDesignerIconCacheInterface::iconToFilePath(const QIcon &icon) const - - Returns the file path associated with the given \a icon. The file path is a path within - an application resources. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::iconToQrcPath(const QIcon &icon) const - - Returns the path to the resource file that refers to the specified \a icon. The resource - path refers to a local file. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::pixmapToFilePath(const QPixmap &pixmap) const - - Returns the file path associated with the given \a pixmap. The file path is a path within - an application resources. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::pixmapToQrcPath(const QPixmap &pixmap) const - - Returns the path to the resource file that refers to the specified \a pixmap. The resource - path refers to a local file. -*/ - -/*! - \fn QList QDesignerIconCacheInterface::pixmapList() const - - Returns a list of pixmaps for the icons provided by the icon cache. -*/ - -/*! - \fn QList QDesignerIconCacheInterface::iconList() const - - Returns a list of icons provided by the icon cache. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::resolveQrcPath(const QString &filePath, const QString &qrcPath, const QString &workingDirectory) const - - Returns a path to a resource specified by the \a filePath within - the resource file located at \a qrcPath. If \a workingDirectory is - a valid path to a directory, the path returned will be relative to - that directory; otherwise an absolute path is returned. - - \omit - ### Needs checking - \endomit -*/ - - -// Doc: Interface only - -/*! - \class QDesignerPropertySheetExtension - - \brief The QDesignerPropertySheetExtension class allows you to - manipulate a widget's properties which is displayed in Qt - Designer's property editor. - - \sa QDesignerDynamicPropertySheetExtension - - \inmodule QtDesigner - - QDesignerPropertySheetExtension provides a collection of functions that - are typically used to query a widget's properties, and to - manipulate the properties' appearance in the property editor. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 15 - - Note that if you change the value of a property using the - QDesignerPropertySheetExtension::setProperty() function, the undo - stack is not updated. To ensure that a property's value can be - reverted using the undo stack, you must use the - QDesignerFormWindowCursorInterface::setProperty() function, or its - buddy \l - {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, - instead. - - When implementing a custom widget plugin, a pointer to \QD's - current QDesignerFormEditorInterface object (\c formEditor in the - example above) is provided by the - QDesignerCustomWidgetInterface::initialize() function's parameter. - - The property sheet, or any other extension, can be retrieved by - querying \QD's extension manager using the qt_extension() - function. When you want to release the extension, you only need to - delete the pointer. - - All widgets have a default property sheet which populates \QD's - property editor with the widget's properties (i.e the ones defined - with the Q_PROPERTY() macro). But QDesignerPropertySheetExtension - also provides an interface for creating custom property sheet - extensions. - - \warning \QD uses the QDesignerPropertySheetExtension to feed its - property editor. Whenever a widget is selected in its workspace, - \QD will query for the widget's property sheet extension. If the - selected widget has an implemented property sheet extension, this - extension will override the default property sheet. - - To create a property sheet extension, your extension class must - inherit from both QObject and - QDesignerPropertySheetExtension. Then, since we are implementing - an interface, we must ensure that it's made known to the meta - object system using the Q_INTERFACES() macro: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 16 - - This enables \QD to use qobject_cast() to query for supported - interfaces using nothing but a QObject pointer. - - In \QD the extensions are not created until they are - required. For that reason, when implementing a property sheet - extension, you must also create a QExtensionFactory, i.e a class - that is able to make an instance of your extension, and register - it using \QD's \l {QExtensionManager}{extension manager}. - - When a property sheet extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until the first one that is able to create a property - sheet extension for the selected widget, is found. This factory - will then make an instance of the extension. If no such factory - can be found, \QD will use the default property sheet. - - There are four available types of extensions in \QD: - QDesignerContainerExtension, QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. Qt - Designer's behavior is the same whether the requested extension is - associated with a multi page container, a member sheet, a property - sheet or a task menu. - - The QExtensionFactory class provides a standard extension factory, - and can also be used as an interface for custom extension - factories. You can either create a new QExtensionFactory and - reimplement the QExtensionFactory::createExtension() function. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 17 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a property sheet extension extension as well. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 18 - - For a complete example using an extension class, see the \l - {designer/taskmenuextension}{Task Menu Extension example}. The - example shows how to create a custom widget plugin for Qt - Designer, and how to to use the QDesignerTaskMenuExtension class - to add custom items to \QD's task menu. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerPropertySheetExtension::~QDesignerPropertySheetExtension() - - Destroys the property sheet extension. -*/ - -/*! - \fn int QDesignerPropertySheetExtension::count() const - - Returns the selected widget's number of properties. -*/ - -/*! - \fn int QDesignerPropertySheetExtension::indexOf(const QString &name) const - - Returns the index for a given property \a name. - - \sa propertyName() -*/ - -/*! - \fn QString QDesignerPropertySheetExtension::propertyName(int index) const - - Returns the name of the property at the given \a index. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerPropertySheetExtension::propertyGroup(int index) const - - Returns the property group for the property at the given \a index. - - \QD's property editor supports property groups, i.e. sections of - related properties. A property can be related to a group using the - setPropertyGroup() function. The default group of any property is - the name of the class that defines it. For example, the - QObject::objectName property appears within the QObject property - group. - - \sa indexOf(), setPropertyGroup() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setPropertyGroup(int index, const QString &group) - - Sets the property group for the property at the given \a index to - \a group. - - Relating a property to a group makes it appear within that group's - section in the property editor. The default property group of any - property is the name of the class that defines it. For example, - the QObject::objectName property appears within the QObject - property group. - - \sa indexOf(), property(), propertyGroup() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::hasReset(int index) const - - Returns true if the property at the given \a index has a reset - button in \QD's property editor, otherwise false. - - \sa indexOf(), reset() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::reset(int index) - - Resets the value of the property at the given \a index, to the - default value. Returns true if a default value could be found, otherwise false. - - \sa indexOf(), hasReset(), isChanged() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::isVisible(int index) const - - Returns true if the property at the given \a index is visible in - \QD's property editor, otherwise false. - - \sa indexOf(), setVisible() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setVisible(int index, bool visible) - - If \a visible is true, the property at the given \a index is - visible in \QD's property editor; otherwise the property is - hidden. - - \sa indexOf(), isVisible() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::isAttribute(int index) const - - Returns true if the property at the given \a index is an attribute, - which will be \e excluded from the UI file, otherwise false. - - \sa indexOf(), setAttribute() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setAttribute(int index, bool attribute) - - If \a attribute is true, the property at the given \a index is - made an attribute which will be \e excluded from the UI file; - otherwise it will be included. - - \sa indexOf(), isAttribute() -*/ - -/*! - \fn QVariant QDesignerPropertySheetExtension::property(int index) const - - Returns the value of the property at the given \a index. - - \sa indexOf(), setProperty(), propertyGroup() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setProperty(int index, const QVariant &value) - - Sets the \a value of the property at the given \a index. - - \warning If you change the value of a property using this - function, the undo stack is not updated. To ensure that a - property's value can be reverted using the undo stack, you must - use the QDesignerFormWindowCursorInterface::setProperty() - function, or its buddy \l - {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, - instead. - - \sa indexOf(), property(), propertyGroup() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::isChanged(int index) const - - Returns true if the value of the property at the given \a index - differs from the property's default value, otherwise false. - - \sa indexOf(), setChanged(), reset() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setChanged(int index, bool changed) - - Sets whether the property at the given \a index is different from - its default value, or not, depending on the \a changed parameter. - - \sa indexOf(), isChanged() -*/ - -// Doc: Interface only - -/*! - \class QDesignerDynamicPropertySheetExtension - - \brief The QDesignerDynamicPropertySheetExtension class allows you to - manipulate a widget's dynamic properties in Qt Designer's property editor. - - \sa QDesignerPropertySheetExtension, {QObject#Dynamic Properties}{Dynamic Properties} - - \inmodule QtDesigner - \since 4.3 -*/ - -/*! - \fn QDesignerDynamicPropertySheetExtension::~QDesignerDynamicPropertySheetExtension() - - Destroys the dynamic property sheet extension. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::dynamicPropertiesAllowed() const - - Returns true if the widget supports dynamic properties; otherwise returns false. -*/ - -/*! - \fn int QDesignerDynamicPropertySheetExtension::addDynamicProperty(const QString &propertyName, const QVariant &value) - - Adds a dynamic property named \a propertyName and sets its value to \a value. - Returns the index of the property if it was added successfully; otherwise returns -1 to - indicate failure. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::removeDynamicProperty(int index) - - Removes the dynamic property at the given \a index. - Returns true if the operation succeeds; otherwise returns false. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::isDynamicProperty(int index) const - - Returns true if the property at the given \a index is a dynamic property; otherwise - returns false. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::canAddDynamicProperty(const QString &propertyName) const - - Returns true if \a propertyName is a valid, unique name for a dynamic - property; otherwise returns false. - -*/ diff --git a/doc/src/qtendian.qdoc b/doc/src/qtendian.qdoc deleted file mode 100644 index dcffb5d..0000000 --- a/doc/src/qtendian.qdoc +++ /dev/null @@ -1,168 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \headerfile - \title Endian Conversion Functions - \ingroup architecture - \brief The header provides functions to convert between - little and big endian representations of numbers. -*/ - -/*! - \fn T qFromBigEndian(const uchar *src) - \since 4.3 - \relates - - Reads a big-endian number from memory location \a src and returns the number in the - host byte order representation. - On CPU architectures where the host byte order is little-endian (such as x86) this - will swap the byte order; otherwise it will just read from \a src. - - \note Template type \c{T} can either be a qint16, qint32 or qint64. Other types of - integers, e.g., qlong, are not applicable. - - There are no data alignment constraints for \a src. - - \sa qFromLittleEndian() - \sa qToBigEndian() - \sa qToLittleEndian() -*/ -/*! - \fn T qFromBigEndian(T src) - \since 4.3 - \relates - \overload - - Converts \a src from big-endian byte order and returns the number in host byte order - representation of that number. - On CPU architectures where the host byte order is little-endian (such as x86) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ -/*! - \fn T qFromLittleEndian(const uchar *src) - \since 4.3 - \relates - - Reads a little-endian number from memory location \a src and returns the number in - the host byte order representation. - On CPU architectures where the host byte order is big-endian (such as PowerPC) this - will swap the byte order; otherwise it will just read from \a src. - - \note Template type \c{T} can either be a qint16, qint32 or qint64. Other types of - integers, e.g., qlong, are not applicable. - - There are no data alignment constraints for \a src. - - \sa qFromBigEndian() - \sa qToBigEndian() - \sa qToLittleEndian() -*/ -/*! - \fn T qFromLittleEndian(T src) - \since 4.3 - \relates - \overload - - Converts \a src from little-endian byte order and returns the number in host byte - order representation of that number. - On CPU architectures where the host byte order is big-endian (such as PowerPC) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ -/*! - \fn void qToBigEndian(T src, uchar *dest) - \since 4.3 - \relates - - Writes the number \a src with template type \c{T} to the memory location at \a dest - in big-endian byte order. - - Note that template type \c{T} can only be an integer data type (signed or unsigned). - - There are no data alignment constraints for \a dest. - - \sa qFromBigEndian() - \sa qFromLittleEndian() - \sa qToLittleEndian() -*/ -/*! - \fn T qToBigEndian(T src) - \since 4.3 - \relates - \overload - - Converts \a src from host byte order and returns the number in big-endian byte order - representation of that number. - On CPU architectures where the host byte order is little-endian (such as x86) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ -/*! - \fn void qToLittleEndian(T src, uchar *dest) - \since 4.3 - \relates - - Writes the number \a src with template type \c{T} to the memory location at \a dest - in little-endian byte order. - - Note that template type \c{T} can only be an integer data type (signed or unsigned). - - There are no data alignment constraints for \a dest. - - \sa qFromBigEndian() - \sa qFromLittleEndian() - \sa qToBigEndian() -*/ -/*! - \fn T qToLittleEndian(T src) - \since 4.3 - \relates - \overload - - Converts \a src from host byte order and returns the number in little-endian byte - order representation of that number. - On CPU architectures where the host byte order is big-endian (such as PowerPC) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ - diff --git a/doc/src/qtestevent.qdoc b/doc/src/qtestevent.qdoc deleted file mode 100644 index 2e111b3..0000000 --- a/doc/src/qtestevent.qdoc +++ /dev/null @@ -1,191 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QTestEventList - \inmodule QtTest - - \brief The QTestEventList class provides a list of GUI events. - - QTestEventList inherits from QList, and provides - convenience functions for populating the list. - - A QTestEventList can be populated with GUI events that can be - stored as test data for later usage, or be replayed on any - QWidget. - - Example: - \snippet doc/src/snippets/code/doc_src_qtestevent.qdoc 0 - - The example above simulates the user entering the character \c a - followed by a backspace, waiting for 200 milliseconds and - repeating it. -*/ - -/*! \fn QTestEventList::QTestEventList() - - Constructs an empty QTestEventList. -*/ - -/*! \fn QTestEventList::QTestEventList(const QTestEventList &other) - - Constructs a new QTestEventList as a copy of \a other. -*/ - -/*! \fn QTestEventList::~QTestEventList() - - Empties the list and destroys all stored events. -*/ - -/*! \fn void QTestEventList::clear() - - Removes all events from the list. -*/ - -/*! \fn void QTestEventList::addKeyClick(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds a new key click to the list. The event will simulate the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyClick() -*/ - -/*! \fn void QTestEventList::addKeyPress(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds a new key press to the list. The event will press the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyPress() -*/ - -/*! \fn void QTestEventList::addKeyRelease(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds a new key release to the list. The event will release the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyRelease() - -*/ - -/*! \fn void QTestEventList::addKeyEvent(QTest::KeyAction action, Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - \internal -*/ - -/*! \fn void QTestEventList::addKeyClick(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - \overload - - Adds a new key click to the list. The event will simulate the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyClick() - -*/ - -/*! \fn void QTestEventList::addKeyPress(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - \overload - - Adds a new key press to the list. The event will press the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyPress() -*/ - -/*! \fn void QTestEventList::addKeyRelease(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - \overload - - Adds a new key release to the list. The event will release the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyRelease() -*/ - -/*! \fn void QTestEventList::addKeyClicks(const QString &keys, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds new keyboard entries to the list. The event will press the \a keys with the \a modifiers and wait \a msecs milliseconds between each key. - - \sa QTest::keyClicks() -*/ - -/*! \fn void QTestEventList::addKeyEvent(QTest::KeyAction action, char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - \internal -*/ - -/*! \fn void QTestEventList::addDelay(int msecs) - - Adds a \a msecs milliseconds delay. - - \sa QTest::qWait() -*/ - -/*! \fn void QTestEventList::simulate(QWidget *w) - - Simulates the events from the list one by one on the widget \a w. - For an example, please read the \l QTestEventList class documentation. -*/ - -/*! \fn void QTestEventList::addMousePress(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a mouse press to the list. The event will press the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mousePress() -*/ -/*! \fn void QTestEventList::addMouseRelease(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a mouse release to the list. The event will release the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mouseRelease() -*/ -/*! \fn void QTestEventList::addMouseClick(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a mouse click to the list. The event will click the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mouseClick() -*/ -/*! \fn void QTestEventList::addMouseDClick(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a double mouse click to the list. The event will double click the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mousePress() -*/ -/*! \fn void QTestEventList::addMouseMove(QPoint pos = QPoint(), int delay=-1) - - Adds a mouse move to the list. The event will move the mouse to the position \a pos. If a \a delay (in milliseconds) is set, the test will wait after moving the mouse. The default position is the center of the widget. - - \sa QTest::mousePress() -*/ - diff --git a/doc/src/qvarlengtharray.qdoc b/doc/src/qvarlengtharray.qdoc deleted file mode 100644 index ac6bb6e..0000000 --- a/doc/src/qvarlengtharray.qdoc +++ /dev/null @@ -1,274 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QVarLengthArray - \brief The QVarLengthArray class provides a low-level variable-length array. - - \ingroup tools - \reentrant - - The C++ language doesn't support variable-length arrays on the stack. - For example, the following code won't compile: - - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 0 - - The alternative is to allocate the array on the heap (with - \c{new}): - - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 1 - - However, if myfunc() is called very frequently from the - application's inner loop, heap allocation can be a major source - of slowdown. - - QVarLengthArray is an attempt to work around this gap in the C++ - language. It allocates a certain number of elements on the stack, - and if you resize the array to a larger size, it automatically - uses the heap instead. Stack allocation has the advantage that - it is much faster than heap allocation. - - Example: - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 2 - - In the example above, QVarLengthArray will preallocate 1024 - elements on the stack and use them unless \c{n + 1} is greater - than 1024. If you omit the second template argument, - QVarLengthArray's default of 256 is used. - - QVarLengthArray's value type must be an \l{assignable data type}. - This covers most data types that are commonly used, but the - compiler won't let you, for example, store a QWidget as a value; - instead, store a QWidget *. - - QVarLengthArray, like QVector, provides a resizable array data - structure. The main differences between the two classes are: - - \list - \o QVarLengthArray's API is much more low-level. It provides no - iterators and lacks much of QVector's functionality. - - \o QVarLengthArray doesn't initialize the memory if the value is - a basic type. (QVector always does.) - - \o QVector uses \l{implicit sharing} as a memory optimization. - QVarLengthArray doesn't provide that feature; however, it - usually produces slightly better performance due to reduced - overhead, especially in tight loops. - \endlist - - In summary, QVarLengthArray is a low-level optimization class - that only makes sense in very specific cases. It is used a few - places inside Qt and was added to Qt's public API for the - convenience of advanced users. - - \sa QVector, QList, QLinkedList -*/ - -/*! \fn QVarLengthArray::QVarLengthArray(int size) - - Constructs an array with an initial size of \a size elements. - - If the value type is a primitive type (e.g., char, int, float) or - a pointer type (e.g., QWidget *), the elements are not - initialized. For other types, the elements are initialized with a - \l{default-constructed value}. -*/ - -/*! \fn QVarLengthArray::~QVarLengthArray() - - Destroys the array. -*/ - -/*! \fn int QVarLengthArray::size() const - - Returns the number of elements in the array. - - \sa isEmpty(), resize() -*/ - -/*! \fn int QVarLengthArray::count() const - - Same as size(). - - \sa isEmpty(), resize() -*/ - -/*! \fn bool QVarLengthArray::isEmpty() const - - Returns true if the array has size 0; otherwise returns false. - - \sa size(), resize() -*/ - -/*! \fn void QVarLengthArray::clear() - - Removes all the elements from the array. - - Same as resize(0). -*/ - -/*! \fn void QVarLengthArray::resize(int size) - - Sets the size of the array to \a size. If \a size is greater than - the current size, elements are added to the end. If \a size is - less than the current size, elements are removed from the end. - - If the value type is a primitive type (e.g., char, int, float) or - a pointer type (e.g., QWidget *), new elements are not - initialized. For other types, the elements are initialized with a - \l{default-constructed value}. - - \sa size() -*/ - -/*! \fn int QVarLengthArray::capacity() const - - Returns the maximum number of elements that can be stored in the - array without forcing a reallocation. - - The sole purpose of this function is to provide a means of fine - tuning QVarLengthArray's memory usage. In general, you will rarely ever - need to call this function. If you want to know how many items are - in the array, call size(). - - \sa reserve() -*/ - -/*! \fn void QVarLengthArray::reserve(int size) - - Attempts to allocate memory for at least \a size elements. If you - know in advance how large the array can get, you can call this - function and if you call resize() often, you are likely to get - better performance. If \a size is an underestimate, the worst - that will happen is that the QVarLengthArray will be a bit - slower. - - The sole purpose of this function is to provide a means of fine - tuning QVarLengthArray's memory usage. In general, you will - rarely ever need to call this function. If you want to change the - size of the array, call resize(). - - \sa capacity() -*/ - -/*! \fn T &QVarLengthArray::operator[](int i) - - Returns a reference to the item at index position \a i. - - \a i must be a valid index position in the array (i.e., 0 <= \a i - < size()). - - \sa data() -*/ - -/*! \fn const T &QVarLengthArray::operator[](int i) const - - \overload -*/ - - -/*! - \fn void QVarLengthArray::append(const T &t) - - Appends item \a t to the array, extending the array if necessary. - - \sa removeLast() -*/ - - -/*! - \fn inline void QVarLengthArray::removeLast() - \since 4.5 - - Decreases the size of the array by one. The allocated size is not changed. - - \sa append() -*/ - -/*! - \fn void QVarLengthArray::append(const T *buf, int size) - - Appends \a size amount of items referenced by \a buf to this array. -*/ - - -/*! \fn T *QVarLengthArray::data() - - Returns a pointer to the data stored in the array. The pointer can - be used to access and modify the items in the array. - - Example: - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 3 - - The pointer remains valid as long as the array isn't reallocated. - - This function is mostly useful to pass an array to a function - that accepts a plain C++ array. - - \sa constData(), operator[]() -*/ - -/*! \fn const T *QVarLengthArray::data() const - - \overload -*/ - -/*! \fn const T *QVarLengthArray::constData() const - - Returns a const pointer to the data stored in the array. The - pointer can be used to access the items in the array. The - pointer remains valid as long as the array isn't reallocated. - - This function is mostly useful to pass an array to a function - that accepts a plain C++ array. - - \sa data(), operator[]() -*/ - -/*! \fn QVarLengthArray &QVarLengthArray::operator=(const QVarLengthArray &other) - Assigns \a other to this array and returns a reference to this array. - */ - -/*! \fn QVarLengthArray::QVarLengthArray(const QVarLengthArray &other) - Constructs a copy of \a other. - */ - diff --git a/doc/src/qwaitcondition.qdoc b/doc/src/qwaitcondition.qdoc deleted file mode 100644 index ae94e35..0000000 --- a/doc/src/qwaitcondition.qdoc +++ /dev/null @@ -1,188 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QWaitCondition - \brief The QWaitCondition class provides a condition variable for - synchronizing threads. - - \threadsafe - - \ingroup thread - \ingroup environment - - QWaitCondition allows a thread to tell other threads that some - sort of condition has been met. One or many threads can block - waiting for a QWaitCondition to set a condition with wakeOne() or - wakeAll(). Use wakeOne() to wake one randomly selected condition or - wakeAll() to wake them all. - - For example, let's suppose that we have three tasks that should - be performed whenever the user presses a key. Each task could be - split into a thread, each of which would have a - \l{QThread::run()}{run()} body like this: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 0 - - Here, the \c keyPressed variable is a global variable of type - QWaitCondition. - - A fourth thread would read key presses and wake the other three - threads up every time it receives one, like this: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 1 - - The order in which the three threads are woken up is undefined. - Also, if some of the threads are still in \c do_something() when - the key is pressed, they won't be woken up (since they're not - waiting on the condition variable) and so the task will not be - performed for that key press. This issue can be solved using a - counter and a QMutex to guard it. For example, here's the new - code for the worker threads: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 2 - - Here's the code for the fourth thread: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 3 - - The mutex is necessary because the results of two threads - attempting to change the value of the same variable - simultaneously are unpredictable. - - Wait conditions are a powerful thread synchronization primitive. - The \l{threads/waitconditions}{Wait Conditions} example shows how - to use QWaitCondition as an alternative to QSemaphore for - controlling access to a circular buffer shared by a producer - thread and a consumer thread. - - \sa QMutex, QSemaphore, QThread, {Wait Conditions Example} -*/ - -/*! - \fn QWaitCondition::QWaitCondition() - - Constructs a new wait condition object. -*/ - -/*! - \fn QWaitCondition::~QWaitCondition() - - Destroys the wait condition object. -*/ - -/*! - \fn void QWaitCondition::wakeOne() - - Wakes one thread waiting on the wait condition. The thread that - is woken up depends on the operating system's scheduling - policies, and cannot be controlled or predicted. - - If you want to wake up a specific thread, the solution is - typically to use different wait conditions and have different - threads wait on different conditions. - - \sa wakeAll() -*/ - -/*! - \fn void QWaitCondition::wakeAll() - - Wakes all threads waiting on the wait condition. The order in - which the threads are woken up depends on the operating system's - scheduling policies and cannot be controlled or predicted. - - \sa wakeOne() -*/ - -/*! - \fn bool QWaitCondition::wait(QMutex *mutex, unsigned long time) - - Releases the locked \a mutex and waits on the wait condition. The - \a mutex must be initially locked by the calling thread. If \a - mutex is not in a locked state, this function returns - immediately. If \a mutex is a recursive mutex, this function - returns immediately. The \a mutex will be unlocked, and the - calling thread will block until either of these conditions is met: - - \list - \o Another thread signals it using wakeOne() or wakeAll(). This - function will return true in this case. - \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX - (the default), then the wait will never timeout (the event - must be signalled). This function will return false if the - wait timed out. - \endlist - - The mutex will be returned to the same locked state. This - function is provided to allow the atomic transition from the - locked state to the wait state. - - \sa wakeOne(), wakeAll() -*/ - -/*! - \fn bool QWaitCondition::wait(QReadWriteLock *readWriteLock, unsigned long time) - \since 4.4 - - Releases the locked \a readWriteLock and waits on the wait - condition. The \a readWriteLock must be initially locked by the - calling thread. If \a readWriteLock is not in a locked state, this - function returns immediately. The \a readWriteLock must not be - locked recursively, otherwise this function will not release the - lock properly. The \a readWriteLock will be unlocked, and the - calling thread will block until either of these conditions is met: - - \list - \o Another thread signals it using wakeOne() or wakeAll(). This - function will return true in this case. - \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX - (the default), then the wait will never timeout (the event - must be signalled). This function will return false if the - wait timed out. - \endlist - - The \a readWriteLock will be returned to the same locked - state. This function is provided to allow the atomic transition - from the locked state to the wait state. - - \sa wakeOne(), wakeAll() -*/ -- cgit v0.12 From 1ef2f7fd3734fbae5fd4e18047f4ad06b217d850 Mon Sep 17 00:00:00 2001 From: Kavindra Devi Palaraja Date: Thu, 30 Jul 2009 14:38:51 +0200 Subject: Doc - Beautifying documentation of autoMaximizeThreshold Reviewed-By: Thomas Hartmann --- src/gui/kernel/qapplication.cpp | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/gui/kernel/qapplication.cpp b/src/gui/kernel/qapplication.cpp index 109ceb1..c0d9957 100644 --- a/src/gui/kernel/qapplication.cpp +++ b/src/gui/kernel/qapplication.cpp @@ -1194,21 +1194,22 @@ bool QApplication::compressEvent(QEvent *event, QObject *receiver, QPostEventLis \since 4.4 \brief defines a threshold for auto maximizing widgets - The auto maximize threshold is only available as part of Qt for Windows CE. + \bold{The auto maximize threshold is only available as part of Qt for + Windows CE.} This property defines a threshold for the size of a window as a percentage of the screen size. If the minimum size hint of a window exceeds the - threshold, calling show() will then cause the window to be maximized + threshold, calling show() will cause the window to be maximized automatically. - Setting the threshold to be 100 or greater means that it will cause it to - always be maximized. Setting it to be 50 means that the widget is maximized - if the vertical minimum size hint is at least 50% of the vertical screen - size. + Setting the threshold to 100 or greater means that the widget will always + be maximized. Alternatively, setting the threshold to 50 means that the + widget will be maximized only if the vertical minimum size hint is at least + 50% of the vertical screen size. - If -1 is specified then this will disable the feature. + Setting the threshold to -1 disables the feature. - On Windows CE the default is -1 (i.e. it is disabled). + On Windows CE the default is -1 (i.e., it is disabled). On Windows Mobile the default is 40. */ -- cgit v0.12 From 91fe038eb280ef64f92a029f9247e657361c90f7 Mon Sep 17 00:00:00 2001 From: Kavindra Devi Palaraja Date: Thu, 30 Jul 2009 15:00:24 +0200 Subject: Doc - Some more cleanups to beautify the documentation Reviewed-By: TrustMe --- src/gui/kernel/qapplication.cpp | 77 ++++++++++++++++++++--------------------- 1 file changed, 38 insertions(+), 39 deletions(-) diff --git a/src/gui/kernel/qapplication.cpp b/src/gui/kernel/qapplication.cpp index c0d9957..e210556 100644 --- a/src/gui/kernel/qapplication.cpp +++ b/src/gui/kernel/qapplication.cpp @@ -673,9 +673,9 @@ QApplication::QApplication(int &argc, char **argv, int _internal) On X11, the window system is initialized if \a GUIenabled is true. If \a GUIenabled is false, the application does not connect to the X server. - On Windows and Macintosh, currently the window system is always - initialized, regardless of the value of GUIenabled. This may change in - future versions of Qt. + On Windows and Mac OS, currently the window system is always initialized, + regardless of the value of GUIenabled. This may change in future versions + of Qt. The following example shows how to create an application that uses a graphical interface when available. @@ -1218,9 +1218,9 @@ bool QApplication::compressEvent(QEvent *event, QObject *receiver, QPostEventLis \since 4.5 \brief toggles automatic SIP (software input panel) visibility - The auto SIP property is only available as part of Qt for Windows CE. + \bold{The auto SIP property is only available as part of Qt for Windows CE.} - Set this property to true to automatically display the SIP when entering + Set this property to \c true to automatically display the SIP when entering widgets that accept keyboard input. This property only affects widgets with the WA_InputMethodEnabled attribute set. */ @@ -1518,7 +1518,7 @@ int QApplication::colorSpec() strategy. Use this option if your application uses buttons, menus, texts and pixmaps with few colors. With this option, the application uses system global colors. This works fine for most - applications under X11, but on Windows machines it may cause + applications under X11, but on the Windows platform, it may cause dithering of non-standard colors. \o QApplication::CustomColor. Use this option if your application needs a small number of custom colors. On X11, this option is the @@ -3514,12 +3514,12 @@ void QApplication::changeOverrideCursor(const QCursor &cursor) We recommend that you connect clean-up code to the \l{QCoreApplication::}{aboutToQuit()} signal, instead of putting it in your - application's \c{main()} function because on some platforms the - QApplication::exec() call may not return. For example, on Windows when the - user logs off, the system terminates the process after Qt closes all - top-level windows. Hence, there is no guarantee that the application will - have time to exit its event loop and execute code at the end of the - \c{main()} function after the QApplication::exec() call. + application's \c{main()} function. This is because, on some platforms the + QApplication::exec() call may not return. For example, on the Windows + platform, when the user logs off, the system terminates the process after Qt + closes all top-level windows. Hence, there is \e{no guarantee} that the + application will have time to exit its event loop and execute code at the + end of the \c{main()} function, after the QApplication::exec() call. \sa quitOnLastWindowClosed, quit(), exit(), processEvents(), QCoreApplication::exec() @@ -4763,7 +4763,7 @@ bool QApplication::keypadNavigationEnabled() On Mac OS X, this works more at the application level and will cause the application icon to bounce in the dock. - On Windows this causes the window's taskbar entry to flash for a time. If + On Windows, this causes the window's taskbar entry to flash for a time. If \a msec is zero, the flashing will stop and the taskbar entry will turn a different color (currently orange). @@ -4780,24 +4780,22 @@ bool QApplication::keypadNavigationEnabled() caret display. Usually the text cursor is displayed for half the cursor flash time, then hidden for the same amount of time, but this may vary. - The default value on X11 is 1000 milliseconds. On Windows, the control - panel value is used. Widgets should not cache this value since it may be - changed at any time by the user changing the global desktop settings. + The default value on X11 is 1000 milliseconds. On Windows, the + \gui{Control Panel} value is used and setting this property sets the cursor + flash time for all applications. - \note On Microsoft Windows, setting this property sets the cursor flash - time for all applications. + We recommend that widgets do not cache this value as it may change at any + time if the user changes the global desktop settings. */ /*! \property QApplication::doubleClickInterval - \brief the time limit in milliseconds that distinguishes a double click from two - consecutive mouse clicks + \brief the time limit in milliseconds that distinguishes a double click + from two consecutive mouse clicks - The default value on X11 is 400 milliseconds. On Windows and Mac OS X, the - operating system's value is used. - - On Microsoft Windows, calling this function sets the double click interval - for all applications. + The default value on X11 is 400 milliseconds. On Windows and Mac OS, the + operating system's value is used. However, on Windows, calling this + function sets the double click interval for all applications. */ /*! @@ -4806,7 +4804,7 @@ bool QApplication::keypadNavigationEnabled() from two consecutive key presses \since 4.2 - The default value on X11 is 400 milliseconds. On Windows and Mac OS X, the + The default value on X11 is 400 milliseconds. On Windows and Mac OS, the operating system's value is used. */ @@ -4871,7 +4869,7 @@ bool QApplication::keypadNavigationEnabled() You need not have a main widget; connecting lastWindowClosed() to quit() is an alternative. - For X11, this function also resizes and moves the main widget according + On X11, this function also resizes and moves the main widget according to the \e -geometry command-line option, so you should set the default geometry (using \l QWidget::setGeometry()) before calling setMainWidget(). @@ -4900,9 +4898,10 @@ bool QApplication::keypadNavigationEnabled() Application cursors are stored on an internal stack. setOverrideCursor() pushes the cursor onto the stack, and restoreOverrideCursor() pops the active cursor off the stack. changeOverrideCursor() changes the curently - active application override cursor. Every setOverrideCursor() must - eventually be followed by a corresponding restoreOverrideCursor(), - otherwise the stack will never be emptied. + active application override cursor. + + Every setOverrideCursor() must eventually be followed by a corresponding + restoreOverrideCursor(), otherwise the stack will never be emptied. Example: \snippet doc/src/snippets/code/src_gui_kernel_qapplication_x11.cpp 0 @@ -5083,19 +5082,19 @@ bool QApplicationPrivate::shouldSetFocus(QWidget *w, Qt::FocusPolicy policy) */ /*! \fn QDecoration* QApplication::qwsSetDecoration(const QString &decoration) - \overload + \overload - Requests a QDecoration object for \a decoration from the QDecorationFactory. + Requests a QDecoration object for \a decoration from the + QDecorationFactory. - The string must be one of the QDecorationFactory::keys(). Keys are - case insensitive. + The string must be one of the QDecorationFactory::keys(). Keys are case + insensitive. - A later call to the QApplication constructor will override the - requested style when a "-style" option is passed in as a commandline - parameter. + A later call to the QApplication constructor will override the requested + style when a "-style" option is passed in as a commandline parameter. - Returns 0 if an unknown \a decoration is passed, otherwise the QStyle object - returned is set as the application's GUI style. + Returns 0 if an unknown \a decoration is passed, otherwise the QStyle object + returned is set as the application's GUI style. */ /*! -- cgit v0.12 From e447e8a5356f5de4a6a62a28c0d21785b09b4cba Mon Sep 17 00:00:00 2001 From: Benjamin C Meyer Date: Thu, 30 Jul 2009 15:12:27 +0200 Subject: When there is no alpha channel significantly improve the speed of blendTiled. Copy the first line from the texture to the destination and from then on reference that copy reducing cache misses. Also progressively copy larger sizes, reducing the amount of time spend figuring out what to copy. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Merge-request: 371 Reviewed-by: Samuel Rødal --- src/gui/painting/qdrawhelper.cpp | 72 ++++++++++++++++++++++++++++------------ 1 file changed, 51 insertions(+), 21 deletions(-) diff --git a/src/gui/painting/qdrawhelper.cpp b/src/gui/painting/qdrawhelper.cpp index 979390a..b6603e4 100644 --- a/src/gui/painting/qdrawhelper.cpp +++ b/src/gui/painting/qdrawhelper.cpp @@ -4794,30 +4794,60 @@ Q_STATIC_TEMPLATE_FUNCTION void blendTiled(int count, const QSpan *spans, void * if (sy < 0) sy += image_height; - while (length) { - int l = qMin(image_width - sx, length); - if (buffer_size < l) - l = buffer_size; - - DST *dest = ((DST*)data->rasterBuffer->scanLine(spans->y)) + x; - const SRC *src = (SRC*)data->texture.scanLine(sy) + sx; - if (modeSource && coverage == 255) { + if (modeSource && coverage == 255) { + // Copy the first texture block + length = image_width; + while (length) { + int l = qMin(image_width - sx, length); + if (buffer_size < l) + l = buffer_size; + DST *dest = ((DST*)data->rasterBuffer->scanLine(spans->y)) + x; + const SRC *src = (SRC*)data->texture.scanLine(sy) + sx; qt_memconvert(dest, src, l); - } else if (sizeof(DST) == 3 && sizeof(SRC) == 3 && l >= 4 && - (quintptr(dest) & 3) == (quintptr(src) & 3)) - { - blendUntransformed_dest24(dest, src, coverage, l); - } else if (sizeof(DST) == 2 && sizeof(SRC) == 2 && l >= 2 && - (quintptr(dest) & 3) == (quintptr(src) & 3)) - { - blendUntransformed_dest16(dest, src, coverage, l); - } else { - blendUntransformed_unaligned(dest, src, coverage, l); + length -= l; + sx = 0; } - x += l; - length -= l; - sx = 0; + // Now use the rasterBuffer as the source of the texture, + // We can now progressively copy larger blocks + // - Less cpu time in code figuring out what to copy + // We are dealing with one block of data + // - More likely to fit in the cache + // - can use memcpy + int copy_image_width = image_width; + length = spans->len - image_width; + DST *src = ((DST*)data->rasterBuffer->scanLine(spans->y)) + x; + DST *dest = src + copy_image_width; + while (copy_image_width < length) { + qt_memconvert(dest, src, copy_image_width); + dest += copy_image_width; + length -= copy_image_width; + copy_image_width *= 2; + } + qt_memconvert(dest, src, length); + } else { + while (length) { + int l = qMin(image_width - sx, length); + if (buffer_size < l) + l = buffer_size; + DST *dest = ((DST*)data->rasterBuffer->scanLine(spans->y)) + x; + const SRC *src = (SRC*)data->texture.scanLine(sy) + sx; + if (sizeof(DST) == 3 && sizeof(SRC) == 3 && l >= 4 && + (quintptr(dest) & 3) == (quintptr(src) & 3)) + { + blendUntransformed_dest24(dest, src, coverage, l); + } else if (sizeof(DST) == 2 && sizeof(SRC) == 2 && l >= 2 && + (quintptr(dest) & 3) == (quintptr(src) & 3)) + { + blendUntransformed_dest16(dest, src, coverage, l); + } else { + blendUntransformed_unaligned(dest, src, coverage, l); + } + + x += l; + length -= l; + sx = 0; + } } ++spans; } -- cgit v0.12 From 1685f9968ea7b1e132df44c8aab3d03ad6cd5e12 Mon Sep 17 00:00:00 2001 From: Kavindra Devi Palaraja Date: Thu, 30 Jul 2009 15:39:19 +0200 Subject: Doc - Fixed a broken link to the Apple Human Interface Guidelines document Task: 254724 Reviewed-By: TrustMe --- src/gui/widgets/qmenubar.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/gui/widgets/qmenubar.cpp b/src/gui/widgets/qmenubar.cpp index a3964f7..4a900d6 100644 --- a/src/gui/widgets/qmenubar.cpp +++ b/src/gui/widgets/qmenubar.cpp @@ -716,7 +716,7 @@ void QMenuBar::initStyleOption(QStyleOptionMenuItem *option, const QAction *acti application examples} also provide menus using these classes. \sa QMenu, QShortcut, QAction, - {http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html}{Introduction to Apple Human Interface Guidelines}, + {http://developer.apple.com/documentation/UserExperience/Conceptual/AppleHIGuidelines/XHIGIntro/XHIGIntro.html}{Introduction to Apple Human Interface Guidelines}, {fowler}{GUI Design Handbook: Menu Bar}, {Menus Example} */ -- cgit v0.12 From 5aa46b1052b05d34cbfef175caaf941928520964 Mon Sep 17 00:00:00 2001 From: Kim Motoyoshi Kalland Date: Mon, 27 Jul 2009 13:20:14 +0200 Subject: Added support for 'vector-effect' in QtSvg. Task-number: 254040 Reviewed-by: Tor Arne --- src/svg/qsvghandler.cpp | 232 +++++++++++++++++++++++++++++++----------------- 1 file changed, 150 insertions(+), 82 deletions(-) diff --git a/src/svg/qsvghandler.cpp b/src/svg/qsvghandler.cpp index f10b26f..b829a22 100644 --- a/src/svg/qsvghandler.cpp +++ b/src/svg/qsvghandler.cpp @@ -697,85 +697,152 @@ static void parseQPen(QPen &pen, QSvgNode *node, QString miterlimit = attributes.value(QLatin1String("stroke-miterlimit")).toString(); QString opacity = attributes.value(QLatin1String("stroke-opacity")).toString(); QString width = attributes.value(QLatin1String("stroke-width")).toString(); + QString vectorEffect = attributes.value(QLatin1String("vector-effect")).toString(); QString myId = someId(attributes); - if (!value.isEmpty() || !width.isEmpty()) { - if (value != QLatin1String("none")) { - if (!value.isEmpty()) { - if (node && value.startsWith(QLatin1String("url"))) { - value = value.remove(0, 3); - QSvgStyleProperty *style = styleFromUrl(node, value); - if (style) { - if (style->type() == QSvgStyleProperty::GRADIENT) { - QBrush b(*((QSvgGradientStyle*)style)->qgradient()); - pen.setBrush(b); - } else if (style->type() == QSvgStyleProperty::SOLID_COLOR) { - pen.setColor( - ((QSvgSolidColorStyle*)style)->qcolor()); - } - } else { - qWarning()<<"QSvgHandler::parsePen could not resolve property" << idFromUrl(value); - } - } else { - QColor color; - if (constructColor(value, opacity, color, handler)) - pen.setColor(color); - } - //since we could inherit stroke="none" - //we need to reset the style of our stroke to something - pen.setStyle(Qt::SolidLine); - } - if (!width.isEmpty()) { - QSvgHandler::LengthType lt; - qreal widthF = parseLength(width, lt, handler); - //### fixme - if (!widthF) { - pen.setStyle(Qt::NoPen); - return; - } - pen.setWidthF(widthF); - } - qreal penw = pen.widthF(); - - if (!linejoin.isEmpty()) { - if (linejoin == QLatin1String("miter")) - pen.setJoinStyle(Qt::SvgMiterJoin); - else if (linejoin == QLatin1String("round")) - pen.setJoinStyle(Qt::RoundJoin); - else if (linejoin == QLatin1String("bevel")) - pen.setJoinStyle(Qt::BevelJoin); - } - if (!miterlimit.isEmpty()) - pen.setMiterLimit(toDouble(miterlimit)); - - if (!linecap.isEmpty()) { - if (linecap == QLatin1String("butt")) - pen.setCapStyle(Qt::FlatCap); - else if (linecap == QLatin1String("round")) - pen.setCapStyle(Qt::RoundCap); - else if (linecap == QLatin1String("square")) - pen.setCapStyle(Qt::SquareCap); - } + QSvgStrokeStyle *inherited = + static_cast(node->parent()->styleProperty( + QSvgStyleProperty::STROKE)); - if (!dashArray.isEmpty()) { - const QChar *s = dashArray.constData(); - QVector dashes = parseNumbersList(s); - qreal *d = dashes.data(); - if (penw != 0) - for (int i = 0; i < dashes.size(); ++i) { - *d /= penw; - ++d; + bool stroke = false; + if (inherited) { + pen = inherited->qpen(); + stroke = inherited->strokePresent(); + } else { + pen = handler->defaultPen(); + } + + // stroke-opacity attribute handling + qreal strokeAlpha; + if (!opacity.isEmpty() && opacity != QLatin1String("inherit")) { + strokeAlpha = qMin(qreal(1.0), qMax(qreal(0.0), toDouble(opacity))); + } else { + strokeAlpha = pen.color().alphaF(); + } + + //stroke attribute handling + if (!value.isEmpty() && value != QLatin1String("inherit")) { + if (value.startsWith(QLatin1String("url"))) { + value = value.remove(0, 3); + QSvgStyleProperty *style = styleFromUrl(node, value); + if (style) { + if (style->type() == QSvgStyleProperty::GRADIENT) { + QBrush b(*((QSvgGradientStyle*)style)->qgradient()); + pen.setBrush(b); + } else if (style->type() == QSvgStyleProperty::SOLID_COLOR) { + pen.setColor(((QSvgSolidColorStyle*)style)->qcolor()); } - pen.setDashPattern(dashes); + stroke = true; + } else { + qWarning() << "QSvgHandler::parsePen could not resolve property" << idFromUrl(value); } - if (!dashOffset.isEmpty()) { - pen.setDashOffset(toDouble(dashOffset)); + } else if (value == QLatin1String("none")) { + QColor color; + color.setAlphaF(strokeAlpha); + pen.setColor(color); + stroke = false; + } else { + QColor color; + if (resolveColor(value, color, handler)) { + color.setAlphaF(strokeAlpha); + pen.setColor(color); } + stroke = true; + } + } else { + QColor color = pen.color(); + color.setAlphaF(strokeAlpha); + pen.setColor(color); + } - } else { - pen.setStyle(Qt::NoPen); + //stroke-width handling + if (!width.isEmpty() && width != QLatin1String("inherit")) { + qreal widthF; + QSvgHandler::LengthType lt; + widthF = parseLength(width, lt, handler); + pen.setWidthF(widthF); + } + + //stroke-linejoin attribute handling + if (!linejoin.isEmpty()) { + if (linejoin == QLatin1String("miter")) + pen.setJoinStyle(Qt::SvgMiterJoin); + else if (linejoin == QLatin1String("round")) + pen.setJoinStyle(Qt::RoundJoin); + else if (linejoin == QLatin1String("bevel")) + pen.setJoinStyle(Qt::BevelJoin); + } + + //stroke-linecap attribute handling + if (!linecap.isEmpty()) { + if (linecap == QLatin1String("butt")) + pen.setCapStyle(Qt::FlatCap); + else if (linecap == QLatin1String("round")) + pen.setCapStyle(Qt::RoundCap); + else if (linecap == QLatin1String("square")) + pen.setCapStyle(Qt::SquareCap); + } + + //strok-dasharray attribute handling + qreal penw = pen.widthF(); + if (!dashArray.isEmpty() && dashArray != QLatin1String("inherit")) { + const QChar *s = dashArray.constData(); + QVector dashes = parseNumbersList(s); + qreal *d = dashes.data(); + if (penw != 0) + for (int i = 0; i < dashes.size(); ++i) { + *d /= penw; + ++d; + } + // if the dash count is odd the dashes should be duplicated + if (dashes.size() % 2 != 0) + dashes << QVector(dashes); + pen.setDashPattern(dashes); + } else if (inherited) { + QVector dashes(inherited->qpen().dashPattern()); + qreal *d = dashes.data(); + if (!penw) + penw = 1.0; + qreal inheritpenw = inherited->qpen().widthF(); + if (!inheritpenw) + inheritpenw = 1.0; + for ( int i = 0; i < dashes.size(); ++i) { + *d *= (inheritpenw/ penw); + ++d; } + pen.setDashPattern(dashes); } + + //stroke-dashoffset attribute handling + if (!dashOffset.isEmpty() && dashOffset != QLatin1String("inherit")) { + qreal doffset = toDouble(dashOffset); + if (penw != 0) + doffset /= penw; + pen.setDashOffset(doffset); + } else if (inherited) { + qreal doffset = pen.dashOffset(); + if (!penw) + penw = 1.0; + qreal inheritpenw = inherited->qpen().widthF(); + if (!inheritpenw) + inheritpenw = 1.0; + doffset *= (inheritpenw / penw); + pen.setDashOffset(doffset); + } + + //vector-effect attribute handling + if (!vectorEffect.isEmpty()) { + if (vectorEffect == QLatin1String("non-scaling-stroke")) + pen.setCosmetic(true); + else if (vectorEffect == QLatin1String("none")) + pen.setCosmetic(false); + } + + if (!miterlimit.isEmpty() && miterlimit != QLatin1String("inherit")) + pen.setMiterLimit(toDouble(miterlimit)); + + if (!stroke) + pen.setStyle(Qt::NoPen); } static QMatrix parseTransformationMatrix(const QString &value) @@ -917,18 +984,15 @@ static void parsePen(QSvgNode *node, QString miterlimit = attributes.value(QLatin1String("stroke-miterlimit")).toString(); QString opacity = attributes.value(QLatin1String("stroke-opacity")).toString(); QString width = attributes.value(QLatin1String("stroke-width")).toString(); + QString vectorEffect = attributes.value(QLatin1String("vector-effect")).toString(); QString myId = someId(attributes); //qDebug()<<"Node "<type()<<", attrs are "<(node->parent()->styleProperty( QSvgStyleProperty::STROKE)); @@ -961,8 +1025,7 @@ static void parsePen(QSvgNode *node, pen.setColor( ((QSvgSolidColorStyle*)style)->qcolor()); } - pen.setStyle(Qt::SolidLine); - stroke = true; + stroke = true; } else { qWarning() << "QSvgHandler::parsePen could not resolve property" << idFromUrl(value); } @@ -991,9 +1054,6 @@ static void parsePen(QSvgNode *node, QSvgHandler::LengthType lt; widthF = parseLength(width, lt, handler); pen.setWidthF(widthF); - } else if (inherited){ - qreal widthF = inherited->qpen().widthF(); - pen.setWidthF(widthF); } //stroke-linejoin attribute handling @@ -1064,6 +1124,14 @@ static void parsePen(QSvgNode *node, pen.setDashOffset(doffset); } + //vector-effect attribute handling + if (!vectorEffect.isEmpty()) { + if (vectorEffect == QLatin1String("non-scaling-stroke")) + pen.setCosmetic(true); + else if (vectorEffect == QLatin1String("none")) + pen.setCosmetic(false); + } + if (!miterlimit.isEmpty() && miterlimit != QLatin1String("inherit")) pen.setMiterLimit(toDouble(miterlimit)); -- cgit v0.12 From 54ed2a3db855aab8219f9588e241d3110bdddfb1 Mon Sep 17 00:00:00 2001 From: Kim Motoyoshi Kalland Date: Thu, 30 Jul 2009 14:33:41 +0200 Subject: Fixed font attribute inheritence, text and textArea elements in QtSvg. Text used to be formatted during the parsing of the SVG file, but because the text can be referenced by a 'use' element, the text formatting is not known at this point in time. Now, font attributes can be inherited from 'use' elements, and the text is formatted each time it is drawn. Reviewed-by: Tor Arne --- src/svg/qsvggraphics.cpp | 286 ++++++++-------- src/svg/qsvggraphics_p.h | 51 ++- src/svg/qsvghandler.cpp | 630 ++++++++--------------------------- src/svg/qsvgnode_p.h | 1 + src/svg/qsvgstyle.cpp | 126 ++++--- src/svg/qsvgstyle_p.h | 80 ++++- tests/arthur/data/1.2/textArea01.svg | 2 +- 7 files changed, 474 insertions(+), 702 deletions(-) diff --git a/src/svg/qsvggraphics.cpp b/src/svg/qsvggraphics.cpp index e09f382..2be7559 100644 --- a/src/svg/qsvggraphics.cpp +++ b/src/svg/qsvggraphics.cpp @@ -266,21 +266,23 @@ void QSvgRect::draw(QPainter *p, QSvgExtraStates &states) } } +QSvgTspan * const QSvgText::LINEBREAK = 0; + QSvgText::QSvgText(QSvgNode *parent, const QPointF &coord) : QSvgNode(parent) , m_coord(coord) - , m_textAlignment(Qt::AlignLeft) - , m_scale(1) - , m_appendSpace(false) , m_type(TEXT) , m_size(0, 0) + , m_mode(Default) { - m_paragraphs.push_back(QString()); - m_formatRanges.push_back(QList()); } QSvgText::~QSvgText() { + for (int i = 0; i < m_tspans.size(); ++i) { + if (m_tspans[i] != LINEBREAK) + delete m_tspans[i]; + } } void QSvgText::setTextArea(const QSizeF &size) @@ -295,175 +297,173 @@ void QSvgText::draw(QPainter *p, QSvgExtraStates &states) { applyStyle(p, states); - QSvgFontStyle *fontStyle = static_cast( - styleProperty(QSvgStyleProperty::FONT)); - if (fontStyle && fontStyle->svgFont()) { - // SVG fonts not fully supported... - QString text = m_paragraphs.front(); - for (int i = 1; i < m_paragraphs.size(); ++i) { - text.append(QLatin1Char('\n')); - text.append(m_paragraphs[i]); - } - fontStyle->svgFont()->draw(p, m_coord, text, fontStyle->pointSize(), m_textAlignment); - revertStyle(p, states); - return; - } + // Force the font to have a size of 100 pixels to avoid truncation problems + // when the font is very small. + qreal scale = 100.0 / p->font().pointSizeF(); + Qt::Alignment alignment = states.textAnchor; - // Scale the font to its correct size. QTransform oldTransform = p->worldTransform(); - p->scale(1 / m_scale, 1 / m_scale); + p->scale(1 / scale, 1 / scale); qreal y = 0; bool initial = true; - qreal px = m_coord.x() * m_scale; - qreal py = m_coord.y() * m_scale; - QSizeF scaledSize = m_size * m_scale; + qreal px = m_coord.x() * scale; + qreal py = m_coord.y() * scale; + QSizeF scaledSize = m_size * scale; if (m_type == TEXTAREA) { - if (m_textAlignment == Qt::AlignHCenter) + if (alignment == Qt::AlignHCenter) px += scaledSize.width() / 2; - else if (m_textAlignment == Qt::AlignRight) + else if (alignment == Qt::AlignRight) px += scaledSize.width(); } QRectF bounds; if (m_size.height() != 0) - bounds = QRectF(0, 0, 1, scaledSize.height()); - - for (int i = 0; i < m_paragraphs.size(); ++i) { - QTextLayout tl(m_paragraphs[i]); - QTextOption op = tl.textOption(); - op.setWrapMode(QTextOption::WrapAtWordBoundaryOrAnywhere); - tl.setTextOption(op); - tl.setAdditionalFormats(m_formatRanges[i]); - tl.beginLayout(); - forever { - QTextLine line = tl.createLine(); - if (!line.isValid()) - break; - - if (m_size.width() != 0) - line.setLineWidth(scaledSize.width()); - } - tl.endLayout(); - - bool endOfBoundsReached = false; - for (int i = 0; i < tl.lineCount(); ++i) { - QTextLine line = tl.lineAt(i); - - qreal x = 0; - if (m_textAlignment == Qt::AlignHCenter) - x -= line.naturalTextWidth() / 2; - else if (m_textAlignment == Qt::AlignRight) - x -= line.naturalTextWidth(); - - if (initial && m_type == TEXT) - y -= line.ascent(); - initial = false; - - line.setPosition(QPointF(x, y)); - if ((m_size.width() != 0 && line.naturalTextWidth() > scaledSize.width()) - || (m_size.height() != 0 && y + line.height() > scaledSize.height())) { - bounds.setHeight(y); - endOfBoundsReached = true; - break; + bounds = QRectF(0, py, 1, scaledSize.height()); // x and width are not used. + + bool appendSpace = false; + QVector paragraphs; + QStack formats; + QVector > formatRanges; + paragraphs.push_back(QString()); + formatRanges.push_back(QList()); + + for (int i = 0; i < m_tspans.size(); ++i) { + if (m_tspans[i] == LINEBREAK) { + if (m_type == TEXTAREA) { + if (paragraphs.back().isEmpty()) { + QFont font = p->font(); + font.setPixelSize(font.pointSizeF() * scale); + + QTextLayout::FormatRange range; + range.start = 0; + range.length = 1; + range.format.setFont(font); + formatRanges.back().append(range); + + paragraphs.back().append(QLatin1Char(' '));; + } + appendSpace = false; + paragraphs.push_back(QString()); + formatRanges.push_back(QList()); } + } else { + WhitespaceMode mode = m_tspans[i]->whitespaceMode(); + m_tspans[i]->applyStyle(p, states); - y += 1.1 * line.height(); - } - tl.draw(p, QPointF(px, py), QVector(), bounds); + QFont font = p->font(); + font.setPixelSize(font.pointSizeF() * scale); - if (endOfBoundsReached) - break; - } + QString newText(m_tspans[i]->text()); + newText.replace(QLatin1Char('\t'), QLatin1Char(' ')); + newText.replace(QLatin1Char('\n'), QLatin1Char(' ')); - p->setWorldTransform(oldTransform, false); - revertStyle(p, states); -} + bool prependSpace = !appendSpace && !m_tspans[i]->isTspan() && (mode == Default) && !paragraphs.back().isEmpty() && newText.startsWith(QLatin1Char(' ')); + if (appendSpace || prependSpace) + paragraphs.back().append(QLatin1Char(' ')); -void QSvgText::insertText(const QString &text, WhitespaceMode mode) -{ - bool isTSpan = (m_formats.count() == 2); - QString newText(text); - newText.replace(QLatin1Char('\t'), QLatin1Char(' ')); - newText.replace(QLatin1Char('\n'), QLatin1Char(' ')); + bool appendSpaceNext = (!m_tspans[i]->isTspan() && (mode == Default) && newText.endsWith(QLatin1Char(' '))); - bool prependSpace = !m_appendSpace && !isTSpan && (mode == Default) && !m_paragraphs.back().isEmpty() && newText.startsWith(QLatin1Char(' ')); - if (m_appendSpace || prependSpace) - m_paragraphs.back().append(QLatin1Char(' ')); + if (mode == Default) { + newText = newText.simplified(); + if (newText.isEmpty()) + appendSpaceNext = false; + } - bool appendSpaceNext = (!isTSpan && (mode == Default) && newText.endsWith(QLatin1Char(' '))); + QTextLayout::FormatRange range; + range.start = paragraphs.back().length(); + range.length = newText.length(); + range.format.setFont(font); + range.format.setTextOutline(p->pen()); + range.format.setForeground(p->brush()); + + if (appendSpace) { + Q_ASSERT(!formatRanges.back().isEmpty()); + ++formatRanges.back().back().length; + } else if (prependSpace) { + --range.start; + ++range.length; + } + formatRanges.back().append(range); - if (mode == Default) { - newText = newText.simplified(); - if (newText.isEmpty()) - appendSpaceNext = false; - } + appendSpace = appendSpaceNext; + paragraphs.back() += newText; - if (!m_formats.isEmpty()) { - QTextLayout::FormatRange range; - range.start = m_paragraphs.back().length(); - range.length = newText.length(); - range.format = m_formats.top(); - if (m_appendSpace) { - Q_ASSERT(!m_formatRanges.back().isEmpty()); - ++m_formatRanges.back().back().length; - } else if (prependSpace) { - --range.start; - ++range.length; + m_tspans[i]->revertStyle(p, states); } - m_formatRanges.back().append(range); } - m_appendSpace = appendSpaceNext; - m_paragraphs.back() += newText; -} - -void QSvgText::insertFormat(const QTextCharFormat &format) -{ - QTextCharFormat mergedFormat = format; - if (!m_formats.isEmpty()) { - mergedFormat = m_formats.top(); - mergedFormat.merge(format); - } - m_formats.push(mergedFormat); -} + if (states.svgFont) { + // SVG fonts not fully supported... + QString text = paragraphs.front(); + for (int i = 1; i < paragraphs.size(); ++i) { + text.append(QLatin1Char('\n')); + text.append(paragraphs[i]); + } + states.svgFont->draw(p, m_coord, text, p->font().pointSizeF() * scale, states.textAnchor); + } else { + for (int i = 0; i < paragraphs.size(); ++i) { + QTextLayout tl(paragraphs[i]); + QTextOption op = tl.textOption(); + op.setWrapMode(QTextOption::WrapAtWordBoundaryOrAnywhere); + tl.setTextOption(op); + tl.setAdditionalFormats(formatRanges[i]); + tl.beginLayout(); + + forever { + QTextLine line = tl.createLine(); + if (!line.isValid()) + break; + if (m_size.width() != 0) + line.setLineWidth(scaledSize.width()); + } + tl.endLayout(); + + bool endOfBoundsReached = false; + for (int i = 0; i < tl.lineCount(); ++i) { + QTextLine line = tl.lineAt(i); + + qreal x = 0; + if (alignment == Qt::AlignHCenter) + x -= 0.5 * line.naturalTextWidth(); + else if (alignment == Qt::AlignRight) + x -= line.naturalTextWidth(); + + if (initial && m_type == TEXT) + y -= line.ascent(); + initial = false; + + line.setPosition(QPointF(x, y)); + + // Check if the current line fits into the bounding rectangle. + if ((m_size.width() != 0 && line.naturalTextWidth() > scaledSize.width()) + || (m_size.height() != 0 && y + line.height() > scaledSize.height())) { + // I need to set the bounds height to 'y-epsilon' to avoid drawing the current + // line. Since the font is scaled to 100 units, 1 should be a safe epsilon. + bounds.setHeight(y - 1); + endOfBoundsReached = true; + break; + } + + y += 1.1 * line.height(); + } + tl.draw(p, QPointF(px, py), QVector(), bounds); -void QSvgText::insertLineBreak() -{ - if (m_type == TEXTAREA) { - if (m_paragraphs.back().isEmpty()) - insertText(QLatin1String(" "), Preserve); - m_appendSpace = false; - m_paragraphs.push_back(QString()); - m_formatRanges.push_back(QList()); + if (endOfBoundsReached) + break; + } } -} -void QSvgText::popFormat() -{ - if (m_formats.count() > 1) - m_formats.pop(); -} - -qreal QSvgText::scale() const -{ - return m_scale; -} - -void QSvgText::setScale(qreal scale) -{ - m_scale = scale; -} - -const QTextCharFormat &QSvgText::topFormat() const -{ - return m_formats.top(); + p->setWorldTransform(oldTransform, false); + revertStyle(p, states); } -void QSvgText::setTextAlignment(const Qt::Alignment &alignment) +void QSvgText::addText(const QString &text) { - m_textAlignment = alignment; + m_tspans.append(new QSvgTspan(this, false)); + m_tspans.back()->setWhitespaceMode(m_mode); + m_tspans.back()->addText(text); } QSvgUse::QSvgUse(const QPointF &start, QSvgNode *parent, QSvgNode *node) diff --git a/src/svg/qsvggraphics_p.h b/src/svg/qsvggraphics_p.h index 4a19c7e..345b90b 100644 --- a/src/svg/qsvggraphics_p.h +++ b/src/svg/qsvggraphics_p.h @@ -187,6 +187,8 @@ private: int m_rx, m_ry; }; +class QSvgTspan; + class QSvgText : public QSvgNode { public: @@ -202,26 +204,47 @@ public: virtual void draw(QPainter *p, QSvgExtraStates &states); virtual Type type() const; - void insertText(const QString &text, WhitespaceMode mode); - void insertFormat(const QTextCharFormat &format); - void insertLineBreak(); - void popFormat(); - void setTextAlignment(const Qt::Alignment &alignment); - const QTextCharFormat &topFormat() const; - qreal scale() const; - void setScale(qreal scale); + + void addTspan(QSvgTspan *tspan) {m_tspans.append(tspan);} + void addText(const QString &text); + void addLineBreak() {m_tspans.append(LINEBREAK);} + void setWhitespaceMode(WhitespaceMode mode) {m_mode = mode;} + //virtual QRectF bounds() const; private: + static QSvgTspan * const LINEBREAK; + QPointF m_coord; - QVector m_paragraphs; - QStack m_formats; - Qt::Alignment m_textAlignment; - QVector > m_formatRanges; - qreal m_scale; - bool m_appendSpace; + // 'm_tspans' is also used to store characters outside tspans and line breaks. + // If a 'm_tspan' item is null, it indicates a line break. + QVector m_tspans; + Type m_type; QSizeF m_size; + WhitespaceMode m_mode; +}; + +class QSvgTspan : public QSvgNode +{ +public: + // tspans are also used to store normal text, so the 'isProperTspan' is used to separate text from tspan. + QSvgTspan(QSvgNode *parent, bool isProperTspan = true) + : QSvgNode(parent), m_mode(QSvgText::Default), m_isTspan(isProperTspan) + { + } + ~QSvgTspan() { }; + virtual Type type() const {return TSPAN;} + virtual void draw(QPainter *, QSvgExtraStates &) {Q_ASSERT(!"Tspans should be drawn through QSvgText::draw().");} + void addText(const QString &text) {m_text += text;} + const QString &text() const {return m_text;} + bool isTspan() const {return m_isTspan;} + void setWhitespaceMode(QSvgText::WhitespaceMode mode) {m_mode = mode;} + QSvgText::WhitespaceMode whitespaceMode() const {return m_mode;} +private: + QString m_text; + QSvgText::WhitespaceMode m_mode; + bool m_isTspan; }; class QSvgUse : public QSvgNode diff --git a/src/svg/qsvghandler.cpp b/src/svg/qsvghandler.cpp index b829a22..73c8b01 100644 --- a/src/svg/qsvghandler.cpp +++ b/src/svg/qsvghandler.cpp @@ -70,6 +70,8 @@ QT_BEGIN_NAMESPACE +static const char *qt_inherit_text = "inherit"; +#define QT_INHERIT QLatin1String(qt_inherit_text) double qstrtod(const char *s00, char const **se, bool *ok); @@ -492,7 +494,7 @@ static bool resolveColor(const QString &colorStr, QColor &color, QSvgHandler *ha int(compo[2])); return true; } else if (colorStr == QLatin1String("inherited") || - colorStr == QLatin1String("inherit")) { + colorStr == QT_INHERIT) { return false; } else if (colorStr == QLatin1String("currentColor")) { color = handler->currentColor(); @@ -646,204 +648,47 @@ static void parseBrush(QSvgNode *node, QString opacity = attributes.value(QLatin1String("fill-opacity")).toString(); QString myId = someId(attributes); - QSvgFillStyle *prop = new QSvgFillStyle(0); + if (!value.isEmpty() || !fillRule.isEmpty() || !opacity.isEmpty()) { + QSvgFillStyle *prop = new QSvgFillStyle(0); - //fill-rule attribute handling - if (!fillRule.isEmpty() && fillRule != QLatin1String("inherit")) { - if (fillRule == QLatin1String("evenodd")) - prop->setFillRule(Qt::OddEvenFill); - else if (fillRule == QLatin1String("nonzero")) - prop->setFillRule(Qt::WindingFill); - } - - //fill-opacity atttribute handling - if (!opacity.isEmpty() && opacity != QLatin1String("inherit")) { - prop->setFillOpacity(qMin(qreal(1.0), qMax(qreal(0.0), toDouble(opacity)))); - } - - //fill attribute handling - if ((!value.isEmpty()) && (value != QLatin1String("inherit")) ) { - if (value.startsWith(QLatin1String("url"))) { - value = value.remove(0, 3); - QSvgStyleProperty *style = styleFromUrl(node, value); - if (style) { - prop->setFillStyle(style); - } else { - QString id = idFromUrl(value); - prop->setGradientId(id); - prop->setGradientResolved(false); - } - } else if (value != QLatin1String("none")) { - QColor color; - if (resolveColor(value, color, handler)) - prop->setBrush(QBrush(color)); - } else { - prop->setBrush(QBrush(Qt::NoBrush)); + //fill-rule attribute handling + if (!fillRule.isEmpty() && fillRule != QT_INHERIT) { + if (fillRule == QLatin1String("evenodd")) + prop->setFillRule(Qt::OddEvenFill); + else if (fillRule == QLatin1String("nonzero")) + prop->setFillRule(Qt::WindingFill); } - } - node->appendStyleProperty(prop,myId); -} - - -static void parseQPen(QPen &pen, QSvgNode *node, - const QSvgAttributes &attributes, - QSvgHandler *handler) -{ - QString value = attributes.value(QLatin1String("stroke")).toString(); - QString dashArray = attributes.value(QLatin1String("stroke-dasharray")).toString(); - QString dashOffset = attributes.value(QLatin1String("stroke-dashoffset")).toString(); - QString linecap = attributes.value(QLatin1String("stroke-linecap")).toString(); - QString linejoin = attributes.value(QLatin1String("stroke-linejoin")).toString(); - QString miterlimit = attributes.value(QLatin1String("stroke-miterlimit")).toString(); - QString opacity = attributes.value(QLatin1String("stroke-opacity")).toString(); - QString width = attributes.value(QLatin1String("stroke-width")).toString(); - QString vectorEffect = attributes.value(QLatin1String("vector-effect")).toString(); - QString myId = someId(attributes); - QSvgStrokeStyle *inherited = - static_cast(node->parent()->styleProperty( - QSvgStyleProperty::STROKE)); - - bool stroke = false; - if (inherited) { - pen = inherited->qpen(); - stroke = inherited->strokePresent(); - } else { - pen = handler->defaultPen(); - } + //fill-opacity atttribute handling + if (!opacity.isEmpty() && opacity != QT_INHERIT) { + prop->setFillOpacity(qMin(qreal(1.0), qMax(qreal(0.0), toDouble(opacity)))); + } - // stroke-opacity attribute handling - qreal strokeAlpha; - if (!opacity.isEmpty() && opacity != QLatin1String("inherit")) { - strokeAlpha = qMin(qreal(1.0), qMax(qreal(0.0), toDouble(opacity))); - } else { - strokeAlpha = pen.color().alphaF(); - } - - //stroke attribute handling - if (!value.isEmpty() && value != QLatin1String("inherit")) { - if (value.startsWith(QLatin1String("url"))) { - value = value.remove(0, 3); - QSvgStyleProperty *style = styleFromUrl(node, value); - if (style) { - if (style->type() == QSvgStyleProperty::GRADIENT) { - QBrush b(*((QSvgGradientStyle*)style)->qgradient()); - pen.setBrush(b); - } else if (style->type() == QSvgStyleProperty::SOLID_COLOR) { - pen.setColor(((QSvgSolidColorStyle*)style)->qcolor()); + //fill attribute handling + if ((!value.isEmpty()) && (value != QT_INHERIT) ) { + if (value.startsWith(QLatin1String("url"))) { + value = value.remove(0, 3); + QSvgStyleProperty *style = styleFromUrl(node, value); + if (style) { + prop->setFillStyle(style); + } else { + QString id = idFromUrl(value); + prop->setGradientId(id); + prop->setGradientResolved(false); } - stroke = true; + } else if (value != QLatin1String("none")) { + QColor color; + if (resolveColor(value, color, handler)) + prop->setBrush(QBrush(color)); } else { - qWarning() << "QSvgHandler::parsePen could not resolve property" << idFromUrl(value); - } - } else if (value == QLatin1String("none")) { - QColor color; - color.setAlphaF(strokeAlpha); - pen.setColor(color); - stroke = false; - } else { - QColor color; - if (resolveColor(value, color, handler)) { - color.setAlphaF(strokeAlpha); - pen.setColor(color); + prop->setBrush(QBrush(Qt::NoBrush)); } - stroke = true; } - } else { - QColor color = pen.color(); - color.setAlphaF(strokeAlpha); - pen.setColor(color); - } - - //stroke-width handling - if (!width.isEmpty() && width != QLatin1String("inherit")) { - qreal widthF; - QSvgHandler::LengthType lt; - widthF = parseLength(width, lt, handler); - pen.setWidthF(widthF); - } - - //stroke-linejoin attribute handling - if (!linejoin.isEmpty()) { - if (linejoin == QLatin1String("miter")) - pen.setJoinStyle(Qt::SvgMiterJoin); - else if (linejoin == QLatin1String("round")) - pen.setJoinStyle(Qt::RoundJoin); - else if (linejoin == QLatin1String("bevel")) - pen.setJoinStyle(Qt::BevelJoin); - } - - //stroke-linecap attribute handling - if (!linecap.isEmpty()) { - if (linecap == QLatin1String("butt")) - pen.setCapStyle(Qt::FlatCap); - else if (linecap == QLatin1String("round")) - pen.setCapStyle(Qt::RoundCap); - else if (linecap == QLatin1String("square")) - pen.setCapStyle(Qt::SquareCap); - } - - //strok-dasharray attribute handling - qreal penw = pen.widthF(); - if (!dashArray.isEmpty() && dashArray != QLatin1String("inherit")) { - const QChar *s = dashArray.constData(); - QVector dashes = parseNumbersList(s); - qreal *d = dashes.data(); - if (penw != 0) - for (int i = 0; i < dashes.size(); ++i) { - *d /= penw; - ++d; - } - // if the dash count is odd the dashes should be duplicated - if (dashes.size() % 2 != 0) - dashes << QVector(dashes); - pen.setDashPattern(dashes); - } else if (inherited) { - QVector dashes(inherited->qpen().dashPattern()); - qreal *d = dashes.data(); - if (!penw) - penw = 1.0; - qreal inheritpenw = inherited->qpen().widthF(); - if (!inheritpenw) - inheritpenw = 1.0; - for ( int i = 0; i < dashes.size(); ++i) { - *d *= (inheritpenw/ penw); - ++d; - } - pen.setDashPattern(dashes); - } - - //stroke-dashoffset attribute handling - if (!dashOffset.isEmpty() && dashOffset != QLatin1String("inherit")) { - qreal doffset = toDouble(dashOffset); - if (penw != 0) - doffset /= penw; - pen.setDashOffset(doffset); - } else if (inherited) { - qreal doffset = pen.dashOffset(); - if (!penw) - penw = 1.0; - qreal inheritpenw = inherited->qpen().widthF(); - if (!inheritpenw) - inheritpenw = 1.0; - doffset *= (inheritpenw / penw); - pen.setDashOffset(doffset); - } - - //vector-effect attribute handling - if (!vectorEffect.isEmpty()) { - if (vectorEffect == QLatin1String("non-scaling-stroke")) - pen.setCosmetic(true); - else if (vectorEffect == QLatin1String("none")) - pen.setCosmetic(false); + node->appendStyleProperty(prop, myId); } +} - if (!miterlimit.isEmpty() && miterlimit != QLatin1String("inherit")) - pen.setMiterLimit(toDouble(miterlimit)); - if (!stroke) - pen.setStyle(Qt::NoPen); -} static QMatrix parseTransformationMatrix(const QString &value) { @@ -1006,14 +851,14 @@ static void parsePen(QSvgNode *node, // stroke-opacity attribute handling qreal strokeAlpha; - if (!opacity.isEmpty() && opacity != QLatin1String("inherit")) { + if (!opacity.isEmpty() && opacity != QT_INHERIT) { strokeAlpha = qMin(qreal(1.0), qMax(qreal(0.0), toDouble(opacity))); } else { strokeAlpha = pen.color().alphaF(); } //stroke attribute handling - if (!value.isEmpty() && value != QLatin1String("inherit")) { + if (!value.isEmpty() && value != QT_INHERIT) { if (value.startsWith(QLatin1String("url"))) { value = value.remove(0, 3); QSvgStyleProperty *style = styleFromUrl(node, value); @@ -1049,7 +894,7 @@ static void parsePen(QSvgNode *node, } //stroke-width handling - if (!width.isEmpty() && width != QLatin1String("inherit")) { + if (!width.isEmpty() && width != QT_INHERIT) { qreal widthF; QSvgHandler::LengthType lt; widthF = parseLength(width, lt, handler); @@ -1078,7 +923,7 @@ static void parsePen(QSvgNode *node, //strok-dasharray attribute handling qreal penw = pen.widthF(); - if (!dashArray.isEmpty() && dashArray != QLatin1String("inherit")) { + if (!dashArray.isEmpty() && dashArray != QT_INHERIT) { const QChar *s = dashArray.constData(); QVector dashes = parseNumbersList(s); qreal *d = dashes.data(); @@ -1108,7 +953,7 @@ static void parsePen(QSvgNode *node, //stroke-dashoffset attribute handling - if (!dashOffset.isEmpty() && dashOffset != QLatin1String("inherit")) { + if (!dashOffset.isEmpty() && dashOffset != QT_INHERIT) { qreal doffset = toDouble(dashOffset); if (penw != 0) doffset /= penw; @@ -1132,7 +977,7 @@ static void parsePen(QSvgNode *node, pen.setCosmetic(false); } - if (!miterlimit.isEmpty() && miterlimit != QLatin1String("inherit")) + if (!miterlimit.isEmpty() && miterlimit != QT_INHERIT) pen.setMiterLimit(toDouble(miterlimit)); QSvgStrokeStyle *prop = new QSvgStrokeStyle(pen); @@ -1141,182 +986,84 @@ static void parsePen(QSvgNode *node, } } - -static bool parseQBrush(const QSvgAttributes &attributes, QSvgNode *node, - QBrush &brush, QSvgHandler *handler) -{ - QString value = attributes.value(QLatin1String("fill")).toString(); - QString opacity = attributes.value(QLatin1String("fill-opacity")).toString(); - - QColor color; - if (!value.isEmpty() || !opacity.isEmpty()) { - if (value.startsWith(QLatin1String("url"))) { - value = value.remove(0, 3); - QSvgStyleProperty *style = styleFromUrl(node, value); - if (style) { - switch (style->type()) { - case QSvgStyleProperty::FILL: - { - brush = static_cast(style)->qbrush(); - break; - } - case QSvgStyleProperty::SOLID_COLOR: - { - brush = QBrush(static_cast(style)->qcolor()); - break; - } - case QSvgStyleProperty::GRADIENT: - { - brush = QBrush(*static_cast(style)->qgradient()); - break; - } - default: - qWarning("Cannot use property \"%s\" as brush.", qPrintable(idFromUrl(value))); - } - } else { - qWarning("Couldn't resolve property: %s", qPrintable(idFromUrl(value))); - } - } else if (value != QLatin1String("none")) { - if (constructColor(value, opacity, color, handler)) { - brush.setStyle(Qt::SolidPattern); - brush.setColor(color); - } - } else { - brush = QBrush(Qt::NoBrush); - } - return true; - } - return false; -} - -static bool parseQFont(const QSvgAttributes &attributes, - QFont &font, qreal &fontSize, QSvgHandler *handler) +static void parseFont(QSvgNode *node, + const QSvgAttributes &attributes, + QSvgHandler *handler) { QString family = attributes.value(QLatin1String("font-family")).toString(); QString size = attributes.value(QLatin1String("font-size")).toString(); QString style = attributes.value(QLatin1String("font-style")).toString(); QString weight = attributes.value(QLatin1String("font-weight")).toString(); + QString variant = attributes.value(QLatin1String("font-variant")).toString(); + QString anchor = attributes.value(QLatin1String("text-anchor")).toString(); - if (!family.isEmpty() || !size.isEmpty() || - !style.isEmpty() || !weight.isEmpty()) { + if (family.isEmpty() && size.isEmpty() && style.isEmpty() && weight.isEmpty() && variant.isEmpty() && anchor.isEmpty()) + return; - if (!family.isEmpty()) { - font.setFamily(family.trimmed()); - } - if (!size.isEmpty()) { - if (size == QLatin1String("inherit")) { - //inherited already - } else { - QSvgHandler::LengthType dummy; // should always be pixel size - fontSize = parseLength(size, dummy, handler); - if (fontSize <= 0) - fontSize = 1; - } - font.setPixelSize(qMax(1, int(fontSize))); - } - if (!style.isEmpty()) { - if (style == QLatin1String("normal")) { - font.setStyle(QFont::StyleNormal); - } else if (style == QLatin1String("italic")) { - font.setStyle(QFont::StyleItalic); - } else if (style == QLatin1String("oblique")) { - font.setStyle(QFont::StyleOblique); - } else if (style == QLatin1String("inherit")) { - //inherited already - } - } - if (!weight.isEmpty()) { - bool ok = false; - int weightNum = weight.toInt(&ok); - if (ok) { - switch (weightNum) { - case 100: - case 200: - font.setWeight(QFont::Light); - break; - case 300: - case 400: - font.setWeight(QFont::Normal); - break; - case 500: - case 600: - font.setWeight(QFont::DemiBold); - break; - case 700: - case 800: - font.setWeight(QFont::Bold); - break; - case 900: - font.setWeight(QFont::Black); - break; - default: - break; - } - } else { - if (weight == QLatin1String("normal")) { - font.setWeight(QFont::Normal); - } else if (weight == QLatin1String("bold")) { - font.setWeight(QFont::Bold); - } else if (weight == QLatin1String("bolder")) { - font.setWeight(QFont::DemiBold); - } else if (weight == QLatin1String("lighter")) { - font.setWeight(QFont::Light); - } - } - } - // QFontInfo fi(font); - // font.setPointSize(fi.pointSize()); - return true; + QString id = someId(attributes); + QSvgTinyDocument *doc = node->document(); + QSvgFontStyle *fontStyle = 0; + if (!family.isEmpty()) { + QSvgFont *svgFont = doc->svgFont(family); + if (svgFont) + fontStyle = new QSvgFontStyle(svgFont, doc); } + if (!fontStyle) + fontStyle = new QSvgFontStyle; - return false; -} + if (!family.isEmpty() && family != QT_INHERIT) + fontStyle->setFamily(family.trimmed()); -static void parseFont(QSvgNode *node, - const QSvgAttributes &attributes, - QSvgHandler *handler) -{ - QFont font; - font.setPixelSize(12); - qreal fontSize = font.pixelSize(); - - QSvgFontStyle *inherited = - static_cast(node->styleProperty( - QSvgStyleProperty::FONT)); - if (!inherited) - inherited = - static_cast(node->parent()->styleProperty( - QSvgStyleProperty::FONT)); - if (inherited) { - font = inherited->qfont(); - fontSize = inherited->pointSize(); - } - // group or any container element can have only text-anchor and should - // be processed, because its children can inherit from it. - // So checking for text-anchor before parseQfont() - QString anchor = attributes.value(QLatin1String("text-anchor")).toString(); - if (parseQFont(attributes, font, fontSize, handler) || (!anchor.isEmpty())) { - QString myId = someId(attributes); - //QString anchor = attributes.value(QLatin1String("text-anchor")).toString(); - QSvgTinyDocument *doc = node->document(); - QSvgFontStyle *fontStyle = 0; - QString family = (font.family().isEmpty())?myId:font.family(); - if (!family.isEmpty()) { - QSvgFont *svgFont = doc->svgFont(family); - if (svgFont) { - fontStyle = new QSvgFontStyle(svgFont, doc); - fontStyle->setPointSize(fontSize); - } + if (!size.isEmpty() && size != QT_INHERIT) { + QSvgHandler::LengthType dummy; // should always be pixel size + fontStyle->setSize(parseLength(size, dummy, handler)); + } + + if (!style.isEmpty() && style != QT_INHERIT) { + if (style == QLatin1String("normal")) { + fontStyle->setStyle(QFont::StyleNormal); + } else if (style == QLatin1String("italic")) { + fontStyle->setStyle(QFont::StyleItalic); + } else if (style == QLatin1String("oblique")) { + fontStyle->setStyle(QFont::StyleOblique); } - if (!fontStyle) { - fontStyle = new QSvgFontStyle(font, node->document()); - fontStyle->setPointSize(fontSize); + } + + if (!weight.isEmpty() && weight != QT_INHERIT) { + bool ok = false; + int weightNum = weight.toInt(&ok); + if (ok) { + fontStyle->setWeight(weightNum); + } else { + if (weight == QLatin1String("normal")) { + fontStyle->setWeight(400); + } else if (weight == QLatin1String("bold")) { + fontStyle->setWeight(700); + } else if (weight == QLatin1String("bolder")) { + fontStyle->setWeight(QSvgFontStyle::BOLDER); + } else if (weight == QLatin1String("lighter")) { + fontStyle->setWeight(QSvgFontStyle::LIGHTER); + } } - if (!anchor.isEmpty()) - fontStyle->setTextAnchor(anchor); + } - node->appendStyleProperty(fontStyle, myId); + if (!variant.isEmpty() && variant != QT_INHERIT) { + if (variant == QLatin1String("normal")) + fontStyle->setVariant(QFont::MixedCase); + else if (variant == QLatin1String("small-caps")) + fontStyle->setVariant(QFont::SmallCaps); + } + + if (!anchor.isEmpty() && anchor != QT_INHERIT) { + if (anchor == QLatin1String("start")) + fontStyle->setTextAnchor(Qt::AlignLeft); + if (anchor == QLatin1String("middle")) + fontStyle->setTextAnchor(Qt::AlignHCenter); + else if (anchor == QLatin1String("end")) + fontStyle->setTextAnchor(Qt::AlignRight); } + + node->appendStyleProperty(fontStyle, id); } static void parseTransform(QSvgNode *node, @@ -1343,7 +1090,7 @@ static void parseVisibility(QSvgNode *node, QString value = attributes.value(QLatin1String("visibility")).toString(); QSvgNode *parent = node->parent(); - if (parent && (value.isEmpty() || value == QLatin1String("inherit"))) + if (parent && (value.isEmpty() || value == QT_INHERIT)) node->setVisible(parent->isVisible()); else if (value == QLatin1String("hidden") || value == QLatin1String("collapse")) { node->setVisible(false); @@ -1954,105 +1701,6 @@ static void cssStyleLookup(QSvgNode *node, parseStyle(node, attributes, handler); } -static bool parseDefaultTextStyle(QSvgNode *node, - const QXmlStreamAttributes &attributes, - bool initial, - QSvgHandler *handler) -{ - Q_ASSERT(node->type() == QSvgText::TEXT || node->type() == QSvgNode::TEXTAREA); - QSvgText *textNode = static_cast(node); - - QSvgAttributes attrs(attributes, handler); - - QString fontFamily = attrs.value(QString(), QLatin1String("font-family")).toString(); - - QString anchor = attrs.value(QString(), QLatin1String("text-anchor")).toString(); - - QSvgFontStyle *fontStyle = static_cast( - node->styleProperty(QSvgStyleProperty::FONT)); - if (fontStyle) { - QSvgTinyDocument *doc = fontStyle->doc(); - if (doc && fontStyle->svgFont()) { - cssStyleLookup(node, handler, handler->selector()); - parseStyle(node, attrs, handler); - return true; - } - } else if (!fontFamily.isEmpty()) { - QSvgTinyDocument *doc = node->document(); - QSvgFont *svgFont = doc->svgFont(fontFamily); - if (svgFont) { - cssStyleLookup(node, handler, handler->selector()); - parseStyle(node, attrs, handler); - return true; - } - } - - QTextCharFormat format; - QBrush brush(QColor(0, 0, 0)); - QFont font; - font.setPixelSize(12); - qreal fontSize = font.pixelSize(); - - if (!initial) { - font = textNode->topFormat().font(); - fontSize = font.pixelSize() / textNode->scale(); - brush = textNode->topFormat().foreground(); - } else { - QSvgFontStyle *fontStyle = static_cast( - node->styleProperty(QSvgStyleProperty::FONT)); - if (!fontStyle) - fontStyle = static_cast( - node->parent()->styleProperty(QSvgStyleProperty::FONT)); - if (fontStyle) { - font = fontStyle->qfont(); - fontSize = fontStyle->pointSize(); - if (anchor.isEmpty() || anchor == QLatin1String("inherit")) - anchor = fontStyle->textAnchor(); - } - - Qt::Alignment align = Qt::AlignLeft; - if (anchor == QLatin1String("middle")) - align = Qt::AlignHCenter; - else if (anchor == QLatin1String("end")) - align = Qt::AlignRight; - textNode->setTextAlignment(align); - - QSvgFillStyle *fillStyle = static_cast( - node->styleProperty(QSvgStyleProperty::FILL)); - if (fillStyle) - brush = fillStyle->qbrush(); - } - - if (parseQFont(attrs, font, fontSize, handler) || initial) { - if (initial) - textNode->setScale(100 / fontSize); - font.setPixelSize(qMax(1, int(fontSize * textNode->scale()))); - format.setFont(font); - } - - if (parseQBrush(attrs, node, brush, handler) || initial) { - if (brush.style() != Qt::NoBrush || initial) - format.setForeground(brush); - } - - QPen pen(Qt::NoPen); -// QSvgStrokeStyle *inherited = -// static_cast(node->parent()->styleProperty( -// QSvgStyleProperty::STROKE)); -// if (inherited) -// pen = inherited->qpen(); - parseQPen(pen, node, attrs, handler); - if (pen.style() != Qt::NoPen) { - format.setTextOutline(pen); - } - - parseTransform(node, attrs, handler); - - textNode->insertFormat(format); - - return true; -} - static inline QStringList stringToList(const QString &str) { QStringList lst = str.split(QLatin1Char(','), QString::SkipEmptyParts); @@ -2211,7 +1859,7 @@ static inline QSvgNode::DisplayMode displayStringToEnum(const QString &str) return QSvgNode::TableCaptionMode; } else if (str == QLatin1String("none")) { return QSvgNode::NoneMode; - } else if (str == QLatin1String("inherit")) { + } else if (str == QT_INHERIT) { return QSvgNode::InheritMode; } return QSvgNode::BlockMode; @@ -3175,7 +2823,6 @@ static QSvgNode *createSvgNode(QSvgNode *parent, node->setHeight(int(height), type == QSvgHandler::LT_PERCENT); } - if (!viewBoxStr.isEmpty()) { QStringList lst = viewBoxStr.split(QLatin1Char(' '), QString::SkipEmptyParts); if (lst.count() != 4) @@ -3225,7 +2872,7 @@ static bool parseTbreakNode(QSvgNode *parent, { if (parent->type() != QSvgNode::TEXTAREA) return false; - static_cast(parent)->insertLineBreak(); + static_cast(parent)->addLineBreak(); return true; } @@ -3240,12 +2887,6 @@ static QSvgNode *createTextNode(QSvgNode *parent, qreal nx = parseLength(x, type, handler); qreal ny = parseLength(y, type, handler); - //### not to pixels but to the default coordinate system - // and text should be already in the correct coordinate - // system here - //nx = convertToPixels(nx, true, type); - //ny = convertToPixels(ny, true, type); - QSvgNode *text = new QSvgText(parent, QPointF(nx, ny)); return text; } @@ -3264,6 +2905,13 @@ static QSvgNode *createTextAreaNode(QSvgNode *parent, return node; } +static QSvgNode *createTspanNode(QSvgNode *parent, + const QXmlStreamAttributes &, + QSvgHandler *) +{ + return new QSvgTspan(parent); +} + static bool parseTitleNode(QSvgNode *parent, const QXmlStreamAttributes &attributes, QSvgHandler *) @@ -3272,15 +2920,6 @@ static bool parseTitleNode(QSvgNode *parent, return true; } -static bool parseTspanNode(QSvgNode *parent, - const QXmlStreamAttributes &attributes, - QSvgHandler *handler) -{ - - cssStyleLookup(parent, handler, handler->selector()); - return parseDefaultTextStyle(parent, attributes, false, handler); -} - static QSvgNode *createUseNode(QSvgNode *parent, const QXmlStreamAttributes &attributes, QSvgHandler *handler) @@ -3394,6 +3033,7 @@ static FactoryMethod findGraphicsFactory(const QString &name) case 't': if (ref == QLatin1String("ext")) return createTextNode; if (ref == QLatin1String("extArea")) return createTextAreaNode; + if (ref == QLatin1String("span")) return createTspanNode; break; case 'u': if (ref == QLatin1String("se")) return createUseNode; @@ -3450,7 +3090,6 @@ static ParseMethod findUtilFactory(const QString &name) case 't': if (ref == QLatin1String("break")) return parseTbreakNode; if (ref == QLatin1String("itle")) return parseTitleNode; - if (ref == QLatin1String("span")) return parseTspanNode; break; default: break; @@ -3659,16 +3298,33 @@ bool QSvgHandler::startElement(const QString &localName, group->addChild(node, someId(attributes)); } break; + case QSvgNode::TEXT: + case QSvgNode::TEXTAREA: + if (node->type() == QSvgNode::TSPAN) { + static_cast(m_nodes.top())->addTspan(static_cast(node)); + } else { + qWarning("\'text\' or \'textArea\' element contains invalid element type."); + delete node; + node = 0; + } + break; default: - Q_ASSERT(!"not a grouping element is the parent"); + qWarning("Could not add child element to parent element because the types are incorrect."); + delete node; + node = 0; + break; } - parseCoreNode(node, attributes); - cssStyleLookup(node, this, m_selector); - if (node->type() != QSvgNode::TEXT && node->type() != QSvgNode::TEXTAREA) + if (node) { + parseCoreNode(node, attributes); + cssStyleLookup(node, this, m_selector); parseStyle(node, attributes, this); - else - parseDefaultTextStyle(node, attributes, true, this); + if (node->type() == QSvgNode::TEXT || node->type() == QSvgNode::TEXTAREA) { + static_cast(node)->setWhitespaceMode(m_whitespaceMode.top()); + } else if (node->type() == QSvgNode::TSPAN) { + static_cast(node)->setWhitespaceMode(m_whitespaceMode.top()); + } + } } } else if (ParseMethod method = findUtilFactory(localName)) { Q_ASSERT(!m_nodes.isEmpty()); @@ -3725,13 +3381,8 @@ bool QSvgHandler::endElement(const QStringRef &localName) return true; } - if (m_inStyle && localName == QLatin1String("style")) { + if (m_inStyle && localName == QLatin1String("style")) m_inStyle = false; - } else if (m_nodes.top()->type() == QSvgNode::TEXT || m_nodes.top()->type() == QSvgNode::TEXTAREA) { - QSvgText *node = static_cast(m_nodes.top()); - if (localName == QLatin1String("tspan")) - node->popFormat(); - } if (node == Graphics) { // Iterate through the m_renderers to resolve any unresolved gradients. @@ -3779,8 +3430,9 @@ bool QSvgHandler::characters(const QStringRef &str) return true; if (m_nodes.top()->type() == QSvgNode::TEXT || m_nodes.top()->type() == QSvgNode::TEXTAREA) { - QSvgText *node = static_cast(m_nodes.top()); - node->insertText(str.toString(), m_whitespaceMode.top()); + static_cast(m_nodes.top())->addText(str.toString()); + } else if (m_nodes.top()->type() == QSvgNode::TSPAN) { + static_cast(m_nodes.top())->addText(str.toString()); } return true; diff --git a/src/svg/qsvgnode_p.h b/src/svg/qsvgnode_p.h index f203ea7..315f228 100644 --- a/src/svg/qsvgnode_p.h +++ b/src/svg/qsvgnode_p.h @@ -86,6 +86,7 @@ public: RECT, TEXT, TEXTAREA, + TSPAN, USE, VIDEO }; diff --git a/src/svg/qsvgstyle.cpp b/src/svg/qsvgstyle.cpp index c3c0a68..3682f47 100644 --- a/src/svg/qsvgstyle.cpp +++ b/src/svg/qsvgstyle.cpp @@ -59,6 +59,9 @@ QT_BEGIN_NAMESPACE QSvgExtraStates::QSvgExtraStates() : fillOpacity(1.0) + , svgFont(0) + , textAnchor(Qt::AlignLeft) + , fontWeight(400) { } @@ -191,39 +194,94 @@ void QSvgViewportFillStyle::revert(QPainter *p, QSvgExtraStates &) } QSvgFontStyle::QSvgFontStyle(QSvgFont *font, QSvgTinyDocument *doc) - : m_font(font), m_pointSize(24), m_doc(doc) -{ -} - -QSvgFontStyle::QSvgFontStyle(const QFont &font, QSvgTinyDocument *doc) - : m_font(0), m_pointSize(24), m_doc(doc), m_qfont(font) -{ -} - - -void QSvgFontStyle::setPointSize(qreal size) -{ - m_pointSize = size; -} - -qreal QSvgFontStyle::pointSize() const -{ - return m_pointSize; -} - -void QSvgFontStyle::apply(QPainter *p, const QRectF &, QSvgNode *, QSvgExtraStates &) -{ - if (!m_font) { - m_oldFont = p->font(); - p->setFont(m_qfont); + : m_svgFont(font) + , m_doc(doc) + , m_familySet(0) + , m_sizeSet(0) + , m_styleSet(0) + , m_variantSet(0) + , m_weightSet(0) + , m_textAnchorSet(0) +{ +} + +QSvgFontStyle::QSvgFontStyle() + : m_doc(0) + , m_svgFont(0) + , m_familySet(0) + , m_sizeSet(0) + , m_styleSet(0) + , m_variantSet(0) + , m_weightSet(0) + , m_textAnchorSet(0) +{ +} + +int QSvgFontStyle::SVGToQtWeight(int weight) { + switch (weight) { + case 100: + case 200: + return QFont::Light; + case 300: + case 400: + return QFont::Normal; + case 500: + case 600: + return QFont::DemiBold; + case 700: + case 800: + return QFont::Bold; + case 900: + return QFont::Black; + } + return QFont::Normal; +} + +void QSvgFontStyle::apply(QPainter *p, const QRectF &, QSvgNode *, QSvgExtraStates &states) +{ + m_oldQFont = p->font(); + m_oldSvgFont = states.svgFont; + m_oldTextAnchor = states.textAnchor; + m_oldWeight = states.fontWeight; + + if (m_textAnchorSet) + states.textAnchor = m_textAnchor; + + QFont font = m_oldQFont; + if (m_familySet) { + states.svgFont = m_svgFont; + font.setFamily(m_qfont.family()); + } + + if (m_sizeSet) + font.setPointSize(m_qfont.pointSizeF()); + + if (m_styleSet) + font.setStyle(m_qfont.style()); + + if (m_variantSet) + font.setCapitalization(m_qfont.capitalization()); + + if (m_weightSet) { + if (m_weight == BOLDER) { + states.fontWeight = qMin(states.fontWeight + 100, 900); + } else if (m_weight == LIGHTER) { + states.fontWeight = qMax(states.fontWeight - 100, 100); + } else { + states.fontWeight = m_weight; + } + font.setWeight(SVGToQtWeight(states.fontWeight)); } + + p->setFont(font); } -void QSvgFontStyle::revert(QPainter *p, QSvgExtraStates &) +void QSvgFontStyle::revert(QPainter *p, QSvgExtraStates &states) { - if (!m_font) { - p->setFont(m_oldFont); - } + p->setFont(m_oldQFont); + states.svgFont = m_oldSvgFont; + states.textAnchor = m_oldTextAnchor; + states.fontWeight = m_oldWeight; } QSvgStrokeStyle::QSvgStrokeStyle(const QPen &pen) @@ -799,16 +857,6 @@ QSvgStyleProperty::Type QSvgAnimateColor::type() const return ANIMATE_COLOR; } -QString QSvgFontStyle::textAnchor() const -{ - return m_textAnchor; -} - -void QSvgFontStyle::setTextAnchor(const QString &anchor) -{ - m_textAnchor = anchor; -} - QSvgOpacityStyle::QSvgOpacityStyle(qreal opacity) : m_opacity(opacity) { diff --git a/src/svg/qsvgstyle_p.h b/src/svg/qsvgstyle_p.h index 70ecf5b..bd28bb6 100644 --- a/src/svg/qsvgstyle_p.h +++ b/src/svg/qsvgstyle_p.h @@ -141,7 +141,11 @@ private: struct QSvgExtraStates { QSvgExtraStates(); + qreal fillOpacity; + QSvgFont *svgFont; + Qt::Alignment textAnchor; + int fontWeight; }; class QSvgStyleProperty : public QSvgRefCounted @@ -307,41 +311,85 @@ private: class QSvgFontStyle : public QSvgStyleProperty { public: + static const int LIGHTER = -1; + static const int BOLDER = 1; + QSvgFontStyle(QSvgFont *font, QSvgTinyDocument *doc); - QSvgFontStyle(const QFont &font, QSvgTinyDocument *doc); + QSvgFontStyle(); virtual void apply(QPainter *p, const QRectF &, QSvgNode *node, QSvgExtraStates &states); virtual void revert(QPainter *p, QSvgExtraStates &states); virtual Type type() const; - void setPointSize(qreal size); - qreal pointSize() const; + void setSize(qreal size) + { + // Store the _pixel_ size in the font. Since QFont::setPixelSize() only takes an int, call + // QFont::SetPointSize() instead. Set proper font size just before rendering. + m_qfont.setPointSize(size); + m_sizeSet = 1; + } - //### hack to avoid having a separate style element for text-anchor - QString textAnchor() const; - void setTextAnchor(const QString &anchor); + void setTextAnchor(Qt::Alignment anchor) + { + m_textAnchor = anchor; + m_textAnchorSet = 1; + } - QSvgFont * svgFont() const + void setFamily(const QString &family) { - return m_font; + m_qfont.setFamily(family); + m_familySet = 1; + } + + void setStyle(QFont::Style fontStyle) { + m_qfont.setStyle(fontStyle); + m_styleSet = 1; } - QSvgTinyDocument *doc() const + + void setVariant(QFont::Capitalization fontVariant) { - return m_doc; + m_qfont.setCapitalization(fontVariant); + m_variantSet = 1; } - const QFont & qfont() const + static int SVGToQtWeight(int weight); + + void setWeight(int weight) + { + m_weight = weight; + m_weightSet = 1; + } + + QSvgFont * svgFont() const + { + return m_svgFont; + } + + const QFont &qfont() const { return m_qfont; } + + QSvgTinyDocument *doc() const {return m_doc;} + private: - QSvgFont *m_font; - qreal m_pointSize; + QSvgFont *m_svgFont; QSvgTinyDocument *m_doc; + QFont m_qfont; - QString m_textAnchor; + int m_weight; + Qt::Alignment m_textAnchor; - QFont m_qfont; - QFont m_oldFont; + QSvgFont *m_oldSvgFont; + QFont m_oldQFont; + Qt::Alignment m_oldTextAnchor; + int m_oldWeight; + + unsigned m_familySet : 1; + unsigned m_sizeSet : 1; + unsigned m_styleSet : 1; + unsigned m_variantSet : 1; + unsigned m_weightSet : 1; + unsigned m_textAnchorSet : 1; }; class QSvgStrokeStyle : public QSvgStyleProperty diff --git a/tests/arthur/data/1.2/textArea01.svg b/tests/arthur/data/1.2/textArea01.svg index 79fcd0a..945c34c 100644 --- a/tests/arthur/data/1.2/textArea01.svg +++ b/tests/arthur/data/1.2/textArea01.svg @@ -6,5 +6,5 @@ height="300">Tomorrow, and tomorrow, and tomorrow; creeps in this petty pace from day to day, until the last syll­able of recorded time. And all our yesterdays have lighted fools the way to dusty death. - + -- cgit v0.12 From 20b6e316285efc8d8d46fee2dec13364187a64a9 Mon Sep 17 00:00:00 2001 From: kh Date: Thu, 30 Jul 2009 15:52:34 +0200 Subject: Fix autotests after QUrl change. Reviewed-by: kh --- tests/auto/auto.pro | 4 +-- tests/auto/qhelpenginecore/data/collection.qhc | Bin 10240 -> 10240 bytes tests/auto/qhelpenginecore/data/collection1.qhc | Bin 10240 -> 10240 bytes tests/auto/qhelpenginecore/data/linguist-3.3.8.qch | Bin 131072 -> 131072 bytes tests/auto/qhelpenginecore/data/qmake-3.3.8.qch | Bin 61440 -> 61440 bytes tests/auto/qhelpenginecore/data/qmake-4.3.0.qch | Bin 93184 -> 93184 bytes tests/auto/qhelpenginecore/data/test.qch | Bin 22528 -> 22528 bytes tests/auto/qhelpenginecore/tst_qhelpenginecore.cpp | 40 ++++++++++----------- tests/auto/qhelpindexmodel/data/collection.qhc | Bin 10240 -> 10240 bytes tests/auto/qhelpindexmodel/data/collection1.qhc | Bin 10240 -> 10240 bytes tests/auto/qhelpindexmodel/data/linguist-3.3.8.qch | Bin 131072 -> 131072 bytes tests/auto/qhelpindexmodel/data/qmake-3.3.8.qch | Bin 61440 -> 61440 bytes tests/auto/qhelpindexmodel/data/qmake-4.3.0.qch | Bin 93184 -> 93184 bytes tests/auto/qhelpindexmodel/data/test.qch | Bin 22528 -> 22528 bytes tests/auto/qhelpindexmodel/tst_qhelpindexmodel.cpp | 6 ++-- 15 files changed, 25 insertions(+), 25 deletions(-) diff --git a/tests/auto/auto.pro b/tests/auto/auto.pro index 6f10922..b4a6600 100644 --- a/tests/auto/auto.pro +++ b/tests/auto/auto.pro @@ -159,9 +159,9 @@ SUBDIRS += _networkselftest \ qhash \ qheaderview \ qhelpcontentmodel \ -# qhelpenginecore \ + qhelpenginecore \ qhelpgenerator \ -# qhelpindexmodel \ + qhelpindexmodel \ qhelpprojectdata \ qhostaddress \ qhostinfo \ diff --git a/tests/auto/qhelpenginecore/data/collection.qhc b/tests/auto/qhelpenginecore/data/collection.qhc index 6fb8abb..bd2f37c 100644 Binary files a/tests/auto/qhelpenginecore/data/collection.qhc and b/tests/auto/qhelpenginecore/data/collection.qhc differ diff --git a/tests/auto/qhelpenginecore/data/collection1.qhc b/tests/auto/qhelpenginecore/data/collection1.qhc index 45acf33..de310ea 100644 Binary files a/tests/auto/qhelpenginecore/data/collection1.qhc and b/tests/auto/qhelpenginecore/data/collection1.qhc differ diff --git a/tests/auto/qhelpenginecore/data/linguist-3.3.8.qch b/tests/auto/qhelpenginecore/data/linguist-3.3.8.qch index 0b53cd8..ed9a89c 100644 Binary files a/tests/auto/qhelpenginecore/data/linguist-3.3.8.qch and b/tests/auto/qhelpenginecore/data/linguist-3.3.8.qch differ diff --git a/tests/auto/qhelpenginecore/data/qmake-3.3.8.qch b/tests/auto/qhelpenginecore/data/qmake-3.3.8.qch index a3ca18a..0e95c14 100644 Binary files a/tests/auto/qhelpenginecore/data/qmake-3.3.8.qch and b/tests/auto/qhelpenginecore/data/qmake-3.3.8.qch differ diff --git a/tests/auto/qhelpenginecore/data/qmake-4.3.0.qch b/tests/auto/qhelpenginecore/data/qmake-4.3.0.qch index 8f76134..337d7a1 100644 Binary files a/tests/auto/qhelpenginecore/data/qmake-4.3.0.qch and b/tests/auto/qhelpenginecore/data/qmake-4.3.0.qch differ diff --git a/tests/auto/qhelpenginecore/data/test.qch b/tests/auto/qhelpenginecore/data/test.qch index 8a8f7a1..06b789a 100644 Binary files a/tests/auto/qhelpenginecore/data/test.qch and b/tests/auto/qhelpenginecore/data/test.qch differ diff --git a/tests/auto/qhelpenginecore/tst_qhelpenginecore.cpp b/tests/auto/qhelpenginecore/tst_qhelpenginecore.cpp index d62c8e5..f9aa653 100644 --- a/tests/auto/qhelpenginecore/tst_qhelpenginecore.cpp +++ b/tests/auto/qhelpenginecore/tst_qhelpenginecore.cpp @@ -130,7 +130,7 @@ void tst_QHelpEngineCore::setCollectionFile() QStringList docs = help.registeredDocumentations(); QCOMPARE(docs.count(), 1); - QCOMPARE(docs.first(), QLatin1String("trolltech.com.1_0_0.test")); + QCOMPARE(docs.first(), QLatin1String("trolltech.com.1-0-0.test")); } void tst_QHelpEngineCore::copyCollectionFile() @@ -177,7 +177,7 @@ void tst_QHelpEngineCore::copyCollectionFile() i = 0; while (m_query->next()) { if (i == 0) { - QCOMPARE(m_query->value(0).toString(), QString("trolltech.com.3_3_8.qmake")); + QCOMPARE(m_query->value(0).toString(), QString("trolltech.com.3-3-8.qmake")); QCOMPARE(m_query->value(1).toString(), QString("data/qmake-3.3.8.qch")); } ++i; @@ -193,9 +193,9 @@ void tst_QHelpEngineCore::copyCollectionFile() void tst_QHelpEngineCore::namespaceName() { QCOMPARE(QHelpEngineCore::namespaceName(m_path + "/data/qmake-3.3.8.qch"), - QString("trolltech.com.3_3_8.qmake")); + QString("trolltech.com.3-3-8.qmake")); QCOMPARE(QHelpEngineCore::namespaceName(m_path + "/data/linguist-3.3.8.qch"), - QString("trolltech.com.3_3_8.linguist")); + QString("trolltech.com.3-3-8.linguist")); } void tst_QHelpEngineCore::registeredDocumentations() @@ -205,8 +205,8 @@ void tst_QHelpEngineCore::registeredDocumentations() QStringList docs = help.registeredDocumentations(); QCOMPARE(docs.count(), 3); QStringList lst; - lst << "trolltech.com.3_3_8.qmake" << "trolltech.com.4_3_0.qmake" - << "trolltech.com.1_0_0.test"; + lst << "trolltech.com.3-3-8.qmake" << "trolltech.com.4-3-0.qmake" + << "trolltech.com.1-0-0.test"; foreach (QString s, docs) lst.removeAll(s); QCOMPARE(lst.isEmpty(), true); @@ -236,7 +236,7 @@ void tst_QHelpEngineCore::registerDocumentation() } QSqlQuery query(db); query.exec("SELECT FilePath FROM NamespaceTable WHERE " - "Name=\'trolltech.com.3_3_8.linguist\'"); + "Name=\'trolltech.com.3-3-8.linguist\'"); if (query.next()) QCOMPARE(query.value(0).toString(), QString("linguist-3.3.8.qch")); @@ -251,7 +251,7 @@ void tst_QHelpEngineCore::unregisterDocumentation() QHelpEngineCore c(m_colFile); QCOMPARE(c.setupData(), true); QCOMPARE(c.registeredDocumentations().count(), 3); - c.unregisterDocumentation("trolltech.com.3_3_8.qmake"); + c.unregisterDocumentation("trolltech.com.3-3-8.qmake"); QCOMPARE(c.registeredDocumentations().count(), 2); QCOMPARE(c.unregisterDocumentation("noexisting"), false); } @@ -260,9 +260,9 @@ void tst_QHelpEngineCore::documentationFileName() { QHelpEngineCore c(m_colFile); QCOMPARE(c.setupData(), true); - QCOMPARE(c.documentationFileName(QLatin1String("trolltech.com.3_3_8.qmake")), + QCOMPARE(c.documentationFileName(QLatin1String("trolltech.com.3-3-8.qmake")), QString(m_path + "/data/qmake-3.3.8.qch")); - QCOMPARE(c.documentationFileName(QLatin1String("trolltech.com.1_0_0.test")), + QCOMPARE(c.documentationFileName(QLatin1String("trolltech.com.1-0-0.test")), QString(m_path + "/data/test.qch")); QCOMPARE(c.documentationFileName(QLatin1String("trolltech.com.empty")), QString()); @@ -337,7 +337,7 @@ void tst_QHelpEngineCore::filterAttributeSets() { QHelpEngineCore help(m_colFile, 0); QCOMPARE(help.setupData(), true); - QList lst = help.filterAttributeSets("trolltech.com.1_0_0.test"); + QList lst = help.filterAttributeSets("trolltech.com.1-0-0.test"); QCOMPARE(lst.count(), 2); QCOMPARE(lst.first().count(), 2); QCOMPARE((bool)lst.first().contains("filter1"), true); @@ -348,22 +348,22 @@ void tst_QHelpEngineCore::files() { QHelpEngineCore help(m_colFile, 0); QCOMPARE(help.setupData(), true); - QList lst = help.files("trolltech.com.4_3_0.qmake", + QList lst = help.files("trolltech.com.4-3-0.qmake", QStringList()); QCOMPARE(lst.count(), 16); - lst = help.files("trolltech.com.4_3_0.qmake", + lst = help.files("trolltech.com.4-3-0.qmake", QStringList(), "png"); QCOMPARE(lst.count(), 2); - lst = help.files("trolltech.com.4_3_0.qmake", + lst = help.files("trolltech.com.4-3-0.qmake", QStringList() << "qt", "html"); QCOMPARE(lst.count(), 13); - lst = help.files("trolltech.com.4_3_0.qmake", + lst = help.files("trolltech.com.4-3-0.qmake", QStringList() << "qt" << "qmake", "html"); QCOMPARE(lst.count(), 13); - lst = help.files("trolltech.com.4_3_0.qmake", + lst = help.files("trolltech.com.4-3-0.qmake", QStringList() << "qt" << "qmake" << "bla", "html"); QCOMPARE(lst.count(), 0); - lst = help.files("trolltech.com.4_3_0.qmake", + lst = help.files("trolltech.com.4-3-0.qmake", QStringList() << "qt" << "qmake", "foo"); QCOMPARE(lst.count(), 0); @@ -378,7 +378,7 @@ void tst_QHelpEngineCore::fileData() QCOMPARE(help.setupData(), true); QByteArray ba = help.fileData(QUrl("NotExisting")); QCOMPARE(ba.size(), 0); - ba = help.fileData(QUrl("qthelp://trolltech.com.1_0_0.test/testFolder/test.html")); + ba = help.fileData(QUrl("qthelp://trolltech.com.1-0-0.test/testFolder/test.html")); QTextStream s(ba, QIODevice::ReadOnly|QIODevice::Text); QFile f(m_path + "/data/test.html"); if (!f.open(QIODevice::ReadOnly|QIODevice::Text)) @@ -396,7 +396,7 @@ void tst_QHelpEngineCore::linksForIdentifier() QCOMPARE(map.contains("Test Manual"), true); QCOMPARE(map.count(), 1); QCOMPARE(map.value("Test Manual"), - QUrl("qthelp://trolltech.com.1_0_0.test/testFolder/test.html#foo")); + QUrl("qthelp://trolltech.com.1-0-0.test/testFolder/test.html#foo")); help.setCurrentFilter("Custom Filter 2"); map = help.linksForIdentifier("People::newton"); @@ -405,7 +405,7 @@ void tst_QHelpEngineCore::linksForIdentifier() QCOMPARE(map.contains("Fancy"), true); QCOMPARE(map.count(), 1); QCOMPARE(map.value("Fancy"), - QUrl("qthelp://trolltech.com.1_0_0.test/testFolder/fancy.html#foobar")); + QUrl("qthelp://trolltech.com.1-0-0.test/testFolder/fancy.html#foobar")); } void tst_QHelpEngineCore::customValue() diff --git a/tests/auto/qhelpindexmodel/data/collection.qhc b/tests/auto/qhelpindexmodel/data/collection.qhc index 6fb8abb..bd2f37c 100644 Binary files a/tests/auto/qhelpindexmodel/data/collection.qhc and b/tests/auto/qhelpindexmodel/data/collection.qhc differ diff --git a/tests/auto/qhelpindexmodel/data/collection1.qhc b/tests/auto/qhelpindexmodel/data/collection1.qhc index 45acf33..de310ea 100644 Binary files a/tests/auto/qhelpindexmodel/data/collection1.qhc and b/tests/auto/qhelpindexmodel/data/collection1.qhc differ diff --git a/tests/auto/qhelpindexmodel/data/linguist-3.3.8.qch b/tests/auto/qhelpindexmodel/data/linguist-3.3.8.qch index 0b53cd8..ed9a89c 100644 Binary files a/tests/auto/qhelpindexmodel/data/linguist-3.3.8.qch and b/tests/auto/qhelpindexmodel/data/linguist-3.3.8.qch differ diff --git a/tests/auto/qhelpindexmodel/data/qmake-3.3.8.qch b/tests/auto/qhelpindexmodel/data/qmake-3.3.8.qch index a3ca18a..0e95c14 100644 Binary files a/tests/auto/qhelpindexmodel/data/qmake-3.3.8.qch and b/tests/auto/qhelpindexmodel/data/qmake-3.3.8.qch differ diff --git a/tests/auto/qhelpindexmodel/data/qmake-4.3.0.qch b/tests/auto/qhelpindexmodel/data/qmake-4.3.0.qch index 8f76134..337d7a1 100644 Binary files a/tests/auto/qhelpindexmodel/data/qmake-4.3.0.qch and b/tests/auto/qhelpindexmodel/data/qmake-4.3.0.qch differ diff --git a/tests/auto/qhelpindexmodel/data/test.qch b/tests/auto/qhelpindexmodel/data/test.qch index 1d6c1a8..4ea9847 100644 Binary files a/tests/auto/qhelpindexmodel/data/test.qch and b/tests/auto/qhelpindexmodel/data/test.qch differ diff --git a/tests/auto/qhelpindexmodel/tst_qhelpindexmodel.cpp b/tests/auto/qhelpindexmodel/tst_qhelpindexmodel.cpp index 9482def..3adb894 100644 --- a/tests/auto/qhelpindexmodel/tst_qhelpindexmodel.cpp +++ b/tests/auto/qhelpindexmodel/tst_qhelpindexmodel.cpp @@ -185,11 +185,11 @@ void tst_QHelpIndexModel::linksForIndex() QCOMPARE(map.count(), 2); QCOMPARE(map.contains("Test Manual"), true); QCOMPARE(map.value("Test Manual"), - QUrl("qthelp://trolltech.com.1_0_0.test/testFolder/test.html#foo")); + QUrl("qthelp://trolltech.com.1-0-0.test/testFolder/test.html#foo")); QCOMPARE(map.contains("Fancy"), true); QCOMPARE(map.value("Fancy"), - QUrl("qthelp://trolltech.com.1_0_0.test/testFolder/fancy.html#foo")); + QUrl("qthelp://trolltech.com.1-0-0.test/testFolder/fancy.html#foo")); map = m->linksForKeyword("foobar"); QCOMPARE(map.count(), 1); @@ -208,7 +208,7 @@ void tst_QHelpIndexModel::linksForIndex() QCOMPARE(map.count(), 1); QCOMPARE(map.contains("Test Manual"), true); QCOMPARE(map.value("Test Manual"), - QUrl("qthelp://trolltech.com.1_0_0.test/testFolder/test.html#foo")); + QUrl("qthelp://trolltech.com.1-0-0.test/testFolder/test.html#foo")); } QTEST_MAIN(tst_QHelpIndexModel) -- cgit v0.12 From 5e966d96419fb68ac1f9528e72f1083b32eecdbb Mon Sep 17 00:00:00 2001 From: Richard Moe Gustavsen Date: Thu, 30 Jul 2009 15:44:57 +0200 Subject: Gestures: fixed install event filter bug made sure that we set the filter on the correct widget RevBy: denis --- src/gui/kernel/qgesture.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/gui/kernel/qgesture.cpp b/src/gui/kernel/qgesture.cpp index d53b419..1f98013 100644 --- a/src/gui/kernel/qgesture.cpp +++ b/src/gui/kernel/qgesture.cpp @@ -153,7 +153,7 @@ QGesture::QGesture(QObject *parent) : QObject(*new QGesturePrivate, parent) { if (parent) - installEventFilter(parent); + parent->installEventFilter(this); } /*! \internal @@ -162,7 +162,7 @@ QGesture::QGesture(QGesturePrivate &dd, QObject *parent) : QObject(dd, parent) { if (parent) - installEventFilter(parent); + parent->installEventFilter(this); } /*! -- cgit v0.12 From 3ae2cab9c8bd1790a00da2755ac036143a3a35f4 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Thu, 30 Jul 2009 16:40:06 +0200 Subject: Fix compilation with xlC 7: operands to ?: must match. "../shared/qm.cpp", line 556.45: 1540-0207 (S) No common type found for operands with type "const char [7]" and "QByteArray". Reviewed-by: Trust Me --- tools/linguist/shared/qm.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/linguist/shared/qm.cpp b/tools/linguist/shared/qm.cpp index 638e997..dc681f5 100644 --- a/tools/linguist/shared/qm.cpp +++ b/tools/linguist/shared/qm.cpp @@ -553,7 +553,7 @@ bool loadQM(Translator &translator, QIODevice &dev, ConversionData &cd) //qDebug() << "NUMITEMS: " << numItems; QTextCodec *codec = QTextCodec::codecForName( - cd.m_codecForSource.isEmpty() ? "Latin1" : cd.m_codecForSource); + cd.m_codecForSource.isEmpty() ? QByteArray("Latin1") : cd.m_codecForSource); QTextCodec *utf8Codec = 0; if (codec->name() != "UTF-8") utf8Codec = QTextCodec::codecForName("UTF-8"); -- cgit v0.12 From 2ebebeebd3dacc7192f2f998d324d16bc8cba9fa Mon Sep 17 00:00:00 2001 From: Oswald Buddenhagen Date: Thu, 30 Jul 2009 12:21:22 +0200 Subject: fix infinite loop when meeting improper trId() --- tools/linguist/lupdate/cpp.cpp | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tools/linguist/lupdate/cpp.cpp b/tools/linguist/lupdate/cpp.cpp index 58e094b..21b230e 100644 --- a/tools/linguist/lupdate/cpp.cpp +++ b/tools/linguist/lupdate/cpp.cpp @@ -1676,7 +1676,9 @@ void CppParser::parseInternal(ConversionData &cd, QSet &inclusions) case Tok_trid: if (!results->tor) goto case_default; - if (!sourcetext.isEmpty()) { + if (sourcetext.isEmpty()) { + yyTok = getToken(); + } else { if (!msgid.isEmpty()) qWarning("%s:%d: //= cannot be used with qtTrId() / QT_TRID_NOOP(). Ignoring\n", qPrintable(yyFileName), yyLineNo); -- cgit v0.12 From 4c3cc938ed17e9b98bbdfc9a7e4c5a5b7efd4a3b Mon Sep 17 00:00:00 2001 From: Benjamin C Meyer Date: Thu, 30 Jul 2009 16:59:02 +0200 Subject: Do not emit activated and close the popup when the item is not enabled. Autotest: included Merge-request: 378 Reviewed-by: Eskil Abrahamsen Blomfeldt --- src/gui/util/qcompleter.cpp | 6 +++++- tests/auto/qcompleter/tst_qcompleter.cpp | 27 ++++++++++++++++++++++++++- 2 files changed, 31 insertions(+), 2 deletions(-) diff --git a/src/gui/util/qcompleter.cpp b/src/gui/util/qcompleter.cpp index bf1fa6a..a0a3756 100644 --- a/src/gui/util/qcompleter.cpp +++ b/src/gui/util/qcompleter.cpp @@ -824,6 +824,9 @@ void QCompleterPrivate::_q_complete(QModelIndex index, bool highlighted) Q_Q(QCompleter); QString completion; + if (!(index.flags() & Qt::ItemIsEnabled)) + return; + if (!index.isValid() || (!proxy->showAll && (index.row() >= proxy->engine->matchCount()))) { completion = prefix; } else { @@ -1102,7 +1105,8 @@ void QCompleter::setPopup(QAbstractItemView *popup) QObject::connect(popup, SIGNAL(clicked(QModelIndex)), this, SLOT(_q_complete(QModelIndex))); - QObject::connect(popup, SIGNAL(clicked(QModelIndex)), popup, SLOT(hide())); + QObject::connect(this, SIGNAL(activated(QModelIndex)), + popup, SLOT(hide())); QObject::connect(popup->selectionModel(), SIGNAL(selectionChanged(QItemSelection,QItemSelection)), this, SLOT(_q_completionSelected(QItemSelection))); diff --git a/tests/auto/qcompleter/tst_qcompleter.cpp b/tests/auto/qcompleter/tst_qcompleter.cpp index 0a9c16a..a65490d 100644 --- a/tests/auto/qcompleter/tst_qcompleter.cpp +++ b/tests/auto/qcompleter/tst_qcompleter.cpp @@ -138,6 +138,7 @@ private slots: void setters(); void dynamicSortOrder(); + void disabledItems(); // task-specific tests below me void task178797_activatedOnReturn(); @@ -147,7 +148,6 @@ private slots: void task253125_lineEditCompletion_data(); void task253125_lineEditCompletion(); - void task247560_keyboardNavigation(); private: @@ -1106,6 +1106,31 @@ void tst_QCompleter::dynamicSortOrder() QCOMPARE(completer.completionCount(), 12); } +void tst_QCompleter::disabledItems() +{ + QLineEdit lineEdit; + QStandardItemModel *model = new QStandardItemModel(&lineEdit); + QStandardItem *suggestions = new QStandardItem("suggestions"); + suggestions->setEnabled(false); + model->appendRow(suggestions); + model->appendRow(new QStandardItem("suggestions Enabled")); + QCompleter *completer = new QCompleter(model, &lineEdit); + QSignalSpy spy(completer, SIGNAL(activated(const QString &))); + lineEdit.setCompleter(completer); + lineEdit.show(); + + QTest::keyPress(&lineEdit, Qt::Key_S); + QTest::keyPress(&lineEdit, Qt::Key_U); + QAbstractItemView *view = lineEdit.completer()->popup(); + QVERIFY(view->isVisible()); + QTest::mouseClick(view->viewport(), Qt::LeftButton, 0, view->visualRect(view->model()->index(0, 0)).center()); + QCOMPARE(spy.count(), 0); + QVERIFY(view->isVisible()); + QTest::mouseClick(view->viewport(), Qt::LeftButton, 0, view->visualRect(view->model()->index(1, 0)).center()); + QCOMPARE(spy.count(), 1); + QVERIFY(!view->isVisible()); +} + void tst_QCompleter::task178797_activatedOnReturn() { QStringList words; -- cgit v0.12 From 85d90102acca3202c410b7af311f52e5d67dc716 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Thu, 30 Jul 2009 16:06:06 +0200 Subject: Autotest: fix crash caused by deleting a QSharedPointer The delete reply; was introduced by a conflicted merge in the VxWorks port. It should not have appeared. But take this opportunity to convert the two other uses of QNetworkReply* without lifetime management to QSharedPointer too. Reviewed-by: Markus Goetz --- tests/auto/qnetworkreply/tst_qnetworkreply.cpp | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/tests/auto/qnetworkreply/tst_qnetworkreply.cpp b/tests/auto/qnetworkreply/tst_qnetworkreply.cpp index 03b1474..adb9b54 100644 --- a/tests/auto/qnetworkreply/tst_qnetworkreply.cpp +++ b/tests/auto/qnetworkreply/tst_qnetworkreply.cpp @@ -513,10 +513,10 @@ public: QTcpSocket *active = new QTcpSocket(this); active->connectToHost("127.0.0.1", server.serverPort()); - if (!active->waitForConnected(10)) + if (!active->waitForConnected(100)) return false; - if (!server.waitForNewConnection(10)) + if (!server.waitForNewConnection(100)) return false; QTcpSocket *passive = server.nextPendingConnection(); passive->setParent(this); @@ -2642,8 +2642,6 @@ void tst_QNetworkReply::ioPutToFileFromProcess() QCOMPARE(file.size(), qint64(data.size())); QByteArray contents = file.readAll(); QCOMPARE(contents, data); - - delete reply; #endif } @@ -3827,7 +3825,7 @@ void tst_QNetworkReply::httpDownloadPerformance() HttpDownloadPerformanceServer server(UploadSize, serverSendsContentLength, chunkedEncoding); QNetworkRequest request(QUrl("http://127.0.0.1:" + QString::number(server.serverPort()) + "/?bare=1")); - QNetworkReply* reply = manager.get(request); + QNetworkReplyPtr reply = manager.get(request); connect(reply, SIGNAL(finished()), &QTestEventLoop::instance(), SLOT(exitLoop()), Qt::QueuedConnection); HttpDownloadPerformanceClient client(reply); @@ -3840,8 +3838,6 @@ void tst_QNetworkReply::httpDownloadPerformance() qint64 elapsed = time.elapsed(); qDebug() << "tst_QNetworkReply::httpDownloadPerformance" << elapsed << "msec, " << ((UploadSize/1024.0)/(elapsed/1000.0)) << " kB/sec"; - - delete reply; } #ifndef QT_NO_OPENSSL @@ -3872,7 +3868,7 @@ void tst_QNetworkReply::ignoreSslErrorsList() { QFETCH(QString, url); QNetworkRequest request(url); - QNetworkReply *reply = manager.get(request); + QNetworkReplyPtr reply = manager.get(request); QFETCH(QList, expectedSslErrors); reply->ignoreSslErrors(expectedSslErrors); @@ -3901,7 +3897,7 @@ void tst_QNetworkReply::ignoreSslErrorsListWithSlot() { QFETCH(QString, url); QNetworkRequest request(url); - QNetworkReply *reply = manager.get(request); + QNetworkReplyPtr reply = manager.get(request); QFETCH(QList, expectedSslErrors); // store the errors to ignore them later in the slot connected below -- cgit v0.12 From 5d9f735289a787fd9ef4d7921374382424f880d7 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Thu, 30 Jul 2009 16:23:52 +0200 Subject: Autotest: reorganise the HTTP performance tests --- tests/auto/qnetworkreply/tst_qnetworkreply.cpp | 249 ++++++++++++------------- 1 file changed, 124 insertions(+), 125 deletions(-) diff --git a/tests/auto/qnetworkreply/tst_qnetworkreply.cpp b/tests/auto/qnetworkreply/tst_qnetworkreply.cpp index adb9b54..4ebc316 100644 --- a/tests/auto/qnetworkreply/tst_qnetworkreply.cpp +++ b/tests/auto/qnetworkreply/tst_qnetworkreply.cpp @@ -223,8 +223,10 @@ private Q_SLOTS: void rateControl(); void downloadPerformance(); void uploadPerformance(); - void httpUploadPerformance(); void performanceControlRate(); + void httpUploadPerformance(); + void httpDownloadPerformance_data(); + void httpDownloadPerformance(); void downloadProgress_data(); void downloadProgress(); @@ -248,8 +250,6 @@ private Q_SLOTS: void authorizationError(); void httpConnectionCount(); - void httpDownloadPerformance_data(); - void httpDownloadPerformance(); #ifndef QT_NO_OPENSSL void ignoreSslErrorsList_data(); @@ -836,6 +836,92 @@ protected: } }; +class HttpDownloadPerformanceClient : QObject { + Q_OBJECT; + QIODevice *device; + public: + HttpDownloadPerformanceClient (QIODevice *dev) : device(dev){ + connect(dev, SIGNAL(readyRead()), this, SLOT(readyReadSlot())); + } + + public slots: + void readyReadSlot() { + device->readAll(); + } + +}; + +class HttpDownloadPerformanceServer : QObject { + Q_OBJECT; + qint64 dataSize; + qint64 dataSent; + QTcpServer server; + QTcpSocket *client; + bool serverSendsContentLength; + bool chunkedEncoding; + +public: + HttpDownloadPerformanceServer (qint64 ds, bool sscl, bool ce) : dataSize(ds), dataSent(0), + client(0), serverSendsContentLength(sscl), chunkedEncoding(ce) { + server.listen(); + connect(&server, SIGNAL(newConnection()), this, SLOT(newConnectionSlot())); + } + + int serverPort() { + return server.serverPort(); + } + +public slots: + + void newConnectionSlot() { + client = server.nextPendingConnection(); + client->setParent(this); + connect(client, SIGNAL(readyRead()), this, SLOT(readyReadSlot())); + connect(client, SIGNAL(bytesWritten(qint64)), this, SLOT(bytesWrittenSlot(qint64))); + } + + void readyReadSlot() { + client->readAll(); + client->write("HTTP/1.0 200 OK\n"); + if (serverSendsContentLength) + client->write(QString("Content-Length: " + QString::number(dataSize) + "\n").toAscii()); + if (chunkedEncoding) + client->write(QString("Transfer-Encoding: chunked\n").toAscii()); + client->write("Connection: close\n\n"); + } + + void bytesWrittenSlot(qint64 amount) { + Q_UNUSED(amount); + if (dataSent == dataSize && client) { + // close eventually + + // chunked encoding: we have to send a last "empty" chunk + if (chunkedEncoding) + client->write(QString("0\r\n\r\n").toAscii()); + + client->disconnectFromHost(); + server.close(); + client = 0; + return; + } + + // send data + if (client && client->bytesToWrite() < 100*1024 && dataSent < dataSize) { + qint64 amount = qMin(qint64(16*1024), dataSize - dataSent); + QByteArray data(amount, '@'); + + if (chunkedEncoding) { + client->write(QString(QString("%1").arg(amount,0,16).toUpper() + "\r\n").toAscii()); + client->write(data.constData(), amount); + client->write(QString("\r\n").toAscii()); + } else { + client->write(data.constData(), amount); + } + + dataSent += amount; + } + } +}; tst_QNetworkReply::tst_QNetworkReply() @@ -3231,6 +3317,41 @@ void tst_QNetworkReply::performanceControlRate() << elapsedTime << "ms"; } +void tst_QNetworkReply::httpDownloadPerformance_data() +{ + QTest::addColumn("serverSendsContentLength"); + QTest::addColumn("chunkedEncoding"); + + QTest::newRow("Server sends no Content-Length") << false << false; + QTest::newRow("Server sends Content-Length") << true << false; + QTest::newRow("Server uses chunked encoding") << false << true; + +} + +void tst_QNetworkReply::httpDownloadPerformance() +{ + QFETCH(bool, serverSendsContentLength); + QFETCH(bool, chunkedEncoding); + + enum {UploadSize = 1000*1024*1024}; // 1000 MB + HttpDownloadPerformanceServer server(UploadSize, serverSendsContentLength, chunkedEncoding); + + QNetworkRequest request(QUrl("http://127.0.0.1:" + QString::number(server.serverPort()) + "/?bare=1")); + QNetworkReplyPtr reply = manager.get(request); + + connect(reply, SIGNAL(finished()), &QTestEventLoop::instance(), SLOT(exitLoop()), Qt::QueuedConnection); + HttpDownloadPerformanceClient client(reply); + + QTime time; + time.start(); + QTestEventLoop::instance().enterLoop(40); + QVERIFY(!QTestEventLoop::instance().timeout()); + + qint64 elapsed = time.elapsed(); + qDebug() << "tst_QNetworkReply::httpDownloadPerformance" << elapsed << "msec, " + << ((UploadSize/1024.0)/(elapsed/1000.0)) << " kB/sec"; +} + void tst_QNetworkReply::downloadProgress_data() { QTest::addColumn("loopCount"); @@ -3718,128 +3839,6 @@ void tst_QNetworkReply::httpConnectionCount() QCOMPARE(pendingConnectionCount, 6); } -class HttpDownloadPerformanceClient : QObject { - Q_OBJECT; - QIODevice *device; - public: - HttpDownloadPerformanceClient (QIODevice *dev) : device(dev){ - connect(dev, SIGNAL(readyRead()), this, SLOT(readyReadSlot())); - } - - public slots: - void readyReadSlot() { - device->readAll(); - } - -}; - -class HttpDownloadPerformanceServer : QObject { - Q_OBJECT; - qint64 dataSize; - qint64 dataSent; - QTcpServer server; - QTcpSocket *client; - bool serverSendsContentLength; - bool chunkedEncoding; - -public: - HttpDownloadPerformanceServer (qint64 ds, bool sscl, bool ce) : dataSize(ds), dataSent(0), - client(0), serverSendsContentLength(sscl), chunkedEncoding(ce) { - server.listen(); - connect(&server, SIGNAL(newConnection()), this, SLOT(newConnectionSlot())); - } - - int serverPort() { - return server.serverPort(); - } - -public slots: - - void newConnectionSlot() { - client = server.nextPendingConnection(); - client->setParent(this); - connect(client, SIGNAL(readyRead()), this, SLOT(readyReadSlot())); - connect(client, SIGNAL(bytesWritten(qint64)), this, SLOT(bytesWrittenSlot(qint64))); - } - - void readyReadSlot() { - client->readAll(); - client->write("HTTP/1.0 200 OK\n"); - if (serverSendsContentLength) - client->write(QString("Content-Length: " + QString::number(dataSize) + "\n").toAscii()); - if (chunkedEncoding) - client->write(QString("Transfer-Encoding: chunked\n").toAscii()); - client->write("Connection: close\n\n"); - } - - void bytesWrittenSlot(qint64 amount) { - Q_UNUSED(amount); - if (dataSent == dataSize && client) { - // close eventually - - // chunked encoding: we have to send a last "empty" chunk - if (chunkedEncoding) - client->write(QString("0\r\n\r\n").toAscii()); - - client->disconnectFromHost(); - server.close(); - client = 0; - return; - } - - // send data - if (client && client->bytesToWrite() < 100*1024 && dataSent < dataSize) { - qint64 amount = qMin(qint64(16*1024), dataSize - dataSent); - QByteArray data(amount, '@'); - - if (chunkedEncoding) { - client->write(QString(QString("%1").arg(amount,0,16).toUpper() + "\r\n").toAscii()); - client->write(data.constData(), amount); - client->write(QString("\r\n").toAscii()); - } else { - client->write(data.constData(), amount); - } - - dataSent += amount; - } - } -}; - -void tst_QNetworkReply::httpDownloadPerformance_data() -{ - QTest::addColumn("serverSendsContentLength"); - QTest::addColumn("chunkedEncoding"); - - QTest::newRow("Server sends no Content-Length") << false << false; - QTest::newRow("Server sends Content-Length") << true << false; - QTest::newRow("Server uses chunked encoding") << false << true; - -} - -void tst_QNetworkReply::httpDownloadPerformance() -{ - QFETCH(bool, serverSendsContentLength); - QFETCH(bool, chunkedEncoding); - - enum {UploadSize = 1000*1024*1024}; // 1000 MB - HttpDownloadPerformanceServer server(UploadSize, serverSendsContentLength, chunkedEncoding); - - QNetworkRequest request(QUrl("http://127.0.0.1:" + QString::number(server.serverPort()) + "/?bare=1")); - QNetworkReplyPtr reply = manager.get(request); - - connect(reply, SIGNAL(finished()), &QTestEventLoop::instance(), SLOT(exitLoop()), Qt::QueuedConnection); - HttpDownloadPerformanceClient client(reply); - - QTime time; - time.start(); - QTestEventLoop::instance().enterLoop(40); - QVERIFY(!QTestEventLoop::instance().timeout()); - - qint64 elapsed = time.elapsed(); - qDebug() << "tst_QNetworkReply::httpDownloadPerformance" << elapsed << "msec, " - << ((UploadSize/1024.0)/(elapsed/1000.0)) << " kB/sec"; -} - #ifndef QT_NO_OPENSSL void tst_QNetworkReply::ignoreSslErrorsList_data() { -- cgit v0.12 From 705a4811e3bdfddc4dbfe1499fe311c1fa3c5b38 Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Thu, 30 Jul 2009 16:38:38 +0200 Subject: Autotest: reduce the amout of data transferred to 128 MB, otherwise the test wouldn't finish. Running under valgrind and slow operating systems, the transfer rate is only a couple of MB per second. As long as you can reach 3.2 MB/s now, it should still work Also, don't kill the thread, for any reason. That causes trouble. Reviewed-by: Markus Goetz --- tests/auto/qnetworkreply/tst_qnetworkreply.cpp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/auto/qnetworkreply/tst_qnetworkreply.cpp b/tests/auto/qnetworkreply/tst_qnetworkreply.cpp index 4ebc316..cfd3dd0 100644 --- a/tests/auto/qnetworkreply/tst_qnetworkreply.cpp +++ b/tests/auto/qnetworkreply/tst_qnetworkreply.cpp @@ -3267,7 +3267,7 @@ void tst_QNetworkReply::uploadPerformance() void tst_QNetworkReply::httpUploadPerformance() { - enum {UploadSize = 1000*1024*1024}; // 1000 MB + enum {UploadSize = 128*1024*1024}; // 128 MB ThreadedDataReaderHttpServer reader; FixedSizeDataGenerator generator(UploadSize); @@ -3289,7 +3289,7 @@ void tst_QNetworkReply::httpUploadPerformance() << ((UploadSize/1024.0)/(elapsed/1000.0)) << " kB/sec"; reader.exit(); - reader.wait(3000); + reader.wait(); } @@ -3333,7 +3333,7 @@ void tst_QNetworkReply::httpDownloadPerformance() QFETCH(bool, serverSendsContentLength); QFETCH(bool, chunkedEncoding); - enum {UploadSize = 1000*1024*1024}; // 1000 MB + enum {UploadSize = 128*1024*1024}; // 128 MB HttpDownloadPerformanceServer server(UploadSize, serverSendsContentLength, chunkedEncoding); QNetworkRequest request(QUrl("http://127.0.0.1:" + QString::number(server.serverPort()) + "/?bare=1")); -- cgit v0.12 From 6a2621b6832dbdd349f77cf1f3242b4a6ba3c740 Mon Sep 17 00:00:00 2001 From: Denis Dzyubenko Date: Wed, 29 Jul 2009 14:33:25 +0200 Subject: Added an ability to remove size constraints from a widget. QWidget::setFixedSize() constrains the size of the widget, however there was no way to remove those constraints, so setting the constraints to QWIDGETSIZE_MAX will make the widget resizable again. Reviewed-by: Leonardo Sobral Cunha --- src/gui/kernel/qwidget.cpp | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/src/gui/kernel/qwidget.cpp b/src/gui/kernel/qwidget.cpp index bca607c..8b8a853 100644 --- a/src/gui/kernel/qwidget.cpp +++ b/src/gui/kernel/qwidget.cpp @@ -3491,11 +3491,16 @@ bool QWidgetPrivate::setMinimumSize_helper(int &minw, int &minh) minh = qMax(minh, 0); } createExtra(); - if (extra->minw == minw && extra->minh == minh) + int mw = minw, mh = minh; + if (mw == QWIDGETSIZE_MAX) + mw = 0; + if (mh == QWIDGETSIZE_MAX) + mh = 0; + if (extra->minw == mw && extra->minh == mh) return false; - extra->minw = minw; - extra->minh = minh; - extra->explicitMinSize = (minw ? Qt::Horizontal : 0) | (minh ? Qt::Vertical : 0); + extra->minw = mw; + extra->minh = mh; + extra->explicitMinSize = (mw ? Qt::Horizontal : 0) | (mh ? Qt::Vertical : 0); return true; } @@ -3555,7 +3560,8 @@ bool QWidgetPrivate::setMaximumSize_helper(int &maxw, int &maxh) return false; extra->maxw = maxw; extra->maxh = maxh; - extra->explicitMaxSize = (maxw != QWIDGETSIZE_MAX ? Qt::Horizontal : 0) | (maxh != QWIDGETSIZE_MAX ? Qt::Vertical : 0); + extra->explicitMaxSize = (maxw != QWIDGETSIZE_MAX ? Qt::Horizontal : 0) | + (maxh != QWIDGETSIZE_MAX ? Qt::Vertical : 0); return true; } @@ -3634,6 +3640,8 @@ void QWidget::setBaseSize(int basew, int baseh) This will override the default size constraints set by QLayout. + To remove constraints, set the size to QWIDGETSIZE_MAX. + Alternatively, if you want the widget to have a fixed size based on its contents, you can call QLayout::setSizeConstraint(QLayout::SetFixedSize); @@ -3675,7 +3683,8 @@ void QWidget::setFixedSize(int w, int h) else d->updateGeometry_helper(true); - resize(w, h); + if (w != QWIDGETSIZE_MAX || h != QWIDGETSIZE_MAX) + resize(w, h); } void QWidget::setMinimumWidth(int w) -- cgit v0.12 From f5a68dc15df4edb48e7bc41f9e918609b57f4356 Mon Sep 17 00:00:00 2001 From: Denis Dzyubenko Date: Wed, 29 Jul 2009 14:54:09 +0200 Subject: Added the windowflags manualtest which is based on the windowflags example. --- tests/manual/windowflags/controllerwindow.cpp | 263 ++++++++++++++++++++++++++ tests/manual/windowflags/controllerwindow.h | 115 +++++++++++ tests/manual/windowflags/main.cpp | 52 +++++ tests/manual/windowflags/previewwindow.cpp | 146 ++++++++++++++ tests/manual/windowflags/previewwindow.h | 81 ++++++++ tests/manual/windowflags/windowflags.pro | 5 + 6 files changed, 662 insertions(+) create mode 100644 tests/manual/windowflags/controllerwindow.cpp create mode 100644 tests/manual/windowflags/controllerwindow.h create mode 100644 tests/manual/windowflags/main.cpp create mode 100644 tests/manual/windowflags/previewwindow.cpp create mode 100644 tests/manual/windowflags/previewwindow.h create mode 100644 tests/manual/windowflags/windowflags.pro diff --git a/tests/manual/windowflags/controllerwindow.cpp b/tests/manual/windowflags/controllerwindow.cpp new file mode 100644 index 0000000..055ff40 --- /dev/null +++ b/tests/manual/windowflags/controllerwindow.cpp @@ -0,0 +1,263 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include + +#include "controllerwindow.h" + +//! [0] +ControllerWindow::ControllerWindow() +{ + parentWindow = new QMainWindow; + parentWindow->setWindowTitle(tr("Preview parent window")); + QLabel *label = new QLabel(tr("Parent window")); + parentWindow->setCentralWidget(label); + + previewWindow = new PreviewWindow; + previewDialog = new PreviewDialog; + + createTypeGroupBox(); + createHintsGroupBox(); + + quitButton = new QPushButton(tr("&Quit")); + connect(quitButton, SIGNAL(clicked()), qApp, SLOT(quit())); + + QHBoxLayout *bottomLayout = new QHBoxLayout; + bottomLayout->addStretch(); + bottomLayout->addWidget(quitButton); + + QVBoxLayout *mainLayout = new QVBoxLayout; + mainLayout->addWidget(widgetTypeGroupBox); + mainLayout->addWidget(additionalOptionsGroupBox); + mainLayout->addWidget(typeGroupBox); + mainLayout->addWidget(hintsGroupBox); + mainLayout->addLayout(bottomLayout); + setLayout(mainLayout); + + setWindowTitle(tr("Window Flags")); + updatePreview(); +} + +void ControllerWindow::updatePreview() +{ + Qt::WindowFlags flags = 0; + + if (windowRadioButton->isChecked()) { + flags = Qt::Window; + } else if (dialogRadioButton->isChecked()) { + flags = Qt::Dialog; + } else if (sheetRadioButton->isChecked()) { + flags = Qt::Sheet; + } else if (drawerRadioButton->isChecked()) { + flags = Qt::Drawer; + } else if (popupRadioButton->isChecked()) { + flags = Qt::Popup; + } else if (toolRadioButton->isChecked()) { + flags = Qt::Tool; + } else if (toolTipRadioButton->isChecked()) { + flags = Qt::ToolTip; + } else if (splashScreenRadioButton->isChecked()) { + flags = Qt::SplashScreen; + } + + if (msWindowsFixedSizeDialogCheckBox->isChecked()) + flags |= Qt::MSWindowsFixedSizeDialogHint; + if (x11BypassWindowManagerCheckBox->isChecked()) + flags |= Qt::X11BypassWindowManagerHint; + if (framelessWindowCheckBox->isChecked()) + flags |= Qt::FramelessWindowHint; + if (windowTitleCheckBox->isChecked()) + flags |= Qt::WindowTitleHint; + if (windowSystemMenuCheckBox->isChecked()) + flags |= Qt::WindowSystemMenuHint; + if (windowMinimizeButtonCheckBox->isChecked()) + flags |= Qt::WindowMinimizeButtonHint; + if (windowMaximizeButtonCheckBox->isChecked()) + flags |= Qt::WindowMaximizeButtonHint; + if (windowCloseButtonCheckBox->isChecked()) + flags |= Qt::WindowCloseButtonHint; + if (windowContextHelpButtonCheckBox->isChecked()) + flags |= Qt::WindowContextHelpButtonHint; + if (windowShadeButtonCheckBox->isChecked()) + flags |= Qt::WindowShadeButtonHint; + if (windowStaysOnTopCheckBox->isChecked()) + flags |= Qt::WindowStaysOnTopHint; + if (windowStaysOnBottomCheckBox->isChecked()) + flags |= Qt::WindowStaysOnBottomHint; + if (customizeWindowHintCheckBox->isChecked()) + flags |= Qt::CustomizeWindowHint; + + previewWindow->hide(); + previewDialog->hide(); + QWidget *widget = 0; + if (previewWidgetButton->isChecked()) + widget = previewWindow; + else + widget = previewDialog; + + if (modalWindowCheckBox->isChecked()) { + parentWindow->show(); + widget->setWindowModality(Qt::WindowModal); + widget->setParent(parentWindow); + } else { + widget->setWindowModality(Qt::NonModal); + widget->setParent(0); + parentWindow->hide(); + } + + widget->setWindowFlags(flags); + + if (fixedSizeWindowCheckBox->isChecked()) { + widget->setFixedSize(300, 300); + } else { + widget->setFixedSize(QWIDGETSIZE_MAX, QWIDGETSIZE_MAX); + } + + QPoint pos = widget->pos(); + if (pos.x() < 0) + pos.setX(0); + if (pos.y() < 0) + pos.setY(0); + widget->move(pos); + widget->show(); +} + +void ControllerWindow::createTypeGroupBox() +{ + widgetTypeGroupBox = new QGroupBox(tr("Widget Type")); + previewWidgetButton = createRadioButton(tr("QWidget")); + previewWidgetButton->setChecked(true); + previewDialogButton = createRadioButton(tr("QDialog")); + QHBoxLayout *l = new QHBoxLayout; + l->addWidget(previewWidgetButton); + l->addWidget(previewDialogButton); + widgetTypeGroupBox->setLayout(l); + + additionalOptionsGroupBox = new QGroupBox(tr("Additional options")); + l = new QHBoxLayout; + modalWindowCheckBox = createCheckBox(tr("Modal window")); + fixedSizeWindowCheckBox = createCheckBox(tr("Fixed size window")); + l->addWidget(modalWindowCheckBox); + l->addWidget(fixedSizeWindowCheckBox); + additionalOptionsGroupBox->setLayout(l); + + typeGroupBox = new QGroupBox(tr("Type")); + + windowRadioButton = createRadioButton(tr("Window")); + dialogRadioButton = createRadioButton(tr("Dialog")); + sheetRadioButton = createRadioButton(tr("Sheet")); + drawerRadioButton = createRadioButton(tr("Drawer")); + popupRadioButton = createRadioButton(tr("Popup")); + toolRadioButton = createRadioButton(tr("Tool")); + toolTipRadioButton = createRadioButton(tr("Tooltip")); + splashScreenRadioButton = createRadioButton(tr("Splash screen")); + windowRadioButton->setChecked(true); + + QGridLayout *layout = new QGridLayout; + layout->addWidget(windowRadioButton, 0, 0); + layout->addWidget(dialogRadioButton, 1, 0); + layout->addWidget(sheetRadioButton, 2, 0); + layout->addWidget(drawerRadioButton, 3, 0); + layout->addWidget(popupRadioButton, 0, 1); + layout->addWidget(toolRadioButton, 1, 1); + layout->addWidget(toolTipRadioButton, 2, 1); + layout->addWidget(splashScreenRadioButton, 3, 1); + typeGroupBox->setLayout(layout); +} +//! [5] + +//! [6] +void ControllerWindow::createHintsGroupBox() +{ + hintsGroupBox = new QGroupBox(tr("Hints")); + + msWindowsFixedSizeDialogCheckBox = + createCheckBox(tr("MS Windows fixed size dialog")); + x11BypassWindowManagerCheckBox = + createCheckBox(tr("X11 bypass window manager")); + framelessWindowCheckBox = createCheckBox(tr("Frameless window")); + windowTitleCheckBox = createCheckBox(tr("Window title")); + windowSystemMenuCheckBox = createCheckBox(tr("Window system menu")); + windowMinimizeButtonCheckBox = createCheckBox(tr("Window minimize button")); + windowMaximizeButtonCheckBox = createCheckBox(tr("Window maximize button")); + windowCloseButtonCheckBox = createCheckBox(tr("Window close button")); + windowContextHelpButtonCheckBox = + createCheckBox(tr("Window context help button")); + windowShadeButtonCheckBox = createCheckBox(tr("Window shade button")); + windowStaysOnTopCheckBox = createCheckBox(tr("Window stays on top")); + windowStaysOnBottomCheckBox = createCheckBox(tr("Window stays on bottom")); + customizeWindowHintCheckBox= createCheckBox(tr("Customize window")); + + QGridLayout *layout = new QGridLayout; + layout->addWidget(msWindowsFixedSizeDialogCheckBox, 0, 0); + layout->addWidget(x11BypassWindowManagerCheckBox, 1, 0); + layout->addWidget(framelessWindowCheckBox, 2, 0); + layout->addWidget(windowTitleCheckBox, 3, 0); + layout->addWidget(windowSystemMenuCheckBox, 4, 0); + layout->addWidget(windowMinimizeButtonCheckBox, 0, 1); + layout->addWidget(windowMaximizeButtonCheckBox, 1, 1); + layout->addWidget(windowCloseButtonCheckBox, 2, 1); + layout->addWidget(windowContextHelpButtonCheckBox, 3, 1); + layout->addWidget(windowShadeButtonCheckBox, 4, 1); + layout->addWidget(windowStaysOnTopCheckBox, 5, 1); + layout->addWidget(windowStaysOnBottomCheckBox, 6, 1); + layout->addWidget(customizeWindowHintCheckBox, 5, 0); + hintsGroupBox->setLayout(layout); +} +//! [6] + +//! [7] +QCheckBox *ControllerWindow::createCheckBox(const QString &text) +{ + QCheckBox *checkBox = new QCheckBox(text); + connect(checkBox, SIGNAL(clicked()), this, SLOT(updatePreview())); + return checkBox; +} +//! [7] + +//! [8] +QRadioButton *ControllerWindow::createRadioButton(const QString &text) +{ + QRadioButton *button = new QRadioButton(text); + connect(button, SIGNAL(clicked()), this, SLOT(updatePreview())); + return button; +} +//! [8] diff --git a/tests/manual/windowflags/controllerwindow.h b/tests/manual/windowflags/controllerwindow.h new file mode 100644 index 0000000..3d315be --- /dev/null +++ b/tests/manual/windowflags/controllerwindow.h @@ -0,0 +1,115 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef CONTROLLERWINDOW_H +#define CONTROLLERWINDOW_H + +#include + +#include "previewwindow.h" + +QT_BEGIN_NAMESPACE +class QCheckBox; +class QGroupBox; +class QLabel; +class QPushButton; +class QRadioButton; +class QMainWindow; +QT_END_NAMESPACE + +//! [0] +class ControllerWindow : public QWidget +{ + Q_OBJECT + +public: + ControllerWindow(); + +private slots: + void updatePreview(); + +private: + void createTypeGroupBox(); + void createHintsGroupBox(); + QCheckBox *createCheckBox(const QString &text); + QRadioButton *createRadioButton(const QString &text); + + QMainWindow *parentWindow; + PreviewWindow *previewWindow; + PreviewDialog *previewDialog; + + QGroupBox *widgetTypeGroupBox; + QGroupBox *additionalOptionsGroupBox; + QGroupBox *typeGroupBox; + QGroupBox *hintsGroupBox; + QPushButton *quitButton; + + QRadioButton *previewWidgetButton; + QRadioButton *previewDialogButton; + QCheckBox *modalWindowCheckBox; + QCheckBox *fixedSizeWindowCheckBox; + + QRadioButton *windowRadioButton; + QRadioButton *dialogRadioButton; + QRadioButton *sheetRadioButton; + QRadioButton *drawerRadioButton; + QRadioButton *popupRadioButton; + QRadioButton *toolRadioButton; + QRadioButton *toolTipRadioButton; + QRadioButton *splashScreenRadioButton; + + QCheckBox *msWindowsFixedSizeDialogCheckBox; + QCheckBox *x11BypassWindowManagerCheckBox; + QCheckBox *framelessWindowCheckBox; + QCheckBox *windowTitleCheckBox; + QCheckBox *windowSystemMenuCheckBox; + QCheckBox *windowMinimizeButtonCheckBox; + QCheckBox *windowMaximizeButtonCheckBox; + QCheckBox *windowCloseButtonCheckBox; + QCheckBox *windowContextHelpButtonCheckBox; + QCheckBox *windowShadeButtonCheckBox; + QCheckBox *windowStaysOnTopCheckBox; + QCheckBox *windowStaysOnBottomCheckBox; + QCheckBox *customizeWindowHintCheckBox; +}; +//! [0] + +#endif diff --git a/tests/manual/windowflags/main.cpp b/tests/manual/windowflags/main.cpp new file mode 100644 index 0000000..011ca3f --- /dev/null +++ b/tests/manual/windowflags/main.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include + +#include "controllerwindow.h" + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + ControllerWindow controller; + controller.show(); + return app.exec(); +} diff --git a/tests/manual/windowflags/previewwindow.cpp b/tests/manual/windowflags/previewwindow.cpp new file mode 100644 index 0000000..796bdb9 --- /dev/null +++ b/tests/manual/windowflags/previewwindow.cpp @@ -0,0 +1,146 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include + +#include "previewwindow.h" + +static QString windowFlagsToString(Qt::WindowFlags flags) +{ + QString text; + + Qt::WindowFlags type = (flags & Qt::WindowType_Mask); + if (type == Qt::Window) { + text = "Qt::Window"; + } else if (type == Qt::Dialog) { + text = "Qt::Dialog"; + } else if (type == Qt::Sheet) { + text = "Qt::Sheet"; + } else if (type == Qt::Drawer) { + text = "Qt::Drawer"; + } else if (type == Qt::Popup) { + text = "Qt::Popup"; + } else if (type == Qt::Tool) { + text = "Qt::Tool"; + } else if (type == Qt::ToolTip) { + text = "Qt::ToolTip"; + } else if (type == Qt::SplashScreen) { + text = "Qt::SplashScreen"; + } + + if (flags & Qt::MSWindowsFixedSizeDialogHint) + text += "\n| Qt::MSWindowsFixedSizeDialogHint"; + if (flags & Qt::X11BypassWindowManagerHint) + text += "\n| Qt::X11BypassWindowManagerHint"; + if (flags & Qt::FramelessWindowHint) + text += "\n| Qt::FramelessWindowHint"; + if (flags & Qt::WindowTitleHint) + text += "\n| Qt::WindowTitleHint"; + if (flags & Qt::WindowSystemMenuHint) + text += "\n| Qt::WindowSystemMenuHint"; + if (flags & Qt::WindowMinimizeButtonHint) + text += "\n| Qt::WindowMinimizeButtonHint"; + if (flags & Qt::WindowMaximizeButtonHint) + text += "\n| Qt::WindowMaximizeButtonHint"; + if (flags & Qt::WindowCloseButtonHint) + text += "\n| Qt::WindowCloseButtonHint"; + if (flags & Qt::WindowContextHelpButtonHint) + text += "\n| Qt::WindowContextHelpButtonHint"; + if (flags & Qt::WindowShadeButtonHint) + text += "\n| Qt::WindowShadeButtonHint"; + if (flags & Qt::WindowStaysOnTopHint) + text += "\n| Qt::WindowStaysOnTopHint"; + if (flags & Qt::CustomizeWindowHint) + text += "\n| Qt::CustomizeWindowHint"; + return text; +} + +PreviewWindow::PreviewWindow(QWidget *parent) + : QWidget(parent) +{ + textEdit = new QTextEdit; + textEdit->setReadOnly(true); + textEdit->setLineWrapMode(QTextEdit::NoWrap); + + closeButton = new QPushButton(tr("&Close")); + connect(closeButton, SIGNAL(clicked()), this, SLOT(close())); + + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(textEdit); + layout->addWidget(closeButton); + setLayout(layout); + + setWindowTitle(tr("Preview ")); +} + +void PreviewWindow::setWindowFlags(Qt::WindowFlags flags) +{ + QWidget::setWindowFlags(flags); + + QString text = windowFlagsToString(flags); + textEdit->setPlainText(text); +} + +PreviewDialog::PreviewDialog(QWidget *parent) + : QDialog(parent) +{ + textEdit = new QTextEdit; + textEdit->setReadOnly(true); + textEdit->setLineWrapMode(QTextEdit::NoWrap); + + closeButton = new QPushButton(tr("&Close")); + connect(closeButton, SIGNAL(clicked()), this, SLOT(close())); + + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(textEdit); + layout->addWidget(closeButton); + setLayout(layout); + + setWindowTitle(tr("Preview ")); +} + +void PreviewDialog::setWindowFlags(Qt::WindowFlags flags) +{ + QWidget::setWindowFlags(flags); + + QString text = windowFlagsToString(flags); + textEdit->setPlainText(text); +} diff --git a/tests/manual/windowflags/previewwindow.h b/tests/manual/windowflags/previewwindow.h new file mode 100644 index 0000000..90ed8ba --- /dev/null +++ b/tests/manual/windowflags/previewwindow.h @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef PREVIEWWINDOW_H +#define PREVIEWWINDOW_H + +#include +#include + +QT_BEGIN_NAMESPACE +class QPushButton; +class QTextEdit; +QT_END_NAMESPACE + +class PreviewWindow : public QWidget +{ + Q_OBJECT + +public: + PreviewWindow(QWidget *parent = 0); + + void setWindowFlags(Qt::WindowFlags flags); + +private: + QTextEdit *textEdit; + QPushButton *closeButton; +}; + +class PreviewDialog : public QDialog +{ + Q_OBJECT + +public: + PreviewDialog(QWidget *parent = 0); + + void setWindowFlags(Qt::WindowFlags flags); + +private: + QTextEdit *textEdit; + QPushButton *closeButton; +}; + +#endif diff --git a/tests/manual/windowflags/windowflags.pro b/tests/manual/windowflags/windowflags.pro new file mode 100644 index 0000000..1b45d0d --- /dev/null +++ b/tests/manual/windowflags/windowflags.pro @@ -0,0 +1,5 @@ +HEADERS = controllerwindow.h \ + previewwindow.h +SOURCES = controllerwindow.cpp \ + previewwindow.cpp \ + main.cpp -- cgit v0.12 From 989e195a4b7b0eb579dc4418dd47c2eca7e8b384 Mon Sep 17 00:00:00 2001 From: Denis Dzyubenko Date: Wed, 29 Jul 2009 15:34:31 +0200 Subject: Allow maximize button on the titlebar for a fixed size window On Windows we will add maximize button to the titlebar even if the window has a fixed size if the user explicitely asked for it by setting Qt::CustomizeWindowHint | Qt::WindowMaximizeButtonHint. Task-number: 250188 Reviewed-by: Leonardo Sobral Cunha --- src/gui/kernel/qwidget_win.cpp | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/gui/kernel/qwidget_win.cpp b/src/gui/kernel/qwidget_win.cpp index 46fa3be..455d06d 100644 --- a/src/gui/kernel/qwidget_win.cpp +++ b/src/gui/kernel/qwidget_win.cpp @@ -1524,6 +1524,11 @@ bool QWidgetPrivate::shouldShowMaximizeButton() { if (data.window_flags & Qt::MSWindowsFixedSizeDialogHint) return false; + // if the user explicitely asked for the maximize button, we try to add + // it even if the window has fixed size. + if (data.window_flags & Qt::CustomizeWindowHint && + data.window_flags & Qt::WindowMaximizeButtonHint) + return true; if (extra) { if ((extra->maxw && extra->maxw != QWIDGETSIZE_MAX && extra->maxw != QLAYOUTSIZE_MAX) || (extra->maxh && extra->maxh != QWIDGETSIZE_MAX && extra->maxh != QLAYOUTSIZE_MAX)) -- cgit v0.12 From 71961def3b006d042fb6f2d46e5f40d527553dc0 Mon Sep 17 00:00:00 2001 From: Denis Dzyubenko Date: Thu, 30 Jul 2009 17:03:53 +0200 Subject: Disabling the close button didn't work correctly Close button was enabled if the native window handle was created implicitely (for example by the setWindowTitle() function). Moved the code that enables of disables the close button to the place where we create native window handle. Task-number: 256360 Reviewed-by: trustme --- src/gui/kernel/qwidget_win.cpp | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/src/gui/kernel/qwidget_win.cpp b/src/gui/kernel/qwidget_win.cpp index 455d06d..2f230d7 100644 --- a/src/gui/kernel/qwidget_win.cpp +++ b/src/gui/kernel/qwidget_win.cpp @@ -467,6 +467,17 @@ void QWidgetPrivate::create_sys(WId window, bool initializeWindow, bool destroyO } } + if (topLevel) { + if (data.window_flags & Qt::CustomizeWindowHint + && data.window_flags & Qt::WindowTitleHint) { + HMENU systemMenu = GetSystemMenu((HWND)q->internalWinId(), FALSE); + if (data.window_flags & Qt::WindowCloseButtonHint) + EnableMenuItem(systemMenu, SC_CLOSE, MF_BYCOMMAND|MF_ENABLED); + else + EnableMenuItem(systemMenu, SC_CLOSE, MF_BYCOMMAND|MF_GRAYED); + } + } + q->setAttribute(Qt::WA_WState_Created); // accept move/resize events hd = 0; // no display context @@ -638,16 +649,6 @@ void QWidgetPrivate::setParent_sys(QWidget *parent, Qt::WindowFlags f) || (!q->isWindow() && q->parentWidget() && q->parentWidget()->testAttribute(Qt::WA_DropSiteRegistered))) q->setAttribute(Qt::WA_DropSiteRegistered, true); - - if (data.window_flags & Qt::CustomizeWindowHint - && data.window_flags & Qt::WindowTitleHint) { - HMENU systemMenu = GetSystemMenu((HWND)q->internalWinId(), FALSE); - if (data.window_flags & Qt::WindowCloseButtonHint) - EnableMenuItem(systemMenu, SC_CLOSE, MF_BYCOMMAND|MF_ENABLED); - else - EnableMenuItem(systemMenu, SC_CLOSE, MF_BYCOMMAND|MF_GRAYED); - } - #ifdef Q_WS_WINCE // Show borderless toplevel windows in tasklist & NavBar if (!parent) { -- cgit v0.12 From 278a6fbb0eb953d02cef2567df130cbf5ea960bc Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Thu, 30 Jul 2009 17:29:01 +0200 Subject: Doc: there is no group of explicitly shared classes, only one class uses this. Explain the implications in the QWebHistoryItem documentation, and get rid of the "group". --- doc/src/groups.qdoc | 111 ----------------- doc/src/implicit-sharing.qdoc | 144 ++++++++++++++++++++++ src/3rdparty/webkit/WebKit/qt/Api/qwebhistory.cpp | 15 ++- src/corelib/tools/qshareddata.cpp | 2 +- 4 files changed, 156 insertions(+), 116 deletions(-) create mode 100644 doc/src/implicit-sharing.qdoc diff --git a/doc/src/groups.qdoc b/doc/src/groups.qdoc index 731ac58..f7296a3 100644 --- a/doc/src/groups.qdoc +++ b/doc/src/groups.qdoc @@ -202,20 +202,6 @@ */ /*! - \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 Classes \ingroup groups @@ -377,103 +363,6 @@ */ /*! - \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 diff --git a/doc/src/implicit-sharing.qdoc b/doc/src/implicit-sharing.qdoc new file mode 100644 index 0000000..85630dc --- /dev/null +++ b/doc/src/implicit-sharing.qdoc @@ -0,0 +1,144 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* TODO: Move some of the documentation from QSharedDataPointer into this + document. */ + +/*! + \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}. + + When implementing your own implicitly shared classes, use the + QSharedData and QSharedDataPointer classes. + + \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}. +*/ diff --git a/src/3rdparty/webkit/WebKit/qt/Api/qwebhistory.cpp b/src/3rdparty/webkit/WebKit/qt/Api/qwebhistory.cpp index e5eb308..1c1c72a 100644 --- a/src/3rdparty/webkit/WebKit/qt/Api/qwebhistory.cpp +++ b/src/3rdparty/webkit/WebKit/qt/Api/qwebhistory.cpp @@ -32,7 +32,6 @@ /*! \class QWebHistoryItem - \ingroup explicitly-shared \since 4.4 \brief The QWebHistoryItem class represents one item in the history of a QWebPage @@ -52,13 +51,17 @@ \row \o userData() \o The user specific data that was stored with the history item. \endtable - \note QWebHistoryItem objects are value based and \l{explicitly shared}. + \note QWebHistoryItem objects are value based, but \e{explicitly shared}. Changing + a QWebHistoryItem instance by calling setUserData() will change all copies of that + instance. \sa QWebHistory, QWebPage::history(), QWebHistoryInterface */ /*! - Constructs a history item from \a other. + Constructs a history item from \a other. The new item and \a other + will share their data, and modifying either this item or \a other will + modify both instances. */ QWebHistoryItem::QWebHistoryItem(const QWebHistoryItem &other) : d(other.d) @@ -66,7 +69,9 @@ QWebHistoryItem::QWebHistoryItem(const QWebHistoryItem &other) } /*! - Assigns the \a other history item to this. + Assigns the \a other history item to this. This item and \a other + will share their data, and modifying either this item or \a other will + modify both instances. */ QWebHistoryItem &QWebHistoryItem::operator=(const QWebHistoryItem &other) { @@ -163,6 +168,8 @@ QVariant QWebHistoryItem::userData() const \since 4.5 Stores user specific data \a userData with the history item. + + \note All copies of this item will be modified. \sa userData() */ diff --git a/src/corelib/tools/qshareddata.cpp b/src/corelib/tools/qshareddata.cpp index 3cd37a7..6cd220c 100644 --- a/src/corelib/tools/qshareddata.cpp +++ b/src/corelib/tools/qshareddata.cpp @@ -51,7 +51,7 @@ QT_BEGIN_NAMESPACE QSharedData is designed to be used with QSharedDataPointer or QExplicitlySharedDataPointer to implement custom \l{implicitly - shared} or \l {explicitly shared} classes. QSharedData provides + shared} or explicitly shared classes. QSharedData provides \l{thread-safe} reference counting. See QSharedDataPointer and QExplicitlySharedDataPointer for details. -- cgit v0.12 From 6a5cabfa371c7daf7708e5f7aa1e90719cfe940d Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Thu, 30 Jul 2009 21:04:30 +0200 Subject: API documentation moved into the classes subdirectory --- doc/src/classes/qnamespace.qdoc | 2718 +++++++++++++++++++++++++++++++++++++++ doc/src/qnamespace.qdoc | 2718 --------------------------------------- 2 files changed, 2718 insertions(+), 2718 deletions(-) create mode 100644 doc/src/classes/qnamespace.qdoc delete mode 100644 doc/src/qnamespace.qdoc diff --git a/doc/src/classes/qnamespace.qdoc b/doc/src/classes/qnamespace.qdoc new file mode 100644 index 0000000..2d40fdd --- /dev/null +++ b/doc/src/classes/qnamespace.qdoc @@ -0,0 +1,2718 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://www.qtsoftware.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \namespace Qt + \inmodule QtCore + + \brief The Qt namespace contains miscellaneous identifiers + used throughout the Qt library. + + \ingroup misc +*/ + +/*! + \enum Qt::Orientation + + This type is used to signify an object's orientation. + + \value Horizontal + \value Vertical + + Orientation is used with QScrollBar for example. +*/ + +/*! + \enum Qt::AlignmentFlag + + This enum type is used to describe alignment. It contains + horizontal and vertical flags that can be combined to produce + the required effect. + + The \l{TextElideMode} enum can also be used in many situations + to fine-tune the appearance of aligned text. + + The horizontal flags are: + + \value AlignLeft Aligns with the left edge. + \value AlignRight Aligns with the right edge. + \value AlignHCenter Centers horizontally in the available space. + \value AlignJustify Justifies the text in the available space. + \omitvalue AlignAuto + + The vertical flags are: + + \value AlignTop Aligns with the top. + \value AlignBottom Aligns with the bottom. + \value AlignVCenter Centers vertically in the available space. + + You can use only one of the horizontal flags at a time. There is + one two-dimensional flag: + + \value AlignCenter Centers in both dimensions. + + You can use at most one horizontal and one vertical flag at a + time. Qt::AlignCenter counts as both horizontal and vertical. + + Three enum values are useful in applications that can be run in + right-to-left mode: + + \value AlignAbsolute If the widget's layout direction is + Qt::RightToLeft (instead of Qt::LeftToRight, the default), + Qt::AlignLeft refers to the \e right edge and Qt::AlignRight + to the \e left edge. This is normally the desired behavior. + If you want Qt::AlignLeft to always mean "left" and + Qt::AlignRight to always mean "right", combine the flag with + Qt::AlignAbsolute. + \value AlignLeading Synonym for Qt::AlignLeft. + \value AlignTrailing Synonym for Qt::AlignRight. + + Masks: + + \value AlignHorizontal_Mask + \value AlignVertical_Mask + + Conflicting combinations of flags have undefined meanings. +*/ + +/*! + \enum Qt::ApplicationAttribute + + This enum describes attributes that change the behavior of + application-wide features. These are enabled and disabled using + QCoreApplication::setAttribute(), and can be tested for with + QCoreApplication::testAttribute(). + + \value AA_ImmediateWidgetCreation Ensures that widgets are created + as soon as they are constructed. By default, resources for + widgets are allocated on demand to improve efficiency and + minimize resource usage. Setting or clearing this attribute + affects widgets constructed after the change. Setting it + tells Qt to create toplevel windows immediately. + Therefore, if it is important to minimize resource + consumption, do not set this attribute. + + \value AA_MSWindowsUseDirect3DByDefault This value is obsolete and + has no effect. + + \value AA_DontShowIconsInMenus Actions with the Icon property won't be + shown in any menus unless specifically set by the + QAction::iconVisibleInMenu property. + + Menus that are currently open or menus already created in the native + Mac OS X menubar \e{may not} pick up a change in this attribute. Changes + in the QAction::iconVisibleInMenu property will always be picked up. + + \value AA_NativeWindows Ensures that widgets have native windows. + + \value AA_DontCreateNativeWidgetSiblings Ensures that siblings of native + widgets stay non-native unless specifically set by the + Qt::WA_NativeWindow attribute. + + \value AA_MacPluginApplication Stops the Qt mac application from doing + specific initializations that do not necessarily make sense when using Qt + to author a plugin. This includes avoiding loading our nib for the main + menu and not taking possession of the native menu bar. When setting this + attribute to true will also set the AA_DontUseNativeMenuBar attribute + to true. + + \value AA_DontUseNativeMenuBar All menubars created while this attribute is + set to true won't be used as a native menubar (e.g, the menubar at + the top of the main screen on Mac OS X or at the bottom in Windows CE). + + \value AA_MacDontSwapCtrlAndMeta On Mac OS X by default, Qt swaps the + Control and Meta (Command) keys (i.e., whenever Control is pressed, Qt + sends Meta and whenever Meta is pressed Control is sent. When this + attribute is true, Qt will not do the flip. QKeySequence::StandardShortcuts + will also flip accordingly (i.e., QKeySequence::Copy will be + Command+C on the keyboard regardless of the value set, though what is output for + QKeySequence::toString(QKeySequence::PortableText) will be different). + + \omitvalue AA_AttributeCount +*/ + +/*! + \enum Qt::MouseButton + + This enum type describes the different mouse buttons. + + \value NoButton The button state does not refer to any + button (see QMouseEvent::button()). + \value LeftButton The left button is pressed, or an event refers + to the left button. (The left button may be the right button on + left-handed mice.) + \value RightButton The right button. + \value MidButton The middle button. + \value XButton1 The first X button. + \value XButton2 The second X button. + + \omitvalue MouseButtonMask + + \sa KeyboardModifier Modifier +*/ + +/*! + \enum Qt::KeyboardModifier + + This enum describes the modifier keys. + + \value NoModifier No modifier key is pressed. + \value ShiftModifier A Shift key on the keyboard is pressed. + \value ControlModifier A Ctrl key on the keyboard is pressed. + \value AltModifier An Alt key on the keyboard is pressed. + \value MetaModifier A Meta key on the keyboard is pressed. + \value KeypadModifier A keypad button is pressed. + \value GroupSwitchModifier X11 only. A Mode_switch key on the keyboard is pressed. + + \omitvalue KeyboardModifierMask + + \note On Mac OS X, the \c ControlModifier value corresponds to + the Command keys on the Macintosh keyboard, and the \c MetaModifier value + corresponds to the Control keys. The \c KeypadModifier value will also be set + when an arrow key is pressed as the arrow keys are considered part of the + keypad. + + \note On Windows Keyboards, Qt::MetaModifier and Qt::Key_Meta are mapped + to the Windows key. + + \sa MouseButton Modifier +*/ + +/*! + \enum Qt::Modifier + + This enum provides shorter names for the keyboard modifier keys + supported by Qt. + + \bold{Note:} On Mac OS X, the \c CTRL value corresponds to + the Command keys on the Macintosh keyboard, and the \c META value + corresponds to the Control keys. + + \value SHIFT The Shift keys provided on all standard keyboards. + \value META The Meta keys. + \value CTRL The Ctrl keys. + \value ALT The normal Alt keys, but not keys like AltGr. + \value UNICODE_ACCEL The shortcut is specified as a Unicode code + point, not as a Qt Key. + \omitvalue MODIFIER_MASK + + \sa KeyboardModifier MouseButton +*/ + +/*! + \enum Qt::GlobalColor + + \raw HTML + + \endraw + + Qt's predefined QColor objects: + + \value white \raw HTML + White (#ffffff) + \endraw + \value black \raw HTML + Black (#000000) + \endraw + \value red \raw HTML + Red (#ff0000) + \endraw + \value darkRed \raw HTML + Dark red (#800000) + \endraw + \value green \raw HTML + Green (#00ff00) + \endraw + \value darkGreen \raw HTML + Dark green (#008000) + \endraw + \value blue \raw HTML + Blue (#0000ff) + \endraw + \value darkBlue \raw HTML + Dark blue (#000080) + \endraw + \value cyan \raw HTML + Cyan (#00ffff) + \endraw + \value darkCyan \raw HTML + Dark cyan (#008080) + \endraw + \value magenta \raw HTML + Magenta (#ff00ff) + \endraw + \value darkMagenta \raw HTML + Dark magenta (#800080) + \endraw + \value yellow \raw HTML + Yellow (#ffff00) + \endraw + \value darkYellow \raw HTML + Dark yellow (#808000) + \endraw + \value gray \raw HTML + Gray (#a0a0a4) + \endraw + \value darkGray \raw HTML + Dark gray (#808080) + \endraw + \value lightGray \raw HTML + Light gray (#c0c0c0) + \endraw + \value transparent a transparent black value (i.e., QColor(0, 0, 0, 0)) + \value color0 0 pixel value (for bitmaps) + \value color1 1 pixel value (for bitmaps) + + \sa QColor + +*/ + +/*! + \enum Qt::PenStyle + + This enum type defines the pen styles that can be drawn using + QPainter. The styles are: + + \table + \row + \o \inlineimage qpen-solid.png + \o \inlineimage qpen-dash.png + \o \inlineimage qpen-dot.png + \row + \o Qt::SolidLine + \o Qt::DashLine + \o Qt::DotLine + \row + \o \inlineimage qpen-dashdot.png + \o \inlineimage qpen-dashdotdot.png + \o \inlineimage qpen-custom.png + \row + \o Qt::DashDotLine + \o Qt::DashDotDotLine + \o Qt::CustomDashLine + \endtable + + \value NoPen no line at all. For example, QPainter::drawRect() + fills but does not draw any boundary line. + + \value SolidLine A plain line. + \value DashLine Dashes separated by a few pixels. + \value DotLine Dots separated by a few pixels. + \value DashDotLine Alternate dots and dashes. + \value DashDotDotLine One dash, two dots, one dash, two dots. + \value CustomDashLine A custom pattern defined using + QPainterPathStroker::setDashPattern(). + + \omitvalue MPenStyle + + \sa QPen +*/ + +/*! + \enum Qt::PenCapStyle + + This enum type defines the pen cap styles supported by Qt, i.e. + the line end caps that can be drawn using QPainter. + + \table + \row + \o \inlineimage qpen-square.png + \o \inlineimage qpen-flat.png + \o \inlineimage qpen-roundcap.png + \row + \o Qt::SquareCap + \o Qt::FlatCap + \o Qt::RoundCap + \endtable + + \value FlatCap a square line end that does not cover the end + point of the line. + \value SquareCap a square line end that covers the end point and + extends beyond it by half the line width. + \value RoundCap a rounded line end. + \omitvalue MPenCapStyle + + \sa QPen +*/ + +/*! + \enum Qt::PenJoinStyle + + This enum type defines the pen join styles supported by Qt, i.e. + which joins between two connected lines can be drawn using + QPainter. + + \table + \row + \o \inlineimage qpen-bevel.png + \o \inlineimage qpen-miter.png + \o \inlineimage qpen-roundjoin.png + \row + \o Qt::BevelJoin + \o Qt::MiterJoin + \o Qt::RoundJoin + \endtable + + \value MiterJoin The outer edges of the lines are extended to + meet at an angle, and this area is filled. + \value BevelJoin The triangular notch between the two lines is filled. + \value RoundJoin A circular arc between the two lines is filled. + \value SvgMiterJoin A miter join corresponding to the definition of + a miter join in the \l{SVG 1.2 Tiny} specification. + \omitvalue MPenJoinStyle + + \sa QPen +*/ + +/*! + \enum Qt::BrushStyle + + This enum type defines the brush styles supported by Qt, i.e. the + fill pattern of shapes drawn using QPainter. + + \image brush-styles.png Brush Styles + + \value NoBrush No brush pattern. + \value SolidPattern Uniform color. + \value Dense1Pattern Extremely dense brush pattern. + \value Dense2Pattern Very dense brush pattern. + \value Dense3Pattern Somewhat dense brush pattern. + \value Dense4Pattern Half dense brush pattern. + \value Dense5Pattern Somewhat sparse brush pattern. + \value Dense6Pattern Very sparse brush pattern. + \value Dense7Pattern Extremely sparse brush pattern. + \value HorPattern Horizontal lines. + \value VerPattern Vertical lines. + \value CrossPattern Crossing horizontal and vertical lines. + \value BDiagPattern Backward diagonal lines. + \value FDiagPattern Forward diagonal lines. + \value DiagCrossPattern Crossing diagonal lines. + \value LinearGradientPattern Linear gradient (set using a dedicated QBrush constructor). + \value ConicalGradientPattern Conical gradient (set using a dedicated QBrush constructor). + \value RadialGradientPattern Radial gradient (set using a dedicated QBrush constructor). + \value TexturePattern Custom pattern (see QBrush::setTexture()). + + \omitvalue CustomPattern + + \sa QBrush +*/ + +/*! + \enum Qt::TextFlag + + This enum type is used to define some modifier flags. Some of + these flags only make sense in the context of printing: + + \value TextSingleLine Treats all whitespace as spaces and prints just + one line. + \value TextDontClip If it's impossible to stay within the given bounds, + it prints outside. + \value TextExpandTabs Makes the U+0009 (ASCII tab) character move to + the next tab stop. + \value TextShowMnemonic Displays the string "\&P" as \underline{P} + (see QButton for an example). For an ampersand, use "\&\&". + \value TextWordWrap Breaks lines at appropriate points, e.g. at word + boundaries. + \value TextWrapAnywhere Breaks lines anywhere, even within words. + \value TextHideMnemonic Same as Qt::TextShowMnemonic but doesn't draw the underlines. + \value TextDontPrint Treat this text as "hidden" and don't print + it. + \value IncludeTrailingSpaces When this option is set, QTextLine::naturalTextWidth() and naturalTextRect() will + return a value that includes the width of trailing spaces in the text; otherwise + this width is excluded. + \value TextIncludeTrailingSpaces Same as IncludeTrailingSpaces + \value TextJustificationForced Ensures that text lines are justified. + + \omitvalue BreakAnywhere + \omitvalue DontClip + \omitvalue DontPrint + \omitvalue ExpandTabs + \omitvalue IncludeTrailingSpaces + \omitvalue NoAccel + \omitvalue ShowPrefix + \omitvalue SingleLine + \omitvalue WordBreak + \omitvalue TextForceLeftToRight + \omitvalue TextForceRightToLeft + + You can use as many modifier flags as you want, except that + Qt::TextSingleLine and Qt::TextWordWrap cannot be combined. + + Flags that are inappropriate for a given use are generally + ignored. +*/ + +/*! + \enum Qt::BGMode + + Background mode: + + \value TransparentMode + \value OpaqueMode +*/ + +/*! + \enum Qt::ConnectionType + + This enum describes the types of connection that can be used between signals and + slots. In particular, it determines whether a particular signal is delivered to a + slot immediately or queued for delivery at a later time. + + \omitvalue AutoCompatConnection + \value DirectConnection When emitted, the signal is immediately delivered to the slot. + \value QueuedConnection When emitted, the signal is queued until the event loop is + able to deliver it to the slot. + \value BlockingQueuedConnection + Same as QueuedConnection, except that the current thread blocks + until the slot has been delivered. This connection type should + only be used for receivers in a different thread. Note that misuse + of this type can lead to deadlocks in your application. + \value AutoConnection If the signal is emitted from the thread + in which the receiving object lives, the + slot is invoked directly, as with + Qt::DirectConnection; otherwise the + signal is queued, as with + Qt::QueuedConnection. + \value UniqueConnection Same as AutoConnection, but there will be a check that the signal is + not already connected to the same slot before connecting, otherwise, + the connection will fail. + This value was introduced in Qt 4.6. + + With queued connections, the parameters must be of types that are known to + Qt's meta-object system, because Qt needs to copy the arguments to store them + in an event behind the scenes. If you try to use a queued connection and + get the error message + + \snippet doc/src/snippets/code/doc_src_qnamespace.qdoc 0 + + call qRegisterMetaType() to register the data type before you + establish the connection. + + \sa {Thread Support in Qt}, QObject::connect(), qRegisterMetaType() +*/ + +/*! + \enum Qt::DateFormat + + \value TextDate The default Qt format, which includes the day and month name, + the day number in the month, and the year in full. The day and month names will + be short, localized names. This is basically equivalent to using the date format + string, "ddd MMM d yyyy". See QDate::toString() for more information. + + \value ISODate ISO 8601 extended format: either \c{YYYY-MM-DD} for dates or + \c{YYYY-MM-DDTHH:MM:SS} for combined dates and times. + + \value SystemLocaleShortDate The \l{QLocale::ShortFormat}{short format} used + by the \l{QLocale::system()}{operating system}. + + \value SystemLocaleLongDate The \l{QLocale::LongFormat}{long format} used + by the \l{QLocale::system()}{operating system}. + + \value DefaultLocaleShortDate The \l{QLocale::ShortFormat}{short format} specified + by the \l{QLocale::setDefault()}{application's locale}. + + \value DefaultLocaleLongDate The \l{QLocale::LongFormat}{long format} used + by the \l{QLocale::setDefault()}{application's locale}. + + \value SystemLocaleDate \e{This enum value is deprecated.} Use Qt::SystemLocaleShortDate + instead (or Qt::SystemLocaleLongDate if you want long dates). + + \value LocaleDate \e{This enum value is deprecated.} Use Qt::DefaultLocaleShortDate + instead (or Qt::DefaultLocaleLongDate if you want long dates). + + \value LocalDate \e{This enum value is deprecated.} Use Qt::SystemLocaleShortDate + instead (or Qt::SystemLocaleLongDate if you want long dates). + + \note For \c ISODate formats, each \c Y, \c M and \c D represents a single digit + of the year, month and day used to specify the date. Each \c H, \c M and \c S + represents a single digit of the hour, minute and second used to specify the time. + The presence of a literal \c T character is used to separate the date and time when + both are specified. +*/ + + +/*! + \enum Qt::TimeSpec + + \value LocalTime Locale dependent time (Timezones and Daylight Savings Time). + \value UTC Coordinated Universal Time, replaces Greenwich Mean Time. + \value OffsetFromUTC An offset in seconds from Coordinated Universal Time. +*/ + +/*! + \enum Qt::DayOfWeek + + \value Monday + \value Tuesday + \value Wednesday + \value Thursday + \value Friday + \value Saturday + \value Sunday +*/ + +/*! + \enum Qt::CaseSensitivity + + \value CaseInsensitive + \value CaseSensitive +*/ + +/*! + \enum Qt::ToolBarArea + + \value LeftToolBarArea + \value RightToolBarArea + \value TopToolBarArea + \value BottomToolBarArea + \value AllToolBarAreas + \value NoToolBarArea + + \omitvalue ToolBarArea_Mask +*/ + +/*! + \enum Qt::DockWidgetArea + + \value LeftDockWidgetArea + \value RightDockWidgetArea + \value TopDockWidgetArea + \value BottomDockWidgetArea + \value AllDockWidgetAreas + \value NoDockWidgetArea + + \omitvalue DockWidgetArea_Mask +*/ + +/*! + \enum Qt::BackgroundMode + + \compat + + \value FixedColor + \value FixedPixmap + \value NoBackground + \value PaletteForeground + \value PaletteButton + \value PaletteLight + \value PaletteMidlight + \value PaletteDark + \value PaletteMid + \value PaletteText + \value PaletteBrightText + \value PaletteBase + \value PaletteBackground + \value PaletteShadow + \value PaletteHighlight + \value PaletteHighlightedText + \value PaletteButtonText + \value PaletteLink + \value PaletteLinkVisited + \value X11ParentRelative +*/ + +/*! + \enum Qt::ImageConversionFlag + + The options marked "(default)" are set if no other values from + the list are included (since the defaults are zero): + + Color/Mono preference (ignored for QBitmap): + + \value AutoColor (default) - If the image has \link + QImage::depth() depth\endlink 1 and contains only + black and white pixels, the pixmap becomes monochrome. + \value ColorOnly The pixmap is dithered/converted to the + \link QPixmap::defaultDepth() native display depth\endlink. + \value MonoOnly The pixmap becomes monochrome. If necessary, + it is dithered using the chosen dithering algorithm. + + Dithering mode preference for RGB channels: + + \value DiffuseDither (default) - A high-quality dither. + \value OrderedDither A faster, more ordered dither. + \value ThresholdDither No dithering; closest color is used. + + Dithering mode preference for alpha channel: + + \value ThresholdAlphaDither (default) - No dithering. + \value OrderedAlphaDither A faster, more ordered dither. + \value DiffuseAlphaDither A high-quality dither. + \omitvalue NoAlpha + + Color matching versus dithering preference: + + \value PreferDither (default when converting to a pixmap) - Always dither + 32-bit images when the image is converted to 8 bits. + \value AvoidDither (default when converting for the purpose of saving to + file) - Dither 32-bit images only if the image has more than 256 + colors and it is being converted to 8 bits. + \omitvalue AutoDither + + \omitvalue ColorMode_Mask + \omitvalue Dither_Mask + \omitvalue AlphaDither_Mask + \omitvalue DitherMode_Mask + \omitvalue NoOpaqueDetection +*/ + +/*! \enum Qt::GUIStyle + + \compat + + \value WindowsStyle + \value MotifStyle + \value MacStyle + \value Win3Style + \value PMStyle +*/ + +/*! + \enum Qt::UIEffect + + This enum describes the available UI effects. + + By default, Qt will try to use the platform specific desktop + settings for each effect. Use the + QApplication::setDesktopSettingsAware() function (passing \c false + as argument) to prevent this, and the + QApplication::setEffectEnabled() to enable or disable a particular + effect. + + Note that all effects are disabled on screens running at less than + 16-bit color depth. + + \omitvalue UI_General + + \value UI_AnimateMenu Show animated menus. + \value UI_FadeMenu Show faded menus. + \value UI_AnimateCombo Show animated comboboxes. + \value UI_AnimateTooltip Show tooltip animations. + \value UI_FadeTooltip Show tooltip fading effects. + \value UI_AnimateToolBox Reserved + + \sa QApplication::setEffectEnabled(), QApplication::setDesktopSettingsAware() +*/ + +/*! \enum Qt::AspectRatioMode + + This enum type defines what happens to the aspect ratio when + scaling an rectangle. + + \image qimage-scaling.png + + \value IgnoreAspectRatio The size is scaled freely. The aspect + ratio is not preserved. + \value KeepAspectRatio The size is scaled to a rectangle as + large as possible inside a given + rectangle, preserving the aspect ratio. + \value KeepAspectRatioByExpanding The size is scaled to a + rectangle as small as possible + outside a given rectangle, + preserving the aspect ratio. + + \omitvalue ScaleFree + \omitvalue ScaleMin + \omitvalue ScaleMax + + \sa QSize::scale(), QImage::scaled() +*/ + +/*! \typedef Qt::ScaleMode + \compat + + Use Qt::AspectRatioMode instead. + + The enum values have been renamed as follows: + + \table + \row \i Old enum value \i New enum value + \row \i Qt::ScaleFree \i Qt::IgnoreAspectRatio + \row \i Qt::ScaleMin \i Qt::KeepAspectRatio + \row \i Qt::ScaleMax \i Qt::KeepAspectRatioByExpanding + \endtable +*/ + +/*! \enum Qt::TransformationMode + + This enum type defines whether image transformations (e.g., + scaling) should be smooth or not. + + \value FastTransformation The transformation is performed + quickly, with no smoothing. + \value SmoothTransformation The resulting image is transformed + using bilinear filtering. + + \sa QImage::scaled() +*/ + +/*! \enum Qt::Axis + + This enum type defines three values to represent the three + axes in the cartesian coordinate system. + + \value XAxis The X axis. + \value YAxis The Y axis. + \value ZAxis The Z axis. + + \sa QTransform::rotate(), QTransform::rotateRadians() + */ + +/*! + \enum Qt::WidgetAttribute + + \keyword widget attributes + + This enum type is used to specify various widget attributes. + Attributes are set and cleared with QWidget::setAttribute(), and + queried with QWidget::testAttribute(), although some have special + convenience functions which are mentioned below. + + \value WA_AcceptDrops Allows data from drag and drop operations + to be dropped onto the widget (see QWidget::setAcceptDrops()). + + \value WA_AlwaysShowToolTips Enables tooltips for inactive windows. + + \value WA_ContentsPropagated This flag is superfluous and + obsolete; it no longer has any effect. Since Qt 4.1, all widgets + that do not set WA_PaintOnScreen propagate their contents. + + \value WA_CustomWhatsThis Indicates that the widget wants to + continue operating normally in "What's This?" mode. This is set by the + widget's author. + + \value WA_DeleteOnClose Makes Qt delete this widget when the + widget has accepted the close event (see QWidget::closeEvent()). + + \value WA_Disabled Indicates that the widget is disabled, i.e. + it does not receive any mouse or keyboard events. There is also a + getter functions QWidget::isEnabled(). This is set/cleared by the + Qt kernel. + + \omitvalue WA_DropSiteRegistered + \omitvalue WA_ForceAcceptDrops + + \value WA_ForceDisabled Indicates that the widget is + explicitly disabled, i.e. it will remain disabled even when all + its ancestors are set to the enabled state. This implies + WA_Disabled. This is set/cleared by QWidget::setEnabled() and + QWidget::setDisabled(). + + \value WA_ForceUpdatesDisabled Indicates that updates are + explicitly disabled for the widget; i.e. it will remain disabled + even when all its ancestors are set to the updates-enabled state. + This implies WA_UpdatesDisabled. This is set/cleared by + QWidget::setUpdatesEnabled(). + + \value WA_GroupLeader + \e{This attribute has been deprecated.} Use QWidget::windowModality + instead. + + \value WA_Hover Forces Qt to generate paint events when the mouse + enters or leaves the widget. This feature is typically used when + implementing custom styles; see the \l{widgets/styles}{Styles} + example for details. + + \value WA_InputMethodEnabled Enables input methods for Asian languages. + Must be set when creating custom text editing widgets. + On Windows CE this flag can be used in addition to + QApplication::autoSipEnabled to automatically display the SIP when + entering a widget. + + \value WA_KeyboardFocusChange Set on a toplevel window when + the users changes focus with the keyboard (tab, backtab, or shortcut). + + \value WA_KeyCompression Enables key event compression if set, + and disables it if not set. By default key compression is off, so + widgets receive one key press event for each key press (or more, + since autorepeat is usually on). If you turn it on and your + program doesn't keep up with key input, Qt may try to compress key + events so that more than one character can be processed in each + event. + For example, a word processor widget might receive 2, 3 or more + characters in each QKeyEvent::text(), if the layout recalculation + takes too long for the CPU. + If a widget supports multiple character unicode input, it is + always safe to turn the compression on. + Qt performs key event compression only for printable characters. + Qt::Modifier keys, cursor movement keys, function keys and + miscellaneous action keys (e.g. Escape, Enter, Backspace, + PrintScreen) will stop key event compression, even if there are + more compressible key events available. + Platforms other than Mac and X11 do not support this compression, + in which case turning it on will have no effect. + This is set/cleared by the widget's author. + + \value WA_LayoutOnEntireRect Indicates that the widget + wants QLayout to operate on the entire QWidget::rect(), not only + on QWidget::contentsRect(). This is set by the widget's author. + + \value WA_LayoutUsesWidgetRect Ignore the layout item rect from the style + when laying out this widget with QLayout. This makes a difference in + QMacStyle and QPlastiqueStyle for some widgets. + + \value WA_MacNoClickThrough When a widget that has this attribute set + is clicked, and its window is inactive, the click will make the window + active but won't be seen by the widget. Typical use of this attribute + is on widgets with "destructive" actions, such as a "Delete" button. + WA_MacNoClickThrough also applies to all child widgets of the widget + that has it set. + + \value WA_MacOpaqueSizeGrip Indicates that the native Carbon size grip + should be opaque instead of transparent (the default). This attribute + is only applicable to Mac OS X and is set by the widget's author. + + \value WA_MacShowFocusRect Indicates that this widget should get a + QFocusFrame around it. Some widgets draw their own focus halo + regardless of this attribute. Not that the QWidget::focusPolicy + also plays the main role in whether something is given focus or + not, this only controls whether or not this gets the focus + frame. This attribute is only applicable to Mac OS X. + + \value WA_MacNormalSize Indicates the widget should have the + normal size for widgets in Mac OS X. This attribute is only + applicable to Mac OS X. + + \value WA_MacSmallSize Indicates the widget should have the small + size for widgets in Mac OS X. This attribute is only applicable to + Mac OS X. + + \value WA_MacMiniSize Indicates the widget should have the mini + size for widgets in Mac OS X. This attribute is only applicable to + Mac OS X. + + \value WA_MacVariableSize Indicates the widget can choose between + alternative sizes for widgets to avoid clipping. + This attribute is only applicable to Mac OS X. + + \value WA_MacBrushedMetal Indicates the widget should be drawn in + the brushed metal style as supported by the windowing system. This + attribute is only applicable to Mac OS X. + + \omitvalue WA_MacMetalStyle + + \value WA_Mapped Indicates that the widget is mapped on screen. + This is set/cleared by the Qt kernel. + + \value WA_MouseNoMask Makes the widget receive mouse events for + the entire widget regardless of the currently set mask, + overriding QWidget::setMask(). This is not applicable for + top-level windows. + + \value WA_MouseTracking Indicates that the widget has mouse + tracking enabled. See QWidget::mouseTracking. + + \value WA_Moved Indicates that the widget has an explicit + position. This is set/cleared by QWidget::move() and + by QWidget::setGeometry(). + + \value WA_MSWindowsUseDirect3D This value is obsolete and has no + effect. + + \value WA_NoBackground This value is obsolete. Use + WA_OpaquePaintEvent instead. + + \value WA_NoChildEventsForParent Indicates that the widget does + not want ChildAdded or ChildRemoved events sent to its + parent. This is rarely necessary but can help to avoid automatic + insertion widgets like splitters and layouts. This is set by a + widget's author. + + \value WA_NoChildEventsFromChildren Indicates that the widget does + not want to receive ChildAdded or ChildRemoved events sent from its + children. This is set by a widget's author. + + \value WA_NoMouseReplay Used for pop-up widgets. Indicates that the most + recent mouse press event should not be replayed when the pop-up widget + closes. The flag is set by the widget's author and cleared by the Qt kernel + every time the widget receives a new mouse event. + + \value WA_NoMousePropagation Prohibits mouse events from being propagated + to the widget's parent. This attribute is disabled by default. + + \value WA_TransparentForMouseEvents When enabled, this attribute disables + the delivery of mouse events to the widget and its children. Mouse events + are delivered to other widgets as if the widget and its children were not + present in the widget hierarchy; mouse clicks and other events effectively + "pass through" them. This attribute is disabled by default. + + \value WA_NoSystemBackground Indicates that the widget has no background, + i.e. when the widget receives paint events, the background is not + automatically repainted. \note Unlike WA_OpaquePaintEvent, newly exposed + areas are \bold never filled with the background (e.g., after showing a + window for the first time the user can see "through" it until the + application processes the paint events). This flag is set or cleared by the + widget's author. + + \value WA_OpaquePaintEvent Indicates that the widget paints all its pixels + when it receives a paint event. Thus, it is not required for operations + like updating, resizing, scrolling and focus changes to erase the widget + before generating paint events. The use of WA_OpaquePaintEvent provides a + small optimization by helping to reduce flicker on systems that do not + support double buffering and avoiding computational cycles necessary to + erase the background prior to painting. \note Unlike + WA_NoSystemBackground, WA_OpaquePaintEvent makes an effort to avoid + transparent window backgrounds. This flag is set or cleared by the widget's + author. + + \value WA_OutsideWSRange Indicates that the widget is outside + the valid range of the window system's coordinate system. A widget + outside the valid range cannot be mapped on screen. This is + set/cleared by the Qt kernel. + + \value WA_PaintOnScreen Indicates that the widget wants to draw directly + onto the screen. Widgets with this attribute set do not participate in + composition management, i.e. they cannot be semi-transparent or shine + through semi-transparent overlapping widgets. \note This flag is only + supported on X11 and it disables double buffering. On Qt for Embedded + Linux, the flag only works when set on a top-level widget and it relies on + support from the active screen driver. This flag is set or cleared by the + widget's author. To render outside of Qt's paint system, e.g., if you + require native painting primitives, you need to reimplement + QWidget::paintEngine() to return 0 and set this flag. + + \value WA_PaintOutsidePaintEvent Makes it possible to use QPainter to + paint on the widget outside \l{QWidget::paintEvent()}{paintEvent()}. This + flag is not supported on Windows, Mac OS X or Embedded Linux. We recommend + that you use it only when porting Qt 3 code to Qt 4. + + \value WA_PaintUnclipped Makes all painters operating on this widget + unclipped. Children of this widget or other widgets in front of it do not + clip the area the painter can paint on. This flag is only supported for + widgets with the WA_PaintOnScreen flag set. The preferred way to do this in + a cross platform way is to create a transparent widget that lies in front + of the other widgets. + + \value WA_PendingMoveEvent Indicates that a move event is pending, e.g., + when a hidden widget was moved. This flag is set or cleared by the Qt + kernel. + + \value WA_PendingResizeEvent Indicates that a resize event is pending, + e.g., when a hidden widget was resized. This flag is set or cleared by the + Qt kernel. + + \value WA_QuitOnClose Makes Qt quit the application when the last widget + with the attribute set has accepted closeEvent(). This behavior can be + modified with the QApplication::quitOnLastWindowClosed property. By default + this attribute is set for all widgets of type Qt::Window. + + \value WA_Resized Indicates that the widget has an explicit size. This flag + is set or cleared by QWidget::resize() and QWidget::setGeometry(). + + \value WA_RightToLeft Indicates that the layout direction for the widget + is right to left. + + \value WA_SetCursor Indicates that the widget has a cursor of its own. This + flag is set or cleared by QWidget::setCursor() and QWidget::unsetCursor(). + + \value WA_SetFont Indicates that the widget has a font of its own. This + flag is set or cleared by QWidget::setFont(). + + \value WA_SetPalette Indicates that the widget has a palette of its own. + This flag is set or cleared by QWidget::setPalette(). + + \value WA_SetStyle Indicates that the widget has a style of its own. This + flag is set or cleared by QWidget::setStyle(). + + \value WA_ShowModal \e{This attribute has been deprecated.} Use + QWidget::windowModality instead. + + \value WA_StaticContents Indicates that the widget contents are north-west + aligned and static. On resize, such a widget will receive paint events only + for parts of itself that are newly visible. This flag is set or cleared by + the widget's author. + + \value WA_StyleSheet Indicates that the widget is styled using a + \l{Qt Style Sheets}{style sheet}. + + \value WA_TranslucentBackground Indicates that the widget should have a + translucent background, i.e., any non-opaque regions of the widgets will be + translucent because the widget will have an alpha channel. Setting this + flag causes WA_NoSystemBackground to be set. On Windows the + widget also needs the Qt::FramelessWindowHint window flag to be set. + This flag is set or cleared by the widget's author. + + \value WA_UnderMouse Indicates that the widget is under the mouse cursor. + The value is not updated correctly during drag and drop operations. There + is also a getter function, QWidget::underMouse(). This flag is set or + cleared by the Qt kernel. + + \value WA_UpdatesDisabled Indicates that updates are blocked (including the + system background). This flag is set or cleared by the Qt kernel. + \warning This flag must \e never be set or cleared by the widget's author. + + \value WA_WindowModified Indicates that the window is marked as modified. + On some platforms this flag will do nothing, on others (including Mac OS X + and Windows) the window will take a modified appearance. This flag is set + or cleared by QWidget::setWindowModified(). + + \value WA_WindowPropagation Makes a toplevel window inherit font and + palette from its parent. + + \value WA_MacAlwaysShowToolWindow On Mac OS X, show the tool window even + when the application is not active. By default, all tool windows are + hidden when the application is inactive. + + \value WA_SetLocale Indicates the locale should be taken into consideration + in the widget. + + \value WA_StyledBackground Indicates the widget should be drawn using a + styled background. + + \value WA_ShowWithoutActivating Show the widget without making it active. + + \value WA_NativeWindow Indicates that a native window is created for the + widget. Enabling this flag will also force a native window for the widget's + ancestors unless Qt::WA_DontCreateNativeAncestors is set. + + \value WA_DontCreateNativeAncestors Indicates that the widget's ancestors + are kept non-native even though the widget itself is native. + + \value WA_X11NetWmWindowTypeDesktop Adds _NET_WM_WINDOW_TYPE_DESKTOP to the + window's _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This attribute + has no effect on non-X11 platforms. + + \value WA_X11NetWmWindowTypeDock Adds _NET_WM_WINDOW_TYPE_DOCK to the + window's _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This attribute + has no effect on non-X11 platforms. + + \value WA_X11NetWmWindowTypeToolBar Adds _NET_WM_WINDOW_TYPE_TOOLBAR to the + window's _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This attribute + has no effect on non-X11 platforms. \note Qt automaticaly sets this + attribute for QToolBar. + + \value WA_X11NetWmWindowTypeMenu Adds _NET_WM_WINDOW_TYPE_MENU to the + window's _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This attribute + has no effect on non-X11 platforms. \note Qt automatically sets this + attribute for QMenu when torn-off. + + \value WA_X11NetWmWindowTypeUtility Adds _NET_WM_WINDOW_TYPE_UTILITY to the + window's _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This attribute + has no effect on non-X11 platforms. \note Qt automatically sets this + attribute for the Qt::Tool window type. + + \value WA_X11NetWmWindowTypeSplash Adds _NET_WM_WINDOW_TYPE_SPLASH to the + window's _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This attribute + has no effect on non-X11 platforms. \note Qt automatically sets this + attribute for the Qt::SplashScreen window type. + + \value WA_X11NetWmWindowTypeDialog Adds _NET_WM_WINDOW_TYPE_DIALOG + to the window's _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This + attribute has no effect on non-X11 platforms. \note Qt automatically sets + this attribute for the Qt::Dialog and Qt::Sheet window types. + + \value WA_X11NetWmWindowTypeDropDownMenu Adds + _NET_WM_WINDOW_TYPE_DROPDOWN_MENU to the window's + _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This + attribute has no effect on non-X11 platforms. \note Qt + automatically sets this attribute for QMenus added to a QMenuBar. + + \value WA_X11NetWmWindowTypePopupMenu Adds _NET_WM_WINDOW_TYPE_POPUP_MENU + to the window's _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This attribute + has no effect on non-X11 platforms. \note Qt automatically sets this + attribute for QMenu. + + \value WA_X11NetWmWindowTypeToolTip Adds _NET_WM_WINDOW_TYPE_TOOLTIP to the + window's _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This attribute + has no effect on non-X11 platforms. \note Qt automatically sets this + attribute for the Qt::ToolTip window type. + + \value WA_X11NetWmWindowTypeNotification Adds + _NET_WM_WINDOW_TYPE_NOTIFICATION to the window's _NET_WM_WINDOW_TYPE X11 + window property. See http://standards.freedesktop.org/wm-spec/ for more + details. This attribute has no effect on non-X11 platforms. + + \value WA_X11NetWmWindowTypeCombo Adds _NET_WM_WINDOW_TYPE_COMBO + to the window's _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This attribute + has no effect on non-X11 platforms. \note Qt automatically sets this + attribute for the QComboBox pop-up. + + \value WA_X11NetWmWindowTypeDND Adds _NET_WM_WINDOW_TYPE_DND to + the window's _NET_WM_WINDOW_TYPE X11 window property. See + http://standards.freedesktop.org/wm-spec/ for more details. This attribute + has no effect on non-X11 platforms. \note Qt automatically sets this + attribute on the feedback widget used during a drag. + + \value WA_MacFrameworkScaled Enables resolution independence aware mode + on Mac when using Carbon. This attribute has no effect on Cocoa. + The attribute is off by default and can be enabled on a per-window basis. + + \value WA_AcceptTouchEvents Allows touch events (see QTouchEvent) + to be sent to the widget. Must be set on all widgets that can + handle touch events. Without this attribute set, events from a + touch device will be sent as mouse events. + + \value WA_TouchPadAcceptSingleTouchEvents Allows touchpad single + touch events to be sent to the widget. + + \omitvalue WA_SetLayoutDirection + \omitvalue WA_InputMethodTransparent + \omitvalue WA_WState_CompressKeys + \omitvalue WA_WState_ConfigPending + \omitvalue WA_WState_Created + \omitvalue WA_WState_DND + \omitvalue WA_WState_ExplicitShowHide + \omitvalue WA_WState_Hidden + \omitvalue WA_WState_InPaintEvent + \omitvalue WA_WState_OwnSizePolicy + \omitvalue WA_WState_Polished + \omitvalue WA_WState_Reparented + \omitvalue WA_WState_Visible + \omitvalue WA_SetWindowIcon + \omitvalue WA_PendingUpdate + \omitvalue WA_LaidOut + \omitvalue WA_GrabbedShortcut + \omitvalue WA_DontShowOnScreen + \omitvalue WA_InvalidSize + \omitvalue WA_ForceUpdatesDisabled + \omitvalue WA_NoX11EventCompression + \omitvalue WA_TintedBackground + \omitvalue WA_X11OpenGLOverlay + \omitvalue WA_CanHostQMdiSubWindowTitleBar + \omitvalue WA_AttributeCount + \omitvalue WA_StyleSheet + \omitvalue WA_X11BypassTransientForHint + \omitvalue WA_SetWindowModality + \omitvalue WA_WState_WindowOpacitySet + \omitvalue WA_WState_AcceptedTouchBeginEvent +*/ + +/*! \typedef Qt::HANDLE + + Platform-specific handle type for system objects. This is + equivalent to \c{void *} on Mac OS X and embedded Linux, + and to \c{unsigned long} on X11. On Windows it is the + DWORD returned by the Win32 function getCurrentThreadId(). + + \warning Using this type is not portable. +*/ + +/*! + \enum Qt::Key + + The key names used by Qt. + + \value Key_Escape + \value Key_Tab + \value Key_Backtab + \omitvalue Key_BackTab + \value Key_Backspace + \omitvalue Key_BackSpace + \value Key_Return + \value Key_Enter Typically located on the keypad. + \value Key_Insert + \value Key_Delete + \value Key_Pause + \value Key_Print + \value Key_SysReq + \value Key_Clear + \value Key_Home + \value Key_End + \value Key_Left + \value Key_Up + \value Key_Right + \value Key_Down + \value Key_PageUp + \omitvalue Key_Prior + \value Key_PageDown + \omitvalue Key_Next + \value Key_Shift + \value Key_Control On Mac OS X, this corresponds to the Command keys. + \value Key_Meta On Mac OS X, this corresponds to the Control keys. + On Windows keyboards, this key is mapped to the + Windows key. + \value Key_Alt + \value Key_AltGr On Windows, when the KeyDown event for this key is + sent, the Ctrl+Alt modifiers are also set. + \value Key_CapsLock + \value Key_NumLock + \value Key_ScrollLock + \value Key_F1 + \value Key_F2 + \value Key_F3 + \value Key_F4 + \value Key_F5 + \value Key_F6 + \value Key_F7 + \value Key_F8 + \value Key_F9 + \value Key_F10 + \value Key_F11 + \value Key_F12 + \value Key_F13 + \value Key_F14 + \value Key_F15 + \value Key_F16 + \value Key_F17 + \value Key_F18 + \value Key_F19 + \value Key_F20 + \value Key_F21 + \value Key_F22 + \value Key_F23 + \value Key_F24 + \value Key_F25 + \value Key_F26 + \value Key_F27 + \value Key_F28 + \value Key_F29 + \value Key_F30 + \value Key_F31 + \value Key_F32 + \value Key_F33 + \value Key_F34 + \value Key_F35 + \value Key_Super_L + \value Key_Super_R + \value Key_Menu + \value Key_Hyper_L + \value Key_Hyper_R + \value Key_Help + \value Key_Direction_L + \value Key_Direction_R + \value Key_Space + \value Key_Any + \value Key_Exclam + \value Key_QuoteDbl + \value Key_NumberSign + \value Key_Dollar + \value Key_Percent + \value Key_Ampersand + \value Key_Apostrophe + \value Key_ParenLeft + \value Key_ParenRight + \value Key_Asterisk + \value Key_Plus + \value Key_Comma + \value Key_Minus + \value Key_Period + \value Key_Slash + \value Key_0 + \value Key_1 + \value Key_2 + \value Key_3 + \value Key_4 + \value Key_5 + \value Key_6 + \value Key_7 + \value Key_8 + \value Key_9 + \value Key_Colon + \value Key_Semicolon + \value Key_Less + \value Key_Equal + \value Key_Greater + \value Key_Question + \value Key_At + \value Key_A + \value Key_B + \value Key_C + \value Key_D + \value Key_E + \value Key_F + \value Key_G + \value Key_H + \value Key_I + \value Key_J + \value Key_K + \value Key_L + \value Key_M + \value Key_N + \value Key_O + \value Key_P + \value Key_Q + \value Key_R + \value Key_S + \value Key_T + \value Key_U + \value Key_V + \value Key_W + \value Key_X + \value Key_Y + \value Key_Z + \value Key_BracketLeft + \value Key_Backslash + \value Key_BracketRight + \value Key_AsciiCircum + \value Key_Underscore + \value Key_QuoteLeft + \value Key_BraceLeft + \value Key_Bar + \value Key_BraceRight + \value Key_AsciiTilde + \value Key_nobreakspace + \value Key_exclamdown + \value Key_cent + \value Key_sterling + \value Key_currency + \value Key_yen + \value Key_brokenbar + \value Key_section + \value Key_diaeresis + \value Key_copyright + \value Key_ordfeminine + \value Key_guillemotleft + \value Key_notsign + \value Key_hyphen + \value Key_registered + \value Key_macron + \value Key_degree + \value Key_plusminus + \value Key_twosuperior + \value Key_threesuperior + \value Key_acute + \value Key_mu + \value Key_paragraph + \value Key_periodcentered + \value Key_cedilla + \value Key_onesuperior + \value Key_masculine + \value Key_guillemotright + \value Key_onequarter + \value Key_onehalf + \value Key_threequarters + \value Key_questiondown + \value Key_Agrave + \value Key_Aacute + \value Key_Acircumflex + \value Key_Atilde + \value Key_Adiaeresis + \value Key_Aring + \value Key_AE + \value Key_Ccedilla + \value Key_Egrave + \value Key_Eacute + \value Key_Ecircumflex + \value Key_Ediaeresis + \value Key_Igrave + \value Key_Iacute + \value Key_Icircumflex + \value Key_Idiaeresis + \value Key_ETH + \value Key_Ntilde + \value Key_Ograve + \value Key_Oacute + \value Key_Ocircumflex + \value Key_Otilde + \value Key_Odiaeresis + \value Key_multiply + \value Key_Ooblique + \value Key_Ugrave + \value Key_Uacute + \value Key_Ucircumflex + \value Key_Udiaeresis + \value Key_Yacute + \value Key_THORN + \value Key_ssharp + \omitvalue Key_agrave + \omitvalue Key_aacute + \omitvalue Key_acircumflex + \omitvalue Key_atilde + \omitvalue Key_adiaeresis + \omitvalue Key_aring + \omitvalue Key_ae + \omitvalue Key_ccedilla + \omitvalue Key_egrave + \omitvalue Key_eacute + \omitvalue Key_ecircumflex + \omitvalue Key_ediaeresis + \omitvalue Key_igrave + \omitvalue Key_iacute + \omitvalue Key_icircumflex + \omitvalue Key_idiaeresis + \omitvalue Key_eth + \omitvalue Key_ntilde + \omitvalue Key_ograve + \omitvalue Key_oacute + \omitvalue Key_ocircumflex + \omitvalue Key_otilde + \omitvalue Key_odiaeresis + \value Key_division + \omitvalue Key_oslash + \omitvalue Key_ugrave + \omitvalue Key_uacute + \omitvalue Key_ucircumflex + \omitvalue Key_udiaeresis + \omitvalue Key_yacute + \omitvalue Key_thorn + \value Key_ydiaeresis + \value Key_Multi_key + \value Key_Codeinput + \value Key_SingleCandidate + \value Key_MultipleCandidate + \value Key_PreviousCandidate + \value Key_Mode_switch + \value Key_Kanji + \value Key_Muhenkan + \value Key_Henkan + \value Key_Romaji + \value Key_Hiragana + \value Key_Katakana + \value Key_Hiragana_Katakana + \value Key_Zenkaku + \value Key_Hankaku + \value Key_Zenkaku_Hankaku + \value Key_Touroku + \value Key_Massyo + \value Key_Kana_Lock + \value Key_Kana_Shift + \value Key_Eisu_Shift + \value Key_Eisu_toggle + \value Key_Hangul + \value Key_Hangul_Start + \value Key_Hangul_End + \value Key_Hangul_Hanja + \value Key_Hangul_Jamo + \value Key_Hangul_Romaja + \value Key_Hangul_Jeonja + \value Key_Hangul_Banja + \value Key_Hangul_PreHanja + \value Key_Hangul_PostHanja + \value Key_Hangul_Special + \value Key_Dead_Grave + \value Key_Dead_Acute + \value Key_Dead_Circumflex + \value Key_Dead_Tilde + \value Key_Dead_Macron + \value Key_Dead_Breve + \value Key_Dead_Abovedot + \value Key_Dead_Diaeresis + \value Key_Dead_Abovering + \value Key_Dead_Doubleacute + \value Key_Dead_Caron + \value Key_Dead_Cedilla + \value Key_Dead_Ogonek + \value Key_Dead_Iota + \value Key_Dead_Voiced_Sound + \value Key_Dead_Semivoiced_Sound + \value Key_Dead_Belowdot + \value Key_Dead_Hook + \value Key_Dead_Horn + \value Key_Back + \value Key_Forward + \value Key_Stop + \value Key_Refresh + \value Key_VolumeDown + \value Key_VolumeMute + \value Key_VolumeUp + \value Key_BassBoost + \value Key_BassUp + \value Key_BassDown + \value Key_TrebleUp + \value Key_TrebleDown + \value Key_MediaPlay + \value Key_MediaStop + \value Key_MediaPrevious + \omitvalue Key_MediaPrev + \value Key_MediaNext + \value Key_MediaRecord + \value Key_HomePage + \value Key_Favorites + \value Key_Search + \value Key_Standby + \value Key_OpenUrl + \value Key_LaunchMail + \value Key_LaunchMedia + \value Key_Launch0 + \value Key_Launch1 + \value Key_Launch2 + \value Key_Launch3 + \value Key_Launch4 + \value Key_Launch5 + \value Key_Launch6 + \value Key_Launch7 + \value Key_Launch8 + \value Key_Launch9 + \value Key_LaunchA + \value Key_LaunchB + \value Key_LaunchC + \value Key_LaunchD + \value Key_LaunchE + \value Key_LaunchF + \value Key_MediaLast + \value Key_unknown + + \value Key_Call + \value Key_Context1 + \value Key_Context2 + \value Key_Context3 + \value Key_Context4 + \value Key_Flip + \value Key_Hangup + \value Key_No + \value Key_Select + \value Key_Yes + + \value Key_Execute + \value Key_Printer + \value Key_Play + \value Key_Sleep + \value Key_Zoom + \value Key_Cancel + + \sa QKeyEvent::key() +*/ + +/*! + \enum Qt::HitTestAccuracy + + This enum contains the types of accuracy that can be used by the + QTextDocument class when testing for mouse clicks on text documents. + + \value ExactHit The point at which input occurred must coincide + exactly with input-sensitive parts of the document. + \value FuzzyHit The point at which input occurred can lie close to + input-sensitive parts of the document. + + This enum is defined in the \c header file. +*/ + +/*! + \enum Qt::WhiteSpaceMode + + This enum describes the types of whitespace mode that are used by + the QTextDocument class to meet the requirements of different kinds + of textual information. + + \value WhiteSpaceNormal The whitespace mode used to display + normal word wrapped text in paragraphs. + \value WhiteSpacePre A preformatted text mode in which + whitespace is reproduced exactly. + \value WhiteSpaceNoWrap + + \omitvalue WhiteSpaceModeUndefined + + This enum is defined in the \c header file. +*/ + +/*! + \enum Qt::ButtonState_enum + \compat + \value ShiftButton + \value ControlButton + \value AltButton + \value MetaButton + \value Keypad + \value KeyButtonMask + + Use Qt::KeyboardModifier instead. +*/ + +/*! + \typedef Qt::ButtonState + \compat + + Use Qt::KeyboardModifier instead. +*/ + +/*! + \enum Qt::CheckState + + This enum describes the state of checkable items, controls, and widgets. + + \value Unchecked The item is unchecked. + \value PartiallyChecked The item is partially checked. Items in hierarchical models + may be partially checked if some, but not all, of their + children are checked. + \value Checked The item is checked. + + \sa QCheckBox, Qt::ItemFlags, Qt::ItemDataRole +*/ + + +/*! + \enum Qt::ToolButtonStyle + + The style of the tool button, describing how the button's text and + icon should be displayed. + + \value ToolButtonIconOnly Only display the icon. + \value ToolButtonTextOnly Only display the text. + \value ToolButtonTextBesideIcon The text appears beside the icon. + \value ToolButtonTextUnderIcon The text appears under the icon. + \value ToolButtonFollowStyle Follow the \l{QStyle::SH_ToolButtonStyle}{style}. +*/ + +/*! + \enum Qt::Corner + + This enum type specifies a corner in a rectangle: + + \value TopLeftCorner The top-left corner of the rectangle. + \value TopRightCorner The top-right corner of the rectangle. + \value BottomLeftCorner The bottom-left corner of the rectangle. + \value BottomRightCorner The bottom-right corner of the rectangle. + + \omitvalue TopLeft + \omitvalue TopRight + \omitvalue BottomLeft + \omitvalue BottomRight +*/ + +/*! + \enum Qt::ScrollBarPolicy + + This enum type describes the various modes of QAbstractScrollArea's scroll + bars. + + \value ScrollBarAsNeeded QAbstractScrollArea shows a scroll bar when the + content is too large to fit and not otherwise. This is the + default. + + \value ScrollBarAlwaysOff QAbstractScrollArea never shows a scroll bar. + + \value ScrollBarAlwaysOn QAbstractScrollArea always shows a scroll bar. + + (The modes for the horizontal and vertical scroll bars are + independent.) +*/ + +/*! + \enum Qt::ArrowType + + \value NoArrow + \value UpArrow + \value DownArrow + \value LeftArrow + \value RightArrow +*/ + +/*! + \enum Qt::FocusReason + + This enum specifies why the focus changed. It will be passed + through QWidget::setFocus and can be retrieved in the QFocusEvent + sent to the widget upon focus change. + + \value MouseFocusReason A mouse action occurred. + \value TabFocusReason The Tab key was pressed. + \value BacktabFocusReason A Backtab occurred. The input for this may + include the Shift or Control keys; + e.g. Shift+Tab. + \value ActiveWindowFocusReason The window system made this window either + active or inactive. + \value PopupFocusReason The application opened/closed a pop-up that + grabbed/released the keyboard focus. + \value ShortcutFocusReason The user typed a label's buddy shortcut + \value MenuBarFocusReason The menu bar took focus. + \value OtherFocusReason Another reason, usually application-specific. + + \omitvalue NoFocusReason + + \sa {Keyboard Focus} +*/ + +/*! + \enum Qt::WindowState + + \keyword window state + + This enum type is used to specify the current state of a top-level + window. + + The states are + + \value WindowNoState The window has no state set (in normal state). + \value WindowMinimized The window is minimized (i.e. iconified). + \value WindowMaximized The window is maximized with a frame around it. + \value WindowFullScreen The window fills the entire screen without any frame around it. + \value WindowActive The window is the active window, i.e. it has keyboard focus. + +*/ + +/*! + \enum Qt::ContextMenuPolicy + + This enum type defines the various policies a widget can have with + respect to showing a context menu. + + \value NoContextMenu the widget does not feature a context menu, + context menu handling is deferred to the widget's parent. + \value PreventContextMenu the widget does not feature a context + menu, and in contrast to \c NoContextMenu, the handling is \e not + deferred to the widget's parent. This means that all right mouse + button events are guaranteed to be delivered to the widget itself + through mousePressEvent(), and mouseReleaseEvent(). + \value DefaultContextMenu the widget's QWidget::contextMenuEvent() handler is called. + \value ActionsContextMenu the widget displays its QWidget::actions() as context menu. + \value CustomContextMenu the widget emits the QWidget::customContextMenuRequested() signal. +*/ + +/*! + \enum Qt::FocusPolicy + + This enum type defines the various policies a widget can have with + respect to acquiring keyboard focus. + + \value TabFocus the widget accepts focus by tabbing. + \value ClickFocus the widget accepts focus by clicking. + \value StrongFocus the widget accepts focus by both tabbing + and clicking. On Mac OS X this will also + be indicate that the widget accepts tab focus + when in 'Text/List focus mode'. + \value WheelFocus like Qt::StrongFocus plus the widget accepts + focus by using the mouse wheel. + \value NoFocus the widget does not accept focus. + +*/ + +/*! + \enum Qt::ShortcutContext + + For a QEvent::Shortcut event to occur, the shortcut's key sequence + must be entered by the user in a context where the shortcut is + active. The possible contexts are these: + + \value WidgetShortcut The shortcut is active when its + parent widget has focus. + \value WidgetWithChildrenShortcut The shortcut is active + when its parent widget, or any of its children has focus. + Children which are top-level widgets, except pop-ups, are + not affected by this shortcut context. + \value WindowShortcut The shortcut is active when its + parent widget is a logical subwidget of the + active top-level window. + \value ApplicationShortcut The shortcut is active when one of + the applications windows are active. +*/ + +/*! + \typedef Qt::WFlags + + Synonym for Qt::WindowFlags. +*/ + +/*! + \enum Qt::WindowType + + \keyword window flag + + This enum type is used to specify various window-system properties + for the widget. They are fairly unusual but necessary in a few + cases. Some of these flags depend on whether the underlying window + manager supports them. + + The main types are + + \value Widget This is the default type for QWidget. Widgets of + this type are child widgets if they have a parent, + and independent windows if they have no parent. + See also Qt::Window and Qt::SubWindow. + + \value Window Indicates that the widget is a window, usually + with a window system frame and a title bar, + irrespective of whether the widget has a parent or + not. Note that it is not possible to unset this + flag if the widget does not have a parent. + + \value Dialog Indicates that the widget is a window that should + be decorated as a dialog (i.e., typically no + maximize or minimize buttons in the title bar). + This is the default type for QDialog. If you want + to use it as a modal dialog, it should be launched + from another window, or have a parent and used + with the QWidget::windowModality property. If you make + it modal, the dialog will prevent other top-level + windows in the application from getting any input. + We refer to a top-level window that has a parent + as a \e secondary window. + + \value Sheet Indicates that the widget is a Macintosh sheet. + + \value Drawer Indicates that the widget is a Macintosh drawer. + + \value Popup Indicates that the widget is a pop-up top-level + window, i.e. that it is modal, but has a window + system frame appropriate for pop-up menus. + + \value Tool Indicates that the widget is a tool window. A tool + window is often a small window with a smaller than + usual title bar and decoration, typically used for + collections of tool buttons. It there is a parent, + the tool window will always be kept on top of it. + If there isn't a parent, you may consider using + Qt::WindowStaysOnTopHint as well. If the window + system supports it, a tool window can be decorated + with a somewhat lighter frame. It can also be + combined with Qt::FramelessWindowHint. + \br + \br + On Mac OS X, tool windows correspond to the + \l{http://developer.apple.com/documentation/Carbon/Conceptual/HandlingWindowsControls/hitb-wind_cont_concept/chapter_2_section_2.html}{Floating} + class of windows. This means that the window lives on a + level above normal windows; it impossible to put a normal + window on top of it. By default, tool windows will disappear + when the application is inactive. This can be controlled by + the Qt::WA_MacAlwaysShowToolWindow attribute. + + \value ToolTip Indicates that the widget is a tooltip. This is + used internally to implement + \l{QWidget::toolTip}{tooltips}. + + \value SplashScreen Indicates that the window is a splash screen. + This is the default type for QSplashScreen. + + \value Desktop Indicates that this widget is the desktop. This + is the type for QDesktopWidget. + + \value SubWindow Indicates that this widget is a sub-window, such + as a QMdiSubWindow widget. + + There are also a number of flags which you can use to customize + the appearance of top-level windows. These have no effect on other + windows: + + \value MSWindowsFixedSizeDialogHint Gives the window a thin dialog border on Windows. + This style is traditionally used for fixed-size dialogs. + + \value MSWindowsOwnDC Gives the window its own display + context on Windows. + + \value X11BypassWindowManagerHint Bypass the window + manager completely. This results in a borderless window + that is not managed at all (i.e., no keyboard input unless + you call QWidget::activateWindow() manually). + + \value FramelessWindowHint Produces a borderless window. + The user cannot move or resize a borderless window via the window + system. On X11, the result of the flag is dependent on the window manager and its + ability to understand Motif and/or NETWM hints. Most existing + modern window managers can handle this. + + The \c CustomizeWindowHint flag is used to enable customization of + the window controls. This flag must be set to allow the \c + WindowTitleHint, \c WindowSystemMenuHint, \c + WindowMinimizeButtonHint, \c WindowMaximizeButtonHint and \c + WindowCloseButtonHint flags to be changed. + + \value CustomizeWindowHint Turns off the default window title hints. + + \value WindowTitleHint Gives the window a title bar. + + \value WindowSystemMenuHint Adds a window system menu, and + possibly a close button (for example on Mac). If you need to hide + or show a close button, it is more portable to use \c + WindowCloseButtonHint. + + \value WindowMinimizeButtonHint Adds a minimize button. On + some platforms this implies Qt::WindowSystemMenuHint for it to work. + + \value WindowMaximizeButtonHint Adds a maximize button. On + some platforms this implies Qt::WindowSystemMenuHint for it to work. + + \value WindowMinMaxButtonsHint Adds a minimize and a maximize + button. On some platforms this implies Qt::WindowSystemMenuHint for it to work. + + \value WindowCloseButtonHint Adds a close button. On + some platforms this implies Qt::WindowSystemMenuHint for it + to work. + + \value WindowContextHelpButtonHint Adds a context help button to dialogs. + On some platforms this implies Qt::WindowSystemMenuHint for it to work. + + \value MacWindowToolBarButtonHint On Mac OS X adds a tool bar button (i.e., + the oblong button that is on the top right of windows that have toolbars. + + \value BypassGraphicsProxyWidget Prevents the window and its children from + automatically embedding themselves into a QGraphicsProxyWidget if the + parent widget is already embedded. You can set this flag if you + want your widget to always be a toplevel widget on the desktop, + regardless of whether the parent widget is embedded in a scene or + not. + + \value WindowShadeButtonHint + + \value WindowStaysOnTopHint Informs the window system that the + window should stay on top of all other windows. Note that + on some window managers on X11 you also have to pass + Qt::X11BypassWindowManagerHint for this flag to work + correctly. + + \value WindowStaysOnBottomHint Informs the window system that the + window should stay on bottom of all other windows. Note + that on X11 this hint will work only in window managers + that support _NET_WM_STATE_BELOW atom. If a window always + on the bottom has a parent, the parent will also be left on + the bottom. This window hint is currently not implemented + for Mac OS X. + + \value WindowOkButtonHint Adds an OK button to the window decoration of a dialog. + Only supported for Windows CE. + + \value WindowCancelButtonHint Adds a Cancel button to the window decoration of a dialog. + Only supported for Windows CE. + + \value WindowType_Mask A mask for extracting the window type + part of the window flags. + + Obsolete flags: + + \value WMouseNoMask Use Qt::WA_MouseNoMask instead. + \value WDestructiveClose Use Qt::WA_DeleteOnClose instead. + \value WStaticContents Use Qt::WA_StaticContents instead. + \value WGroupLeader No longer needed. + \value WShowModal Use QWidget::windowModality instead. + \value WNoMousePropagation Use Qt::WA_NoMousePropagation instead. + \value WType_TopLevel Use Qt::Window instead. + \value WType_Dialog Use Qt::Dialog instead. + \value WType_Popup Use Qt::Popup instead. + \value WType_Desktop Use Qt::Desktop instead. + \value WType_Mask Use Qt::WindowType_Mask instead. + + \value WStyle_Customize No longer needed. + \value WStyle_NormalBorder No longer needed. + \value WStyle_DialogBorder Use Qt::MSWindowsFixedSizeDialogHint instead. + \value WStyle_NoBorder Use Qt::FramelessWindowHint instead. + \value WStyle_Title Use Qt::WindowTitleHint instead. + \value WStyle_SysMenu Use Qt::WindowSystemMenuHint instead. + \value WStyle_Minimize Use Qt::WindowMinimizeButtonHint instead. + \value WStyle_Maximize Use Qt::WindowMaximizeButtonHint instead. + \value WStyle_MinMax Use Qt::WindowMinMaxButtonsHint instead. + \value WStyle_Tool Use Qt::Tool instead. + \value WStyle_StaysOnTop Use Qt::WindowStaysOnTopHint instead. + \value WStyle_ContextHelp Use Qt::WindowContextHelpButtonHint instead. + + \value WPaintDesktop No longer needed. + \value WPaintClever No longer needed. + + \value WX11BypassWM Use Qt::X11BypassWindowManagerHint instead. + \value WWinOwnDC Use Qt::MSWindowsOwnDC instead. + \value WMacSheet Use Qt::Sheet instead. + \value WMacDrawer Use Qt::Drawer instead. + + \value WStyle_Splash Use Qt::SplashScreen instead. + + \value WNoAutoErase No longer needed. + \value WRepaintNoErase No longer needed. + \value WNorthWestGravity Use Qt::WA_StaticContents instead. + \value WType_Modal Use Qt::Dialog and QWidget::windowModality instead. + \value WStyle_Dialog Use Qt::Dialog instead. + \value WStyle_NoBorderEx Use Qt::FramelessWindowHint instead. + \value WResizeNoErase No longer needed. + \value WMacNoSheet No longer needed. + + \sa QWidget::windowFlags, {Window Flags Example} +*/ + +/*! + \enum Qt::DropAction + + \value CopyAction Copy the data to the target. + \value MoveAction Move the data from the source to the target. + \value LinkAction Create a link from the source to the target. + \value ActionMask + \value IgnoreAction Ignore the action (do nothing with the data). + \value TargetMoveAction On Windows, this value is used when the ownership of the D&D data + should be taken over by the target application, + i.e., the source application should not delete + the data. + \br + On X11 this value is used to do a move. + \br + TargetMoveAction is not used on the Mac. +*/ + +#if defined(Q_OS_WIN) && defined(QT3_SUPPORT) +/*! + \enum Qt::WindowsVersion + \compat + + \value WV_32s + \value WV_95 + \value WV_98 + \value WV_Me + \value WV_DOS_based + \value WV_NT + \value WV_2000 + \value WV_XP + \value WV_2003 + \value WV_NT_based + \value WV_CE + \value WV_CENET + \value WV_CE_based + \value WV_CE_5 + \value WV_CE_6 +*/ +#endif + +#if defined(Q_OS_MAC) && defined(QT3_SUPPORT) +/*! + \enum Qt::MacintoshVersion + \compat + + \value MV_Unknown Use QSysInfo::MV_Unknown instead. + \value MV_9 Use QSysInfo::MV_9 instead. + \value MV_10_DOT_0 Use QSysInfo::MV_10_0 instead. + \value MV_10_DOT_1 Use QSysInfo::MV_10_1 instead. + \value MV_10_DOT_2 Use QSysInfo::MV_10_2 instead. + \value MV_10_DOT_3 Use QSysInfo::MV_10_3 instead. + \value MV_10_DOT_4 Use QSysInfo::MV_10_4 instead. + + \value MV_CHEETAH Use QSysInfo::MV_10_0 instead. + \value MV_PUMA Use QSysInfo::MV_10_1 instead. + \value MV_JAGUAR Use QSysInfo::MV_10_2 instead. + \value MV_PANTHER Use QSysInfo::MV_10_3 instead. + \value MV_TIGER Use QSysInfo::MV_10_4 instead. + + \sa QSysInfo::MacVersion +*/ +#endif + +/*! \typedef Qt::ToolBarDock + \compat + + Use Qt::Dock instead. +*/ + +/*! + \enum Qt::Dock + \compat + + Each dock window can be in one of the following positions: + + \value DockUnmanaged not managed by a Q3MainWindow. + + \value DockTornOff the dock window floats as its own top level + window which always stays on top of the main window. + + \value DockTop above the central widget, below the menu bar. + + \value DockBottom below the central widget, above the status bar. + + \value DockRight to the right of the central widget. + + \value DockLeft to the left of the central widget. + + \value DockMinimized the dock window is not shown (this is + effectively a 'hidden' dock area); the handles of all minimized + dock windows are drawn in one row below the menu bar. + + \omitvalue Bottom + \omitvalue Left + \omitvalue Minimized + \omitvalue Right + \omitvalue Top + \omitvalue TornOff + \omitvalue Unmanaged +*/ + +/*! + \enum Qt::AnchorAttribute + + An anchor has one or more of the following attributes: + + \value AnchorName the name attribute of the anchor. This attribute is + used when scrolling to an anchor in the document. + + \value AnchorHref the href attribute of the anchor. This attribute is + used when a link is clicked to determine what content to load. +*/ + +/*! + \enum Qt::SortOrder + + This enum describes how the items in a widget are sorted. + + \value AscendingOrder The items are sorted ascending e.g. starts with + 'AAA' ends with 'ZZZ' in Latin-1 locales + + \value DescendingOrder The items are sorted descending e.g. starts with + 'ZZZ' ends with 'AAA' in Latin-1 locales + + \omitvalue Ascending + \omitvalue Descending +*/ + +/*! + \enum Qt::ClipOperation + + \value NoClip This operation turns clipping off. + + \value ReplaceClip Replaces the current clip path/rect/region with + the one supplied in the function call. + + \value IntersectClip Intersects the current clip path/rect/region + with the one supplied in the function call. + + \value UniteClip Unites the current clip path/rect/region with the + one supplied in the function call. +*/ + +/*! + \enum Qt::ItemSelectionMode + + This enum is used in QGraphicsItem, QGraphicsScene and QGraphicsView to + specify how items are selected, or how to determine if a shapes and items + collide. + + \value ContainsItemShape The output list contains only items whose + \l{QGraphicsItem::shape()}{shape} is fully contained inside the + selection area. Items that intersect with the area's outline are + not included. + + \value IntersectsItemShape The output list contains both items whose + \l{QGraphicsItem::shape()}{shape} is fully contained inside the + selection area, and items that intersect with the area's + outline. This is a common mode for rubber band selection. + + \value ContainsItemBoundingRect The output list contains only items whose + \l{QGraphicsItem::boundingRect()}{bounding rectangle} is fully + contained inside the selection area. Items that intersect with the + area's outline are not included. + + \value IntersectsItemBoundingRect The output list contains both items + whose \l{QGraphicsItem::boundingRect()}{bounding rectangle} is + fully contained inside the selection area, and items that intersect + with the area's outline. This method is commonly used for + determining areas that need redrawing. + + \sa QGraphicsScene::items(), QGraphicsScene::collidingItems(), + QGraphicsView::items(), QGraphicsItem::collidesWithItem(), + QGraphicsItem::collidesWithPath() +*/ + +/*! + \enum Qt::FillRule + + Specifies which method should be used to fill the paths and polygons. + + \value OddEvenFill Specifies that the region is filled using the + odd even fill rule. With this rule, we determine whether a point + is inside the shape by using the following method. + Draw 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 mode is the + default. + + \value WindingFill Specifies that the region is filled using the + non zero winding rule. With this rule, we determine whether a + point is inside the shape by using the following method. + Draw a horizontal line from the point to a location outside the shape. + Determine 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. This fill mode can also in most cases be considered + as the intersection of closed shapes. +*/ + +/*! + \enum Qt::PaintUnit + + \compat + + \value PixelUnit + \value LoMetricUnit Obsolete + \value HiMetricUnit Obsolete + \value LoEnglishUnit Obsolete + \value HiEnglishUnit Obsolete + \value TwipsUnit Obsolete +*/ + +/*! + \enum Qt::TextFormat + + This enum is used in widgets that can display both plain text and + rich text, e.g. QLabel. It is used for deciding whether a text + string should be interpreted as one or the other. This is normally + done by passing one of the enum values to a setTextFormat() + function. + + \value PlainText The text string is interpreted as a plain text + string. + + \value RichText The text string is interpreted as a rich text + string. + + \value AutoText The text string is interpreted as for + Qt::RichText if Qt::mightBeRichText() returns true, otherwise + as Qt::PlainText. + + \value LogText A special, limited text format which is only used + by Q3TextEdit in an optimized mode. +*/ + +/*! + \enum Qt::CursorShape + + This enum type defines the various cursors that can be used. + + The standard arrow cursor is the default for widgets in a normal state. + + \value ArrowCursor \inlineimage cursor-arrow.png + The standard arrow cursor. + \value UpArrowCursor \inlineimage cursor-uparrow.png + An arrow pointing upwards toward the top of the screen. + \value CrossCursor \inlineimage cursor-cross.png + A crosshair cursor, typically used to help the + user accurately select a point on the screen. + \value WaitCursor \inlineimage cursor-wait.png + An hourglass or watch cursor, usually shown during + operations that prevent the user from interacting with + the application. + \value IBeamCursor \inlineimage cursor-ibeam.png + A caret or ibeam cursor, indicating that a widget can + accept and display text input. + \value SizeVerCursor \inlineimage cursor-sizev.png + A cursor used for elements that are used to vertically + resize top-level windows. + \value SizeHorCursor \inlineimage cursor-sizeh.png + A cursor used for elements that are used to horizontally + resize top-level windows. + \value SizeBDiagCursor \inlineimage cursor-sizeb.png + A cursor used for elements that are used to diagonally + resize top-level windows at their top-right and + bottom-left corners. + \value SizeFDiagCursor \inlineimage cursor-sizef.png + A cursor used for elements that are used to diagonally + resize top-level windows at their top-left and + bottom-right corners. + \value SizeAllCursor \inlineimage cursor-sizeall.png + A cursor used for elements that are used to resize + top-level windows in any direction. + \value BlankCursor A blank/invisible cursor, typically used when the cursor + shape needs to be hidden. + \value SplitVCursor \inlineimage cursor-vsplit.png + A cursor used for vertical splitters, indicating that + a handle can be dragged horizontally to adjust the use + of available space. + \value SplitHCursor \inlineimage cursor-hsplit.png + A cursor used for horizontal splitters, indicating that + a handle can be dragged vertically to adjust the use + of available space. + \value PointingHandCursor \inlineimage cursor-hand.png + A pointing hand cursor that is typically used for + clickable elements such as hyperlinks. + \value ForbiddenCursor \inlineimage cursor-forbidden.png + A slashed circle cursor, typically used during drag + and drop operations to indicate that dragged content + cannot be dropped on particular widgets or inside + certain regions. + \value OpenHandCursor \inlineimage cursor-openhand.png + A cursor representing an open hand, typically used to + indicate that the area under the cursor is the visible + part of a canvas that the user can click and drag in + order to scroll around. + \value ClosedHandCursor \inlineimage cursor-closedhand.png + A cursor representing a closed hand, typically used to + indicate that a dragging operation is in progress that + involves scrolling. + \value WhatsThisCursor \inlineimage cursor-whatsthis.png + An arrow with a question mark, typically used to indicate + the presence of What's This? help for a widget. + \value BusyCursor \inlineimage cursor-wait.png + An hourglass or watch cursor, usually shown during + operations that allow the user to interact with + the application while they are performed in the + background. + \value BitmapCursor + \omitvalue LastCursor + \omitvalue CustomCursor + + \omitvalue arrowCursor + \omitvalue upArrowCursor + \omitvalue crossCursor + \omitvalue waitCursor + \omitvalue ibeamCursor + \omitvalue sizeVerCursor + \omitvalue sizeHorCursor + \omitvalue sizeBDiagCursor + \omitvalue sizeFDiagCursor + \omitvalue sizeAllCursor + \omitvalue blankCursor + \omitvalue splitVCursor + \omitvalue splitHCursor + \omitvalue pointingHandCursor + \omitvalue forbiddenCursor + \omitvalue whatsThisCursor +*/ + +/*! + \typedef Qt::TextFlags + \compat + + Use Qt::TextFlag instead. +*/ + +/*! + \enum Qt::LayoutDirection + + Specifies the direction of Qt's layouts: + + \value LeftToRight Left-to-right layout. + \value RightToLeft Right-to-left layout. + + Right-to-left layouts are necessary for certain languages, + notably Arabic and Hebrew. + + \sa QApplication::setLayoutDirection(), QWidget::setLayoutDirection() +*/ + +/*! + \enum Qt::InputMethodQuery + + \value ImMicroFocus The rectangle covering the area of the input cursor in widget coordinates. + \value ImFont The currently used font for text input. + \value ImCursorPosition The logical position of the cursor within the text surrounding the input area (see ImSurroundingText). + If any text is selected, the position returned will be at the logical end of the + selection, even if the real cursor is located at the logical start. + \value ImSurroundingText The plain text around the input area, for example the current paragraph. + \value ImCurrentSelection The currently selected text. +*/ + +/*! + \enum Qt::ItemDataRole + + Each item in the model has a set of data elements associated with + it, each with its own role. The roles are used by the view to indicate + to the model which type of data it needs. + + The general purpose roles are: + + \value DisplayRole The key data to be rendered in the form of text. + \value DecorationRole The data to be rendered as a decoration in the form + of an icon. + \value EditRole The data in a form suitable for editing in an + editor. + \value ToolTipRole The data displayed in the item's tooltip. + \value StatusTipRole The data displayed in the status bar. + \value WhatsThisRole The data displayed for the item in "What's This?" + mode. + \value SizeHintRole The size hint for the item that will be supplied + to views. + + Roles describing appearance and meta data: + + \value FontRole The font used for items rendered with the default + delegate. + \value TextAlignmentRole The alignment of the text for items rendered with the + default delegate. + \value BackgroundRole The background brush used for items rendered with + the default delegate. + \value BackgroundColorRole This role is obsolete. Use BackgroundRole instead. + \value ForegroundRole The foreground brush (text color, typically) + used for items rendered with the default delegate. + \value TextColorRole This role is obsolete. Use ForegroundRole instead. + \value CheckStateRole This role is used to obtain the checked state of + an item (see \l Qt::CheckState). + + Accessibility roles: + + \value AccessibleTextRole The text to be used by accessibility + extensions and plugins, such as screen + readers. + \value AccessibleDescriptionRole A description of the item for accessibility + purposes. + + User roles: + + \value UserRole The first role that can be used for application-specific purposes. + + \omitvalue DisplayPropertyRole + \omitvalue DecorationPropertyRole + \omitvalue ToolTipPropertyRole + \omitvalue StatusTipPropertyRole + \omitvalue WhatsThisPropertyRole +*/ + +/*! + \enum Qt::ItemFlag + + This enum describes the properties of an item: + + \value NoItemFlags It does not have any properties set. + \value ItemIsSelectable It can be selected. + \value ItemIsEditable It can be edited. + \value ItemIsDragEnabled It can be dragged. + \value ItemIsDropEnabled It can be used as a drop target. + \value ItemIsUserCheckable It can be checked or unchecked by the user. + \value ItemIsEnabled The user can interact with the item. + \value ItemIsTristate The item is checkable with three separate states. + + Note that checkable items need to be given both a suitable set of flags + and an initial state, indicating whether the item is checked or not. + This is handled automatically for model/view components, but needs + to be explicitly set for instances of QListWidgetItem, QTableWidgetItem, + and QTreeWidgetItem. + + \sa QAbstractItemModel +*/ + +/*! + \enum Qt::MatchFlag + + This enum describes the type of matches that can be used when searching + for items in a model. + + \value MatchExactly Performs QVariant-based matching. + \value MatchFixedString Performs string-based matching. + String-based comparisons are case-insensitive unless the + \c MatchCaseSensitive flag is also specified. + \value MatchContains The search term is contained in the item. + \value MatchStartsWith The search term matches the start of the item. + \value MatchEndsWith The search term matches the end of the item. + \value MatchCaseSensitive The search is case sensitive. + \value MatchRegExp Performs string-based matching using a regular + expression as the search term. + \value MatchWildcard Performs string-based matching using a string with + wildcards as the search term. + \value MatchWrap Perform a search that wraps around, so that when + the search reaches the last item in the model, it begins again at + the first item and continues until all items have been examined. + \value MatchRecursive Searches the entire hierarchy. + + \sa QString::compare(), QRegExp +*/ + +/*! + \enum Qt::TextElideMode + + This enum specifies where the ellipsis should appear when + displaying texts that don't fit: + + \value ElideLeft The ellipsis should appear at the beginning of the text. + \value ElideRight The ellipsis should appear at the end of the text. + \value ElideMiddle The ellipsis should appear in the middle of the text. + \value ElideNone Ellipsis should NOT appear in the text. + + Qt::ElideMiddle is normally the most appropriate choice for URLs (e.g., + "\l{http://www.qtsoftware.com/careers/movingto/beijing/}{http://www.qtsof...ovingto/beijing/}"), + whereas Qt::ElideRight is appropriate + for other strings (e.g., + "\l{http://doc.trolltech.com/qq/qq09-mac-deployment.html}{Deploying Applications on Ma...}"). + + \sa QAbstractItemView::textElideMode, QFontMetrics::elidedText(), AlignmentFlag QTabBar::elideMode +*/ + +/*! + \enum Qt::WindowModality + + \keyword modal + + This enum specifies the behavior of a modal window. A modal window + is one that blocks input to other windows. Note that windows that + are children of a modal window are not blocked. + + The values are: + \value NonModal The window is not modal and does not block input to other windows. + \value WindowModal The window is modal to a single window hierarchy and blocks input to its parent window, all grandparent windows, and all siblings of its parent and grandparent windows. + \value ApplicationModal The window is modal to the application and blocks input to all windows. + + \sa QWidget::windowModality, QDialog +*/ + +/*! + \enum Qt::TextInteractionFlag + + This enum specifies how a text displaying widget reacts to user input. + + \value NoTextInteraction No interaction with the text is possible. + \value TextSelectableByMouse Text can be selected with the mouse and copied to the clipboard using + a context menu or standard keyboard shortcuts. + \value TextSelectableByKeyboard Text can be selected with the cursor keys on the keyboard. A text cursor is shown. + \value LinksAccessibleByMouse Links can be highlighted and activated with the mouse. + \value LinksAccessibleByKeyboard Links can be focused using tab and activated with enter. + \value TextEditable The text is fully editable. + + \value TextEditorInteraction The default for a text editor. + \value TextBrowserInteraction The default for QTextBrowser. +*/ + +/*! + \enum Qt::MaskMode + + This enum specifies the behavior of the + QPixmap::createMaskFromColor() and QImage::createMaskFromColor() + functions. + + \value MaskInColor Creates a mask where all pixels matching the given color are opaque. + \value MaskOutColor Creates a mask where all pixels matching the given color are transparent. +*/ + +/*! + \enum Qt::DockWidgetAreaSizes + \internal +*/ + +/*! + \enum Qt::ToolBarAreaSizes + \internal +*/ + +/*! + \enum Qt::EventPriority + + This enum can be used to specify event priorities. + + \value HighEventPriority Events with this priority are sent before + events with NormalEventPriority or LowEventPriority. + + \value NormalEventPriority Events with this priority are sent + after events with HighEventPriority, but before events with + LowEventPriority. + + \value LowEventPriority Events with this priority are sent after + events with HighEventPriority or NormalEventPriority. + + Note that these values are provided purely for convenience, since + event priorities can be any value between \c INT_MAX and \c + INT_MIN, inclusive. For example, you can define custom priorities + as being relative to each other: + + \snippet doc/src/snippets/code/doc_src_qnamespace.qdoc 1 + + \sa QCoreApplication::postEvent() +*/ +/*! + \enum Qt::SizeHint + \since 4.4 + + This enum is used by QGraphicsLayoutItem::sizeHint() + + \value MinimumSize is used to specify the minimum size of a graphics layout item. + \value PreferredSize is used to specify the preferred size of a graphics layout item. + \value MaximumSize is used to specify the maximum size of a graphics layout item. + \value MinimumDescent is used to specify the minimum descent of a text string in a graphics layout item. + \omitvalue NSizeHints + + \sa QGraphicsLayoutItem::sizeHint() +*/ + +/*! + \enum Qt::SizeMode + \since 4.4 + + This enum is used by QPainter::drawRoundedRect() and QPainterPath::addRoundedRect() + functions to specify the radii of rectangle corners with respect to the dimensions + of the bounding rectangles specified. + + \value AbsoluteSize Specifies the size using absolute measurements. + \value RelativeSize Specifies the size relative to the bounding rectangle, + typically using percentage measurements. +*/ + +/*! + \enum Qt::WindowFrameSection + \since 4.4 + + This enum is used to describe parts of a window frame. It is returned by + QGraphicsWidget::windowFrameSectionAt() to describe what section of the window + frame is under the mouse. + + \value NoSection + \value LeftSection + \value TopLeftSection + \value TopSection + \value TopRightSection + \value RightSection + \value BottomRightSection + \value BottomSection + \value BottomLeftSection + \value TitleBarArea + + \sa QGraphicsWidget::windowFrameEvent() + \sa QGraphicsWidget::paintWindowFrame() + \sa QGraphicsWidget::windowFrameSectionAt() + +*/ + +/*! + \enum Qt::TileRule + \since 4.6 + + This enum describes how to repeat or stretch the parts of an image + when drawing. + + \value Stretch Scale the image to fit to the available area. + + \value Repeat Tile the image until there is no more space. May crop + the last image. + + \value Round Like Repeat, but scales the images down to ensure that + the last image is not cropped. +*/ + +/*! + \enum Qt::Initialization + \internal +*/ + +/*! + \enum Qt::GestureState + \since 4.6 + + This enum type describes the state of a gesture. + + \omitvalue NoGesture + \value GestureStarted A continuous gesture has started. + \value GestureUpdated A gesture continues. + \value GestureFinished A gesture has finished. + + \sa QGesture +*/ diff --git a/doc/src/qnamespace.qdoc b/doc/src/qnamespace.qdoc deleted file mode 100644 index 2d40fdd..0000000 --- a/doc/src/qnamespace.qdoc +++ /dev/null @@ -1,2718 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://www.qtsoftware.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \namespace Qt - \inmodule QtCore - - \brief The Qt namespace contains miscellaneous identifiers - used throughout the Qt library. - - \ingroup misc -*/ - -/*! - \enum Qt::Orientation - - This type is used to signify an object's orientation. - - \value Horizontal - \value Vertical - - Orientation is used with QScrollBar for example. -*/ - -/*! - \enum Qt::AlignmentFlag - - This enum type is used to describe alignment. It contains - horizontal and vertical flags that can be combined to produce - the required effect. - - The \l{TextElideMode} enum can also be used in many situations - to fine-tune the appearance of aligned text. - - The horizontal flags are: - - \value AlignLeft Aligns with the left edge. - \value AlignRight Aligns with the right edge. - \value AlignHCenter Centers horizontally in the available space. - \value AlignJustify Justifies the text in the available space. - \omitvalue AlignAuto - - The vertical flags are: - - \value AlignTop Aligns with the top. - \value AlignBottom Aligns with the bottom. - \value AlignVCenter Centers vertically in the available space. - - You can use only one of the horizontal flags at a time. There is - one two-dimensional flag: - - \value AlignCenter Centers in both dimensions. - - You can use at most one horizontal and one vertical flag at a - time. Qt::AlignCenter counts as both horizontal and vertical. - - Three enum values are useful in applications that can be run in - right-to-left mode: - - \value AlignAbsolute If the widget's layout direction is - Qt::RightToLeft (instead of Qt::LeftToRight, the default), - Qt::AlignLeft refers to the \e right edge and Qt::AlignRight - to the \e left edge. This is normally the desired behavior. - If you want Qt::AlignLeft to always mean "left" and - Qt::AlignRight to always mean "right", combine the flag with - Qt::AlignAbsolute. - \value AlignLeading Synonym for Qt::AlignLeft. - \value AlignTrailing Synonym for Qt::AlignRight. - - Masks: - - \value AlignHorizontal_Mask - \value AlignVertical_Mask - - Conflicting combinations of flags have undefined meanings. -*/ - -/*! - \enum Qt::ApplicationAttribute - - This enum describes attributes that change the behavior of - application-wide features. These are enabled and disabled using - QCoreApplication::setAttribute(), and can be tested for with - QCoreApplication::testAttribute(). - - \value AA_ImmediateWidgetCreation Ensures that widgets are created - as soon as they are constructed. By default, resources for - widgets are allocated on demand to improve efficiency and - minimize resource usage. Setting or clearing this attribute - affects widgets constructed after the change. Setting it - tells Qt to create toplevel windows immediately. - Therefore, if it is important to minimize resource - consumption, do not set this attribute. - - \value AA_MSWindowsUseDirect3DByDefault This value is obsolete and - has no effect. - - \value AA_DontShowIconsInMenus Actions with the Icon property won't be - shown in any menus unless specifically set by the - QAction::iconVisibleInMenu property. - - Menus that are currently open or menus already created in the native - Mac OS X menubar \e{may not} pick up a change in this attribute. Changes - in the QAction::iconVisibleInMenu property will always be picked up. - - \value AA_NativeWindows Ensures that widgets have native windows. - - \value AA_DontCreateNativeWidgetSiblings Ensures that siblings of native - widgets stay non-native unless specifically set by the - Qt::WA_NativeWindow attribute. - - \value AA_MacPluginApplication Stops the Qt mac application from doing - specific initializations that do not necessarily make sense when using Qt - to author a plugin. This includes avoiding loading our nib for the main - menu and not taking possession of the native menu bar. When setting this - attribute to true will also set the AA_DontUseNativeMenuBar attribute - to true. - - \value AA_DontUseNativeMenuBar All menubars created while this attribute is - set to true won't be used as a native menubar (e.g, the menubar at - the top of the main screen on Mac OS X or at the bottom in Windows CE). - - \value AA_MacDontSwapCtrlAndMeta On Mac OS X by default, Qt swaps the - Control and Meta (Command) keys (i.e., whenever Control is pressed, Qt - sends Meta and whenever Meta is pressed Control is sent. When this - attribute is true, Qt will not do the flip. QKeySequence::StandardShortcuts - will also flip accordingly (i.e., QKeySequence::Copy will be - Command+C on the keyboard regardless of the value set, though what is output for - QKeySequence::toString(QKeySequence::PortableText) will be different). - - \omitvalue AA_AttributeCount -*/ - -/*! - \enum Qt::MouseButton - - This enum type describes the different mouse buttons. - - \value NoButton The button state does not refer to any - button (see QMouseEvent::button()). - \value LeftButton The left button is pressed, or an event refers - to the left button. (The left button may be the right button on - left-handed mice.) - \value RightButton The right button. - \value MidButton The middle button. - \value XButton1 The first X button. - \value XButton2 The second X button. - - \omitvalue MouseButtonMask - - \sa KeyboardModifier Modifier -*/ - -/*! - \enum Qt::KeyboardModifier - - This enum describes the modifier keys. - - \value NoModifier No modifier key is pressed. - \value ShiftModifier A Shift key on the keyboard is pressed. - \value ControlModifier A Ctrl key on the keyboard is pressed. - \value AltModifier An Alt key on the keyboard is pressed. - \value MetaModifier A Meta key on the keyboard is pressed. - \value KeypadModifier A keypad button is pressed. - \value GroupSwitchModifier X11 only. A Mode_switch key on the keyboard is pressed. - - \omitvalue KeyboardModifierMask - - \note On Mac OS X, the \c ControlModifier value corresponds to - the Command keys on the Macintosh keyboard, and the \c MetaModifier value - corresponds to the Control keys. The \c KeypadModifier value will also be set - when an arrow key is pressed as the arrow keys are considered part of the - keypad. - - \note On Windows Keyboards, Qt::MetaModifier and Qt::Key_Meta are mapped - to the Windows key. - - \sa MouseButton Modifier -*/ - -/*! - \enum Qt::Modifier - - This enum provides shorter names for the keyboard modifier keys - supported by Qt. - - \bold{Note:} On Mac OS X, the \c CTRL value corresponds to - the Command keys on the Macintosh keyboard, and the \c META value - corresponds to the Control keys. - - \value SHIFT The Shift keys provided on all standard keyboards. - \value META The Meta keys. - \value CTRL The Ctrl keys. - \value ALT The normal Alt keys, but not keys like AltGr. - \value UNICODE_ACCEL The shortcut is specified as a Unicode code - point, not as a Qt Key. - \omitvalue MODIFIER_MASK - - \sa KeyboardModifier MouseButton -*/ - -/*! - \enum Qt::GlobalColor - - \raw HTML - - \endraw - - Qt's predefined QColor objects: - - \value white \raw HTML - White (#ffffff) - \endraw - \value black \raw HTML - Black (#000000) - \endraw - \value red \raw HTML - Red (#ff0000) - \endraw - \value darkRed \raw HTML - Dark red (#800000) - \endraw - \value green \raw HTML - Green (#00ff00) - \endraw - \value darkGreen \raw HTML - Dark green (#008000) - \endraw - \value blue \raw HTML - Blue (#0000ff) - \endraw - \value darkBlue \raw HTML - Dark blue (#000080) - \endraw - \value cyan \raw HTML - Cyan (#00ffff) - \endraw - \value darkCyan \raw HTML - Dark cyan (#008080) - \endraw - \value magenta \raw HTML - Magenta (#ff00ff) - \endraw - \value darkMagenta \raw HTML - Dark magenta (#800080) - \endraw - \value yellow \raw HTML - Yellow (#ffff00) - \endraw - \value darkYellow \raw HTML - Dark yellow (#808000) - \endraw - \value gray \raw HTML - Gray (#a0a0a4) - \endraw - \value darkGray \raw HTML - Dark gray (#808080) - \endraw - \value lightGray \raw HTML - Light gray (#c0c0c0) - \endraw - \value transparent a transparent black value (i.e., QColor(0, 0, 0, 0)) - \value color0 0 pixel value (for bitmaps) - \value color1 1 pixel value (for bitmaps) - - \sa QColor - -*/ - -/*! - \enum Qt::PenStyle - - This enum type defines the pen styles that can be drawn using - QPainter. The styles are: - - \table - \row - \o \inlineimage qpen-solid.png - \o \inlineimage qpen-dash.png - \o \inlineimage qpen-dot.png - \row - \o Qt::SolidLine - \o Qt::DashLine - \o Qt::DotLine - \row - \o \inlineimage qpen-dashdot.png - \o \inlineimage qpen-dashdotdot.png - \o \inlineimage qpen-custom.png - \row - \o Qt::DashDotLine - \o Qt::DashDotDotLine - \o Qt::CustomDashLine - \endtable - - \value NoPen no line at all. For example, QPainter::drawRect() - fills but does not draw any boundary line. - - \value SolidLine A plain line. - \value DashLine Dashes separated by a few pixels. - \value DotLine Dots separated by a few pixels. - \value DashDotLine Alternate dots and dashes. - \value DashDotDotLine One dash, two dots, one dash, two dots. - \value CustomDashLine A custom pattern defined using - QPainterPathStroker::setDashPattern(). - - \omitvalue MPenStyle - - \sa QPen -*/ - -/*! - \enum Qt::PenCapStyle - - This enum type defines the pen cap styles supported by Qt, i.e. - the line end caps that can be drawn using QPainter. - - \table - \row - \o \inlineimage qpen-square.png - \o \inlineimage qpen-flat.png - \o \inlineimage qpen-roundcap.png - \row - \o Qt::SquareCap - \o Qt::FlatCap - \o Qt::RoundCap - \endtable - - \value FlatCap a square line end that does not cover the end - point of the line. - \value SquareCap a square line end that covers the end point and - extends beyond it by half the line width. - \value RoundCap a rounded line end. - \omitvalue MPenCapStyle - - \sa QPen -*/ - -/*! - \enum Qt::PenJoinStyle - - This enum type defines the pen join styles supported by Qt, i.e. - which joins between two connected lines can be drawn using - QPainter. - - \table - \row - \o \inlineimage qpen-bevel.png - \o \inlineimage qpen-miter.png - \o \inlineimage qpen-roundjoin.png - \row - \o Qt::BevelJoin - \o Qt::MiterJoin - \o Qt::RoundJoin - \endtable - - \value MiterJoin The outer edges of the lines are extended to - meet at an angle, and this area is filled. - \value BevelJoin The triangular notch between the two lines is filled. - \value RoundJoin A circular arc between the two lines is filled. - \value SvgMiterJoin A miter join corresponding to the definition of - a miter join in the \l{SVG 1.2 Tiny} specification. - \omitvalue MPenJoinStyle - - \sa QPen -*/ - -/*! - \enum Qt::BrushStyle - - This enum type defines the brush styles supported by Qt, i.e. the - fill pattern of shapes drawn using QPainter. - - \image brush-styles.png Brush Styles - - \value NoBrush No brush pattern. - \value SolidPattern Uniform color. - \value Dense1Pattern Extremely dense brush pattern. - \value Dense2Pattern Very dense brush pattern. - \value Dense3Pattern Somewhat dense brush pattern. - \value Dense4Pattern Half dense brush pattern. - \value Dense5Pattern Somewhat sparse brush pattern. - \value Dense6Pattern Very sparse brush pattern. - \value Dense7Pattern Extremely sparse brush pattern. - \value HorPattern Horizontal lines. - \value VerPattern Vertical lines. - \value CrossPattern Crossing horizontal and vertical lines. - \value BDiagPattern Backward diagonal lines. - \value FDiagPattern Forward diagonal lines. - \value DiagCrossPattern Crossing diagonal lines. - \value LinearGradientPattern Linear gradient (set using a dedicated QBrush constructor). - \value ConicalGradientPattern Conical gradient (set using a dedicated QBrush constructor). - \value RadialGradientPattern Radial gradient (set using a dedicated QBrush constructor). - \value TexturePattern Custom pattern (see QBrush::setTexture()). - - \omitvalue CustomPattern - - \sa QBrush -*/ - -/*! - \enum Qt::TextFlag - - This enum type is used to define some modifier flags. Some of - these flags only make sense in the context of printing: - - \value TextSingleLine Treats all whitespace as spaces and prints just - one line. - \value TextDontClip If it's impossible to stay within the given bounds, - it prints outside. - \value TextExpandTabs Makes the U+0009 (ASCII tab) character move to - the next tab stop. - \value TextShowMnemonic Displays the string "\&P" as \underline{P} - (see QButton for an example). For an ampersand, use "\&\&". - \value TextWordWrap Breaks lines at appropriate points, e.g. at word - boundaries. - \value TextWrapAnywhere Breaks lines anywhere, even within words. - \value TextHideMnemonic Same as Qt::TextShowMnemonic but doesn't draw the underlines. - \value TextDontPrint Treat this text as "hidden" and don't print - it. - \value IncludeTrailingSpaces When this option is set, QTextLine::naturalTextWidth() and naturalTextRect() will - return a value that includes the width of trailing spaces in the text; otherwise - this width is excluded. - \value TextIncludeTrailingSpaces Same as IncludeTrailingSpaces - \value TextJustificationForced Ensures that text lines are justified. - - \omitvalue BreakAnywhere - \omitvalue DontClip - \omitvalue DontPrint - \omitvalue ExpandTabs - \omitvalue IncludeTrailingSpaces - \omitvalue NoAccel - \omitvalue ShowPrefix - \omitvalue SingleLine - \omitvalue WordBreak - \omitvalue TextForceLeftToRight - \omitvalue TextForceRightToLeft - - You can use as many modifier flags as you want, except that - Qt::TextSingleLine and Qt::TextWordWrap cannot be combined. - - Flags that are inappropriate for a given use are generally - ignored. -*/ - -/*! - \enum Qt::BGMode - - Background mode: - - \value TransparentMode - \value OpaqueMode -*/ - -/*! - \enum Qt::ConnectionType - - This enum describes the types of connection that can be used between signals and - slots. In particular, it determines whether a particular signal is delivered to a - slot immediately or queued for delivery at a later time. - - \omitvalue AutoCompatConnection - \value DirectConnection When emitted, the signal is immediately delivered to the slot. - \value QueuedConnection When emitted, the signal is queued until the event loop is - able to deliver it to the slot. - \value BlockingQueuedConnection - Same as QueuedConnection, except that the current thread blocks - until the slot has been delivered. This connection type should - only be used for receivers in a different thread. Note that misuse - of this type can lead to deadlocks in your application. - \value AutoConnection If the signal is emitted from the thread - in which the receiving object lives, the - slot is invoked directly, as with - Qt::DirectConnection; otherwise the - signal is queued, as with - Qt::QueuedConnection. - \value UniqueConnection Same as AutoConnection, but there will be a check that the signal is - not already connected to the same slot before connecting, otherwise, - the connection will fail. - This value was introduced in Qt 4.6. - - With queued connections, the parameters must be of types that are known to - Qt's meta-object system, because Qt needs to copy the arguments to store them - in an event behind the scenes. If you try to use a queued connection and - get the error message - - \snippet doc/src/snippets/code/doc_src_qnamespace.qdoc 0 - - call qRegisterMetaType() to register the data type before you - establish the connection. - - \sa {Thread Support in Qt}, QObject::connect(), qRegisterMetaType() -*/ - -/*! - \enum Qt::DateFormat - - \value TextDate The default Qt format, which includes the day and month name, - the day number in the month, and the year in full. The day and month names will - be short, localized names. This is basically equivalent to using the date format - string, "ddd MMM d yyyy". See QDate::toString() for more information. - - \value ISODate ISO 8601 extended format: either \c{YYYY-MM-DD} for dates or - \c{YYYY-MM-DDTHH:MM:SS} for combined dates and times. - - \value SystemLocaleShortDate The \l{QLocale::ShortFormat}{short format} used - by the \l{QLocale::system()}{operating system}. - - \value SystemLocaleLongDate The \l{QLocale::LongFormat}{long format} used - by the \l{QLocale::system()}{operating system}. - - \value DefaultLocaleShortDate The \l{QLocale::ShortFormat}{short format} specified - by the \l{QLocale::setDefault()}{application's locale}. - - \value DefaultLocaleLongDate The \l{QLocale::LongFormat}{long format} used - by the \l{QLocale::setDefault()}{application's locale}. - - \value SystemLocaleDate \e{This enum value is deprecated.} Use Qt::SystemLocaleShortDate - instead (or Qt::SystemLocaleLongDate if you want long dates). - - \value LocaleDate \e{This enum value is deprecated.} Use Qt::DefaultLocaleShortDate - instead (or Qt::DefaultLocaleLongDate if you want long dates). - - \value LocalDate \e{This enum value is deprecated.} Use Qt::SystemLocaleShortDate - instead (or Qt::SystemLocaleLongDate if you want long dates). - - \note For \c ISODate formats, each \c Y, \c M and \c D represents a single digit - of the year, month and day used to specify the date. Each \c H, \c M and \c S - represents a single digit of the hour, minute and second used to specify the time. - The presence of a literal \c T character is used to separate the date and time when - both are specified. -*/ - - -/*! - \enum Qt::TimeSpec - - \value LocalTime Locale dependent time (Timezones and Daylight Savings Time). - \value UTC Coordinated Universal Time, replaces Greenwich Mean Time. - \value OffsetFromUTC An offset in seconds from Coordinated Universal Time. -*/ - -/*! - \enum Qt::DayOfWeek - - \value Monday - \value Tuesday - \value Wednesday - \value Thursday - \value Friday - \value Saturday - \value Sunday -*/ - -/*! - \enum Qt::CaseSensitivity - - \value CaseInsensitive - \value CaseSensitive -*/ - -/*! - \enum Qt::ToolBarArea - - \value LeftToolBarArea - \value RightToolBarArea - \value TopToolBarArea - \value BottomToolBarArea - \value AllToolBarAreas - \value NoToolBarArea - - \omitvalue ToolBarArea_Mask -*/ - -/*! - \enum Qt::DockWidgetArea - - \value LeftDockWidgetArea - \value RightDockWidgetArea - \value TopDockWidgetArea - \value BottomDockWidgetArea - \value AllDockWidgetAreas - \value NoDockWidgetArea - - \omitvalue DockWidgetArea_Mask -*/ - -/*! - \enum Qt::BackgroundMode - - \compat - - \value FixedColor - \value FixedPixmap - \value NoBackground - \value PaletteForeground - \value PaletteButton - \value PaletteLight - \value PaletteMidlight - \value PaletteDark - \value PaletteMid - \value PaletteText - \value PaletteBrightText - \value PaletteBase - \value PaletteBackground - \value PaletteShadow - \value PaletteHighlight - \value PaletteHighlightedText - \value PaletteButtonText - \value PaletteLink - \value PaletteLinkVisited - \value X11ParentRelative -*/ - -/*! - \enum Qt::ImageConversionFlag - - The options marked "(default)" are set if no other values from - the list are included (since the defaults are zero): - - Color/Mono preference (ignored for QBitmap): - - \value AutoColor (default) - If the image has \link - QImage::depth() depth\endlink 1 and contains only - black and white pixels, the pixmap becomes monochrome. - \value ColorOnly The pixmap is dithered/converted to the - \link QPixmap::defaultDepth() native display depth\endlink. - \value MonoOnly The pixmap becomes monochrome. If necessary, - it is dithered using the chosen dithering algorithm. - - Dithering mode preference for RGB channels: - - \value DiffuseDither (default) - A high-quality dither. - \value OrderedDither A faster, more ordered dither. - \value ThresholdDither No dithering; closest color is used. - - Dithering mode preference for alpha channel: - - \value ThresholdAlphaDither (default) - No dithering. - \value OrderedAlphaDither A faster, more ordered dither. - \value DiffuseAlphaDither A high-quality dither. - \omitvalue NoAlpha - - Color matching versus dithering preference: - - \value PreferDither (default when converting to a pixmap) - Always dither - 32-bit images when the image is converted to 8 bits. - \value AvoidDither (default when converting for the purpose of saving to - file) - Dither 32-bit images only if the image has more than 256 - colors and it is being converted to 8 bits. - \omitvalue AutoDither - - \omitvalue ColorMode_Mask - \omitvalue Dither_Mask - \omitvalue AlphaDither_Mask - \omitvalue DitherMode_Mask - \omitvalue NoOpaqueDetection -*/ - -/*! \enum Qt::GUIStyle - - \compat - - \value WindowsStyle - \value MotifStyle - \value MacStyle - \value Win3Style - \value PMStyle -*/ - -/*! - \enum Qt::UIEffect - - This enum describes the available UI effects. - - By default, Qt will try to use the platform specific desktop - settings for each effect. Use the - QApplication::setDesktopSettingsAware() function (passing \c false - as argument) to prevent this, and the - QApplication::setEffectEnabled() to enable or disable a particular - effect. - - Note that all effects are disabled on screens running at less than - 16-bit color depth. - - \omitvalue UI_General - - \value UI_AnimateMenu Show animated menus. - \value UI_FadeMenu Show faded menus. - \value UI_AnimateCombo Show animated comboboxes. - \value UI_AnimateTooltip Show tooltip animations. - \value UI_FadeTooltip Show tooltip fading effects. - \value UI_AnimateToolBox Reserved - - \sa QApplication::setEffectEnabled(), QApplication::setDesktopSettingsAware() -*/ - -/*! \enum Qt::AspectRatioMode - - This enum type defines what happens to the aspect ratio when - scaling an rectangle. - - \image qimage-scaling.png - - \value IgnoreAspectRatio The size is scaled freely. The aspect - ratio is not preserved. - \value KeepAspectRatio The size is scaled to a rectangle as - large as possible inside a given - rectangle, preserving the aspect ratio. - \value KeepAspectRatioByExpanding The size is scaled to a - rectangle as small as possible - outside a given rectangle, - preserving the aspect ratio. - - \omitvalue ScaleFree - \omitvalue ScaleMin - \omitvalue ScaleMax - - \sa QSize::scale(), QImage::scaled() -*/ - -/*! \typedef Qt::ScaleMode - \compat - - Use Qt::AspectRatioMode instead. - - The enum values have been renamed as follows: - - \table - \row \i Old enum value \i New enum value - \row \i Qt::ScaleFree \i Qt::IgnoreAspectRatio - \row \i Qt::ScaleMin \i Qt::KeepAspectRatio - \row \i Qt::ScaleMax \i Qt::KeepAspectRatioByExpanding - \endtable -*/ - -/*! \enum Qt::TransformationMode - - This enum type defines whether image transformations (e.g., - scaling) should be smooth or not. - - \value FastTransformation The transformation is performed - quickly, with no smoothing. - \value SmoothTransformation The resulting image is transformed - using bilinear filtering. - - \sa QImage::scaled() -*/ - -/*! \enum Qt::Axis - - This enum type defines three values to represent the three - axes in the cartesian coordinate system. - - \value XAxis The X axis. - \value YAxis The Y axis. - \value ZAxis The Z axis. - - \sa QTransform::rotate(), QTransform::rotateRadians() - */ - -/*! - \enum Qt::WidgetAttribute - - \keyword widget attributes - - This enum type is used to specify various widget attributes. - Attributes are set and cleared with QWidget::setAttribute(), and - queried with QWidget::testAttribute(), although some have special - convenience functions which are mentioned below. - - \value WA_AcceptDrops Allows data from drag and drop operations - to be dropped onto the widget (see QWidget::setAcceptDrops()). - - \value WA_AlwaysShowToolTips Enables tooltips for inactive windows. - - \value WA_ContentsPropagated This flag is superfluous and - obsolete; it no longer has any effect. Since Qt 4.1, all widgets - that do not set WA_PaintOnScreen propagate their contents. - - \value WA_CustomWhatsThis Indicates that the widget wants to - continue operating normally in "What's This?" mode. This is set by the - widget's author. - - \value WA_DeleteOnClose Makes Qt delete this widget when the - widget has accepted the close event (see QWidget::closeEvent()). - - \value WA_Disabled Indicates that the widget is disabled, i.e. - it does not receive any mouse or keyboard events. There is also a - getter functions QWidget::isEnabled(). This is set/cleared by the - Qt kernel. - - \omitvalue WA_DropSiteRegistered - \omitvalue WA_ForceAcceptDrops - - \value WA_ForceDisabled Indicates that the widget is - explicitly disabled, i.e. it will remain disabled even when all - its ancestors are set to the enabled state. This implies - WA_Disabled. This is set/cleared by QWidget::setEnabled() and - QWidget::setDisabled(). - - \value WA_ForceUpdatesDisabled Indicates that updates are - explicitly disabled for the widget; i.e. it will remain disabled - even when all its ancestors are set to the updates-enabled state. - This implies WA_UpdatesDisabled. This is set/cleared by - QWidget::setUpdatesEnabled(). - - \value WA_GroupLeader - \e{This attribute has been deprecated.} Use QWidget::windowModality - instead. - - \value WA_Hover Forces Qt to generate paint events when the mouse - enters or leaves the widget. This feature is typically used when - implementing custom styles; see the \l{widgets/styles}{Styles} - example for details. - - \value WA_InputMethodEnabled Enables input methods for Asian languages. - Must be set when creating custom text editing widgets. - On Windows CE this flag can be used in addition to - QApplication::autoSipEnabled to automatically display the SIP when - entering a widget. - - \value WA_KeyboardFocusChange Set on a toplevel window when - the users changes focus with the keyboard (tab, backtab, or shortcut). - - \value WA_KeyCompression Enables key event compression if set, - and disables it if not set. By default key compression is off, so - widgets receive one key press event for each key press (or more, - since autorepeat is usually on). If you turn it on and your - program doesn't keep up with key input, Qt may try to compress key - events so that more than one character can be processed in each - event. - For example, a word processor widget might receive 2, 3 or more - characters in each QKeyEvent::text(), if the layout recalculation - takes too long for the CPU. - If a widget supports multiple character unicode input, it is - always safe to turn the compression on. - Qt performs key event compression only for printable characters. - Qt::Modifier keys, cursor movement keys, function keys and - miscellaneous action keys (e.g. Escape, Enter, Backspace, - PrintScreen) will stop key event compression, even if there are - more compressible key events available. - Platforms other than Mac and X11 do not support this compression, - in which case turning it on will have no effect. - This is set/cleared by the widget's author. - - \value WA_LayoutOnEntireRect Indicates that the widget - wants QLayout to operate on the entire QWidget::rect(), not only - on QWidget::contentsRect(). This is set by the widget's author. - - \value WA_LayoutUsesWidgetRect Ignore the layout item rect from the style - when laying out this widget with QLayout. This makes a difference in - QMacStyle and QPlastiqueStyle for some widgets. - - \value WA_MacNoClickThrough When a widget that has this attribute set - is clicked, and its window is inactive, the click will make the window - active but won't be seen by the widget. Typical use of this attribute - is on widgets with "destructive" actions, such as a "Delete" button. - WA_MacNoClickThrough also applies to all child widgets of the widget - that has it set. - - \value WA_MacOpaqueSizeGrip Indicates that the native Carbon size grip - should be opaque instead of transparent (the default). This attribute - is only applicable to Mac OS X and is set by the widget's author. - - \value WA_MacShowFocusRect Indicates that this widget should get a - QFocusFrame around it. Some widgets draw their own focus halo - regardless of this attribute. Not that the QWidget::focusPolicy - also plays the main role in whether something is given focus or - not, this only controls whether or not this gets the focus - frame. This attribute is only applicable to Mac OS X. - - \value WA_MacNormalSize Indicates the widget should have the - normal size for widgets in Mac OS X. This attribute is only - applicable to Mac OS X. - - \value WA_MacSmallSize Indicates the widget should have the small - size for widgets in Mac OS X. This attribute is only applicable to - Mac OS X. - - \value WA_MacMiniSize Indicates the widget should have the mini - size for widgets in Mac OS X. This attribute is only applicable to - Mac OS X. - - \value WA_MacVariableSize Indicates the widget can choose between - alternative sizes for widgets to avoid clipping. - This attribute is only applicable to Mac OS X. - - \value WA_MacBrushedMetal Indicates the widget should be drawn in - the brushed metal style as supported by the windowing system. This - attribute is only applicable to Mac OS X. - - \omitvalue WA_MacMetalStyle - - \value WA_Mapped Indicates that the widget is mapped on screen. - This is set/cleared by the Qt kernel. - - \value WA_MouseNoMask Makes the widget receive mouse events for - the entire widget regardless of the currently set mask, - overriding QWidget::setMask(). This is not applicable for - top-level windows. - - \value WA_MouseTracking Indicates that the widget has mouse - tracking enabled. See QWidget::mouseTracking. - - \value WA_Moved Indicates that the widget has an explicit - position. This is set/cleared by QWidget::move() and - by QWidget::setGeometry(). - - \value WA_MSWindowsUseDirect3D This value is obsolete and has no - effect. - - \value WA_NoBackground This value is obsolete. Use - WA_OpaquePaintEvent instead. - - \value WA_NoChildEventsForParent Indicates that the widget does - not want ChildAdded or ChildRemoved events sent to its - parent. This is rarely necessary but can help to avoid automatic - insertion widgets like splitters and layouts. This is set by a - widget's author. - - \value WA_NoChildEventsFromChildren Indicates that the widget does - not want to receive ChildAdded or ChildRemoved events sent from its - children. This is set by a widget's author. - - \value WA_NoMouseReplay Used for pop-up widgets. Indicates that the most - recent mouse press event should not be replayed when the pop-up widget - closes. The flag is set by the widget's author and cleared by the Qt kernel - every time the widget receives a new mouse event. - - \value WA_NoMousePropagation Prohibits mouse events from being propagated - to the widget's parent. This attribute is disabled by default. - - \value WA_TransparentForMouseEvents When enabled, this attribute disables - the delivery of mouse events to the widget and its children. Mouse events - are delivered to other widgets as if the widget and its children were not - present in the widget hierarchy; mouse clicks and other events effectively - "pass through" them. This attribute is disabled by default. - - \value WA_NoSystemBackground Indicates that the widget has no background, - i.e. when the widget receives paint events, the background is not - automatically repainted. \note Unlike WA_OpaquePaintEvent, newly exposed - areas are \bold never filled with the background (e.g., after showing a - window for the first time the user can see "through" it until the - application processes the paint events). This flag is set or cleared by the - widget's author. - - \value WA_OpaquePaintEvent Indicates that the widget paints all its pixels - when it receives a paint event. Thus, it is not required for operations - like updating, resizing, scrolling and focus changes to erase the widget - before generating paint events. The use of WA_OpaquePaintEvent provides a - small optimization by helping to reduce flicker on systems that do not - support double buffering and avoiding computational cycles necessary to - erase the background prior to painting. \note Unlike - WA_NoSystemBackground, WA_OpaquePaintEvent makes an effort to avoid - transparent window backgrounds. This flag is set or cleared by the widget's - author. - - \value WA_OutsideWSRange Indicates that the widget is outside - the valid range of the window system's coordinate system. A widget - outside the valid range cannot be mapped on screen. This is - set/cleared by the Qt kernel. - - \value WA_PaintOnScreen Indicates that the widget wants to draw directly - onto the screen. Widgets with this attribute set do not participate in - composition management, i.e. they cannot be semi-transparent or shine - through semi-transparent overlapping widgets. \note This flag is only - supported on X11 and it disables double buffering. On Qt for Embedded - Linux, the flag only works when set on a top-level widget and it relies on - support from the active screen driver. This flag is set or cleared by the - widget's author. To render outside of Qt's paint system, e.g., if you - require native painting primitives, you need to reimplement - QWidget::paintEngine() to return 0 and set this flag. - - \value WA_PaintOutsidePaintEvent Makes it possible to use QPainter to - paint on the widget outside \l{QWidget::paintEvent()}{paintEvent()}. This - flag is not supported on Windows, Mac OS X or Embedded Linux. We recommend - that you use it only when porting Qt 3 code to Qt 4. - - \value WA_PaintUnclipped Makes all painters operating on this widget - unclipped. Children of this widget or other widgets in front of it do not - clip the area the painter can paint on. This flag is only supported for - widgets with the WA_PaintOnScreen flag set. The preferred way to do this in - a cross platform way is to create a transparent widget that lies in front - of the other widgets. - - \value WA_PendingMoveEvent Indicates that a move event is pending, e.g., - when a hidden widget was moved. This flag is set or cleared by the Qt - kernel. - - \value WA_PendingResizeEvent Indicates that a resize event is pending, - e.g., when a hidden widget was resized. This flag is set or cleared by the - Qt kernel. - - \value WA_QuitOnClose Makes Qt quit the application when the last widget - with the attribute set has accepted closeEvent(). This behavior can be - modified with the QApplication::quitOnLastWindowClosed property. By default - this attribute is set for all widgets of type Qt::Window. - - \value WA_Resized Indicates that the widget has an explicit size. This flag - is set or cleared by QWidget::resize() and QWidget::setGeometry(). - - \value WA_RightToLeft Indicates that the layout direction for the widget - is right to left. - - \value WA_SetCursor Indicates that the widget has a cursor of its own. This - flag is set or cleared by QWidget::setCursor() and QWidget::unsetCursor(). - - \value WA_SetFont Indicates that the widget has a font of its own. This - flag is set or cleared by QWidget::setFont(). - - \value WA_SetPalette Indicates that the widget has a palette of its own. - This flag is set or cleared by QWidget::setPalette(). - - \value WA_SetStyle Indicates that the widget has a style of its own. This - flag is set or cleared by QWidget::setStyle(). - - \value WA_ShowModal \e{This attribute has been deprecated.} Use - QWidget::windowModality instead. - - \value WA_StaticContents Indicates that the widget contents are north-west - aligned and static. On resize, such a widget will receive paint events only - for parts of itself that are newly visible. This flag is set or cleared by - the widget's author. - - \value WA_StyleSheet Indicates that the widget is styled using a - \l{Qt Style Sheets}{style sheet}. - - \value WA_TranslucentBackground Indicates that the widget should have a - translucent background, i.e., any non-opaque regions of the widgets will be - translucent because the widget will have an alpha channel. Setting this - flag causes WA_NoSystemBackground to be set. On Windows the - widget also needs the Qt::FramelessWindowHint window flag to be set. - This flag is set or cleared by the widget's author. - - \value WA_UnderMouse Indicates that the widget is under the mouse cursor. - The value is not updated correctly during drag and drop operations. There - is also a getter function, QWidget::underMouse(). This flag is set or - cleared by the Qt kernel. - - \value WA_UpdatesDisabled Indicates that updates are blocked (including the - system background). This flag is set or cleared by the Qt kernel. - \warning This flag must \e never be set or cleared by the widget's author. - - \value WA_WindowModified Indicates that the window is marked as modified. - On some platforms this flag will do nothing, on others (including Mac OS X - and Windows) the window will take a modified appearance. This flag is set - or cleared by QWidget::setWindowModified(). - - \value WA_WindowPropagation Makes a toplevel window inherit font and - palette from its parent. - - \value WA_MacAlwaysShowToolWindow On Mac OS X, show the tool window even - when the application is not active. By default, all tool windows are - hidden when the application is inactive. - - \value WA_SetLocale Indicates the locale should be taken into consideration - in the widget. - - \value WA_StyledBackground Indicates the widget should be drawn using a - styled background. - - \value WA_ShowWithoutActivating Show the widget without making it active. - - \value WA_NativeWindow Indicates that a native window is created for the - widget. Enabling this flag will also force a native window for the widget's - ancestors unless Qt::WA_DontCreateNativeAncestors is set. - - \value WA_DontCreateNativeAncestors Indicates that the widget's ancestors - are kept non-native even though the widget itself is native. - - \value WA_X11NetWmWindowTypeDesktop Adds _NET_WM_WINDOW_TYPE_DESKTOP to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. - - \value WA_X11NetWmWindowTypeDock Adds _NET_WM_WINDOW_TYPE_DOCK to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. - - \value WA_X11NetWmWindowTypeToolBar Adds _NET_WM_WINDOW_TYPE_TOOLBAR to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automaticaly sets this - attribute for QToolBar. - - \value WA_X11NetWmWindowTypeMenu Adds _NET_WM_WINDOW_TYPE_MENU to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for QMenu when torn-off. - - \value WA_X11NetWmWindowTypeUtility Adds _NET_WM_WINDOW_TYPE_UTILITY to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for the Qt::Tool window type. - - \value WA_X11NetWmWindowTypeSplash Adds _NET_WM_WINDOW_TYPE_SPLASH to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for the Qt::SplashScreen window type. - - \value WA_X11NetWmWindowTypeDialog Adds _NET_WM_WINDOW_TYPE_DIALOG - to the window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This - attribute has no effect on non-X11 platforms. \note Qt automatically sets - this attribute for the Qt::Dialog and Qt::Sheet window types. - - \value WA_X11NetWmWindowTypeDropDownMenu Adds - _NET_WM_WINDOW_TYPE_DROPDOWN_MENU to the window's - _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This - attribute has no effect on non-X11 platforms. \note Qt - automatically sets this attribute for QMenus added to a QMenuBar. - - \value WA_X11NetWmWindowTypePopupMenu Adds _NET_WM_WINDOW_TYPE_POPUP_MENU - to the window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for QMenu. - - \value WA_X11NetWmWindowTypeToolTip Adds _NET_WM_WINDOW_TYPE_TOOLTIP to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for the Qt::ToolTip window type. - - \value WA_X11NetWmWindowTypeNotification Adds - _NET_WM_WINDOW_TYPE_NOTIFICATION to the window's _NET_WM_WINDOW_TYPE X11 - window property. See http://standards.freedesktop.org/wm-spec/ for more - details. This attribute has no effect on non-X11 platforms. - - \value WA_X11NetWmWindowTypeCombo Adds _NET_WM_WINDOW_TYPE_COMBO - to the window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for the QComboBox pop-up. - - \value WA_X11NetWmWindowTypeDND Adds _NET_WM_WINDOW_TYPE_DND to - the window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute on the feedback widget used during a drag. - - \value WA_MacFrameworkScaled Enables resolution independence aware mode - on Mac when using Carbon. This attribute has no effect on Cocoa. - The attribute is off by default and can be enabled on a per-window basis. - - \value WA_AcceptTouchEvents Allows touch events (see QTouchEvent) - to be sent to the widget. Must be set on all widgets that can - handle touch events. Without this attribute set, events from a - touch device will be sent as mouse events. - - \value WA_TouchPadAcceptSingleTouchEvents Allows touchpad single - touch events to be sent to the widget. - - \omitvalue WA_SetLayoutDirection - \omitvalue WA_InputMethodTransparent - \omitvalue WA_WState_CompressKeys - \omitvalue WA_WState_ConfigPending - \omitvalue WA_WState_Created - \omitvalue WA_WState_DND - \omitvalue WA_WState_ExplicitShowHide - \omitvalue WA_WState_Hidden - \omitvalue WA_WState_InPaintEvent - \omitvalue WA_WState_OwnSizePolicy - \omitvalue WA_WState_Polished - \omitvalue WA_WState_Reparented - \omitvalue WA_WState_Visible - \omitvalue WA_SetWindowIcon - \omitvalue WA_PendingUpdate - \omitvalue WA_LaidOut - \omitvalue WA_GrabbedShortcut - \omitvalue WA_DontShowOnScreen - \omitvalue WA_InvalidSize - \omitvalue WA_ForceUpdatesDisabled - \omitvalue WA_NoX11EventCompression - \omitvalue WA_TintedBackground - \omitvalue WA_X11OpenGLOverlay - \omitvalue WA_CanHostQMdiSubWindowTitleBar - \omitvalue WA_AttributeCount - \omitvalue WA_StyleSheet - \omitvalue WA_X11BypassTransientForHint - \omitvalue WA_SetWindowModality - \omitvalue WA_WState_WindowOpacitySet - \omitvalue WA_WState_AcceptedTouchBeginEvent -*/ - -/*! \typedef Qt::HANDLE - - Platform-specific handle type for system objects. This is - equivalent to \c{void *} on Mac OS X and embedded Linux, - and to \c{unsigned long} on X11. On Windows it is the - DWORD returned by the Win32 function getCurrentThreadId(). - - \warning Using this type is not portable. -*/ - -/*! - \enum Qt::Key - - The key names used by Qt. - - \value Key_Escape - \value Key_Tab - \value Key_Backtab - \omitvalue Key_BackTab - \value Key_Backspace - \omitvalue Key_BackSpace - \value Key_Return - \value Key_Enter Typically located on the keypad. - \value Key_Insert - \value Key_Delete - \value Key_Pause - \value Key_Print - \value Key_SysReq - \value Key_Clear - \value Key_Home - \value Key_End - \value Key_Left - \value Key_Up - \value Key_Right - \value Key_Down - \value Key_PageUp - \omitvalue Key_Prior - \value Key_PageDown - \omitvalue Key_Next - \value Key_Shift - \value Key_Control On Mac OS X, this corresponds to the Command keys. - \value Key_Meta On Mac OS X, this corresponds to the Control keys. - On Windows keyboards, this key is mapped to the - Windows key. - \value Key_Alt - \value Key_AltGr On Windows, when the KeyDown event for this key is - sent, the Ctrl+Alt modifiers are also set. - \value Key_CapsLock - \value Key_NumLock - \value Key_ScrollLock - \value Key_F1 - \value Key_F2 - \value Key_F3 - \value Key_F4 - \value Key_F5 - \value Key_F6 - \value Key_F7 - \value Key_F8 - \value Key_F9 - \value Key_F10 - \value Key_F11 - \value Key_F12 - \value Key_F13 - \value Key_F14 - \value Key_F15 - \value Key_F16 - \value Key_F17 - \value Key_F18 - \value Key_F19 - \value Key_F20 - \value Key_F21 - \value Key_F22 - \value Key_F23 - \value Key_F24 - \value Key_F25 - \value Key_F26 - \value Key_F27 - \value Key_F28 - \value Key_F29 - \value Key_F30 - \value Key_F31 - \value Key_F32 - \value Key_F33 - \value Key_F34 - \value Key_F35 - \value Key_Super_L - \value Key_Super_R - \value Key_Menu - \value Key_Hyper_L - \value Key_Hyper_R - \value Key_Help - \value Key_Direction_L - \value Key_Direction_R - \value Key_Space - \value Key_Any - \value Key_Exclam - \value Key_QuoteDbl - \value Key_NumberSign - \value Key_Dollar - \value Key_Percent - \value Key_Ampersand - \value Key_Apostrophe - \value Key_ParenLeft - \value Key_ParenRight - \value Key_Asterisk - \value Key_Plus - \value Key_Comma - \value Key_Minus - \value Key_Period - \value Key_Slash - \value Key_0 - \value Key_1 - \value Key_2 - \value Key_3 - \value Key_4 - \value Key_5 - \value Key_6 - \value Key_7 - \value Key_8 - \value Key_9 - \value Key_Colon - \value Key_Semicolon - \value Key_Less - \value Key_Equal - \value Key_Greater - \value Key_Question - \value Key_At - \value Key_A - \value Key_B - \value Key_C - \value Key_D - \value Key_E - \value Key_F - \value Key_G - \value Key_H - \value Key_I - \value Key_J - \value Key_K - \value Key_L - \value Key_M - \value Key_N - \value Key_O - \value Key_P - \value Key_Q - \value Key_R - \value Key_S - \value Key_T - \value Key_U - \value Key_V - \value Key_W - \value Key_X - \value Key_Y - \value Key_Z - \value Key_BracketLeft - \value Key_Backslash - \value Key_BracketRight - \value Key_AsciiCircum - \value Key_Underscore - \value Key_QuoteLeft - \value Key_BraceLeft - \value Key_Bar - \value Key_BraceRight - \value Key_AsciiTilde - \value Key_nobreakspace - \value Key_exclamdown - \value Key_cent - \value Key_sterling - \value Key_currency - \value Key_yen - \value Key_brokenbar - \value Key_section - \value Key_diaeresis - \value Key_copyright - \value Key_ordfeminine - \value Key_guillemotleft - \value Key_notsign - \value Key_hyphen - \value Key_registered - \value Key_macron - \value Key_degree - \value Key_plusminus - \value Key_twosuperior - \value Key_threesuperior - \value Key_acute - \value Key_mu - \value Key_paragraph - \value Key_periodcentered - \value Key_cedilla - \value Key_onesuperior - \value Key_masculine - \value Key_guillemotright - \value Key_onequarter - \value Key_onehalf - \value Key_threequarters - \value Key_questiondown - \value Key_Agrave - \value Key_Aacute - \value Key_Acircumflex - \value Key_Atilde - \value Key_Adiaeresis - \value Key_Aring - \value Key_AE - \value Key_Ccedilla - \value Key_Egrave - \value Key_Eacute - \value Key_Ecircumflex - \value Key_Ediaeresis - \value Key_Igrave - \value Key_Iacute - \value Key_Icircumflex - \value Key_Idiaeresis - \value Key_ETH - \value Key_Ntilde - \value Key_Ograve - \value Key_Oacute - \value Key_Ocircumflex - \value Key_Otilde - \value Key_Odiaeresis - \value Key_multiply - \value Key_Ooblique - \value Key_Ugrave - \value Key_Uacute - \value Key_Ucircumflex - \value Key_Udiaeresis - \value Key_Yacute - \value Key_THORN - \value Key_ssharp - \omitvalue Key_agrave - \omitvalue Key_aacute - \omitvalue Key_acircumflex - \omitvalue Key_atilde - \omitvalue Key_adiaeresis - \omitvalue Key_aring - \omitvalue Key_ae - \omitvalue Key_ccedilla - \omitvalue Key_egrave - \omitvalue Key_eacute - \omitvalue Key_ecircumflex - \omitvalue Key_ediaeresis - \omitvalue Key_igrave - \omitvalue Key_iacute - \omitvalue Key_icircumflex - \omitvalue Key_idiaeresis - \omitvalue Key_eth - \omitvalue Key_ntilde - \omitvalue Key_ograve - \omitvalue Key_oacute - \omitvalue Key_ocircumflex - \omitvalue Key_otilde - \omitvalue Key_odiaeresis - \value Key_division - \omitvalue Key_oslash - \omitvalue Key_ugrave - \omitvalue Key_uacute - \omitvalue Key_ucircumflex - \omitvalue Key_udiaeresis - \omitvalue Key_yacute - \omitvalue Key_thorn - \value Key_ydiaeresis - \value Key_Multi_key - \value Key_Codeinput - \value Key_SingleCandidate - \value Key_MultipleCandidate - \value Key_PreviousCandidate - \value Key_Mode_switch - \value Key_Kanji - \value Key_Muhenkan - \value Key_Henkan - \value Key_Romaji - \value Key_Hiragana - \value Key_Katakana - \value Key_Hiragana_Katakana - \value Key_Zenkaku - \value Key_Hankaku - \value Key_Zenkaku_Hankaku - \value Key_Touroku - \value Key_Massyo - \value Key_Kana_Lock - \value Key_Kana_Shift - \value Key_Eisu_Shift - \value Key_Eisu_toggle - \value Key_Hangul - \value Key_Hangul_Start - \value Key_Hangul_End - \value Key_Hangul_Hanja - \value Key_Hangul_Jamo - \value Key_Hangul_Romaja - \value Key_Hangul_Jeonja - \value Key_Hangul_Banja - \value Key_Hangul_PreHanja - \value Key_Hangul_PostHanja - \value Key_Hangul_Special - \value Key_Dead_Grave - \value Key_Dead_Acute - \value Key_Dead_Circumflex - \value Key_Dead_Tilde - \value Key_Dead_Macron - \value Key_Dead_Breve - \value Key_Dead_Abovedot - \value Key_Dead_Diaeresis - \value Key_Dead_Abovering - \value Key_Dead_Doubleacute - \value Key_Dead_Caron - \value Key_Dead_Cedilla - \value Key_Dead_Ogonek - \value Key_Dead_Iota - \value Key_Dead_Voiced_Sound - \value Key_Dead_Semivoiced_Sound - \value Key_Dead_Belowdot - \value Key_Dead_Hook - \value Key_Dead_Horn - \value Key_Back - \value Key_Forward - \value Key_Stop - \value Key_Refresh - \value Key_VolumeDown - \value Key_VolumeMute - \value Key_VolumeUp - \value Key_BassBoost - \value Key_BassUp - \value Key_BassDown - \value Key_TrebleUp - \value Key_TrebleDown - \value Key_MediaPlay - \value Key_MediaStop - \value Key_MediaPrevious - \omitvalue Key_MediaPrev - \value Key_MediaNext - \value Key_MediaRecord - \value Key_HomePage - \value Key_Favorites - \value Key_Search - \value Key_Standby - \value Key_OpenUrl - \value Key_LaunchMail - \value Key_LaunchMedia - \value Key_Launch0 - \value Key_Launch1 - \value Key_Launch2 - \value Key_Launch3 - \value Key_Launch4 - \value Key_Launch5 - \value Key_Launch6 - \value Key_Launch7 - \value Key_Launch8 - \value Key_Launch9 - \value Key_LaunchA - \value Key_LaunchB - \value Key_LaunchC - \value Key_LaunchD - \value Key_LaunchE - \value Key_LaunchF - \value Key_MediaLast - \value Key_unknown - - \value Key_Call - \value Key_Context1 - \value Key_Context2 - \value Key_Context3 - \value Key_Context4 - \value Key_Flip - \value Key_Hangup - \value Key_No - \value Key_Select - \value Key_Yes - - \value Key_Execute - \value Key_Printer - \value Key_Play - \value Key_Sleep - \value Key_Zoom - \value Key_Cancel - - \sa QKeyEvent::key() -*/ - -/*! - \enum Qt::HitTestAccuracy - - This enum contains the types of accuracy that can be used by the - QTextDocument class when testing for mouse clicks on text documents. - - \value ExactHit The point at which input occurred must coincide - exactly with input-sensitive parts of the document. - \value FuzzyHit The point at which input occurred can lie close to - input-sensitive parts of the document. - - This enum is defined in the \c header file. -*/ - -/*! - \enum Qt::WhiteSpaceMode - - This enum describes the types of whitespace mode that are used by - the QTextDocument class to meet the requirements of different kinds - of textual information. - - \value WhiteSpaceNormal The whitespace mode used to display - normal word wrapped text in paragraphs. - \value WhiteSpacePre A preformatted text mode in which - whitespace is reproduced exactly. - \value WhiteSpaceNoWrap - - \omitvalue WhiteSpaceModeUndefined - - This enum is defined in the \c header file. -*/ - -/*! - \enum Qt::ButtonState_enum - \compat - \value ShiftButton - \value ControlButton - \value AltButton - \value MetaButton - \value Keypad - \value KeyButtonMask - - Use Qt::KeyboardModifier instead. -*/ - -/*! - \typedef Qt::ButtonState - \compat - - Use Qt::KeyboardModifier instead. -*/ - -/*! - \enum Qt::CheckState - - This enum describes the state of checkable items, controls, and widgets. - - \value Unchecked The item is unchecked. - \value PartiallyChecked The item is partially checked. Items in hierarchical models - may be partially checked if some, but not all, of their - children are checked. - \value Checked The item is checked. - - \sa QCheckBox, Qt::ItemFlags, Qt::ItemDataRole -*/ - - -/*! - \enum Qt::ToolButtonStyle - - The style of the tool button, describing how the button's text and - icon should be displayed. - - \value ToolButtonIconOnly Only display the icon. - \value ToolButtonTextOnly Only display the text. - \value ToolButtonTextBesideIcon The text appears beside the icon. - \value ToolButtonTextUnderIcon The text appears under the icon. - \value ToolButtonFollowStyle Follow the \l{QStyle::SH_ToolButtonStyle}{style}. -*/ - -/*! - \enum Qt::Corner - - This enum type specifies a corner in a rectangle: - - \value TopLeftCorner The top-left corner of the rectangle. - \value TopRightCorner The top-right corner of the rectangle. - \value BottomLeftCorner The bottom-left corner of the rectangle. - \value BottomRightCorner The bottom-right corner of the rectangle. - - \omitvalue TopLeft - \omitvalue TopRight - \omitvalue BottomLeft - \omitvalue BottomRight -*/ - -/*! - \enum Qt::ScrollBarPolicy - - This enum type describes the various modes of QAbstractScrollArea's scroll - bars. - - \value ScrollBarAsNeeded QAbstractScrollArea shows a scroll bar when the - content is too large to fit and not otherwise. This is the - default. - - \value ScrollBarAlwaysOff QAbstractScrollArea never shows a scroll bar. - - \value ScrollBarAlwaysOn QAbstractScrollArea always shows a scroll bar. - - (The modes for the horizontal and vertical scroll bars are - independent.) -*/ - -/*! - \enum Qt::ArrowType - - \value NoArrow - \value UpArrow - \value DownArrow - \value LeftArrow - \value RightArrow -*/ - -/*! - \enum Qt::FocusReason - - This enum specifies why the focus changed. It will be passed - through QWidget::setFocus and can be retrieved in the QFocusEvent - sent to the widget upon focus change. - - \value MouseFocusReason A mouse action occurred. - \value TabFocusReason The Tab key was pressed. - \value BacktabFocusReason A Backtab occurred. The input for this may - include the Shift or Control keys; - e.g. Shift+Tab. - \value ActiveWindowFocusReason The window system made this window either - active or inactive. - \value PopupFocusReason The application opened/closed a pop-up that - grabbed/released the keyboard focus. - \value ShortcutFocusReason The user typed a label's buddy shortcut - \value MenuBarFocusReason The menu bar took focus. - \value OtherFocusReason Another reason, usually application-specific. - - \omitvalue NoFocusReason - - \sa {Keyboard Focus} -*/ - -/*! - \enum Qt::WindowState - - \keyword window state - - This enum type is used to specify the current state of a top-level - window. - - The states are - - \value WindowNoState The window has no state set (in normal state). - \value WindowMinimized The window is minimized (i.e. iconified). - \value WindowMaximized The window is maximized with a frame around it. - \value WindowFullScreen The window fills the entire screen without any frame around it. - \value WindowActive The window is the active window, i.e. it has keyboard focus. - -*/ - -/*! - \enum Qt::ContextMenuPolicy - - This enum type defines the various policies a widget can have with - respect to showing a context menu. - - \value NoContextMenu the widget does not feature a context menu, - context menu handling is deferred to the widget's parent. - \value PreventContextMenu the widget does not feature a context - menu, and in contrast to \c NoContextMenu, the handling is \e not - deferred to the widget's parent. This means that all right mouse - button events are guaranteed to be delivered to the widget itself - through mousePressEvent(), and mouseReleaseEvent(). - \value DefaultContextMenu the widget's QWidget::contextMenuEvent() handler is called. - \value ActionsContextMenu the widget displays its QWidget::actions() as context menu. - \value CustomContextMenu the widget emits the QWidget::customContextMenuRequested() signal. -*/ - -/*! - \enum Qt::FocusPolicy - - This enum type defines the various policies a widget can have with - respect to acquiring keyboard focus. - - \value TabFocus the widget accepts focus by tabbing. - \value ClickFocus the widget accepts focus by clicking. - \value StrongFocus the widget accepts focus by both tabbing - and clicking. On Mac OS X this will also - be indicate that the widget accepts tab focus - when in 'Text/List focus mode'. - \value WheelFocus like Qt::StrongFocus plus the widget accepts - focus by using the mouse wheel. - \value NoFocus the widget does not accept focus. - -*/ - -/*! - \enum Qt::ShortcutContext - - For a QEvent::Shortcut event to occur, the shortcut's key sequence - must be entered by the user in a context where the shortcut is - active. The possible contexts are these: - - \value WidgetShortcut The shortcut is active when its - parent widget has focus. - \value WidgetWithChildrenShortcut The shortcut is active - when its parent widget, or any of its children has focus. - Children which are top-level widgets, except pop-ups, are - not affected by this shortcut context. - \value WindowShortcut The shortcut is active when its - parent widget is a logical subwidget of the - active top-level window. - \value ApplicationShortcut The shortcut is active when one of - the applications windows are active. -*/ - -/*! - \typedef Qt::WFlags - - Synonym for Qt::WindowFlags. -*/ - -/*! - \enum Qt::WindowType - - \keyword window flag - - This enum type is used to specify various window-system properties - for the widget. They are fairly unusual but necessary in a few - cases. Some of these flags depend on whether the underlying window - manager supports them. - - The main types are - - \value Widget This is the default type for QWidget. Widgets of - this type are child widgets if they have a parent, - and independent windows if they have no parent. - See also Qt::Window and Qt::SubWindow. - - \value Window Indicates that the widget is a window, usually - with a window system frame and a title bar, - irrespective of whether the widget has a parent or - not. Note that it is not possible to unset this - flag if the widget does not have a parent. - - \value Dialog Indicates that the widget is a window that should - be decorated as a dialog (i.e., typically no - maximize or minimize buttons in the title bar). - This is the default type for QDialog. If you want - to use it as a modal dialog, it should be launched - from another window, or have a parent and used - with the QWidget::windowModality property. If you make - it modal, the dialog will prevent other top-level - windows in the application from getting any input. - We refer to a top-level window that has a parent - as a \e secondary window. - - \value Sheet Indicates that the widget is a Macintosh sheet. - - \value Drawer Indicates that the widget is a Macintosh drawer. - - \value Popup Indicates that the widget is a pop-up top-level - window, i.e. that it is modal, but has a window - system frame appropriate for pop-up menus. - - \value Tool Indicates that the widget is a tool window. A tool - window is often a small window with a smaller than - usual title bar and decoration, typically used for - collections of tool buttons. It there is a parent, - the tool window will always be kept on top of it. - If there isn't a parent, you may consider using - Qt::WindowStaysOnTopHint as well. If the window - system supports it, a tool window can be decorated - with a somewhat lighter frame. It can also be - combined with Qt::FramelessWindowHint. - \br - \br - On Mac OS X, tool windows correspond to the - \l{http://developer.apple.com/documentation/Carbon/Conceptual/HandlingWindowsControls/hitb-wind_cont_concept/chapter_2_section_2.html}{Floating} - class of windows. This means that the window lives on a - level above normal windows; it impossible to put a normal - window on top of it. By default, tool windows will disappear - when the application is inactive. This can be controlled by - the Qt::WA_MacAlwaysShowToolWindow attribute. - - \value ToolTip Indicates that the widget is a tooltip. This is - used internally to implement - \l{QWidget::toolTip}{tooltips}. - - \value SplashScreen Indicates that the window is a splash screen. - This is the default type for QSplashScreen. - - \value Desktop Indicates that this widget is the desktop. This - is the type for QDesktopWidget. - - \value SubWindow Indicates that this widget is a sub-window, such - as a QMdiSubWindow widget. - - There are also a number of flags which you can use to customize - the appearance of top-level windows. These have no effect on other - windows: - - \value MSWindowsFixedSizeDialogHint Gives the window a thin dialog border on Windows. - This style is traditionally used for fixed-size dialogs. - - \value MSWindowsOwnDC Gives the window its own display - context on Windows. - - \value X11BypassWindowManagerHint Bypass the window - manager completely. This results in a borderless window - that is not managed at all (i.e., no keyboard input unless - you call QWidget::activateWindow() manually). - - \value FramelessWindowHint Produces a borderless window. - The user cannot move or resize a borderless window via the window - system. On X11, the result of the flag is dependent on the window manager and its - ability to understand Motif and/or NETWM hints. Most existing - modern window managers can handle this. - - The \c CustomizeWindowHint flag is used to enable customization of - the window controls. This flag must be set to allow the \c - WindowTitleHint, \c WindowSystemMenuHint, \c - WindowMinimizeButtonHint, \c WindowMaximizeButtonHint and \c - WindowCloseButtonHint flags to be changed. - - \value CustomizeWindowHint Turns off the default window title hints. - - \value WindowTitleHint Gives the window a title bar. - - \value WindowSystemMenuHint Adds a window system menu, and - possibly a close button (for example on Mac). If you need to hide - or show a close button, it is more portable to use \c - WindowCloseButtonHint. - - \value WindowMinimizeButtonHint Adds a minimize button. On - some platforms this implies Qt::WindowSystemMenuHint for it to work. - - \value WindowMaximizeButtonHint Adds a maximize button. On - some platforms this implies Qt::WindowSystemMenuHint for it to work. - - \value WindowMinMaxButtonsHint Adds a minimize and a maximize - button. On some platforms this implies Qt::WindowSystemMenuHint for it to work. - - \value WindowCloseButtonHint Adds a close button. On - some platforms this implies Qt::WindowSystemMenuHint for it - to work. - - \value WindowContextHelpButtonHint Adds a context help button to dialogs. - On some platforms this implies Qt::WindowSystemMenuHint for it to work. - - \value MacWindowToolBarButtonHint On Mac OS X adds a tool bar button (i.e., - the oblong button that is on the top right of windows that have toolbars. - - \value BypassGraphicsProxyWidget Prevents the window and its children from - automatically embedding themselves into a QGraphicsProxyWidget if the - parent widget is already embedded. You can set this flag if you - want your widget to always be a toplevel widget on the desktop, - regardless of whether the parent widget is embedded in a scene or - not. - - \value WindowShadeButtonHint - - \value WindowStaysOnTopHint Informs the window system that the - window should stay on top of all other windows. Note that - on some window managers on X11 you also have to pass - Qt::X11BypassWindowManagerHint for this flag to work - correctly. - - \value WindowStaysOnBottomHint Informs the window system that the - window should stay on bottom of all other windows. Note - that on X11 this hint will work only in window managers - that support _NET_WM_STATE_BELOW atom. If a window always - on the bottom has a parent, the parent will also be left on - the bottom. This window hint is currently not implemented - for Mac OS X. - - \value WindowOkButtonHint Adds an OK button to the window decoration of a dialog. - Only supported for Windows CE. - - \value WindowCancelButtonHint Adds a Cancel button to the window decoration of a dialog. - Only supported for Windows CE. - - \value WindowType_Mask A mask for extracting the window type - part of the window flags. - - Obsolete flags: - - \value WMouseNoMask Use Qt::WA_MouseNoMask instead. - \value WDestructiveClose Use Qt::WA_DeleteOnClose instead. - \value WStaticContents Use Qt::WA_StaticContents instead. - \value WGroupLeader No longer needed. - \value WShowModal Use QWidget::windowModality instead. - \value WNoMousePropagation Use Qt::WA_NoMousePropagation instead. - \value WType_TopLevel Use Qt::Window instead. - \value WType_Dialog Use Qt::Dialog instead. - \value WType_Popup Use Qt::Popup instead. - \value WType_Desktop Use Qt::Desktop instead. - \value WType_Mask Use Qt::WindowType_Mask instead. - - \value WStyle_Customize No longer needed. - \value WStyle_NormalBorder No longer needed. - \value WStyle_DialogBorder Use Qt::MSWindowsFixedSizeDialogHint instead. - \value WStyle_NoBorder Use Qt::FramelessWindowHint instead. - \value WStyle_Title Use Qt::WindowTitleHint instead. - \value WStyle_SysMenu Use Qt::WindowSystemMenuHint instead. - \value WStyle_Minimize Use Qt::WindowMinimizeButtonHint instead. - \value WStyle_Maximize Use Qt::WindowMaximizeButtonHint instead. - \value WStyle_MinMax Use Qt::WindowMinMaxButtonsHint instead. - \value WStyle_Tool Use Qt::Tool instead. - \value WStyle_StaysOnTop Use Qt::WindowStaysOnTopHint instead. - \value WStyle_ContextHelp Use Qt::WindowContextHelpButtonHint instead. - - \value WPaintDesktop No longer needed. - \value WPaintClever No longer needed. - - \value WX11BypassWM Use Qt::X11BypassWindowManagerHint instead. - \value WWinOwnDC Use Qt::MSWindowsOwnDC instead. - \value WMacSheet Use Qt::Sheet instead. - \value WMacDrawer Use Qt::Drawer instead. - - \value WStyle_Splash Use Qt::SplashScreen instead. - - \value WNoAutoErase No longer needed. - \value WRepaintNoErase No longer needed. - \value WNorthWestGravity Use Qt::WA_StaticContents instead. - \value WType_Modal Use Qt::Dialog and QWidget::windowModality instead. - \value WStyle_Dialog Use Qt::Dialog instead. - \value WStyle_NoBorderEx Use Qt::FramelessWindowHint instead. - \value WResizeNoErase No longer needed. - \value WMacNoSheet No longer needed. - - \sa QWidget::windowFlags, {Window Flags Example} -*/ - -/*! - \enum Qt::DropAction - - \value CopyAction Copy the data to the target. - \value MoveAction Move the data from the source to the target. - \value LinkAction Create a link from the source to the target. - \value ActionMask - \value IgnoreAction Ignore the action (do nothing with the data). - \value TargetMoveAction On Windows, this value is used when the ownership of the D&D data - should be taken over by the target application, - i.e., the source application should not delete - the data. - \br - On X11 this value is used to do a move. - \br - TargetMoveAction is not used on the Mac. -*/ - -#if defined(Q_OS_WIN) && defined(QT3_SUPPORT) -/*! - \enum Qt::WindowsVersion - \compat - - \value WV_32s - \value WV_95 - \value WV_98 - \value WV_Me - \value WV_DOS_based - \value WV_NT - \value WV_2000 - \value WV_XP - \value WV_2003 - \value WV_NT_based - \value WV_CE - \value WV_CENET - \value WV_CE_based - \value WV_CE_5 - \value WV_CE_6 -*/ -#endif - -#if defined(Q_OS_MAC) && defined(QT3_SUPPORT) -/*! - \enum Qt::MacintoshVersion - \compat - - \value MV_Unknown Use QSysInfo::MV_Unknown instead. - \value MV_9 Use QSysInfo::MV_9 instead. - \value MV_10_DOT_0 Use QSysInfo::MV_10_0 instead. - \value MV_10_DOT_1 Use QSysInfo::MV_10_1 instead. - \value MV_10_DOT_2 Use QSysInfo::MV_10_2 instead. - \value MV_10_DOT_3 Use QSysInfo::MV_10_3 instead. - \value MV_10_DOT_4 Use QSysInfo::MV_10_4 instead. - - \value MV_CHEETAH Use QSysInfo::MV_10_0 instead. - \value MV_PUMA Use QSysInfo::MV_10_1 instead. - \value MV_JAGUAR Use QSysInfo::MV_10_2 instead. - \value MV_PANTHER Use QSysInfo::MV_10_3 instead. - \value MV_TIGER Use QSysInfo::MV_10_4 instead. - - \sa QSysInfo::MacVersion -*/ -#endif - -/*! \typedef Qt::ToolBarDock - \compat - - Use Qt::Dock instead. -*/ - -/*! - \enum Qt::Dock - \compat - - Each dock window can be in one of the following positions: - - \value DockUnmanaged not managed by a Q3MainWindow. - - \value DockTornOff the dock window floats as its own top level - window which always stays on top of the main window. - - \value DockTop above the central widget, below the menu bar. - - \value DockBottom below the central widget, above the status bar. - - \value DockRight to the right of the central widget. - - \value DockLeft to the left of the central widget. - - \value DockMinimized the dock window is not shown (this is - effectively a 'hidden' dock area); the handles of all minimized - dock windows are drawn in one row below the menu bar. - - \omitvalue Bottom - \omitvalue Left - \omitvalue Minimized - \omitvalue Right - \omitvalue Top - \omitvalue TornOff - \omitvalue Unmanaged -*/ - -/*! - \enum Qt::AnchorAttribute - - An anchor has one or more of the following attributes: - - \value AnchorName the name attribute of the anchor. This attribute is - used when scrolling to an anchor in the document. - - \value AnchorHref the href attribute of the anchor. This attribute is - used when a link is clicked to determine what content to load. -*/ - -/*! - \enum Qt::SortOrder - - This enum describes how the items in a widget are sorted. - - \value AscendingOrder The items are sorted ascending e.g. starts with - 'AAA' ends with 'ZZZ' in Latin-1 locales - - \value DescendingOrder The items are sorted descending e.g. starts with - 'ZZZ' ends with 'AAA' in Latin-1 locales - - \omitvalue Ascending - \omitvalue Descending -*/ - -/*! - \enum Qt::ClipOperation - - \value NoClip This operation turns clipping off. - - \value ReplaceClip Replaces the current clip path/rect/region with - the one supplied in the function call. - - \value IntersectClip Intersects the current clip path/rect/region - with the one supplied in the function call. - - \value UniteClip Unites the current clip path/rect/region with the - one supplied in the function call. -*/ - -/*! - \enum Qt::ItemSelectionMode - - This enum is used in QGraphicsItem, QGraphicsScene and QGraphicsView to - specify how items are selected, or how to determine if a shapes and items - collide. - - \value ContainsItemShape The output list contains only items whose - \l{QGraphicsItem::shape()}{shape} is fully contained inside the - selection area. Items that intersect with the area's outline are - not included. - - \value IntersectsItemShape The output list contains both items whose - \l{QGraphicsItem::shape()}{shape} is fully contained inside the - selection area, and items that intersect with the area's - outline. This is a common mode for rubber band selection. - - \value ContainsItemBoundingRect The output list contains only items whose - \l{QGraphicsItem::boundingRect()}{bounding rectangle} is fully - contained inside the selection area. Items that intersect with the - area's outline are not included. - - \value IntersectsItemBoundingRect The output list contains both items - whose \l{QGraphicsItem::boundingRect()}{bounding rectangle} is - fully contained inside the selection area, and items that intersect - with the area's outline. This method is commonly used for - determining areas that need redrawing. - - \sa QGraphicsScene::items(), QGraphicsScene::collidingItems(), - QGraphicsView::items(), QGraphicsItem::collidesWithItem(), - QGraphicsItem::collidesWithPath() -*/ - -/*! - \enum Qt::FillRule - - Specifies which method should be used to fill the paths and polygons. - - \value OddEvenFill Specifies that the region is filled using the - odd even fill rule. With this rule, we determine whether a point - is inside the shape by using the following method. - Draw 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 mode is the - default. - - \value WindingFill Specifies that the region is filled using the - non zero winding rule. With this rule, we determine whether a - point is inside the shape by using the following method. - Draw a horizontal line from the point to a location outside the shape. - Determine 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. This fill mode can also in most cases be considered - as the intersection of closed shapes. -*/ - -/*! - \enum Qt::PaintUnit - - \compat - - \value PixelUnit - \value LoMetricUnit Obsolete - \value HiMetricUnit Obsolete - \value LoEnglishUnit Obsolete - \value HiEnglishUnit Obsolete - \value TwipsUnit Obsolete -*/ - -/*! - \enum Qt::TextFormat - - This enum is used in widgets that can display both plain text and - rich text, e.g. QLabel. It is used for deciding whether a text - string should be interpreted as one or the other. This is normally - done by passing one of the enum values to a setTextFormat() - function. - - \value PlainText The text string is interpreted as a plain text - string. - - \value RichText The text string is interpreted as a rich text - string. - - \value AutoText The text string is interpreted as for - Qt::RichText if Qt::mightBeRichText() returns true, otherwise - as Qt::PlainText. - - \value LogText A special, limited text format which is only used - by Q3TextEdit in an optimized mode. -*/ - -/*! - \enum Qt::CursorShape - - This enum type defines the various cursors that can be used. - - The standard arrow cursor is the default for widgets in a normal state. - - \value ArrowCursor \inlineimage cursor-arrow.png - The standard arrow cursor. - \value UpArrowCursor \inlineimage cursor-uparrow.png - An arrow pointing upwards toward the top of the screen. - \value CrossCursor \inlineimage cursor-cross.png - A crosshair cursor, typically used to help the - user accurately select a point on the screen. - \value WaitCursor \inlineimage cursor-wait.png - An hourglass or watch cursor, usually shown during - operations that prevent the user from interacting with - the application. - \value IBeamCursor \inlineimage cursor-ibeam.png - A caret or ibeam cursor, indicating that a widget can - accept and display text input. - \value SizeVerCursor \inlineimage cursor-sizev.png - A cursor used for elements that are used to vertically - resize top-level windows. - \value SizeHorCursor \inlineimage cursor-sizeh.png - A cursor used for elements that are used to horizontally - resize top-level windows. - \value SizeBDiagCursor \inlineimage cursor-sizeb.png - A cursor used for elements that are used to diagonally - resize top-level windows at their top-right and - bottom-left corners. - \value SizeFDiagCursor \inlineimage cursor-sizef.png - A cursor used for elements that are used to diagonally - resize top-level windows at their top-left and - bottom-right corners. - \value SizeAllCursor \inlineimage cursor-sizeall.png - A cursor used for elements that are used to resize - top-level windows in any direction. - \value BlankCursor A blank/invisible cursor, typically used when the cursor - shape needs to be hidden. - \value SplitVCursor \inlineimage cursor-vsplit.png - A cursor used for vertical splitters, indicating that - a handle can be dragged horizontally to adjust the use - of available space. - \value SplitHCursor \inlineimage cursor-hsplit.png - A cursor used for horizontal splitters, indicating that - a handle can be dragged vertically to adjust the use - of available space. - \value PointingHandCursor \inlineimage cursor-hand.png - A pointing hand cursor that is typically used for - clickable elements such as hyperlinks. - \value ForbiddenCursor \inlineimage cursor-forbidden.png - A slashed circle cursor, typically used during drag - and drop operations to indicate that dragged content - cannot be dropped on particular widgets or inside - certain regions. - \value OpenHandCursor \inlineimage cursor-openhand.png - A cursor representing an open hand, typically used to - indicate that the area under the cursor is the visible - part of a canvas that the user can click and drag in - order to scroll around. - \value ClosedHandCursor \inlineimage cursor-closedhand.png - A cursor representing a closed hand, typically used to - indicate that a dragging operation is in progress that - involves scrolling. - \value WhatsThisCursor \inlineimage cursor-whatsthis.png - An arrow with a question mark, typically used to indicate - the presence of What's This? help for a widget. - \value BusyCursor \inlineimage cursor-wait.png - An hourglass or watch cursor, usually shown during - operations that allow the user to interact with - the application while they are performed in the - background. - \value BitmapCursor - \omitvalue LastCursor - \omitvalue CustomCursor - - \omitvalue arrowCursor - \omitvalue upArrowCursor - \omitvalue crossCursor - \omitvalue waitCursor - \omitvalue ibeamCursor - \omitvalue sizeVerCursor - \omitvalue sizeHorCursor - \omitvalue sizeBDiagCursor - \omitvalue sizeFDiagCursor - \omitvalue sizeAllCursor - \omitvalue blankCursor - \omitvalue splitVCursor - \omitvalue splitHCursor - \omitvalue pointingHandCursor - \omitvalue forbiddenCursor - \omitvalue whatsThisCursor -*/ - -/*! - \typedef Qt::TextFlags - \compat - - Use Qt::TextFlag instead. -*/ - -/*! - \enum Qt::LayoutDirection - - Specifies the direction of Qt's layouts: - - \value LeftToRight Left-to-right layout. - \value RightToLeft Right-to-left layout. - - Right-to-left layouts are necessary for certain languages, - notably Arabic and Hebrew. - - \sa QApplication::setLayoutDirection(), QWidget::setLayoutDirection() -*/ - -/*! - \enum Qt::InputMethodQuery - - \value ImMicroFocus The rectangle covering the area of the input cursor in widget coordinates. - \value ImFont The currently used font for text input. - \value ImCursorPosition The logical position of the cursor within the text surrounding the input area (see ImSurroundingText). - If any text is selected, the position returned will be at the logical end of the - selection, even if the real cursor is located at the logical start. - \value ImSurroundingText The plain text around the input area, for example the current paragraph. - \value ImCurrentSelection The currently selected text. -*/ - -/*! - \enum Qt::ItemDataRole - - Each item in the model has a set of data elements associated with - it, each with its own role. The roles are used by the view to indicate - to the model which type of data it needs. - - The general purpose roles are: - - \value DisplayRole The key data to be rendered in the form of text. - \value DecorationRole The data to be rendered as a decoration in the form - of an icon. - \value EditRole The data in a form suitable for editing in an - editor. - \value ToolTipRole The data displayed in the item's tooltip. - \value StatusTipRole The data displayed in the status bar. - \value WhatsThisRole The data displayed for the item in "What's This?" - mode. - \value SizeHintRole The size hint for the item that will be supplied - to views. - - Roles describing appearance and meta data: - - \value FontRole The font used for items rendered with the default - delegate. - \value TextAlignmentRole The alignment of the text for items rendered with the - default delegate. - \value BackgroundRole The background brush used for items rendered with - the default delegate. - \value BackgroundColorRole This role is obsolete. Use BackgroundRole instead. - \value ForegroundRole The foreground brush (text color, typically) - used for items rendered with the default delegate. - \value TextColorRole This role is obsolete. Use ForegroundRole instead. - \value CheckStateRole This role is used to obtain the checked state of - an item (see \l Qt::CheckState). - - Accessibility roles: - - \value AccessibleTextRole The text to be used by accessibility - extensions and plugins, such as screen - readers. - \value AccessibleDescriptionRole A description of the item for accessibility - purposes. - - User roles: - - \value UserRole The first role that can be used for application-specific purposes. - - \omitvalue DisplayPropertyRole - \omitvalue DecorationPropertyRole - \omitvalue ToolTipPropertyRole - \omitvalue StatusTipPropertyRole - \omitvalue WhatsThisPropertyRole -*/ - -/*! - \enum Qt::ItemFlag - - This enum describes the properties of an item: - - \value NoItemFlags It does not have any properties set. - \value ItemIsSelectable It can be selected. - \value ItemIsEditable It can be edited. - \value ItemIsDragEnabled It can be dragged. - \value ItemIsDropEnabled It can be used as a drop target. - \value ItemIsUserCheckable It can be checked or unchecked by the user. - \value ItemIsEnabled The user can interact with the item. - \value ItemIsTristate The item is checkable with three separate states. - - Note that checkable items need to be given both a suitable set of flags - and an initial state, indicating whether the item is checked or not. - This is handled automatically for model/view components, but needs - to be explicitly set for instances of QListWidgetItem, QTableWidgetItem, - and QTreeWidgetItem. - - \sa QAbstractItemModel -*/ - -/*! - \enum Qt::MatchFlag - - This enum describes the type of matches that can be used when searching - for items in a model. - - \value MatchExactly Performs QVariant-based matching. - \value MatchFixedString Performs string-based matching. - String-based comparisons are case-insensitive unless the - \c MatchCaseSensitive flag is also specified. - \value MatchContains The search term is contained in the item. - \value MatchStartsWith The search term matches the start of the item. - \value MatchEndsWith The search term matches the end of the item. - \value MatchCaseSensitive The search is case sensitive. - \value MatchRegExp Performs string-based matching using a regular - expression as the search term. - \value MatchWildcard Performs string-based matching using a string with - wildcards as the search term. - \value MatchWrap Perform a search that wraps around, so that when - the search reaches the last item in the model, it begins again at - the first item and continues until all items have been examined. - \value MatchRecursive Searches the entire hierarchy. - - \sa QString::compare(), QRegExp -*/ - -/*! - \enum Qt::TextElideMode - - This enum specifies where the ellipsis should appear when - displaying texts that don't fit: - - \value ElideLeft The ellipsis should appear at the beginning of the text. - \value ElideRight The ellipsis should appear at the end of the text. - \value ElideMiddle The ellipsis should appear in the middle of the text. - \value ElideNone Ellipsis should NOT appear in the text. - - Qt::ElideMiddle is normally the most appropriate choice for URLs (e.g., - "\l{http://www.qtsoftware.com/careers/movingto/beijing/}{http://www.qtsof...ovingto/beijing/}"), - whereas Qt::ElideRight is appropriate - for other strings (e.g., - "\l{http://doc.trolltech.com/qq/qq09-mac-deployment.html}{Deploying Applications on Ma...}"). - - \sa QAbstractItemView::textElideMode, QFontMetrics::elidedText(), AlignmentFlag QTabBar::elideMode -*/ - -/*! - \enum Qt::WindowModality - - \keyword modal - - This enum specifies the behavior of a modal window. A modal window - is one that blocks input to other windows. Note that windows that - are children of a modal window are not blocked. - - The values are: - \value NonModal The window is not modal and does not block input to other windows. - \value WindowModal The window is modal to a single window hierarchy and blocks input to its parent window, all grandparent windows, and all siblings of its parent and grandparent windows. - \value ApplicationModal The window is modal to the application and blocks input to all windows. - - \sa QWidget::windowModality, QDialog -*/ - -/*! - \enum Qt::TextInteractionFlag - - This enum specifies how a text displaying widget reacts to user input. - - \value NoTextInteraction No interaction with the text is possible. - \value TextSelectableByMouse Text can be selected with the mouse and copied to the clipboard using - a context menu or standard keyboard shortcuts. - \value TextSelectableByKeyboard Text can be selected with the cursor keys on the keyboard. A text cursor is shown. - \value LinksAccessibleByMouse Links can be highlighted and activated with the mouse. - \value LinksAccessibleByKeyboard Links can be focused using tab and activated with enter. - \value TextEditable The text is fully editable. - - \value TextEditorInteraction The default for a text editor. - \value TextBrowserInteraction The default for QTextBrowser. -*/ - -/*! - \enum Qt::MaskMode - - This enum specifies the behavior of the - QPixmap::createMaskFromColor() and QImage::createMaskFromColor() - functions. - - \value MaskInColor Creates a mask where all pixels matching the given color are opaque. - \value MaskOutColor Creates a mask where all pixels matching the given color are transparent. -*/ - -/*! - \enum Qt::DockWidgetAreaSizes - \internal -*/ - -/*! - \enum Qt::ToolBarAreaSizes - \internal -*/ - -/*! - \enum Qt::EventPriority - - This enum can be used to specify event priorities. - - \value HighEventPriority Events with this priority are sent before - events with NormalEventPriority or LowEventPriority. - - \value NormalEventPriority Events with this priority are sent - after events with HighEventPriority, but before events with - LowEventPriority. - - \value LowEventPriority Events with this priority are sent after - events with HighEventPriority or NormalEventPriority. - - Note that these values are provided purely for convenience, since - event priorities can be any value between \c INT_MAX and \c - INT_MIN, inclusive. For example, you can define custom priorities - as being relative to each other: - - \snippet doc/src/snippets/code/doc_src_qnamespace.qdoc 1 - - \sa QCoreApplication::postEvent() -*/ -/*! - \enum Qt::SizeHint - \since 4.4 - - This enum is used by QGraphicsLayoutItem::sizeHint() - - \value MinimumSize is used to specify the minimum size of a graphics layout item. - \value PreferredSize is used to specify the preferred size of a graphics layout item. - \value MaximumSize is used to specify the maximum size of a graphics layout item. - \value MinimumDescent is used to specify the minimum descent of a text string in a graphics layout item. - \omitvalue NSizeHints - - \sa QGraphicsLayoutItem::sizeHint() -*/ - -/*! - \enum Qt::SizeMode - \since 4.4 - - This enum is used by QPainter::drawRoundedRect() and QPainterPath::addRoundedRect() - functions to specify the radii of rectangle corners with respect to the dimensions - of the bounding rectangles specified. - - \value AbsoluteSize Specifies the size using absolute measurements. - \value RelativeSize Specifies the size relative to the bounding rectangle, - typically using percentage measurements. -*/ - -/*! - \enum Qt::WindowFrameSection - \since 4.4 - - This enum is used to describe parts of a window frame. It is returned by - QGraphicsWidget::windowFrameSectionAt() to describe what section of the window - frame is under the mouse. - - \value NoSection - \value LeftSection - \value TopLeftSection - \value TopSection - \value TopRightSection - \value RightSection - \value BottomRightSection - \value BottomSection - \value BottomLeftSection - \value TitleBarArea - - \sa QGraphicsWidget::windowFrameEvent() - \sa QGraphicsWidget::paintWindowFrame() - \sa QGraphicsWidget::windowFrameSectionAt() - -*/ - -/*! - \enum Qt::TileRule - \since 4.6 - - This enum describes how to repeat or stretch the parts of an image - when drawing. - - \value Stretch Scale the image to fit to the available area. - - \value Repeat Tile the image until there is no more space. May crop - the last image. - - \value Round Like Repeat, but scales the images down to ensure that - the last image is not cropped. -*/ - -/*! - \enum Qt::Initialization - \internal -*/ - -/*! - \enum Qt::GestureState - \since 4.6 - - This enum type describes the state of a gesture. - - \omitvalue NoGesture - \value GestureStarted A continuous gesture has started. - \value GestureUpdated A gesture continues. - \value GestureFinished A gesture has finished. - - \sa QGesture -*/ -- cgit v0.12 From 0ba7569ab7911bf65b6321ad65ac979d9d034c2b Mon Sep 17 00:00:00 2001 From: Andreas Aardal Hanssen Date: Thu, 30 Jul 2009 06:27:34 +0200 Subject: Docs: Improve QGraphicsTransform and subclasses Fix a few typos and add more descriptive documentation to the class itself and its subclasses. Reviewed-by: Volker Hilsheimer Reviewed-by: Martin Smith --- src/gui/graphicsview/qgraphicsitem.cpp | 163 ++++++---- src/gui/graphicsview/qgraphicsitem_p.h | 5 +- .../graphicsview/qgraphicsscenebsptreeindex.cpp | 9 +- src/gui/graphicsview/qgraphicstransform.cpp | 340 +++++++++++++-------- src/gui/graphicsview/qgraphicstransform.h | 1 + 5 files changed, 327 insertions(+), 191 deletions(-) diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp index 5aae93e..75d6ead 100644 --- a/src/gui/graphicsview/qgraphicsitem.cpp +++ b/src/gui/graphicsview/qgraphicsitem.cpp @@ -135,38 +135,39 @@ \section1 Transformation - QGraphicsItem supports affine transformations in addition to its base - position, pos(). To change the item's transformation, you can pass - a transformation matrix to setTransform() - - Item transformations accumulate from parent to child, so if both a - parent and child item are rotated 90 degrees, the child's total - transformation will be 180 degrees. Similarly, if the item's - parent is scaled to 2x its original size, its children will also - be twice as large. An item's transformation does not affect its - own local geometry; all geometry functions (e.g., contains(), - update(), and all the mapping functions) still operate in local - coordinates. For convenience, QGraphicsItem provides the functions - sceneTransform(), which returns the item's total transformation + QGraphicsItem supports projective transformations in addition to its base + position, pos(). There are several ways to change an item's transformation. + For simple transformations, you can call either of the convenience + functions setRotation() or setScale(), or you can pass any transformation + matrix to setTransform(). For advanced transformation control you also have + the option of setting several combined transformations by calling + setTransformations(). + + Item transformations accumulate from parent to child, so if both a parent + and child item are rotated 90 degrees, the child's total transformation + will be 180 degrees. Similarly, if the item's parent is scaled to 2x its + original size, its children will also be twice as large. An item's + transformation does not affect its own local geometry; all geometry + functions (e.g., contains(), update(), and all the mapping functions) still + operate in local coordinates. For convenience, QGraphicsItem provides the + functions sceneTransform(), which returns the item's total transformation matrix (including its position and all parents' positions and - transformations), and scenePos(), which returns its position in - scene coordinates. To reset an item's matrix, call - resetTransform(). + transformations), and scenePos(), which returns its position in scene + coordinates. To reset an item's matrix, call resetTransform(). - Another way to apply transformation to an item is to use the , or - set the different transformation properties (transformOrigin, - x/y/zRotation, x/yScale, horizontal/verticalShear). Those - properties come in addition to the base transformation + Certain transformation operations produce a different outcome depending on + the order in which they are applied. For example, if you scale an + transform, and then rotate it, you may get a different result than if the + transform was rotated first. However, the order you set the transformation + properties on QGraphicsItem does not affect the resulting transformation; + QGraphicsItem always applies the properties in a fixed, defined order: - The order you set the transformation properties does not affect - the resulting transformation The resulting transformation is - always computed in the following order - - \code - [Origin] [Base] [RotateX] [RotateY] [RotateZ] [Shear] [Scale] [-Origin] - \endcode - - Where [Base] is the stransformation set by setTransform + \list + \o The item's base transform is applied (transform()) + \o The item's transformations list is applied in order (transformations()) + \o The item is rotated relative to its transform origin point (rotation(), transformOriginPoint()) + \o The item is scaled relative to its transform origin point (scale(), transformOriginPoint()) + \endlist \section1 Painting @@ -2969,11 +2970,10 @@ QMatrix QGraphicsItem::matrix() const Returns this item's transformation matrix. - Either the one set by setTransform, or the resulting transformation from - all the transfmation properties - - If no matrix or transformation property has been set, the - identity matrix is returned. + The transformation matrix is combined with the item's rotation(), scale() + and transformations() into a combined transformations for the item. + + The default transformation matrix is an identity matrix. \sa setTransform(), sceneTransform() */ @@ -2987,13 +2987,13 @@ QTransform QGraphicsItem::transform() const /*! \since 4.6 - Returns the rotation around the Z axis. - - The default is 0 + Returns the clockwise rotation, in degrees, around the Z axis. The default + value is 0 (i.e., the item is not rotated). - \warning The value doesn't take in account any rotation set with the setTransform() method. + The rotation is combined with the item's scale(), transform() and + transformations() to map the item's coordinate system to the parent item. - \sa setRotation(), {Transformations} + \sa setRotation(), transformOriginPoint(), {Transformations} */ qreal QGraphicsItem::rotation() const { @@ -3005,9 +3005,19 @@ qreal QGraphicsItem::rotation() const /*! \since 4.6 - Sets the rotation around the Z axis to \a angle degrees. + Sets the clockwise rotation \a angle, in degrees, around the Z axis. The + default value is 0 (i.e., the item is not rotated). Assigning a negative + value will rotate the item counter-clockwise. Normally the rotation angle + is in the range (-360, 360), but it's also possible to assign values + outside of this range (e.g., a rotation of 370 degrees is the same as a + rotation of 10 degrees). + + The item is rotated around its transform origin point, which by default + is (0, 0). You can select a different transformation origin by calling + setTransformOriginPoint(). - \warning The value doesn't take in account any rotation set with the setTransform() method. + The rotation is combined with the item's scale(), transform() and + transformations() to map the item's coordinate system to the parent item. \sa rotation(), setTransformOriginPoint(), {Transformations} */ @@ -3027,13 +3037,13 @@ void QGraphicsItem::setRotation(qreal angle) /*! \since 4.6 - Returns the scale factor of the item. + Returns the scale factor of the item. The default scale factor is 1.0 + (i.e., the item is not scaled). - The default is 1 + The scale is combined with the item's rotation(), transform() and + transformations() to map the item's coordinate system to the parent item. - \warning The value doesn't take in account any scaling set with the setTransform() method. - - \sa setScale(), {Transformations} + \sa setScale(), rotation(), {Transformations} */ qreal QGraphicsItem::scale() const { @@ -3045,9 +3055,17 @@ qreal QGraphicsItem::scale() const /*! \since 4.6 - Sets the scale factor of the item to \a factor. + Sets the scale \a factor of the item. The default scale factor is 1.0 + (i.e., the item is not scaled). A scale factor of 0.0 will collapse the + item to a single point. If you provide a negative scale factor, the + item will be flipped and mirrored (i.e., rotated 180 degrees). + + The item is scaled around its transform origin point, which by default + is (0, 0). You can select a different transformation origin by calling + setTransformOriginPoint(). - \warning The value doesn't take in account any scaling set with the setTransform() method. + The scale is combined with the item's rotation(), transform() and + transformations() to map the item's coordinate system to the parent item. \sa scale(), setTransformOriginPoint(), {Transformations} */ @@ -3068,9 +3086,17 @@ void QGraphicsItem::setScale(qreal factor) /*! \since 4.6 - returns list of graphics transformations on the item. + Returns a list of graphics transforms that currently apply to this item. - \sa scale(), setTransformOriginPoint(), {Transformations} + QGraphicsTransform is for applying and controlling a chain of individual + transformation operations on an item. It's particularily useful in + animations, where each transform operation needs to be interpolated + independently, or differently. + + The transformations are combined with the item's rotation(), scale() and + transform() to map the item's coordinate system to the parent item. + + \sa scale(), rotation(), transformOriginPoint(), {Transformations} */ QList QGraphicsItem::transformations() const { @@ -3082,7 +3108,20 @@ QList QGraphicsItem::transformations() const /*! \since 4.6 - Sets a list of graphics transformations on the item to \a transformations. + Sets a list of graphics \a transformations (QGraphicsTransform) that + currently apply to this item. + + If all you want is to rotate or scale an item, you should call setRotation() + or setScale() instead. If you want to set an arbitrary transformation on + an item, you can call setTransform(). + + QGraphicsTransform is for applying and controlling a chain of individual + transformation operations on an item. It's particularily useful in + animations, where each transform operation needs to be interpolated + independently, or differently. + + The transformations are combined with the item's rotation(), scale() and + transform() to map the item's coordinate system to the parent item. \sa scale(), setTransformOriginPoint(), {Transformations} */ @@ -3098,7 +3137,9 @@ void QGraphicsItem::setTransformations(const QList &transf d_ptr->dirtySceneTransform = 1; } - +/*! + \internal +*/ void QGraphicsItemPrivate::appendGraphicsTransform(QGraphicsTransform *t) { if (!transformData) @@ -3432,7 +3473,9 @@ void QGraphicsItem::setMatrix(const QMatrix &matrix, bool combine) to map an item coordiate to a scene coordinate, or mapFromScene() to map from scene coordinates to item coordinates. - \warning using this function doesnt affect the value of the transformation properties + The transformation matrix is combined with the item's rotation(), scale() + and transformations() into a combined transformation that maps the item's + coordinate system to its parent. \sa transform(), setRotation(), setScale(), setTransformOriginPoint(), {The Graphics View Coordinate System}, {Transformations} */ @@ -3491,7 +3534,8 @@ void QGraphicsItem::resetTransform() /*! \obsolete - Use setZRotation() instead + + Use setRotation() instead Rotates the current item transformation \a angle degrees clockwise around its origin. To translate around an arbitrary point (x, y), you need to @@ -3501,8 +3545,6 @@ void QGraphicsItem::resetTransform() \snippet doc/src/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp 6 - \warning using this functionhas no effect on the zRotation value - \sa setTransform(), transform(), scale(), shear(), translate() */ void QGraphicsItem::rotate(qreal angle) @@ -3512,6 +3554,7 @@ void QGraphicsItem::rotate(qreal angle) /*! \obsolete + Use setScale() instead Scales the current item transformation by (\a sx, \a sy) around its @@ -3522,8 +3565,6 @@ void QGraphicsItem::rotate(qreal angle) \snippet doc/src/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp 7 - \warning using this function has no effect on the xScale or yScale value - \sa setTransform(), transform() */ void QGraphicsItem::scale(qreal sx, qreal sy) @@ -3533,11 +3574,10 @@ void QGraphicsItem::scale(qreal sx, qreal sy) /*! \obsolete - Use setShear instead. - Shears the current item transformation by (\a sh, \a sv). + Use setTransform() instead. - \warning using this function has no effect on the horizontalShear or verticalShear value + Shears the current item transformation by (\a sh, \a sv). \sa setTransform(), transform() */ @@ -3548,6 +3588,7 @@ void QGraphicsItem::shear(qreal sh, qreal sv) /*! \obsolete + Use setPos() or setTransformOriginPoint() instead. Translates the current item transformation by (\a dx, \a dy). diff --git a/src/gui/graphicsview/qgraphicsitem_p.h b/src/gui/graphicsview/qgraphicsitem_p.h index b8d98c1..5c3622b 100644 --- a/src/gui/graphicsview/qgraphicsitem_p.h +++ b/src/gui/graphicsview/qgraphicsitem_p.h @@ -468,7 +468,8 @@ public: QGraphicsItem *q_ptr; }; -struct QGraphicsItemPrivate::TransformData { +struct QGraphicsItemPrivate::TransformData +{ QTransform transform; qreal scale; qreal rotation; @@ -481,7 +482,7 @@ struct QGraphicsItemPrivate::TransformData { scale(1.0), rotation(0.0), xOrigin(0.0), yOrigin(0.0), onlyTransform(true) - {} + { } QTransform computedFullTransform(QTransform *postmultiplyTransform = 0) const { diff --git a/src/gui/graphicsview/qgraphicsscenebsptreeindex.cpp b/src/gui/graphicsview/qgraphicsscenebsptreeindex.cpp index 3cb33d1..07d23b7 100644 --- a/src/gui/graphicsview/qgraphicsscenebsptreeindex.cpp +++ b/src/gui/graphicsview/qgraphicsscenebsptreeindex.cpp @@ -525,7 +525,7 @@ QGraphicsSceneBspTreeIndex::~QGraphicsSceneBspTreeIndex() } /*! - \reimp + \internal Clear the all the BSP index. */ void QGraphicsSceneBspTreeIndex::clear() @@ -566,7 +566,7 @@ void QGraphicsSceneBspTreeIndex::removeItem(QGraphicsItem *item) } /*! - \reimp + \internal Update the BSP when the \a item 's bounding rect has changed. */ void QGraphicsSceneBspTreeIndex::prepareBoundingRectChange(const QGraphicsItem *item) @@ -682,7 +682,7 @@ void QGraphicsSceneBspTreeIndex::setBspTreeDepth(int depth) } /*! - \reimp + \internal This method react to the \a rect change of the scene and reset the BSP tree index. @@ -695,11 +695,10 @@ void QGraphicsSceneBspTreeIndex::updateSceneRect(const QRectF &rect) } /*! - \reimp + \internal This method react to the \a change of the \a item and use the \a value to update the BSP tree if necessary. - */ void QGraphicsSceneBspTreeIndex::itemChange(const QGraphicsItem *item, QGraphicsItem::GraphicsItemChange change, const QVariant &value) { diff --git a/src/gui/graphicsview/qgraphicstransform.cpp b/src/gui/graphicsview/qgraphicstransform.cpp index b55d78e..890aff7 100644 --- a/src/gui/graphicsview/qgraphicstransform.cpp +++ b/src/gui/graphicsview/qgraphicstransform.cpp @@ -39,6 +39,43 @@ ** ****************************************************************************/ +/*! + \class QGraphicsTransform + \brief The QGraphicsTransform class is an abstract base class for building + advanced transformations on QGraphicsItems. + \since 4.6 + + As an alternative to QGraphicsItem::transform, QGraphicsTransform lets you + create and control advanced transformations that can be configured + independently using specialized properties. + + QGraphicsItem allows you to assign any number of QGraphicsTransform + instances to one QGraphicsItem. Each QGraphicsTransform is applied in + order, one at a time, to the QGraphicsItem it's assigned to. + + QGraphicsTransform is particularily useful for animations. Whereas + QGraphicsItem::setTransform() lets you assign any transform directly to an + item, there is no direct way to interpolate between two different + transformations (e.g., when transitioning between two states, each for + which the item has a different arbitrary transform assigned). Using + QGraphicsTransform you can interpolate the property values of each + independent transformation. The resulting operation is then combined into a + single transform which is applied to QGraphicsItem. + + If you want to create your own configurable transformation, you can create + a subclass of QGraphicsTransform (or any or the existing subclasses), and + reimplement the pure virtual applyTo() function, which takes a pointer to a + QTransform. Each operation you would like to apply should be exposed as + properties (e.g., customTransform->setVerticalShear(2.5)). Inside you + reimplementation of applyTo(), you can modify the provided transform + respectively. + + QGraphicsTransform can be used together with QGraphicsItem::setTransform(), + QGraphicsItem::setRotation(), and QGraphicsItem::setScale(). + + \sa QGraphicsItem::transform(), QGraphicsScale, QGraphicsRotation, QGraphicsRotation3D +*/ + #include "qgraphicstransform.h" #include "qgraphicsitem_p.h" #include "qgraphicstransform_p.h" @@ -51,7 +88,6 @@ QT_BEGIN_NAMESPACE - void QGraphicsTransformPrivate::setItem(QGraphicsItem *i) { if (item == i) @@ -77,15 +113,38 @@ void QGraphicsTransformPrivate::updateItem(QGraphicsItem *item) item->d_ptr->dirtySceneTransform = 1; } -void QGraphicsTransform::update() +/*! + Constructs a new QGraphicsTransform with the given \a parent. +*/ +QGraphicsTransform::QGraphicsTransform(QObject *parent) + : QObject(*new QGraphicsTransformPrivate, parent) +{ +} + +/*! + Destroys the graphics transform. +*/ +QGraphicsTransform::~QGraphicsTransform() { Q_D(QGraphicsTransform); - if (d->item) - d->updateItem(d->item); + d->setItem(0); +} + +/*! + \internal +*/ +QGraphicsTransform::QGraphicsTransform(QGraphicsTransformPrivate &p, QObject *parent) + : QObject(p, parent) +{ } /*! - returns this object as a QTransform. + Applies this transformation to an identity transform, and returns the + resulting transform. + + This is equivalent to passing an identity transform to applyTo(). + + \sa applyTo() */ QTransform QGraphicsTransform::transform() const { @@ -95,76 +154,65 @@ QTransform QGraphicsTransform::transform() const } /*! - \class QGraphicsTransform - \brief The QGraphicsTransform class is an abstract base class for tranformations on QGraphicsItems. - \since 4.6 - - The classes that inherit QGraphicsTransform express different types of transformations - that can be applied to graphics items. + \fn void QGraphicsTransform::applyTo(QTransform *transform) const - A list of these transformations can be applied to any graphics item. These - transformations are then easily modifyable and usable from e.g. within animations. + This pure virtual method has to be reimplemented in derived classes. - QGraphicsTransform is an abstract base class that is implemented by QGraphicsScale, - QGraphicsRotation and QGraphicsRotation3D. Subclasses have to implement the applyTo method. + It applies this transformation to \a transform. - \sa QGraphicsItem::transform(), QGraphicsScale, QGraphicsRotation, QGraphicsRotation3D + \sa QGraphicsItem::transform() */ /*! - Constructs a new QGraphicsTransform with \a parent. -*/ -QGraphicsTransform::QGraphicsTransform(QObject *parent) : - QObject(*new QGraphicsTransformPrivate, parent) -{ -} + Notifies that this transform operation has changed its parameters in such a + way that applyTo() will return a different result than before. -/*! - Destructs the graphics transform. + When implementing you own custom graphics transform, you must call this + function every time you change a parameter, to let QGraphicsItem know that + its transformation needs to be updated. + + \sa applyTo() */ -QGraphicsTransform::~QGraphicsTransform() +void QGraphicsTransform::update() { Q_D(QGraphicsTransform); - d->setItem(0); + if (d->item) + d->updateItem(d->item); } /*! - \internal -*/ -QGraphicsTransform::QGraphicsTransform(QGraphicsTransformPrivate &p, QObject *parent) - : QObject(p, parent) -{ -} - -/*! \fn void QGraphicsTransform::applyTo(QTransform *transform) const + \class QGraphicsScale + \brief The QGraphicsScale class provides a scale transformation. + \since 4.6 - This pure virtual method has to be reimplemented in derived classes. + QGraphicsScene provides certain parameters to help control how the scale + should be applied. - It applies this transformation to \a transform. -*/ + The origin is the point that the item is scaled from (i.e., it stays fixed + relative to the parent as the rest of the item grows). By default the + origin is QPointF(0, 0). + The two parameters xScale and yScale describe the scale factors to apply in + horizontal and vertical direction. They can take on any value, including 0 + (to collapse the item to a point) or negativate value. A negative xScale + value will mirror the item horizontally. A negative yScale value will flip + the item vertically. -/*! - \class QGraphicsScale - \brief The QGraphicsScale class provides a way to scale a graphics item in 2 dimensions. - \since 4.6 - - QGraphicsScale contains an \a origin around which the scaling happens, and two - scale factors, xScale and yScale, the x and one for the y axis. + \sa QGraphicsTransform, QGraphicsItem::setScale(), QTransform::scale() */ class QGraphicsScalePrivate : public QGraphicsTransformPrivate { public: QGraphicsScalePrivate() - : xScale(1), yScale(1) {} + : xScale(1), yScale(1) {} QPointF origin; qreal xScale; qreal yScale; }; /*! - Constructs a new graphics scale object with \a parent. + Constructs an empty QGraphicsScale object with the given \a parent. */ QGraphicsScale::QGraphicsScale(QObject *parent) : QGraphicsTransform(*new QGraphicsScalePrivate, parent) @@ -172,24 +220,26 @@ QGraphicsScale::QGraphicsScale(QObject *parent) } /*! - Destroys the object + Destroys the graphics scale. */ QGraphicsScale::~QGraphicsScale() { } /*! - \property QGraphicsScale::origin - The origin of the scale. All scaling will be done relative to this point. + \property QGraphicsScale::origin + \brief The QGraphicsScene class provides the origin of the scale. + + All scaling will be done relative to this point (i.e., this point + will stay fixed, relative to the parent, when the item is scaled). - The \a origin is in other words the fixed point for the transformation. + \sa xScale, yScale */ QPointF QGraphicsScale::origin() const { Q_D(const QGraphicsScale); return d->origin; } - void QGraphicsScale::setOrigin(const QPointF &point) { Q_D(QGraphicsScale); @@ -199,26 +249,21 @@ void QGraphicsScale::setOrigin(const QPointF &point) } /*! - \fn QGraphicsScale::originChanged() - - This signal is emitted whenever the origin of the object - changes. -*/ - -/*! - \property QGraphicsScale::xScale + \property QGraphicsScale::xScale + \brief the horizontal scale factor. - The scale factor in x direction. The x direction is - in the graphics items logical coordinates. + The scale factor can be any real number; the default value is 1.0. If you + set the factor to 0.0, the item will be collapsed to a single point. If you + provide a negative value, the item will be mirrored horizontally around its + origin. - \sa yScale + \sa yScale, origin */ qreal QGraphicsScale::xScale() const { Q_D(const QGraphicsScale); return d->xScale; } - void QGraphicsScale::setXScale(qreal scale) { Q_D(QGraphicsScale); @@ -230,19 +275,21 @@ void QGraphicsScale::setXScale(qreal scale) } /*! - \property QGraphicsScale::yScale + \property QGraphicsScale::yScale + \brief the vertical scale factor. - The scale factor in y direction. The y direction is - in the graphics items logical coordinates. + The scale factor can be any real number; the default value is 1.0. If you + set the factor to 0.0, the item will be collapsed to a single point. If you + provide a negative value, the item will be flipped vertically around its + origin. - \sa xScale + \sa xScale, origin */ qreal QGraphicsScale::yScale() const { Q_D(const QGraphicsScale); return d->yScale; } - void QGraphicsScale::setYScale(qreal scale) { Q_D(QGraphicsScale); @@ -254,14 +301,7 @@ void QGraphicsScale::setYScale(qreal scale) } /*! - \fn QGraphicsScale::scaleChanged() - - This signal is emitted whenever the xScale or yScale of the object - changes. -*/ - -/*! - \reimp + \reimp */ void QGraphicsScale::applyTo(QTransform *transform) const { @@ -272,12 +312,41 @@ void QGraphicsScale::applyTo(QTransform *transform) const } /*! - \class QGraphicsRotation - \brief The QGraphicsRotation class provides a way to rotate a graphics item in 2 dimensions. - \since 4.6 + \fn QGraphicsScale::originChanged() + + QGraphicsScale emits this signal when its origin changes. + + \sa QGraphicsScale::origin +*/ + +/*! + \fn QGraphicsScale::scaleChanged() + + This signal is emitted whenever the xScale or yScale of the object + changes. - QGraphicsRotation contains an \a origin around which the rotation happens, and one - angle in degrees describing the amount of the rotation. + \sa QGraphicsScale::xScale, QGraphicsScale::yScale +*/ + +/*! + \class QGraphicsRotation + \brief The QGraphicsRotation class provides a rotation transformation. + \since 4.6 + + QGraphicsRotation provides certain parameters to help control how the + rotation should be applied. + + The origin is the point that the item is rotated around (i.e., it stays + fixed relative to the parent as the rest of the item is rotated). By + default the origin is QPointF(0, 0). + + The angle property provides the number of degrees to rotate the item + clockwise around the origin. This value also be negative, indicating a + counter-clockwise rotation. For animation purposes it may also be useful to + provide rotation angles exceeding (-360, 360) degrees, for instance to + animate how an item rotates several times. + + \sa QGraphicsTransform, QGraphicsItem::setRotation(), QTransform::rotate() */ class QGraphicsRotationPrivate : public QGraphicsTransformPrivate @@ -291,7 +360,7 @@ public: }; /*! - Constructs a new graphics rotation with \a parent. + Constructs a new QGraphicsRotation with the given \a parent. */ QGraphicsRotation::QGraphicsRotation(QObject *parent) : QGraphicsTransform(*new QGraphicsRotationPrivate, parent) @@ -299,7 +368,7 @@ QGraphicsRotation::QGraphicsRotation(QObject *parent) } /*! - \internal + \internal */ QGraphicsRotation::QGraphicsRotation(QGraphicsRotationPrivate &p, QObject *parent) : QGraphicsTransform(p, parent) @@ -307,24 +376,26 @@ QGraphicsRotation::QGraphicsRotation(QGraphicsRotationPrivate &p, QObject *paren } /*! - Destructs the object + Destroys the graphics rotation. */ QGraphicsRotation::~QGraphicsRotation() { } /*! - \property QGraphicsRotation::origin - The origin around which this object will rotate the graphics item. + \property QGraphicsRotation::origin + \brief the origin of the rotation. - The \a origin is in other words the fixed point for the transformation. + All rotations will be done relative to this point (i.e., this point + will stay fixed, relative to the parent, when the item is rotated). + + \sa angle */ QPointF QGraphicsRotation::origin() const { Q_D(const QGraphicsRotation); return d->origin; } - void QGraphicsRotation::setOrigin(const QPointF &point) { Q_D(QGraphicsRotation); @@ -334,22 +405,22 @@ void QGraphicsRotation::setOrigin(const QPointF &point) } /*! - \fn QGraphicsRotation::originChanged() + \property QGraphicsRotation::angle + \brief the angle for clockwise rotation, in degrees. - This signal is emitted whenever the origin of the object - changes. -*/ + The angle can be any real number; the default value is 0.0. A value of 180 + will rotate 180 degrees, clockwise. If you provide a negative number, the + item will be rotated counter-clockwise. Normally the rotation angle will be + in the range (-360, 360), but you can also provide numbers outside of this + range (e.g., a angle of 370 degrees gives the same result as 10 degrees). -/*! - \property QGraphicsRotation::angle - The angle, in degrees, of the rotation. + \sa origin */ qreal QGraphicsRotation::angle() const { Q_D(const QGraphicsRotation); return d->angle; } - void QGraphicsRotation::setAngle(qreal angle) { Q_D(QGraphicsRotation); @@ -361,33 +432,50 @@ void QGraphicsRotation::setAngle(qreal angle) } /*! - \fn void QGraphicsRotation::angleChanged() - - This signal is emitted whenever the angle of the object - changes. -*/ - -/*! - \reimp + \reimp */ void QGraphicsRotation::applyTo(QTransform *t) const { Q_D(const QGraphicsRotation); - if(d->angle) { + if (d->angle) { t->translate(d->origin.x(), d->origin.y()); t->rotate(d->angle); t->translate(-d->origin.x(), -d->origin.y()); } } +/*! + \fn QGraphicsRotation::originChanged() + + This signal is emitted whenever the origin has changed. + + \sa QGraphicsRotation::origin +*/ /*! - \class QGraphicsRotation3D - \brief The QGraphicsRotation3D class provides a way to rotate a graphics item in 3 dimensions. - \since 4.6 + \fn void QGraphicsRotation::angleChanged() - In addition to the origin and angle of a simple QGraphicsRotation, QGraphicsRotation3D contains - also an axis that describes around which axis in space the rotation is supposed to happen. + This signal is emitted whenever the angle has changed. + + \sa QGraphicsRotation::angle +*/ + +/*! + \class QGraphicsRotation3D + \brief The QGraphicsRotation3D class provides rotation in 3 dimensions. + \since 4.6 + + QGraphicsRotation3D extends QGraphicsRotation with the ability to rotate + around a given axis. + + You can provide the desired axis by assigning a QVector3D to the axis + property. The angle property, which is provided by QGraphicsRotation, now + describes the number of degrees to rotate around this axis. + + By default the axis is (0, 0, 1), giving QGraphicsRotation3D the same + default behavior as QGraphicsRotation (i.e., rotation around the Z axis). + + \sa QGraphicsTransform, QGraphicsItem::setRotation(), QTransform::rotate() */ class QGraphicsRotation3DPrivate : public QGraphicsRotationPrivate @@ -399,7 +487,7 @@ public: }; /*! - Constructs a new 3D rotation with \a parent. + Constructs a new QGraphicsRotation3D with the given \a parent. */ QGraphicsRotation3D::QGraphicsRotation3D(QObject *parent) : QGraphicsRotation(*new QGraphicsRotation3DPrivate, parent) @@ -407,7 +495,7 @@ QGraphicsRotation3D::QGraphicsRotation3D(QObject *parent) } /*! - Destroys the object + Destroys the 3D graphics rotation. */ QGraphicsRotation3D::~QGraphicsRotation3D() { @@ -415,15 +503,22 @@ QGraphicsRotation3D::~QGraphicsRotation3D() /*! \property QGraphicsRotation3D::axis + \brief a rotation axis, specified by a vector in 3D space. + + This can be any axis in 3D space. By default the axis is (0, 0, 1), + which is aligned with the Z axis and provides the same behavior + for the rotation angle as QGraphicsRotation. If you provide another + axis, QGraphicsRotation3D will provide a transformation that rotates + around this axis. For example, if you would like to rotate an item + around its X axis, you could pass (1, 0, 0) as the axis. - A rotation axis is specified by a vector in 3D space. + \sa QTransform, QGraphicsRotation::angle */ QVector3D QGraphicsRotation3D::axis() { Q_D(QGraphicsRotation3D); return d->axis; } - void QGraphicsRotation3D::setAxis(const QVector3D &axis) { Q_D(QGraphicsRotation3D); @@ -431,17 +526,10 @@ void QGraphicsRotation3D::setAxis(const QVector3D &axis) update(); } -/*! - \fn void QGraphicsRotation3D::axisChanged() - - This signal is emitted whenever the axis of the object - changes. -*/ - -const qreal inv_dist_to_plane = 1. / 1024.; +static const qreal inv_dist_to_plane = 1. / 1024.; /*! - \reimp + \reimp */ void QGraphicsRotation3D::applyTo(QTransform *t) const { @@ -474,6 +562,12 @@ void QGraphicsRotation3D::applyTo(QTransform *t) const t->translate(-d->origin.x(), -d->origin.y()); } +/*! + \fn void QGraphicsRotation3D::axisChanged() + + This signal is emitted whenever the axis of the object changes. +*/ + #include "moc_qgraphicstransform.cpp" QT_END_NAMESPACE diff --git a/src/gui/graphicsview/qgraphicstransform.h b/src/gui/graphicsview/qgraphicstransform.h index b5d8d84..d7c07d0 100644 --- a/src/gui/graphicsview/qgraphicstransform.h +++ b/src/gui/graphicsview/qgraphicstransform.h @@ -70,6 +70,7 @@ protected Q_SLOTS: protected: QGraphicsTransform(QGraphicsTransformPrivate &p, QObject *parent); + private: friend class QGraphicsItem; friend class QGraphicsItemPrivate; -- cgit v0.12 From 56b6a5924008ab5cdbae36e9662eddba923acd5e Mon Sep 17 00:00:00 2001 From: Rohan McGovern Date: Fri, 31 Jul 2009 08:50:07 +1000 Subject: Fixed corrupt testlogs on Windows and other places where vsnprintf is not C99-compliant. C99 says vsnprintf returns >= `size' when not enough memory was available. In practice, on Windows, glibc < 2.0.6, and probably plenty of other places it returns -1 instead. Reviewed-by: Rhys Weatherley --- src/testlib/qtestcase.cpp | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/testlib/qtestcase.cpp b/src/testlib/qtestcase.cpp index e44be9c..1dae828 100644 --- a/src/testlib/qtestcase.cpp +++ b/src/testlib/qtestcase.cpp @@ -834,11 +834,12 @@ int qt_asprintf(char **str, const char *format, ...) res = qvsnprintf(*str, size, format, ap); va_end(ap); (*str)[size - 1] = '\0'; - if (res < size) { - // We succeeded or fatally failed + if (res >= 0 && res < size) { + // We succeeded break; } - // buffer wasn't big enough, try again + // buffer wasn't big enough, try again. + // Note, we're assuming that a result of -1 is always due to running out of space. size *= 2; if (size > MAXSIZE) { break; -- cgit v0.12