diff options
author | Jason Barron <jbarron@trolltech.com> | 2009-08-18 06:34:18 (GMT) |
---|---|---|
committer | Jason Barron <jbarron@trolltech.com> | 2009-08-18 06:34:18 (GMT) |
commit | fd6740b6ade6e7f8e51a9cc558b723e7fae15ccf (patch) | |
tree | aa2ba4ce64d047d73c29ab0616e8a89d352c3abd /doc/src | |
parent | d24029e3d4639f1300e7a68858936911df969f69 (diff) | |
parent | 572e165dcb8cc8fcdfaa4ab9bdab050f6a6cc173 (diff) | |
download | Qt-fd6740b6ade6e7f8e51a9cc558b723e7fae15ccf.zip Qt-fd6740b6ade6e7f8e51a9cc558b723e7fae15ccf.tar.gz Qt-fd6740b6ade6e7f8e51a9cc558b723e7fae15ccf.tar.bz2 |
Merge commit 'qt/master'
Conflicts:
doc/src/examples.qdoc
doc/src/plugins-howto.qdoc
doc/src/topics.qdoc
examples/phonon/musicplayer/mainwindow.cpp
src/3rdparty/freetype/src/base/ftobjs.c
src/corelib/global/qglobal.h
src/corelib/tools/qalgorithms.h
src/corelib/tools/qshareddata.cpp
src/corelib/tools/qsharedpointer.cpp
src/corelib/tools/tools.pri
src/corelib/xml/qxmlstream.h
src/gui/painting/painting.pri
src/gui/widgets/qdatetimeedit.cpp
tests/auto/qdesktopservices/qdesktopservices.pro
tests/auto/qgraphicsitem/tst_qgraphicsitem.cpp
tests/auto/qtextcodec/test/test.pro
Diffstat (limited to 'doc/src')
-rw-r--r-- | doc/src/bughowto.qdoc | 1 | ||||
-rw-r--r-- | doc/src/classes.qdoc | 31 | ||||
-rw-r--r-- | doc/src/classes/exportedfunctions.qdoc (renamed from doc/src/exportedfunctions.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/classes/phonon-namespace.qdoc (renamed from doc/src/qtassistant.qdoc) | 18 | ||||
-rw-r--r-- | doc/src/classes/q3asciicache.qdoc | 465 | ||||
-rw-r--r-- | doc/src/classes/q3asciidict.qdoc | 416 | ||||
-rw-r--r-- | doc/src/classes/q3cache.qdoc | 461 | ||||
-rw-r--r-- | doc/src/classes/q3dict.qdoc | 446 | ||||
-rw-r--r-- | doc/src/classes/q3intcache.qdoc | 446 | ||||
-rw-r--r-- | doc/src/classes/q3intdict.qdoc | 390 | ||||
-rw-r--r-- | doc/src/classes/q3memarray.qdoc | 523 | ||||
-rw-r--r-- | doc/src/classes/q3ptrdict.qdoc | 388 | ||||
-rw-r--r-- | doc/src/classes/q3ptrlist.qdoc | 1157 | ||||
-rw-r--r-- | doc/src/classes/q3ptrqueue.qdoc | 230 | ||||
-rw-r--r-- | doc/src/classes/q3ptrstack.qdoc | 217 | ||||
-rw-r--r-- | doc/src/classes/q3ptrvector.qdoc | 427 | ||||
-rw-r--r-- | doc/src/classes/q3sqlfieldinfo.qdoc | 234 | ||||
-rw-r--r-- | doc/src/classes/q3valuelist.qdoc | 569 | ||||
-rw-r--r-- | doc/src/classes/q3valuestack.qdoc | 149 | ||||
-rw-r--r-- | doc/src/classes/q3valuevector.qdoc | 274 | ||||
-rw-r--r-- | doc/src/classes/qalgorithms.qdoc | 651 | ||||
-rw-r--r-- | doc/src/classes/qcache.qdoc | 244 | ||||
-rw-r--r-- | doc/src/classes/qcolormap.qdoc | 152 | ||||
-rw-r--r-- | doc/src/classes/qdesktopwidget.qdoc | 266 | ||||
-rw-r--r-- | doc/src/classes/qiterator.qdoc | 1431 | ||||
-rw-r--r-- | doc/src/classes/qmacstyle.qdoc | 261 | ||||
-rw-r--r-- | doc/src/classes/qnamespace.qdoc | 2751 | ||||
-rw-r--r-- | doc/src/classes/qpaintdevice.qdoc | 289 | ||||
-rw-r--r-- | doc/src/classes/qpair.qdoc | 229 | ||||
-rw-r--r-- | doc/src/classes/qplugin.qdoc | 135 | ||||
-rw-r--r-- | doc/src/classes/qprinterinfo.qdoc | 137 | ||||
-rw-r--r-- | doc/src/classes/qset.qdoc | 953 | ||||
-rw-r--r-- | doc/src/classes/qsignalspy.qdoc | 98 | ||||
-rw-r--r-- | doc/src/classes/qsizepolicy.qdoc | 522 | ||||
-rw-r--r-- | doc/src/classes/qtdesigner-api.qdoc | 1413 | ||||
-rw-r--r-- | doc/src/classes/qtendian.qdoc | 168 | ||||
-rw-r--r-- | doc/src/classes/qtestevent.qdoc | 191 | ||||
-rw-r--r-- | doc/src/classes/qvarlengtharray.qdoc | 274 | ||||
-rw-r--r-- | doc/src/classes/qwaitcondition.qdoc | 188 | ||||
-rw-r--r-- | doc/src/codecs.qdoc | 534 | ||||
-rw-r--r-- | doc/src/demos/qtdemo.qdoc (renamed from doc/src/qtdemo.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/deployment/deployment-plugins.qdoc | 236 | ||||
-rw-r--r-- | doc/src/deployment/deployment.qdoc (renamed from doc/src/deployment.qdoc) | 18 | ||||
-rw-r--r-- | doc/src/deployment/qt-conf.qdoc (renamed from doc/src/qt-conf.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/deployment/qtconfig.qdoc (renamed from doc/src/qtconfig.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/desktop-integration.qdoc | 90 | ||||
-rw-r--r-- | doc/src/development/activeqt-dumpcpp.qdoc (renamed from doc/src/activeqt-dumpcpp.qdoc) | 12 | ||||
-rw-r--r-- | doc/src/development/activeqt-dumpdoc.qdoc (renamed from doc/src/activeqt-dumpdoc.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/development/activeqt-idc.qdoc (renamed from doc/src/activeqt-idc.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/development/activeqt-testcon.qdoc (renamed from doc/src/activeqt-testcon.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/development/assistant-manual.qdoc (renamed from doc/src/assistant-manual.qdoc) | 4 | ||||
-rw-r--r-- | doc/src/development/debug.qdoc (renamed from doc/src/debug.qdoc) | 13 | ||||
-rw-r--r-- | doc/src/development/designer-manual.qdoc (renamed from doc/src/designer-manual.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/development/developing-on-mac.qdoc (renamed from doc/src/developing-on-mac.qdoc) | 2 | ||||
-rw-r--r-- | doc/src/development/developing-with-qt.qdoc (renamed from doc/src/classes/q3popupmenu.qdoc) | 60 | ||||
-rw-r--r-- | doc/src/development/moc.qdoc (renamed from doc/src/moc.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/development/qmake-manual.qdoc (renamed from doc/src/qmake-manual.qdoc) | 5 | ||||
-rw-r--r-- | doc/src/development/qmsdev.qdoc (renamed from doc/src/qmsdev.qdoc) | 37 | ||||
-rw-r--r-- | doc/src/development/qtestlib.qdoc (renamed from doc/src/qtestlib.qdoc) | 3 | ||||
-rw-r--r-- | doc/src/development/rcc.qdoc (renamed from doc/src/rcc.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/development/tools-list.qdoc (renamed from doc/src/tools-list.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/development/uic.qdoc (renamed from doc/src/uic.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/distributingqt.qdoc | 154 | ||||
-rw-r--r-- | doc/src/examples-overview.qdoc | 367 | ||||
-rw-r--r-- | doc/src/examples.qdoc | 438 | ||||
-rw-r--r-- | doc/src/examples/application.qdoc | 2 | ||||
-rw-r--r-- | doc/src/examples/drilldown.qdoc | 4 | ||||
-rw-r--r-- | doc/src/examples/qtscriptcalculator.qdoc | 1 | ||||
-rw-r--r-- | doc/src/examples/trafficinfo.qdoc | 2 | ||||
-rw-r--r-- | doc/src/files-and-resources/datastreamformat.qdoc (renamed from doc/src/datastreamformat.qdoc) | 13 | ||||
-rw-r--r-- | doc/src/files-and-resources/resources.qdoc (renamed from doc/src/resources.qdoc) | 13 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/accessible.qdoc (renamed from doc/src/accessible.qdoc) | 32 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/activeqt-container.qdoc (renamed from doc/src/qaxcontainer.qdoc) | 48 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/activeqt-server.qdoc (renamed from doc/src/qaxserver.qdoc) | 54 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/activeqt.qdoc (renamed from doc/src/activeqt.qdoc) | 14 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/animation.qdoc (renamed from doc/src/animation.qdoc) | 17 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/containers.qdoc (renamed from doc/src/containers.qdoc) | 41 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/dbus-adaptors.qdoc (renamed from doc/src/qdbusadaptors.qdoc) | 56 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/dbus-intro.qdoc (renamed from doc/src/introtodbus.qdoc) | 4 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/desktop-integration.qdoc | 111 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/dnd.qdoc (renamed from doc/src/dnd.qdoc) | 129 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/eventsandfilters.qdoc (renamed from doc/src/eventsandfilters.qdoc) | 16 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/gestures.qdoc | 170 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/graphicsview.qdoc (renamed from doc/src/graphicsview.qdoc) | 15 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/implicit-sharing.qdoc (renamed from doc/src/implicit-sharing.qdoc) | 16 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/ipc.qdoc (renamed from doc/src/ipc.qdoc) | 28 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/model-view-programming.qdoc (renamed from doc/src/model-view-programming.qdoc) | 19 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/phonon.qdoc (renamed from doc/src/phonon.qdoc) | 87 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/plugins-howto.qdoc (renamed from doc/src/plugins-howto.qdoc) | 279 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/qthelp.qdoc (renamed from doc/src/qthelp.qdoc) | 76 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/qundo.qdoc | 113 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/richtext.qdoc | 1226 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/statemachine.qdoc (renamed from doc/src/statemachine.qdoc) | 14 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/templates.qdoc (renamed from doc/src/templates.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/threads.qdoc (renamed from doc/src/threads.qdoc) | 388 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/unicode.qdoc (renamed from doc/src/unicode.qdoc) | 51 | ||||
-rw-r--r-- | doc/src/geometry.qdoc | 150 | ||||
-rw-r--r-- | doc/src/getting-started/demos.qdoc (renamed from doc/src/demos.qdoc) | 21 | ||||
-rw-r--r-- | doc/src/getting-started/examples.qdoc | 1108 | ||||
-rw-r--r-- | doc/src/getting-started/how-to-learn-qt.qdoc (renamed from doc/src/how-to-learn-qt.qdoc) | 15 | ||||
-rw-r--r-- | doc/src/getting-started/installation.qdoc (renamed from doc/src/installation.qdoc) | 16 | ||||
-rw-r--r-- | doc/src/getting-started/known-issues.qdoc (renamed from doc/src/known-issues.qdoc) | 33 | ||||
-rw-r--r-- | doc/src/getting-started/tutorials.qdoc | 103 | ||||
-rw-r--r-- | doc/src/groups.qdoc | 487 | ||||
-rw-r--r-- | doc/src/howtos/accelerators.qdoc (renamed from doc/src/accelerators.qdoc) | 3 | ||||
-rw-r--r-- | doc/src/howtos/appicon.qdoc (renamed from doc/src/appicon.qdoc) | 15 | ||||
-rw-r--r-- | doc/src/howtos/custom-types.qdoc (renamed from doc/src/custom-types.qdoc) | 3 | ||||
-rw-r--r-- | doc/src/howtos/guibooks.qdoc (renamed from doc/src/guibooks.qdoc) | 3 | ||||
-rw-r--r-- | doc/src/howtos/openvg.qdoc (renamed from doc/src/qtopenvg.qdoc) | 24 | ||||
-rw-r--r-- | doc/src/howtos/qtdesigner.qdoc (renamed from doc/src/qtdesigner.qdoc) | 30 | ||||
-rw-r--r-- | doc/src/howtos/restoring-geometry.qdoc | 87 | ||||
-rw-r--r-- | doc/src/howtos/session.qdoc (renamed from doc/src/session.qdoc) | 3 | ||||
-rw-r--r-- | doc/src/howtos/sharedlibrary.qdoc (renamed from doc/src/sharedlibrary.qdoc) | 16 | ||||
-rw-r--r-- | doc/src/howtos/timers.qdoc (renamed from doc/src/timers.qdoc) | 3 | ||||
-rw-r--r-- | doc/src/howtos/unix-signal-handlers.qdoc (renamed from doc/src/unix-signal-handlers.qdoc) | 4 | ||||
-rw-r--r-- | doc/src/images/activeqt-examples.png | bin | 0 -> 6671 bytes | |||
-rw-r--r-- | doc/src/images/animation-examples.png | bin | 0 -> 28060 bytes | |||
-rw-r--r-- | doc/src/images/ipc-examples.png | bin | 0 -> 7727 bytes | |||
-rw-r--r-- | doc/src/images/qq-thumbnail.png | bin | 0 -> 27022 bytes | |||
-rw-r--r-- | doc/src/images/statemachine-examples.png | bin | 0 -> 3326 bytes | |||
-rw-r--r-- | doc/src/images/webkit-examples.png | bin | 26874 -> 19323 bytes | |||
-rw-r--r-- | doc/src/index.qdoc | 195 | ||||
-rw-r--r-- | doc/src/internationalization/i18n.qdoc (renamed from doc/src/i18n.qdoc) | 19 | ||||
-rw-r--r-- | doc/src/internationalization/linguist-manual.qdoc (renamed from doc/src/linguist-manual.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/legal/commercialeditions.qdoc | 3 | ||||
-rw-r--r-- | doc/src/legal/editions.qdoc | 12 | ||||
-rw-r--r-- | doc/src/legal/licenses.qdoc | 1 | ||||
-rw-r--r-- | doc/src/modules.qdoc | 952 | ||||
-rw-r--r-- | doc/src/network-programming/qtnetwork.qdoc (renamed from doc/src/qtnetwork.qdoc) | 50 | ||||
-rw-r--r-- | doc/src/network-programming/ssl.qdoc (renamed from doc/src/classes/qpagesetupdialog.qdoc) | 55 | ||||
-rw-r--r-- | doc/src/objectmodel/metaobjects.qdoc (renamed from doc/src/metaobjects.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/objectmodel/object.qdoc (renamed from doc/src/object.qdoc) | 9 | ||||
-rw-r--r-- | doc/src/objectmodel/objecttrees.qdoc | 115 | ||||
-rw-r--r-- | doc/src/objectmodel/properties.qdoc (renamed from doc/src/properties.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/objectmodel/signalsandslots.qdoc (renamed from doc/src/signalsandslots.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/objecttrees.qdoc | 117 | ||||
-rw-r--r-- | doc/src/overviews.qdoc | 25 | ||||
-rw-r--r-- | doc/src/painting-and-printing/coordsys.qdoc (renamed from doc/src/coordsys.qdoc) | 17 | ||||
-rw-r--r-- | doc/src/painting-and-printing/paintsystem.qdoc (renamed from doc/src/paintsystem.qdoc) | 447 | ||||
-rw-r--r-- | doc/src/painting-and-printing/printing.qdoc (renamed from doc/src/printing.qdoc) | 20 | ||||
-rw-r--r-- | doc/src/platforms/atomic-operations.qdoc (renamed from doc/src/atomic-operations.qdoc) | 13 | ||||
-rw-r--r-- | doc/src/platforms/compiler-notes.qdoc (renamed from doc/src/compiler-notes.qdoc) | 2 | ||||
-rw-r--r-- | doc/src/platforms/emb-accel.qdoc (renamed from doc/src/emb-accel.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-architecture.qdoc (renamed from doc/src/qtopiacore-architecture.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-charinput.qdoc (renamed from doc/src/emb-charinput.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-crosscompiling.qdoc (renamed from doc/src/emb-crosscompiling.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-deployment.qdoc (renamed from doc/src/emb-deployment.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-differences.qdoc (renamed from doc/src/emb-differences.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-displaymanagement.qdoc (renamed from doc/src/qtopiacore-displaymanagement.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-envvars.qdoc (renamed from doc/src/emb-envvars.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-features.qdoc (renamed from doc/src/emb-features.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-fonts.qdoc (renamed from doc/src/emb-fonts.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-framebuffer-howto.qdoc (renamed from doc/src/emb-framebuffer-howto.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-install.qdoc (renamed from doc/src/emb-install.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-kmap2qmap.qdoc (renamed from doc/src/emb-kmap2qmap.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-makeqpf.qdoc (renamed from doc/src/emb-makeqpf.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-opengl.qdoc (renamed from doc/src/qtopiacore-opengl.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-performance.qdoc (renamed from doc/src/emb-performance.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-pointer.qdoc (renamed from doc/src/emb-pointer.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-porting.qdoc (renamed from doc/src/emb-porting.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-qvfb.qdoc (renamed from doc/src/emb-qvfb.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-running.qdoc (renamed from doc/src/emb-running.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/emb-vnc.qdoc (renamed from doc/src/emb-vnc.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/mac-differences.qdoc (renamed from doc/src/mac-differences.qdoc) | 2 | ||||
-rw-r--r-- | doc/src/platforms/platform-notes-rtos.qdoc (renamed from doc/src/platform-notes-rtos.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/platform-notes.qdoc (renamed from doc/src/platform-notes.qdoc) | 15 | ||||
-rw-r--r-- | doc/src/platforms/qt-embedded-linux.qdoc (renamed from doc/src/qtopiacore.qdoc) | 16 | ||||
-rw-r--r-- | doc/src/platforms/qt-embedded.qdoc (renamed from doc/src/qt-embedded.qdoc) | 2 | ||||
-rw-r--r-- | doc/src/platforms/qtmac-as-native.qdoc (renamed from doc/src/qtmac-as-native.qdoc) | 2 | ||||
-rw-r--r-- | doc/src/platforms/supported-platforms.qdoc (renamed from doc/src/supported-platforms.qdoc) | 2 | ||||
-rw-r--r-- | doc/src/platforms/wince-customization.qdoc (renamed from doc/src/wince-customization.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/wince-introduction.qdoc (renamed from doc/src/wince-introduction.qdoc) | 34 | ||||
-rw-r--r-- | doc/src/platforms/wince-opengl.qdoc (renamed from doc/src/wince-opengl.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/winsystem.qdoc (renamed from doc/src/winsystem.qdoc) | 3 | ||||
-rw-r--r-- | doc/src/platforms/x11overlays.qdoc (renamed from doc/src/qtopengl.qdoc) | 69 | ||||
-rw-r--r-- | doc/src/porting/porting-qsa.qdoc (renamed from doc/src/porting-qsa.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-canvas.qdoc (renamed from doc/src/porting4-canvas.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/porting/porting4-designer.qdoc (renamed from doc/src/porting4-designer.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-dnd.qdoc | 152 | ||||
-rw-r--r-- | doc/src/porting/porting4-modifiedvirtual.qdocinc (renamed from doc/src/porting4-modifiedvirtual.qdocinc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-obsoletedmechanism.qdocinc (renamed from doc/src/porting4-obsoletedmechanism.qdocinc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-overview.qdoc (renamed from doc/src/porting4-overview.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-removedenumvalues.qdocinc (renamed from doc/src/porting4-removedenumvalues.qdocinc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-removedtypes.qdocinc (renamed from doc/src/porting4-removedtypes.qdocinc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-removedvariantfunctions.qdocinc (renamed from doc/src/porting4-removedvariantfunctions.qdocinc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-removedvirtual.qdocinc (renamed from doc/src/porting4-removedvirtual.qdocinc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-renamedclasses.qdocinc (renamed from doc/src/porting4-renamedclasses.qdocinc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-renamedenumvalues.qdocinc (renamed from doc/src/porting4-renamedenumvalues.qdocinc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-renamedfunctions.qdocinc (renamed from doc/src/porting4-renamedfunctions.qdocinc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-renamedstatic.qdocinc (renamed from doc/src/porting4-renamedstatic.qdocinc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4-renamedtypes.qdocinc (renamed from doc/src/porting4-renamedtypes.qdocinc) | 0 | ||||
-rw-r--r-- | doc/src/porting/porting4.qdoc (renamed from doc/src/porting4.qdoc) | 37 | ||||
-rw-r--r-- | doc/src/porting/qt3to4.qdoc (renamed from doc/src/qt3to4.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/qt4-accessibility.qdoc (renamed from doc/src/qt4-accessibility.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/porting/qt4-arthur.qdoc (renamed from doc/src/qt4-arthur.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/qt4-designer.qdoc (renamed from doc/src/qt4-designer.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/qt4-interview.qdoc (renamed from doc/src/qt4-interview.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/qt4-mainwindow.qdoc (renamed from doc/src/qt4-mainwindow.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/qt4-network.qdoc (renamed from doc/src/qt4-network.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/qt4-scribe.qdoc (renamed from doc/src/qt4-scribe.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/qt4-sql.qdoc (renamed from doc/src/qt4-sql.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/qt4-styles.qdoc (renamed from doc/src/qt4-styles.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/qt4-threads.qdoc (renamed from doc/src/qt4-threads.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/porting/qt4-tulip.qdoc (renamed from doc/src/qt4-tulip.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/qsql.qdoc | 139 | ||||
-rw-r--r-- | doc/src/qt-webpages.qdoc (renamed from doc/src/trolltech-webpages.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/qt3support.qdoc | 81 | ||||
-rw-r--r-- | doc/src/qt4-intro.qdoc | 6 | ||||
-rw-r--r-- | doc/src/qtdbus.qdoc | 124 | ||||
-rw-r--r-- | doc/src/qtgui.qdoc | 59 | ||||
-rw-r--r-- | doc/src/qtmain.qdoc | 93 | ||||
-rw-r--r-- | doc/src/qtsvg.qdoc | 135 | ||||
-rw-r--r-- | doc/src/qttest.qdoc | 70 | ||||
-rw-r--r-- | doc/src/qtuiloader.qdoc | 82 | ||||
-rw-r--r-- | doc/src/qundo.qdoc | 113 | ||||
-rw-r--r-- | doc/src/richtext.qdoc | 1076 | ||||
-rw-r--r-- | doc/src/scripting/ecmascript.qdoc (renamed from doc/src/ecmascript.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/scripting/qtscriptdebugger-manual.qdoc (renamed from doc/src/qtscriptdebugger-manual.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/scripting/qtscriptextensions.qdoc (renamed from doc/src/qtscriptextensions.qdoc) | 11 | ||||
-rw-r--r-- | doc/src/scripting/scripting.qdoc (renamed from doc/src/qtscript.qdoc) | 61 | ||||
-rw-r--r-- | doc/src/snippets/code/doc_src_qalgorithms.qdoc | 2 | ||||
-rw-r--r-- | doc/src/snippets/code/doc_src_qtmultimedia.qdoc | 8 | ||||
-rw-r--r-- | doc/src/snippets/gestures/imageviewer/imagewidget.cpp | 364 | ||||
-rw-r--r-- | doc/src/snippets/gestures/imageviewer/imagewidget.h | 137 | ||||
-rw-r--r-- | doc/src/snippets/gestures/imageviewer/tapandholdgesture.cpp | 159 | ||||
-rw-r--r-- | doc/src/snippets/gestures/imageviewer/tapandholdgesture.h (renamed from doc/src/qtcore.qdoc) | 44 | ||||
-rw-r--r-- | doc/src/snippets/gestures/qgesture.cpp | 283 | ||||
-rw-r--r-- | doc/src/snippets/gestures/qgesture.h (renamed from doc/src/qtscripttools.qdoc) | 75 | ||||
-rw-r--r-- | doc/src/snippets/gestures/qstandardgestures.cpp | 483 | ||||
-rw-r--r-- | doc/src/snippets/gestures/qstandardgestures.h (renamed from doc/src/classes/q3sqlrecordinfo.qdoc) | 109 | ||||
-rw-r--r-- | doc/src/sql-programming/qsqldatatype-table.qdoc (renamed from doc/src/qsqldatatype-table.qdoc) | 4 | ||||
-rw-r--r-- | doc/src/sql-programming/sql-driver.qdoc (renamed from doc/src/sql-driver.qdoc) | 12 | ||||
-rw-r--r-- | doc/src/sql-programming/sql-programming.qdoc (renamed from doc/src/qtsql.qdoc) | 153 | ||||
-rw-r--r-- | doc/src/topics.qdoc | 305 | ||||
-rw-r--r-- | doc/src/tutorials/addressbook-fr.qdoc | 3 | ||||
-rw-r--r-- | doc/src/tutorials/addressbook.qdoc | 3 | ||||
-rw-r--r-- | doc/src/tutorials/widgets-tutorial.qdoc | 15 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/focus.qdoc (renamed from doc/src/focus.qdoc) | 17 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/gallery-cde.qdoc (renamed from doc/src/gallery-cde.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/gallery-cleanlooks.qdoc (renamed from doc/src/gallery-cleanlooks.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/gallery-gtk.qdoc (renamed from doc/src/gallery-gtk.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/gallery-macintosh.qdoc (renamed from doc/src/gallery-macintosh.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/gallery-motif.qdoc (renamed from doc/src/gallery-motif.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/gallery-plastique.qdoc (renamed from doc/src/gallery-plastique.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/gallery-windows.qdoc (renamed from doc/src/gallery-windows.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/gallery-windowsvista.qdoc (renamed from doc/src/gallery-windowsvista.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/gallery-windowsxp.qdoc (renamed from doc/src/gallery-windowsxp.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/gallery.qdoc (renamed from doc/src/gallery.qdoc) | 1 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/layout.qdoc (renamed from doc/src/layout.qdoc) | 16 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/styles.qdoc (renamed from doc/src/styles.qdoc) | 100 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/stylesheet.qdoc (renamed from doc/src/stylesheet.qdoc) | 42 | ||||
-rw-r--r-- | doc/src/widgets-and-layouts/widgets.qdoc | 187 | ||||
-rw-r--r-- | doc/src/windows-and-dialogs/dialogs.qdoc (renamed from doc/src/classes/qprintdialog.qdoc) | 44 | ||||
-rw-r--r-- | doc/src/windows-and-dialogs/mainwindow.qdoc | 279 | ||||
-rw-r--r-- | doc/src/xml-processing/xml-patterns.qdoc (renamed from doc/src/qtxmlpatterns.qdoc) | 76 | ||||
-rw-r--r-- | doc/src/xml-processing/xml-processing.qdoc (renamed from doc/src/qtxml.qdoc) | 402 | ||||
-rw-r--r-- | doc/src/xml-processing/xquery-introduction.qdoc (renamed from doc/src/xquery-introduction.qdoc) | 3 |
257 files changed, 8233 insertions, 23873 deletions
diff --git a/doc/src/bughowto.qdoc b/doc/src/bughowto.qdoc index b6520f3..645154b 100644 --- a/doc/src/bughowto.qdoc +++ b/doc/src/bughowto.qdoc @@ -43,7 +43,6 @@ \page bughowto.html \title How to Report a Bug \brief Information about ways to report bugs in Qt. - \ingroup howto If you think you have found a bug in Qt, we would like to hear about it so that we can fix it. diff --git a/doc/src/classes.qdoc b/doc/src/classes.qdoc index d9a0ae9..864445f 100644 --- a/doc/src/classes.qdoc +++ b/doc/src/classes.qdoc @@ -40,6 +40,18 @@ ****************************************************************************/ /*! + \group classlists + \title Class and Function Indexes + \brief Collections of classes and functions grouped together into lists. + + The following documents contain collections of classes, grouped by + subject area or related to particular functionality, or comprehensive + lists of classes and functions. + + \generatelist{related} +*/ + +/*! \group groups \title Grouped Classes \ingroup classlists @@ -56,11 +68,9 @@ \title Qt's Classes \ingroup classlists - This is a list of all Qt classes. For a shorter list of the most - frequently used Qt classes, see \l{Qt's Main Classes}. For a list - of the classes provided for compatibility with Qt3, see \l{Qt 3 - compatibility classes}. For classes that have been deprecated, see - the \l{Obsolete Classes} list. + This is a list of all Qt classes. For a list of the classes provided + for compatibility with Qt3, see \l{Qt 3 compatibility classes}. For + classes that have been deprecated, see the \l{Obsolete Classes} list. \generatelist classes @@ -128,17 +138,6 @@ */ /*! - \page mainclasses.html - \title Qt's Main Classes - \ingroup classlists - - These are the most frequently used Qt classes. For the complete - list see \link classes.html Qt's Classes \endlink. - - \generatelist mainclasses -*/ - -/*! \page compatclasses.html \title Qt 3 Compatibility Classes \ingroup classlists diff --git a/doc/src/exportedfunctions.qdoc b/doc/src/classes/exportedfunctions.qdoc index c51ace4..c51ace4 100644 --- a/doc/src/exportedfunctions.qdoc +++ b/doc/src/classes/exportedfunctions.qdoc diff --git a/doc/src/qtassistant.qdoc b/doc/src/classes/phonon-namespace.qdoc index 9e52ccf..8007ddf 100644 --- a/doc/src/qtassistant.qdoc +++ b/doc/src/classes/phonon-namespace.qdoc @@ -40,15 +40,15 @@ ****************************************************************************/ /*! - \module QtAssistant - \title QtAssistant Module - \contentspage Qt's Modules - \previouspage QtHelp - \nextpage QtTest - \ingroup modules + \namespace Phonon + \brief The Phonon namespace contains classes and functions for multimedia applications. + \since 4.4 - \brief The QtAssistant module provides a means of launching \QA - to provide online help. + This namespace contains classes to access multimedia functions for + audio and video playback. Those classes are not dependent on any specific + framework, but rather use exchangeable backends to do the work. - \sa {Qt Assistant Manual} + See the \l{Phonon Module} page for general information about the + framework and the \l{Phonon Overview} for an introductory tour of its + features. */ diff --git a/doc/src/classes/q3asciicache.qdoc b/doc/src/classes/q3asciicache.qdoc deleted file mode 100644 index b86113f..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type> &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<type>& Q3AsciiCache::operator=( const Q3AsciiCache<type> &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<type> &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<type> & 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<type>& Q3AsciiCacheIterator::operator=( const Q3AsciiCacheIterator<type> &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 deleted file mode 100644 index 1262a37..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type> &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<type> &Q3AsciiDict::operator=(const Q3AsciiDict<type> &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\<X\> to create a dictionary - iterator that operates on Q3AsciiDict\<X\> (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<type> &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 deleted file mode 100644 index 20b777f..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type> &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<type>& Q3Cache::operator=( const Q3Cache<type> &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<type> &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<type> & 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<type>& Q3CacheIterator::operator=( const Q3CacheIterator<type> &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 deleted file mode 100644 index 2234c2d..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type> &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<type> &Q3Dict::operator=(const Q3Dict<type> &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\<X\> to create a dictionary - iterator that operates on Q3Dict\<X\> (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<type> &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 deleted file mode 100644 index 770532e..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type> &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<type>& Q3IntCache::operator=( const Q3IntCache<type> &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<type> &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<type> & 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<type>& Q3IntCacheIterator::operator=( const Q3IntCacheIterator<type> &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 deleted file mode 100644 index 731050d..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type> &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<type> &Q3IntDict::operator=(const Q3IntDict<type> &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\<X\> to create a dictionary - iterator that operates on Q3IntDict\<X\> (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<type> &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 deleted file mode 100644 index eb0648c..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type>() const - - Automatically converts the Q3MemArray<type> into a QVector<type>. -*/ - -/*! \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<type> &a ) - - Constructs a shallow copy of \a a. - - \sa assign() -*/ - -/*! - \fn Q3MemArray::Q3MemArray(const QVector<type> &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<type> &Q3MemArray::operator=( const Q3MemArray<type> &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<type> Q3MemArray::copy() const - - Returns a deep copy of this array. - - \sa detach(), duplicate() -*/ - -/*! - \fn Q3MemArray<type> &Q3MemArray::assign( const Q3MemArray<type> &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<type> &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<type> &Q3MemArray::duplicate( const Q3MemArray<type> &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<type> &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<type> &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<type> &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<type> &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/q3ptrdict.qdoc b/doc/src/classes/q3ptrdict.qdoc deleted file mode 100644 index 531b085..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type> &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<type> &Q3PtrDict::operator=(const Q3PtrDict<type> &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\<X\> to create a dictionary - iterator that operates on Q3PtrDict\<X\> (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<type> &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 deleted file mode 100644 index b2b9c3f..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type> &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<type> &Q3PtrList::operator=(const Q3PtrList<type> &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<type> &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<type> &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\<X\> to create a list - iterator that operates on Q3PtrList\<X\> (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<type> &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<type>& Q3PtrListIterator::operator=( const Q3PtrListIterator<type> &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\<char\> 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<QByteArray>() const - - Automatically converts a Q3StrList into a QList<QByteArray>. -*/ - -/*! - \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<QByteArray> &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<QByteArray> &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\<char\> 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\<char\> 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 deleted file mode 100644 index c60193c..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type>& 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<type>& Q3PtrQueue::operator= (const Q3PtrQueue<type>& 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 deleted file mode 100644 index 071fcd0..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type>& 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<type>& Q3PtrStack::operator= (const Q3PtrStack<type>& 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 deleted file mode 100644 index c734064..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<type> &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<type> &Q3PtrVector::operator=(const Q3PtrVector<type> &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<type> &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 deleted file mode 100644 index 6f6f359..0000000 --- a/doc/src/classes/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://qt.nokia.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/q3valuelist.qdoc b/doc/src/classes/q3valuelist.qdoc deleted file mode 100644 index 062a9da..0000000 --- a/doc/src/classes/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://qt.nokia.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\<T\> 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<T>& l ) - \fn Q3ValueList::Q3ValueList( const QList<T>& l ) - \fn Q3ValueList::Q3ValueList( const QLinkedList<T>& l ) - - Constructs a copy of \a l. -*/ - -/*! - \fn Q3ValueList::Q3ValueList( const std::list<T>& 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<T>& 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<T>& 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<T>& Q3ValueList::operator= ( const Q3ValueList<T>& 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<T>& Q3ValueList::operator= ( const QList<T>& 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<T>& Q3ValueList::operator= ( const std::list<T>& 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<T>& l ) const - - Compares both lists. - - Returns TRUE if this list and \a l are unequal; otherwise returns - FALSE. -*/ - -/*! - \fn iterator Q3ValueList::insert( typename Q3ValueList<T>::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<T>& 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<T>& 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<T>::Iterator pos, - typename Q3ValueList<T>::size_type n, const T& x ) - - \overload - - Inserts \a n copies of \a x before position \a pos. -*/ - -/*! - \fn Q3ValueList<T>& 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<T>::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<T>::size_type i ) - - \overload - - Returns a non-const reference to the item with index \a i. -*/ - -/*! - \fn const_iterator Q3ValueList::at( typename Q3ValueList<T>::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<T>::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<T> Q3ValueList::operator+( const Q3ValueList<T>& 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<T>& Q3ValueList::operator+= ( const Q3ValueList<T>& l ) - - Appends the items of \a l to this list. Returns a reference to - this list. -*/ - -/*! - \fn Q3ValueList<T>& 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<T>::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<T>::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<T>::const_iterator &o) - \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList<T>::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<int>, Iterator is a Q3ValueListIterator<int>. 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<int>, ConstIterator is a - Q3ValueListConstIterator<int>. 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<T>() const - - Automatically converts a Q3ValueList<T> into a QList<T>. -*/ diff --git a/doc/src/classes/q3valuestack.qdoc b/doc/src/classes/q3valuestack.qdoc deleted file mode 100644 index bc44235..0000000 --- a/doc/src/classes/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://qt.nokia.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\<X\> 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<T>::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 deleted file mode 100644 index 4ab8896..0000000 --- a/doc/src/classes/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://qt.nokia.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\<T\> 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<T>& 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<T>& v ) - - This operation costs O(n) time because \a v is copied. -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector( QVector<T>::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<T>& Q3ValueVector::operator=( const Q3ValueVector<T>& 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<T>& Q3ValueVector::operator=( const std::vector<T>& 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 deleted file mode 100644 index 0b30879..0000000 --- a/doc/src/classes/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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \headerfile <QtAlgorithms> - \title Generic Algorithms - \ingroup architecture - - \brief The <QtAlgorithms> header provides generic template-based algorithms. - - Qt provides a number of global template functions in \c - <QtAlgorithms> 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 <algorithm> 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}, <QtGlobal> -*/ - -/*! \fn OutputIterator qCopy(InputIterator begin1, InputIterator end1, OutputIterator begin2) - \relates <QtAlgorithms> - - 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 <QtAlgorithms> - - 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 <QtAlgorithms> - - 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 <QtAlgorithms> - - 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 <QtAlgorithms> - - \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 <QtAlgorithms> - - 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 <QtAlgorithms> - - \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 <QtAlgorithms> - - 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 <QtAlgorithms> - -\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 <QtAlgorithms> - - 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 <QtAlgorithms> - - 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 <QtAlgorithms> - - \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<T>()} 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 <QtAlgorithms> - - \overload - - This is the same as qSort(\a{container}.begin(), \a{container}.end()); -*/ - -/*! - \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end) - \relates <QtAlgorithms> - - 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 <QtAlgorithms> - - \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<T>()} 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 <QtAlgorithms> - - \overload - - This is the same as qStableSort(\a{container}.begin(), \a{container}.end()); -*/ - -/*! \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) - \relates <QtAlgorithms> - - 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 <QtAlgorithms> - - \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 <QtAlgorithms> - - \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 <QtAlgorithms> - - 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 <QtAlgorithms> - - \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 <QtAlgorithms> - - \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 <QtAlgorithms> - - 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{<QtAlgorithms>#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 <QtAlgorithms> - - \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 <QtAlgorithms> - - \overload - - This is the same as qBinaryFind(\a{container}.begin(), \a{container}.end(), value); -*/ - - -/*! - \fn void qDeleteAll(ForwardIterator begin, ForwardIterator end) - \relates <QtAlgorithms> - - 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 <QtAlgorithms> - - \overload - - This is the same as qDeleteAll(\a{c}.begin(), \a{c}.end()). -*/ - -/*! \fn LessThan qLess() - \relates <QtAlgorithms> - - 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<T>()} -*/ - -/*! \fn LessThan qGreater() - \relates <QtAlgorithms> - - 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<T>()} -*/ diff --git a/doc/src/classes/qcache.qdoc b/doc/src/classes/qcache.qdoc deleted file mode 100644 index b79eba8..0000000 --- a/doc/src/classes/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://qt.nokia.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\<Key, T\> 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<Key> 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 deleted file mode 100644 index 5536137..0000000 --- a/doc/src/classes/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://qt.nokia.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<QColor> 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 deleted file mode 100644 index 4717e3a..0000000 --- a/doc/src/classes/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://qt.nokia.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 deleted file mode 100644 index c767be3..0000000 --- a/doc/src/classes/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://qt.nokia.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\<T\> allows you to iterate over a QList\<T\> (or a - QQueue\<T\>). If you want to modify the list as you iterate over - it, use QMutableListIterator\<T\> 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\<T\> allows you to iterate over a - QLinkedList\<T\>. If you want to modify the list as you iterate - over it, use QMutableLinkedListIterator\<T\> 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\<T\> allows you to iterate over a QVector\<T\> - (or a QStack\<T\>). If you want to modify the vector as you - iterate over it, use QMutableVectorIterator\<T\> 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\<T\> allows you to iterate over a QSet\<T\>. If you - want to modify the set as you iterate over it, use - QMutableSetIterator\<T\> 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\<T\> allows you to iterate over a QList\<T\> - (or a QQueue\<T\>) and modify the list. If you don't want to - modify the list (or have a const QList), use the slightly faster - QListIterator\<T\> 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\<T\> allows you to iterate over a - QLinkedList\<T\> and modify the list. If you don't want to modify - the list (or have a const QLinkedList), use the slightly faster - QLinkedListIterator\<T\> 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\<T\> allows you to iterate over a - QVector\<T\> and modify the vector. If you don't want to modify - the vector (or have a const QVector), use the slightly faster - QVectorIterator\<T\> 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\<T\> allows you to iterate over a QSet\<T\> - 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\<T\> 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<T> &list) - \fn QLinkedListIterator::QLinkedListIterator(const QLinkedList<T> &list) - \fn QMutableListIterator::QMutableListIterator(QList<T> &list) - \fn QMutableLinkedListIterator::QMutableLinkedListIterator(QLinkedList<T> &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<T> &vector) - \fn QMutableVectorIterator::QMutableVectorIterator(QVector<T> &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<T> &set) - \fn QMutableSetIterator::QMutableSetIterator(QSet<T> &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<T> &list) - \fn QMutableLinkedListIterator &QMutableLinkedListIterator::operator=(QLinkedList<T> &list) - \fn QListIterator &QListIterator::operator=(const QList<T> &list) - \fn QLinkedListIterator &QLinkedListIterator::operator=(const QLinkedList<T> &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<T> &vector) - \fn QMutableVectorIterator &QMutableVectorIterator::operator=(QVector<T> &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<T> &set) - \fn QMutableSetIterator &QMutableSetIterator::operator=(QSet<T> &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\<Key, T\> 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\<Key, T\> 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\<Key, T\> 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\<Key, T\> 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<Key, T> &map) - \fn QMutableMapIterator::QMutableMapIterator(QMap<Key, T> &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<Key, T> &hash) - \fn QMutableHashIterator::QMutableHashIterator(QHash<Key, T> &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<Key, T> &map) - \fn QMutableMapIterator &QMutableMapIterator::operator=(QMap<Key, T> &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<Key, T> &hash) - \fn QMutableHashIterator &QMutableHashIterator::operator=(QHash<Key, T> &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 deleted file mode 100644 index 171ddb0..0000000 --- a/doc/src/classes/qmacstyle.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://qt.nokia.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/qnamespace.qdoc b/doc/src/classes/qnamespace.qdoc deleted file mode 100644 index 3041050..0000000 --- a/doc/src/classes/qnamespace.qdoc +++ /dev/null @@ -1,2751 +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://qt.nokia.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 - <style type="text/css" id="colorstyles"> - #white { background-color: #ffffff; color: #000000 } - #black { background-color: #000000; color: #ffffff } - #red { background-color: #ff0000; color: #000000 } - #darkRed { background-color: #800000; color: #ffffff } - #green { background-color: #00ff00; color: #000000 } - #darkGreen { background-color: #008000; color: #ffffff } - #blue { background-color: #0000ff; color: #ffffff } - #darkBlue { background-color: #000080; color: #ffffff } - #cyan { background-color: #00ffff; color: #000000 } - #darkCyan { background-color: #008080; color: #ffffff } - #magenta { background-color: #ff00ff; color: #000000 } - #darkMagenta { background-color: #800080; color: #ffffff } - #yellow { background-color: #ffff00; color: #000000 } - #darkYellow { background-color: #808000; color: #ffffff } - #gray { background-color: #a0a0a4; color: #000000 } - #darkGray { background-color: #808080; color: #ffffff } - #lightGray { background-color: #c0c0c0; color: #000000 } - </style> - \endraw - - Qt's predefined QColor objects: - - \value white \raw HTML - White <tt id="white">(#ffffff)</tt> - \endraw - \value black \raw HTML - Black <tt id="black">(#000000)</tt> - \endraw - \value red \raw HTML - Red <tt id="red">(#ff0000)</tt> - \endraw - \value darkRed \raw HTML - Dark red <tt id="darkRed">(#800000)</tt> - \endraw - \value green \raw HTML - Green <tt id="green">(#00ff00)</tt> - \endraw - \value darkGreen \raw HTML - Dark green <tt id="darkGreen">(#008000)</tt> - \endraw - \value blue \raw HTML - Blue <tt id="blue">(#0000ff)</tt> - \endraw - \value darkBlue \raw HTML - Dark blue <tt id="darkBlue">(#000080)</tt> - \endraw - \value cyan \raw HTML - Cyan <tt id="cyan">(#00ffff)</tt> - \endraw - \value darkCyan \raw HTML - Dark cyan <tt id="darkCyan">(#008080)</tt> - \endraw - \value magenta \raw HTML - Magenta <tt id="magenta">(#ff00ff)</tt> - \endraw - \value darkMagenta \raw HTML - Dark magenta <tt id="darkMagenta">(#800080)</tt> - \endraw - \value yellow \raw HTML - Yellow <tt id="yellow">(#ffff00)</tt> - \endraw - \value darkYellow \raw HTML - Dark yellow <tt id="darkYellow">(#808000)</tt> - \endraw - \value gray \raw HTML - Gray <tt id="gray">(#a0a0a4)</tt> - \endraw - \value darkGray \raw HTML - Dark gray <tt id="darkGray">(#808080)</tt> - \endraw - \value lightGray \raw HTML - Light gray <tt id="lightGray">(#c0c0c0)</tt> - \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 - \omitvalue TextLongestVariant Always use the longest variant when computing the size of a multi-variant string - - 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. - - \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. - \value AutoCompatConnection - The default connection type for signals and slots when Qt 3 support - is enabled. Equivalent to AutoConnection for connections but will cause warnings - to be output under certain circumstances. See - \l{Porting to Qt 4#Compatibility Signals and Slots}{Compatibility Signals and Slots} - for further information. - - 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 <QTextDocument> 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 <QTextDocument> 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 window is a Macintosh sheet. Since - using a sheet implies window modality, the recommended - way is to use QWidget::setWindowModality(), or - QDialog::open(), instead. - - \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::InputMethodHint - - \value ImhNone No hints. - \value ImhHiddenText Characters should be hidden, as is typically used when entering passwords. - This is automatically set when setting QLineEdit::echoMode to \c Password. - \value ImhNumbersOnly Only number input is allowed. - \value ImhUppercaseOnly Only upper case letter input is allowed. - \value ImhLowercaseOnly Only lower case letter input is allowed. - \value ImhNoAutoUppercase The input method should not try to automatically switch to upper case - when a sentence ends. - \value ImhPreferNumbers Numbers are preferred (but not required). - \value ImhPreferUppercase Upper case letters are preferred (but not required). - \value ImhPreferLowercase Lower case letters are preferred (but not required). - \value ImhNoPredictiveText Do not use predictive text (i.e. dictionary lookup) while typing. - \value ImhDialableCharactersOnly Only characters suitable for phone dialling are allowed. - - \note If several flags ending with \c Only are ORed together, the resulting character set will - consist of the union of the specified sets. For instance specifying \c ImhNumbersOnly and - \c ImhUppercaseOnly would yield a set consisting of numbers and uppercase letters. - - \sa QGraphicsItem::inputMethodHints() -*/ - -/*! - \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 \c ImSurroundingText). - \value ImSurroundingText The plain text around the input area, for example the current paragraph. - \value ImCurrentSelection The currently selected text. - \value ImMaximumTextLength The maximum number of characters that the widget can hold. If there is no limit, QVariant() is returned. - \value ImAnchorPosition The position of the selection anchor. This may be less or greater than \c ImCursorPosition, depending on which side of selection the cursor is. If there is no selection, it returns the same as \c ImCursorPosition. -*/ - -/*! - \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://qt.nokia.com/careers/movingto/brisbane/}{http://qt.nok...ovingto/brisbane/}"), - whereas Qt::ElideRight is appropriate - for other strings (e.g., - "\l{http://qt.nokia.com/doc/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/classes/qpaintdevice.qdoc b/doc/src/classes/qpaintdevice.qdoc deleted file mode 100644 index 6e7c561..0000000 --- a/doc/src/classes/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://qt.nokia.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 deleted file mode 100644 index 9c8ac89..0000000 --- a/doc/src/classes/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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QPair - \brief The QPair class is a template class that stores a pair of items. - - \ingroup tools - - QPair\<T1, T2\> 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<T1, T2> &QPair::operator=(const QPair<T1, T2> &other) - - Assigns \a other to this pair. -*/ - -/*! \fn bool operator==(const QPair<T1, T2> &p1, const QPair<T1, T2> &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<T1, T2> &p1, const QPair<T1, T2> &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<T1, T2> &p1, const QPair<T1, T2> &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<T1, T2> &p1, const QPair<T1, T2> &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<T1, T2> &p1, const QPair<T1, T2> &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<T1, T2> &p1, const QPair<T1, T2> &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<T1, T2> qMakePair(const T1 &value1, const T2 &value2) - - \relates QPair - - Returns a QPair\<T1, T2\> that contains \a value1 and \a value2. - Example: - - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 2 - - This is equivalent to QPair<T1, T2>(\a value1, \a value2), but - usually requires less typing. -*/ - -/*! \fn QDataStream &operator>>(QDataStream &in, QPair<T1, T2> &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<T1, T2> &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/qplugin.qdoc b/doc/src/classes/qplugin.qdoc deleted file mode 100644 index 3b8f1b0..0000000 --- a/doc/src/classes/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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \headerfile <QtPlugin> - \title Macros for Defining Plugins - - \brief The <QtPlugin> header files defines macros for defining plugins. - - \sa {How to Create Qt Plugins} -*/ - -/*! - \macro Q_DECLARE_INTERFACE(ClassName, Identifier) - \relates <QtPlugin> - - 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 <QtPlugin> - \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 <QtPlugin> - \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 <QtPlugin> - - 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 <QtPlugin> - \internal -*/ diff --git a/doc/src/classes/qprinterinfo.qdoc b/doc/src/classes/qprinterinfo.qdoc deleted file mode 100644 index 7507e8a..0000000 --- a/doc/src/classes/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://qt.nokia.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> 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 deleted file mode 100644 index 8409e13..0000000 --- a/doc/src/classes/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://qt.nokia.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<T> 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<T> 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<QWidget *> 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<T> &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<T> &QSet::operator=(const QSet<T> &other) - - Assigns the \a other set to this set and returns a reference to - this set. -*/ - -/*! - \fn bool QSet::operator==(const QSet<T> &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<T> &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<T> &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<T> &QSet::unite(const QSet<T> &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<T> &QSet::intersect(const QSet<T> &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<T> &QSet::subtract(const QSet<T> &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<T> &QSet::operator<<(const T &value) - \fn QSet<T> &QSet::operator+=(const T &value) - \fn QSet<T> &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<T> &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<T> &QSet::operator|=(const QSet<T> &other) - \fn QSet<T> &QSet::operator+=(const QSet<T> &other) - - Same as unite(\a other). - - \sa operator|(), operator&=(), operator-=() -*/ - -/*! - \fn QSet<T> &QSet::operator&=(const QSet<T> &other) - - Same as intersect(\a other). - - \sa operator&(), operator|=(), operator-=() -*/ - -/*! - \fn QSet<T> &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<T> &QSet::operator-=(const QSet<T> &other) - - Same as subtract(\a{other}). - - \sa operator-(), operator|=(), operator&=() -*/ - -/*! - \fn QSet<T> QSet::operator|(const QSet<T> &other) const - \fn QSet<T> QSet::operator+(const QSet<T> &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<T> QSet::operator&(const QSet<T> &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<T> QSet::operator-(const QSet<T> &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<T> QSet::operator-(const QSet<T> &other) - \fn QSet<T> QSet::operator|(const QSet<T> &other) - \fn QSet<T> QSet::operator+(const QSet<T> &other) - \fn QSet<T> QSet::operator&(const QSet<T> &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<T>::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\<T\>::iterator allows you to iterate over a QSet\<T\> 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\<Key, T\>::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<T> QSet<T>::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<T> QSet<T>::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<T> QSet<T>::fromList(const QList<T> &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<T> &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<T> &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 deleted file mode 100644 index 02cb771..0000000 --- a/doc/src/classes/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://qt.nokia.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 deleted file mode 100644 index f7366c5..0000000 --- a/doc/src/classes/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://qt.nokia.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 deleted file mode 100644 index 60dd9f8..0000000 --- a/doc/src/classes/qtdesigner-api.qdoc +++ /dev/null @@ -1,1413 +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://qt.nokia.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<QByteArray> 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<QByteArray> 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<QWidget*> 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<int, int> 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<int, int> &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<QAction*> 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<QDesignerCustomWidgetInterface*> 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<QPixmap> QDesignerIconCacheInterface::pixmapList() const - - Returns a list of pixmaps for the icons provided by the icon cache. -*/ - -/*! - \fn QList<QIcon> 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 deleted file mode 100644 index e96ba0f..0000000 --- a/doc/src/classes/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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \headerfile <QtEndian> - \title Endian Conversion Functions - \ingroup architecture - \brief The <QtEndian> header provides functions to convert between - little and big endian representations of numbers. -*/ - -/*! - \fn T qFromBigEndian(const uchar *src) - \since 4.3 - \relates <QtEndian> - - 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 <QtEndian> - \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 <QtEndian> - - 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 <QtEndian> - \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 <QtEndian> - - 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 <QtEndian> - \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 <QtEndian> - - 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 <QtEndian> - \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 deleted file mode 100644 index 7c67d95..0000000 --- a/doc/src/classes/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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \class QTestEventList - \inmodule QtTest - - \brief The QTestEventList class provides a list of GUI events. - - QTestEventList inherits from QList<QTestEvent *>, 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 deleted file mode 100644 index 9cc7bef..0000000 --- a/doc/src/classes/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://qt.nokia.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<T, Prealloc> &QVarLengthArray::operator=(const QVarLengthArray<T, Prealloc> &other) - Assigns \a other to this array and returns a reference to this array. - */ - -/*! \fn QVarLengthArray::QVarLengthArray(const QVarLengthArray<T, Prealloc> &other) - Constructs a copy of \a other. - */ - diff --git a/doc/src/classes/qwaitcondition.qdoc b/doc/src/classes/qwaitcondition.qdoc deleted file mode 100644 index f19f51e..0000000 --- a/doc/src/classes/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://qt.nokia.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/codecs.qdoc b/doc/src/codecs.qdoc deleted file mode 100644 index 7359b79..0000000 --- a/doc/src/codecs.qdoc +++ /dev/null @@ -1,534 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page codec-big5.html - \title Big5 Text Codec - \ingroup codecs - - The Big5 codec provides conversion to and from the Big5 encoding. - The code was originally contributed by Ming-Che Chuang - \<mingche@cobra.ee.ntu.edu.tw\> for the Big-5+ encoding, and was - included in Qt with the author's permission, and the grateful - thanks of the Qt team. (Note: Ming-Che's code is QPL'd, as - per an mail to qt-info@nokia.com.) - - However, since Big-5+ was never formally approved, and was never - used by anyone, the Taiwan Free Software community and the Li18nux - Big5 Standard Subgroup agree that the de-facto standard Big5-ETen - (zh_TW.Big5 or zh_TW.TW-Big5) be used instead. - - The Big5 is currently implemented as a pure subset of the - Big5-HKSCS codec, so more fine-tuning is needed to make it - identical to the standard Big5 mapping as determined by - Li18nux-Big5. See \l{http://www.autrijus.org/xml/} for the draft - Big5 (2002) standard. - - James Su \<suzhe@turbolinux.com.cn\> \<suzhe@gnuchina.org\> - generated the Big5-HKSCS-to-Unicode tables with a very - space-efficient algorithm. He generously donated his code to glibc - in May 2002. Subsequently, James has kindly allowed Anthony Fok - \<anthony@thizlinux.com\> \<foka@debian.org\> to adapt the code - for Qt. - - \legalese - Copyright (C) 2000 Ming-Che Chuang \BR - Copyright (C) 2002 James Su, Turbolinux Inc. \BR - Copyright (C) 2002 Anthony Fok, ThizLinux Laboratory Ltd. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-big5hkscs.html - \title Big5-HKSCS Text Codec - \ingroup codecs - - The Big5-HKSCS codec provides conversion to and from the - Big5-HKSCS encoding. - - The codec grew out of the QBig5Codec originally contributed by - Ming-Che Chuang \<mingche@cobra.ee.ntu.edu.tw\>. James Su - \<suzhe@turbolinux.com.cn\> \<suzhe@gnuchina.org\> and Anthony Fok - \<anthony@thizlinux.com\> \<foka@debian.org\> implemented HKSCS-1999 - QBig5hkscsCodec for Qt-2.3.x, but it was too late in Qt development - schedule to be officially included in the Qt-2.3.x series. - - Wu Yi \<wuyi@hancom.com\> ported the HKSCS-1999 QBig5hkscsCodec to - Qt-3.0.1 in March 2002. - - With the advent of the new HKSCS-2001 standard, James Su - \<suzhe@turbolinux.com.cn\> \<suzhe@gnuchina.org\> generated the - Big5-HKSCS<->Unicode tables with a very space-efficient algorithm. - He generously donated his code to glibc in May 2002. Subsequently, - James has generously allowed Anthony Fok to adapt the code for - Qt-3.0.5. - - Currently, the Big5-HKSCS tables are generated from the following - sources, and with the Euro character added: - \list 1 - \o \l{http://www.microsoft.com/typography/unicode/950.txt} - \o \l{http://www.info.gov.hk/digital21/chi/hkscs/download/big5-iso.txt} - \o \l{http://www.info.gov.hk/digital21/chi/hkscs/download/big5cmp.txt} - \endlist - - There may be more fine-tuning to the QBig5hkscsCodec to maximize its - compatibility with the standard Big5 (2002) mapping as determined by - Li18nux Big5 Standard Subgroup. See \l{http://www.autrijus.org/xml/} - for the various Big5 CharMapML tables. - - \legalese - Copyright (C) 2000 Ming-Che Chuang \BR - Copyright (C) 2001, 2002 James Su, Turbolinux Inc. \BR - Copyright (C) 2002 WU Yi, HancomLinux Inc. \BR - Copyright (C) 2001, 2002 Anthony Fok, ThizLinux Laboratory Ltd. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-eucjp.html - \title EUC-JP Text Codec - \ingroup codecs - - The EUC-JP codec provides conversion to and from EUC-JP, the main - legacy encoding for Unix machines in Japan. - - The environment variable \c UNICODEMAP_JP can be used to - fine-tune the JIS, Shift-JIS, and EUC-JP codecs. The \l{ISO - 2022-JP (JIS) Text Codec} documentation describes how to use this - variable. - - Most of the code here was written by Serika Kurusugawa, - a.k.a. Junji Takagi, and is included in Qt with the author's - permission and the grateful thanks of the Qt team. Here is - the copyright statement for that code: - - \legalese - - Copyright (C) 1999 Serika Kurusugawa. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS". - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-euckr.html - \title EUC-KR Text Codec - \ingroup codecs - - The EUC-KR codec provides conversion to and from EUC-KR, KR, the - main legacy encoding for Unix machines in Korea. - - It was largely written by Mizi Research Inc. Here is the - copyright statement for the code as it was at the point of - contribution. The subsequent modifications are covered by - the usual copyright for Qt. - - \legalese - - Copyright (C) 1999-2000 Mizi Research Inc. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-gbk.html - \title GBK Text Codec - \ingroup codecs - - The GBK codec provides conversion to and from the Chinese - GB18030/GBK/GB2312 encoding. - - GBK, formally the Chinese Internal Code Specification, is a commonly - used extension of GB 2312-80. Microsoft Windows uses it under the - name codepage 936. - - GBK has been superseded by the new Chinese national standard - GB 18030-2000, which added a 4-byte encoding while remaining - compatible with GB2312 and GBK. The new GB 18030-2000 may be described - as a special encoding of Unicode 3.x and ISO-10646-1. - - Special thanks to charset gurus Markus Scherer (IBM), - Dirk Meyer (Adobe Systems) and Ken Lunde (Adobe Systems) for publishing - an excellent GB 18030-2000 summary and specification on the Internet. - Some must-read documents are: - - \list - \o \l{ftp://ftp.oreilly.com/pub/examples/nutshell/cjkv/pdf/GB18030_Summary.pdf} - \o \l{http://oss.software.ibm.com/cvs/icu/~checkout~/charset/source/gb18030/gb18030.html} - \o \l{http://oss.software.ibm.com/cvs/icu/~checkout~/charset/data/xml/gb-18030-2000.xml} - \endlist - - The GBK codec was contributed to Qt by - Justin Yu \<justiny@turbolinux.com.cn\> and - Sean Chen \<seanc@turbolinux.com.cn\>. They may also be reached at - Yu Mingjian \<yumj@sun.ihep.ac.cn\>, \<yumingjian@china.com\> - Chen Xiangyang \<chenxy@sun.ihep.ac.cn\> - - The GB18030 codec Qt functions were contributed to Qt by - James Su \<suzhe@gnuchina.org\>, \<suzhe@turbolinux.com.cn\> - who pioneered much of GB18030 development on GNU/Linux systems. - - The GB18030 codec was contributed to Qt by - Anthony Fok \<anthony@thizlinux.com\>, \<foka@debian.org\> - using a Perl script to generate C++ tables from gb-18030-2000.xml - while merging contributions from James Su, Justin Yu and Sean Chen. - A copy of the source Perl script is available at - \l{http://people.debian.org/~foka/gb18030/gen-qgb18030codec.pl} - - The copyright notice for their code follows: - - \legalese - Copyright (C) 2000 TurboLinux, Inc. Written by Justin Yu and Sean Chen. \BR - Copyright (C) 2001, 2002 Turbolinux, Inc. Written by James Su. \BR - Copyright (C) 2001, 2002 ThizLinux Laboratory Ltd. Written by Anthony Fok. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codecs-jis.html - \title ISO 2022-JP (JIS) Text Codec - \ingroup codecs - - The JIS codec provides conversion to and from ISO 2022-JP. - - The environment variable \c UNICODEMAP_JP can be used to - fine-tune the JIS, Shift-JIS, and EUC-JP codecs. The mapping - names are as for the Japanese XML working group's \link - http://www.y-adagio.com/public/standards/tr_xml_jpf/toc.htm XML - Japanese Profile\endlink, because it names and explains all the - widely used mappings. Here are brief descriptions, written by - Serika Kurusugawa: - - \list - - \o "unicode-0.9" or "unicode-0201" for Unicode style. This assumes - JISX0201 for 0x00-0x7f. (0.9 is a table version of jisx02xx mapping - used for Unicode 1.1.) - - \o "unicode-ascii" This assumes US-ASCII for 0x00-0x7f; some - chars (JISX0208 0x2140 and JISX0212 0x2237) are different from - Unicode 1.1 to avoid conflict. - - \o "open-19970715-0201" ("open-0201" for convenience) or - "jisx0221-1995" for JISX0221-JISX0201 style. JIS X 0221 is JIS - version of Unicode, but a few chars (0x5c, 0x7e, 0x2140, 0x216f, - 0x2131) are different from Unicode 1.1. This is used when 0x5c is - treated as YEN SIGN. - - \o "open-19970715-ascii" ("open-ascii" for convenience) for - JISX0221-ASCII style. This is used when 0x5c is treated as REVERSE - SOLIDUS. - - \o "open-19970715-ms" ("open-ms" for convenience) or "cp932" for - Microsoft Windows style. Windows Code Page 932. Some chars (0x2140, - 0x2141, 0x2142, 0x215d, 0x2171, 0x2172) are different from Unicode - 1.1. - - \o "jdk1.1.7" for Sun's JDK style. Same as Unicode 1.1, except that - JIS 0x2140 is mapped to UFF3C. Either ASCII or JISX0201 can be used - for 0x00-0x7f. - - \endlist - - In addition, the extensions "nec-vdc", "ibm-vdc" and "udc" are - supported. - - For example, if you want to use Unicode style conversion but with - NEC's extension, set \c UNICODEMAP_JP to \c {unicode-0.9, - nec-vdc}. (You will probably need to quote that in a shell - command.) - - Most of the code here was written by Serika Kurusugawa, - a.k.a. Junji Takagi, and is included in Qt with the author's - permission and the grateful thanks of the Qt team. Here is - the copyright statement for that code: - - \legalese - - Copyright (C) 1999 Serika Kurusugawa. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS". - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-sjis.html - \title Shift-JIS Text Codec - \ingroup codecs - - The Shift-JIS codec provides conversion to and from Shift-JIS, an - encoding of JIS X 0201 Latin, JIS X 0201 Kana and JIS X 0208. - - The environment variable \c UNICODEMAP_JP can be used to - fine-tune the codec. The \l{ISO 2022-JP (JIS) Text Codec} - documentation describes how to use this variable. - - Most of the code here was written by Serika Kurusugawa, a.k.a. - Junji Takagi, and is included in Qt with the author's permission - and the grateful thanks of the Qt team. Here is the - copyright statement for the code as it was at the point of - contribution. The subsequent modifications are covered by - the usual copyright for Qt. - - \legalese - - Copyright (C) 1999 Serika Kurusugawa. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS". - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-tscii.html - \title TSCII Text Codec - \ingroup codecs - - The TSCII codec provides conversion to and from the Tamil TSCII - encoding. - - TSCII, formally the Tamil Standard Code Information Interchange - specification, is a commonly used charset for Tamils. The - official page for the standard is at - \link http://www.tamil.net/tscii/ http://www.tamil.net/tscii/\endlink - - This codec uses the mapping table found at - \link http://www.geocities.com/Athens/5180/tsciiset.html - http://www.geocities.com/Athens/5180/tsciiset.html\endlink. - Tamil uses composed Unicode which might cause some - problems if you are using Unicode fonts instead of TSCII fonts. - - Most of the code was written by Hans Petter Bieker and is - included in Qt with the author's permission and the grateful - thanks of the Qt team. Here is the copyright statement for - the code as it was at the point of contribution. The - subsequent modifications are covered by the usual copyright for - Qt: - - \legalese - - Copyright (c) 2000 Hans Petter Bieker. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ diff --git a/doc/src/qtdemo.qdoc b/doc/src/demos/qtdemo.qdoc index 60f896a..60f896a 100644 --- a/doc/src/qtdemo.qdoc +++ b/doc/src/demos/qtdemo.qdoc diff --git a/doc/src/deployment/deployment-plugins.qdoc b/doc/src/deployment/deployment-plugins.qdoc new file mode 100644 index 0000000..b02bdd8 --- /dev/null +++ b/doc/src/deployment/deployment-plugins.qdoc @@ -0,0 +1,236 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page deployment-plugins.html + \title Deploying Plugins + \brief A guide to plugins-specific aspects of deploying Qt and Qt Application + + This document explains how to deploy plugin libraries that Qt or + your application should load at runtime. If you use + \l{How to Create Qt Plugins#Static Plugins}{static plugins}, then the + plugin code is already part of your application executable, and no + separate deployment steps are required. + + \tableofcontents + + \section1 The Plugin Directory + + When the application is run, Qt will first treat the application's + executable directory as the \c{pluginsbase}. For example if the + application is in \c{C:\Program Files\MyApp} and has a style plugin, + Qt will look in \c{C:\Program Files\MyApp\styles}. (See + QCoreApplication::applicationDirPath() for how to find out where + the application's executable is.) Qt will also look in the + directory specified by + QLibraryInfo::location(QLibraryInfo::PluginsPath), which typically + is located in \c QTDIR/plugins (where \c QTDIR is the directory + where Qt is installed). If you want Qt to look in additional + places you can add as many paths as you need with calls to + QCoreApplication::addLibraryPath(). And if you want to set your + own path or paths you can use QCoreApplication::setLibraryPaths(). + You can also use a \c qt.conf file to override the hard-coded + paths that are compiled into the Qt library. For more information, + see the \l {Using qt.conf} documentation. Yet another possibility + is to set the \c QT_PLUGIN_PATH environment variable before running + the application. If set, Qt will look for plugins in the + paths (separated by the system path separator) specified in the variable. + + \section1 Loading and Verifying Plugins Dynamically + + When loading plugins, the Qt library does some sanity checking to + determine whether or not the plugin can be loaded and used. This + provides the ability to have multiple versions and configurations of + the Qt library installed side by side. + + \list + \o Plugins linked with a Qt library that has a higher version number + will not be loaded by a library with a lower version number. + + \br + \bold{Example:} Qt 4.3.0 will \e{not} load a plugin built with Qt 4.3.1. + + \o Plugins linked with a Qt library that has a lower major version + number will not be loaded by a library with a higher major version + number. + + \br + \bold{Example:} Qt 4.3.1 will \e{not} load a plugin built with Qt 3.3.1. + \br + \bold{Example:} Qt 4.3.1 will load plugins built with Qt 4.3.0 and Qt 4.2.3. + + \o The Qt library and all plugins are built using a \e {build + key}. The build key in the Qt library is examined against the build + key in the plugin, and if they match, the plugin is loaded. If the + build keys do not match, then the Qt library refuses to load the + plugin. + + \br \bold{Rationale:} See the \l{#The Build Key}{The Build Key} section below. + \endlist + + When building plugins to extend an application, it is important to ensure + that the plugin is configured in the same way as the application. This means + that if the application was built in release mode, plugins should be built + in release mode, too. + + If you configure Qt to be built in both debug and release modes, + but only build applications in release mode, you need to ensure that your + plugins are also built in release mode. By default, if a debug build of Qt is + available, plugins will \e only be built in debug mode. To force the + plugins to be built in release mode, add the following line to the plugin's + project file: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 3 + + This will ensure that the plugin is compatible with the version of the library + used in the application. + + \section2 The Build Key + + When loading plugins, Qt checks the build key of each plugin against its + own configuration to ensure that only compatible plugins are loaded; any + plugins that are configured differently are not loaded. + + The build key contains the following information: + \list + \o Architecture, operating system and compiler. + + \e {Rationale:} + In cases where different versions of the same compiler do not + produce binary compatible code, the version of the compiler is + also present in the build key. + + \o Configuration of the Qt library. The configuration is a list + of the missing features that affect the available API in the + library. + + \e {Rationale:} + Two different configurations of the same version of + the Qt library are not binary compatible. The Qt library that + loads the plugin uses the list of (missing) features to + determine if the plugin is binary compatible. + + \e {Note:} There are cases where a plugin can use features that are + available in two different configurations. However, the + developer writing plugins would need to know which features are + in use, both in their plugin and internally by the utility + classes in Qt. The Qt library would require complex feature + and dependency queries and verification when loading plugins. + Requiring this would place an unnecessary burden on the developer, and + increase the overhead of loading a plugin. To reduce both + development time and application runtime costs, a simple string + comparision of the build keys is used. + + \o Optionally, an extra string may be specified on the configure + script command line. + + \e {Rationale:} + When distributing binaries of the Qt library with an + application, this provides a way for developers to write + plugins that can only be loaded by the library with which the + plugins were linked. + \endlist + + For debugging purposes, it is possible to override the run-time build key + checks by configuring Qt with the \c QT_NO_PLUGIN_CHECK preprocessor macro + defined. + + \section1 The Plugin Cache + + In order to speed up loading and validation of plugins, some of + the information that is collected when plugins are loaded is cached + through QSettings. This includes information about whether or not + a plugin was successfully loaded, so that subsequent load operations + don't try to load an invalid plugin. However, if the "last modified" + timestamp of a plugin has changed, the plugin's cache entry is + invalidated and the plugin is reloaded regardless of the values in + the cache entry, and the cache entry itself is updated with the new + result. + + This also means that the timestamp must be updated each time the + plugin or any dependent resources (such as a shared library) is + updated, since the dependent resources might influence the result + of loading a plugin. + + Sometimes, when developing plugins, it is necessary to remove entries + from the plugin cache. Since Qt uses QSettings to manage the plugin + cache, the locations of plugins are platform-dependent; see + \l{QSettings#Platform-Specific Notes}{the QSettings documentation} + for more information about each platform. + + For example, on Windows the entries are stored in the registry, and the + paths for each plugin will typically begin with either of these two strings: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 6 + + \section1 Debugging Plugins + + There are a number of issues that may prevent correctly-written plugins from + working with the applications that are designed to use them. Many of these + are related to differences in the way that plugins and applications have been + built, often arising from separate build systems and processes. + + The following table contains descriptions of the common causes of problems + developers experience when creating plugins: + + \table + \header \o Problem \o Cause \o Solution + \row \o Plugins sliently fail to load even when opened directly by the + application. \QD shows the plugin libraries in its + \gui{Help|About Plugins} dialog, but no plugins are listed under each + of them. + \o The application and its plugins are built in different modes. + \o Either share the same build information or build the plugins in both + debug and release modes by appending the \c debug_and_release to + the \l{qmake Variable Reference#CONFIG}{CONFIG} variable in each of + their project files. + \row \o A valid plugin that replaces an invalid (or broken) plugin fails to load. + \o The entry for the plugin in the plugin cache indicates that the original + plugin could not be loaded, causing Qt to ignore the replacement. + \o Either ensure that the plugin's timestamp is updated, or delete the + entry in the \l{#The Plugin Cache}{plugin cache}. + \endtable + + You can also use the \c QT_DEBUG_PLUGINS environment variable to obtain + diagnostic information from Qt about each plugin it tries to load. Set this + variable to a non-zero value in the environment from which your application is + launched. +*/ diff --git a/doc/src/deployment.qdoc b/doc/src/deployment/deployment.qdoc index 9f8ee8f..75b870f 100644 --- a/doc/src/deployment.qdoc +++ b/doc/src/deployment/deployment.qdoc @@ -39,20 +39,9 @@ ** ****************************************************************************/ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - /*! - \group deployment + \page deployment.html \title Deploying Qt Applications - \ingroup buildsystem Deploying an Qt application does not require any C++ programming. All you need to do is to build Qt and your @@ -200,7 +189,7 @@ \o \l{Deploying Qt for Embedded Linux Applications}{Qt for Embedded Linux} \endlist - \sa Installation {Window System Specific Notes} + \sa Installation {Platform-Specific Documentation} */ /*! @@ -208,7 +197,6 @@ \contentspage Deploying Qt Applications \title Deploying an Application on X11 Platforms - \ingroup deployment Due to the proliferation of Unix systems (commercial Unices, Linux distributions, etc.), deployment on Unix is a complex @@ -529,7 +517,6 @@ \contentspage Deploying Qt Applications \title Deploying an Application on Windows - \ingroup deployment This documentation will describe how to determine which files you should include in your distribution, and how to make sure that the @@ -933,7 +920,6 @@ \contentspage Deploying Qt Applications \title Deploying an Application on Mac OS X - \ingroup deployment Starting with version 4.5, Qt now includes a \l {macdeploy}{deployment tool} that automates the prodecures described in this document. diff --git a/doc/src/qt-conf.qdoc b/doc/src/deployment/qt-conf.qdoc index ce32aa8..229fa45 100644 --- a/doc/src/qt-conf.qdoc +++ b/doc/src/deployment/qt-conf.qdoc @@ -43,7 +43,6 @@ \page qt-conf.html \title Using qt.conf - \ingroup deployment The \c qt.conf file overrides the hard-coded paths that are compiled into the Qt library. These paths are accessible using the diff --git a/doc/src/qtconfig.qdoc b/doc/src/deployment/qtconfig.qdoc index 2e02fe6..2e02fe6 100644 --- a/doc/src/qtconfig.qdoc +++ b/doc/src/deployment/qtconfig.qdoc diff --git a/doc/src/desktop-integration.qdoc b/doc/src/desktop-integration.qdoc deleted file mode 100644 index 1c10ed9..0000000 --- a/doc/src/desktop-integration.qdoc +++ /dev/null @@ -1,90 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page desktop-integration.html - \title Desktop Integration - \ingroup gui-programming - - Various classes in Qt are designed to help developers integrate applications into - users' desktop environments. These classes enable developers to take advantage - of native services while still using a cross-platform API. - - \tableofcontents - - \section1 Opening External Resources - - Although Qt provides facilities to handle and display resources, such as - \l{QImageIOHandler}{common image formats} and \l{QTextDocument}{HTML}, - it is sometimes necessary to open files and external resources using external - applications. - - QDesktopServices provides an interface to services offered by the user's desktop - environment. In particular, the \l{QDesktopServices::}{openUrl()} function is - used to open resources using the appropriate application, which may have been - specifically configured by the user. - - \section1 System Tray Icons - - Many modern desktop environments feature docks or panels with \e{system trays} - in which applications can install icons. Applications often use system tray icons - to display status information, either by updating the icon itself or by showing - information in "balloon messages". Additionally, many applications provide - pop-up menus that can be accessed via their system tray icons. - - The QSystemTrayIcon class exposes all of the above features via an intuitive - Qt-style API that can be used on all desktop platforms. - - \section1 Desktop Widgets - - On systems where the user's desktop is displayed using more than one screen, - certain types of applications may need to obtain information about the - configuration of the user's workspace to ensure that new windows and dialogs - are opened in appropriate locations. - - The QDesktopWidget class can be used to monitor the positions of widgets and - notify applications about changes to the way the desktop is split over the - available screens. This enables applications to implement policies for - positioning new windows so that, for example, they do not distract a user - who is working on a specific task. - - -*/ diff --git a/doc/src/activeqt-dumpcpp.qdoc b/doc/src/development/activeqt-dumpcpp.qdoc index 63e35ee..8c743a1 100644 --- a/doc/src/activeqt-dumpcpp.qdoc +++ b/doc/src/development/activeqt-dumpcpp.qdoc @@ -93,15 +93,15 @@ for each \c coclass and \c interface declared in the type library. coclasses marked with the \c control attribute will be wrapped by a QAxWidget subclass. - Those classes that wrap creatable
coclasses
(i.e. coclasses that are not marked + Those classes that wrap creatable coclasses (i.e. coclasses that are not marked as \c noncreatable) have a default constructor; this is typically a single class of type \c Application. \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 0 All other classes can only be created by passing an IDispatch interface pointer - to the constructor; those classes should however not
be created explicitly. - Instead, use the appropriate API of already created
objects. + to the constructor; those classes should however not be created explicitly. + Instead, use the appropriate API of already created objects. \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 1 @@ -123,16 +123,16 @@ By default, methods and property returning subobjects will use the type as in the type library. The caller of the function is responsible for deleting or - reparenting the object
returned. If the \c -compat switch is set, properties + reparenting the object returned. If the \c -compat switch is set, properties and method returning a COM object have the return type \c IDispatch*, and - the namespace will not declare wrapper classes for
interfaces. + the namespace will not declare wrapper classes for interfaces. In this case, create the correct wrapper class explicitly: \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 4 You can of course use the IDispatch* returned directly, in which case you have to - call
\c Release() when finished with the interface. + call \c Release() when finished with the interface. All classes in the namespace are tagged with a macro that allows you to export or import them from a DLL. To do that, declare the macro to expand to diff --git a/doc/src/activeqt-dumpdoc.qdoc b/doc/src/development/activeqt-dumpdoc.qdoc index 55ab2d7..55ab2d7 100644 --- a/doc/src/activeqt-dumpdoc.qdoc +++ b/doc/src/development/activeqt-dumpdoc.qdoc diff --git a/doc/src/activeqt-idc.qdoc b/doc/src/development/activeqt-idc.qdoc index 974eddc..974eddc 100644 --- a/doc/src/activeqt-idc.qdoc +++ b/doc/src/development/activeqt-idc.qdoc diff --git a/doc/src/activeqt-testcon.qdoc b/doc/src/development/activeqt-testcon.qdoc index 9fcfed6..9fcfed6 100644 --- a/doc/src/activeqt-testcon.qdoc +++ b/doc/src/development/activeqt-testcon.qdoc diff --git a/doc/src/assistant-manual.qdoc b/doc/src/development/assistant-manual.qdoc index 1b82b1a..b26efcc 100644 --- a/doc/src/assistant-manual.qdoc +++ b/doc/src/development/assistant-manual.qdoc @@ -642,8 +642,8 @@ \endtable In addition to those \QA specific tags, the tags for generating and registering - documentation can be used. See \l{QtHelp Module#Creating a Qt Help Collection}{Qt Help Collection} - documentation for more information. + documentation can be used. See \l{The Qt Help Framework#Creating a Qt Help Collection} + {Qt Help Collection} documentation for more information. An example of a help collection file that uses all the available tags is shown below: diff --git a/doc/src/debug.qdoc b/doc/src/development/debug.qdoc index bedf73d..f0fe128 100644 --- a/doc/src/debug.qdoc +++ b/doc/src/development/debug.qdoc @@ -39,22 +39,9 @@ ** ****************************************************************************/ -/**************************************************************************** -** -** Qt Debugging Techniques -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - /*! \page debug.html \title Debugging Techniques - \ingroup buildsystem Here we present some useful hints to help you with debugging your Qt-based software. diff --git a/doc/src/designer-manual.qdoc b/doc/src/development/designer-manual.qdoc index 5d8587a..5d8587a 100644 --- a/doc/src/designer-manual.qdoc +++ b/doc/src/development/designer-manual.qdoc diff --git a/doc/src/developing-on-mac.qdoc b/doc/src/development/developing-on-mac.qdoc index 2546ef1..dee6d4d 100644 --- a/doc/src/developing-on-mac.qdoc +++ b/doc/src/development/developing-on-mac.qdoc @@ -44,7 +44,7 @@ \title Developing Qt Applications on Mac OS X \brief A overview of items to be aware of when developing Qt applications on Mac OS X - \ingroup platform-notes + \ingroup platform-specific \tableofcontents diff --git a/doc/src/classes/q3popupmenu.qdoc b/doc/src/development/developing-with-qt.qdoc index c20dadc..9fa2242 100644 --- a/doc/src/classes/q3popupmenu.qdoc +++ b/doc/src/development/developing-with-qt.qdoc @@ -40,37 +40,35 @@ ****************************************************************************/ /*! - \class Q3PopupMenu - \brief The Q3PopupMenu class is a thin compatibility wrapper around QMenu. - \compat + \page developing-with-qt.html + \title Cross Platform Development with Qt - 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. + Qt is provided with a set of build tools to help developers automate + the process of building and installing Qt applications. - \sa QMenu::exec() + \table 100% + \header \o Development \o Cross-Platform Issues \o Specific Tools + \row + \o + \list + \o \l {Debugging Techniques} + \o \l {Qt's Tools} + \o \l {The Qt Resource System} + \o \l {Using Precompiled Headers} + \endlist + \o + \list + \o \l {Cross Compiling Qt for Embedded Linux Applications} + \o \l {Deploying Qt Applications} + \o \l {Installation}{Installing Qt} + \o \l {Window System Specific Notes} + \endlist + \o + \list + \o \l lupdate and \l lrelease + \o \l {moc}{Meta-Object Compiler (moc)} + \o \l {User Interface Compiler (uic)} + \o \l {Resource Compiler (rcc)} + \endlist + \endtable */ diff --git a/doc/src/moc.qdoc b/doc/src/development/moc.qdoc index ee57f7e..747c68d 100644 --- a/doc/src/moc.qdoc +++ b/doc/src/development/moc.qdoc @@ -42,7 +42,6 @@ /*! \page moc.html \title Using the Meta-Object Compiler (moc) - \ingroup buildsystem \ingroup qttools \keyword moc diff --git a/doc/src/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc index 6082d29..5fdc4e8 100644 --- a/doc/src/qmake-manual.qdoc +++ b/doc/src/development/qmake-manual.qdoc @@ -45,7 +45,6 @@ \startpage {index.html}{Qt Reference Documentation} \nextpage qmake Tutorial - \ingroup buildsystem \ingroup qttools \keyword qmake @@ -4245,7 +4244,6 @@ \contentspage {qmake Manual}{Contents} \previouspage qmake Advanced Usage \nextpage qmake Reference - \ingroup buildsystem \target Introduction @@ -4664,8 +4662,7 @@ \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 0 - See the \l{Qt Examples#Qt Designer}{Qt Designer examples} for more - examples of plugin-based projects. + See the \l{Qt Designer Examples} for more examples of plugin-based projects. \section1 Building and Installing in Debug and Release Modes diff --git a/doc/src/qmsdev.qdoc b/doc/src/development/qmsdev.qdoc index b6126a5..ceed4c1 100644 --- a/doc/src/qmsdev.qdoc +++ b/doc/src/development/qmsdev.qdoc @@ -1,12 +1,41 @@ /**************************************************************************** ** -** Documentation of Visual Studio Integration Plugin. -** ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). ** Contact: Nokia Corporation (qt-info@nokia.com) ** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ ** ****************************************************************************/ diff --git a/doc/src/qtestlib.qdoc b/doc/src/development/qtestlib.qdoc index 57683e6..13a5b7c 100644 --- a/doc/src/qtestlib.qdoc +++ b/doc/src/development/qtestlib.qdoc @@ -42,9 +42,9 @@ /*! \page qtestlib-manual.html \title QTestLib Manual - \ingroup architecture \brief An overview of Qt's unit testing framework. + \ingroup frameworks-technologies \keyword qtestlib The QTestLib framework, provided by Nokia, is a tool for unit @@ -383,7 +383,6 @@ \nextpage {Chapter 1: Writing a Unit Test}{Chapter 1} \title QTestLib Tutorial - \ingroup howto This tutorial gives a short introduction to how to use some of the features of the QTestLib framework. It is divided into four diff --git a/doc/src/rcc.qdoc b/doc/src/development/rcc.qdoc index 5eb5547..1da641c 100644 --- a/doc/src/rcc.qdoc +++ b/doc/src/development/rcc.qdoc @@ -42,7 +42,6 @@ /*! \page rcc.html \title Resource Compiler (rcc) - \ingroup buildsystem \ingroup qttools \keyword rcc diff --git a/doc/src/tools-list.qdoc b/doc/src/development/tools-list.qdoc index 509a1e7..01f71d3 100644 --- a/doc/src/tools-list.qdoc +++ b/doc/src/development/tools-list.qdoc @@ -42,7 +42,6 @@ /*! \group qttools \title Qt's Tools - \ingroup buildsystem Qt is supplied with several command line and graphical tools to ease and speed the development process. Each tool is listed here diff --git a/doc/src/uic.qdoc b/doc/src/development/uic.qdoc index f774fa8..b05643c 100644 --- a/doc/src/uic.qdoc +++ b/doc/src/development/uic.qdoc @@ -42,7 +42,6 @@ /*! \page uic.html \title User Interface Compiler (uic) - \ingroup buildsystem \ingroup qttools \keyword uic diff --git a/doc/src/distributingqt.qdoc b/doc/src/distributingqt.qdoc deleted file mode 100644 index 0739976..0000000 --- a/doc/src/distributingqt.qdoc +++ /dev/null @@ -1,154 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/**************************************************************************** -** -** Documentation on deploying Qt. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - -/* -\page distributingqt.html - -\title Deploying Qt Applications - -This document lists the platform-specific files needed to distribute -Qt applications. We do not include any compiler-specific files that -may also be required. (See also, \link winsystem.html Window -System-specific Notes\endlink.) - -\tableofcontents - -Also see the "deployment" articles in -\e{\link http://qt.nokia.com/doc/qq/ Qt Quarterly\endlink}: -\list -\i \link http://qt.nokia.com/doc/qq/qq09-mac-deployment.html -Deploying Applications on Mac OS X\endlink -\i \link http://qt.nokia.com/doc/qq/qq10-windows-deployment.html -Deploying Applications on Windows\endlink -\i \link http://qt.nokia.com/doc/qq/qq11-unix-deployment.html -Deploying Applications on X11\endlink -\endlist - -\section1 Static Qt Applications - -To distribute static Qt applications, you need the following file for -all platforms: - -\list -\i your application's executable -\endlist - -\section1 Dynamic Qt Applications - -To distribute dynamic Qt applications, you will need the following -files for all platforms: - -\list -\i application executable -\i the Qt library -\endlist - -The Qt library must either be in the same directory as the application -executable or in a directory which is included in the system library -path. - -The library is provided by the following platform specific files: - -\table -\header \i Platform \i File -\row \i Windows \i \c qt[version].dll -\row \i Unix/Linux \i \c libqt[version].so -\row \i Mac \i \c libqt[version].dylib -\endtable - -\e version includes the three version numbers. - -\section2 Distributing Plugins - -You must include any plugin files required by the application. - -Plugins must be put into a subdirectory under a directory known to -Qt as a plugin directory. The subdirectory must have the name of the -plugin category (e.g. \c styles, \c sqldrivers, \c designer, etc.). - -Qt searches in the following directories for plugin categories: - -\list -\i Application specific plugin paths -\i Build-directory of Qt -\i The application directory -\endlist - -Application specific plugin paths can be added using -QCoreApplication::addLibraryPath(). The build-directory of Qt is hardcoded -in the Qt library and can be changed as a part of the installation -process. - -\section1 Dynamic Dialogs - -For dynamic dialogs if you use QWidgetFactory, you need the following -files for all platforms: - -\list -\i The same files as used for dynamic Qt applications -\i The QUI Library -\endlist - -The QUI library is provided by the following platform specific files: -\table -\header \i Platform \i File -\row \i Windows \i\c qui.lib -\row \i Unix/Linux \i\c libqui.so -\row \i Mac \i \c libqui.dylib -\endtable - -The QUI library must either be in the same directory as the -application executable or in a directory which is included in the -system library path. - -*/ diff --git a/doc/src/examples-overview.qdoc b/doc/src/examples-overview.qdoc deleted file mode 100644 index 50c19fa..0000000 --- a/doc/src/examples-overview.qdoc +++ /dev/null @@ -1,367 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page examples-overview.html - \title An Overview of Qt's Examples - \brief A short guide to the different categories of examples included with Qt. - \ingroup howto - - Qt is supplied with a variety of examples that cover almost every aspect - of development. These examples are ordered by functional area, but many - examples often use features from many parts of Qt to highlight one area - in particular. - - This document provides a brief overview of each example category and - provides links to the more formal \l{Qt Examples}{list of examples}. - - \section1 \l{Qt Examples#Widgets}{Widgets} - - \l{Qt Examples#Widgets}{\inlineimage widget-examples.png - } - - Qt comes with a large range of standard widgets that users of modern - applications have come to expect. - - You can also develop your own custom widgets and controls, and use them - alongside standard widgets. - - It is even possible to provide custom styles and themes for widgets that can - be used to change the appearance of standard widgets and appropriately - written custom widgets. - - \section1 \l{Qt Examples#Dialogs}{Dialogs} - - \l{Qt Examples#Dialogs}{\inlineimage dialog-examples.png - } - - Qt includes standard dialogs for many common operations, such as file - selection, printing, and color selection. - - Custom dialogs can also be created for specialized modal or modeless - interactions with users. - - \section1 \l{Qt Examples#Main Windows}{Main Windows} - - \l{Qt Examples#Main Windows}{\inlineimage mainwindow-examples.png - } - - All the standard features of application main windows are provided by Qt. - - Main windows can have pull down menus, tool bars, and dock windows. These - separate forms of user input are unified in an integrated action system that - also supports keyboard shortcuts and accelerator keys in menu items. - - \section1 \l{Qt Examples#Layouts}{Layouts} - - \l{Qt Examples#Layouts}{\inlineimage layout-examples.png - } - - Qt uses a layout-based approach to widget management. Widgets are arranged in - the optimal positions in windows based on simple layout rules, leading to a - consistent look and feel. - - Custom layouts can be used to provide more control over the positions and - sizes of child widgets. - - \section1 \l{Qt Examples#Painting}{Painting} - - \l{Qt Examples#Painting}{\inlineimage painting-examples.png - } - - Qt's painting system is able to render vector graphics, images, and outline - font-based text with sub-pixel accuracy accuracy using anti-aliasing to - improve rendering quality. - - These examples show the most common techniques that are used when painting - with Qt, from basic concepts such as drawing simple primitives to the use of - transformations. - - \section1 \l{Qt Examples#Item Views}{Item Views} - - \l{Qt Examples#Item Views}{\inlineimage itemview-examples.png - } - - Item views are widgets that typically display data sets. Qt 4's model/view - framework lets you handle large data sets by separating the underlying data - from the way it is represented to the user, and provides support for - customized rendering through the use of delegates. - - \section1 \l{Qt Examples#Graphics View}{Graphics View} - - \l{Qt Examples#Graphics View}{\inlineimage graphicsview-examples.png - } - - Qt is provided with a comprehensive canvas through the GraphicsView - classes. - - These examples demonstrate the fundamental aspects of canvas programming - with Qt. - - \section1 \l{Qt Examples#Rich Text}{Rich Text} - - \l{Qt Examples#Rich Text}{\inlineimage richtext-examples.png - } - - Qt provides powerful document-oriented rich text engine that supports Unicode - and right-to-left scripts. Documents can be manipulated using a cursor-based - API, and their contents can be imported and exported as both HTML and in a - custom XML format. - - \section1 \l{Qt Examples#Tools}{Tools} - - \l{Qt Examples#Tools}{\inlineimage tool-examples.png - } - - Qt is equipped with a range of capable tool classes, from containers and - iterators to classes for string handling and manipulation. - - Other classes provide application infrastructure support, handling plugin - loading and managing configuration files. - - \section1 \l{Qt Examples#Desktop}{Desktop} - - \l{Qt Examples#Desktop}{\inlineimage desktop-examples.png - } - - Qt provides features to enable applications to integrate with the user's - preferred desktop environment. - - Features such as system tray icons, access to the desktop widget, and - support for desktop services can be used to improve the appearance of - applications and take advantage of underlying desktop facilities. - - \section1 \l{Qt Examples#Drag and Drop}{Drag and Drop} - - \l{Qt Examples#Drag and Drop}{\inlineimage draganddrop-examples.png - } - - Qt supports native drag and drop on all platforms via an extensible - MIME-based system that enables applications to send data to each other in the - most appropriate formats. - - Drag and drop can also be implemented for internal use by applications. - - \section1 \l{Qt Examples#Threads}{Threads} - - \l{Qt Examples#Threads}{\inlineimage thread-examples.png - } - - Qt 4 makes it easier than ever to write multithreaded applications. More - classes have been made usable from non-GUI threads, and the signals and slots - mechanism can now be used to communicate between threads. - - Additionally, it is now possible to move objects between threads. - - \section1 \l{Qt Examples#Concurrent Programming}{Concurrent Programming} - - The QtConcurrent namespace includes a collection of classes and functions - for straightforward concurrent programming. - - These examples show how to apply the basic techniques of concurrent - programming to simple problems. - - \section1 \l{Qt Examples#Network}{Network} - - \l{Qt Examples#Network}{\inlineimage network-examples.png - } - - Qt is provided with an extensive set of network classes to support both - client-based and server side network programming. - - These examples demonstrate the fundamental aspects of network programming - with Qt. - - \section1 \l{Qt Examples#XML}{XML} - - \l{Qt Examples#XML}{\inlineimage xml-examples.png - } - - XML parsing and handling is supported through SAX and DOM compliant APIs. - - Qt's SAX compliant classes allow you to parse XML incrementally; the DOM - classes enable more complex document-level operations to be performed on - XML files. - - \section1 \l{Qt Examples#XQuery, XPath}{XQuery, XPath} - - Qt provides an XQuery/XPath engine, QtXmlPatterns, for querying XML - files and custom data models, similar to the model/view framework. - - \section1 \l{Qt Examples#OpenGL}{OpenGL} - - \l{Qt Examples#OpenGL}{\inlineimage opengl-examples.png - } - - Qt provides support for integration with OpenGL implementations on all - platforms, giving developers the opportunity to display hardware accelerated - 3D graphics alongside a more conventional user interface. - - These examples demonstrate the basic techniques used to take advantage of - OpenGL in Qt applications. - - \section1 \l{Qt Examples#Multimedia}{Multimedia} - - \l{Qt Examples#Multimedia} - - Qt provides low-level audio support on linux,windows and mac platforms by default and - an audio plugin API to allow developers to implement there own audio support for - custom devices and platforms. - - These examples demonstrate the basic techniques used to take advantage of - Audio API in Qt applications. - - \section1 \l{Qt Examples#SQL}{SQL} - - \l{Qt Examples#SQL}{\inlineimage sql-examples.png - } - - Qt provides extensive database interoperability, with support for products - from both open source and proprietary vendors. - - SQL support is integrated with Qt's model/view architecture, making it easier - to provide GUI integration for your database applications. - - \section1 \l{Qt Examples#Help System}{Help System} - - \l{Qt Examples#Help System}{\inlineimage assistant-examples.png - } - - Support for interactive help is provided by the Qt Assistant application. - Developers can take advantages of the facilities it offers to display - specially-prepared documentation to users of their applications. - - \section1 \l{Qt Examples#Qt Designer}{Qt Designer} - - \l{Qt Examples#Qt Designer}{\inlineimage designer-examples.png - } - - Qt Designer is a capable graphical user interface designer that lets you - create and configure forms without writing code. GUIs created with - Qt Designer can be compiled into an application or created at run-time. - - \section1 \l{Qt Examples#UiTools}{UiTools} - - \l{Qt Examples#UiTools}{\inlineimage uitools-examples.png - } - - Qt is equipped with a range of capable tool classes, from containers and - iterators to classes for string handling and manipulation. - - Other classes provide application infrastructure support, handling plugin - loading and managing configuration files. - - \section1 \l{Qt Examples#Qt Linguist}{Qt Linguist} - - \l{Qt Examples#Qt Linguist}{\inlineimage linguist-examples.png - } - - Internationalization is a core feature of Qt. These examples show how to - access translation and localization facilities at run-time. - - \section1 \l{Qt Examples#Qt Script}{Qt Script} - - \l{Qt Examples#Qt Script}{\inlineimage qtscript-examples.png - } - - Qt is provided with a powerful embedded scripting environment through the QtScript - classes. - - These examples demonstrate the fundamental aspects of scripting applications - with Qt. - - \section1 \l{Qt Examples#Phonon Multimedia Framework}{Phonon Multimedia Framework} - - \l{Qt Examples#Phonon Multimedia Framework}{\inlineimage phonon-examples.png - } - - The Phonon Multimedia Framework brings multimedia support to Qt applications. - - The examples and demonstrations provided show how to play music and movies - using the Phonon API. - - \section1 \l{Qt Examples#WebKit}{WebKit} - - \l{Qt Examples#WebKit}{\inlineimage webkit-examples.png - } - - Qt provides an integrated Web browser component based on WebKit, the popular - open source browser engine. - - These examples and demonstrations show a range of different uses for WebKit, - from displaying Web pages within a Qt user interface to an implementation of - a basic function Web browser. - - \section1 \l{Qt Examples#State Machine}{State Machine} - - Qt provides a powerful hierchical finite state machine through the Qt State - Machine classes. - - These examples demonstrate the fundamental aspects of implementing - Statecharts with Qt. - - \section1 \l{Qt Examples#Qt for Embedded Linux}{Qt for Embedded Linux} - - \l{Qt Examples#Qt for Embedded Linux}{\inlineimage qt-embedded-examples.png - } - - These examples show how to take advantage of features specifically designed - for use on systems with limited resources, specialized hardware, and small - screens. - - \section1 \l{Qt Examples#ActiveQt}{ActiveQt} - - Qt is supplied with a number of example applications and demonstrations that - have been written to provide developers with examples of the Qt API in use, - highlight good programming practice, and showcase features found in each of - Qt's core technologies. - - The example and demo launcher can be used to explore the different categories - available. It provides an overview of each example, lets you view the - documentation in Qt Assistant, and is able to launch examples and demos. - - \section1 \l{http://qt.nokia.com/doc/qq}{Another Source of Examples} - - One more valuable source for examples and explanations of Qt - features is the archive of the \l {http://qt.nokia.com/doc/qq} - {Qt Quarterly}. - -*/ diff --git a/doc/src/examples.qdoc b/doc/src/examples.qdoc deleted file mode 100644 index 8f80e64..0000000 --- a/doc/src/examples.qdoc +++ /dev/null @@ -1,438 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page examples.html - \title Qt Examples - \brief Information about the example programs provided with Qt. - \ingroup howto - - This is the list of examples in Qt's \c examples directory. The - examples demonstrate Qt features in small, self-contained - programs. They are not all designed to be impressive when you run - them, but their source code is carefully written to show good Qt - programming practices. You can launch any of these programs from the - \l{Examples and Demos Launcher} application. - - If you are new to Qt, you should probably start by going through - the \l{Tutorials} before you have a look at the - \l{mainwindows/application}{Application} example. - - In addition to the examples and the tutorial, Qt includes a - \l{Qt Demonstrations}{selection of demos} that deliberately show off - Qt's features. You might want to look at these as well. - - One more valuable source for examples and explanations of Qt - features is the archive of the \l {Qt Quarterly}. - - In the list below, examples marked with an asterisk (*) are fully - documented. Eventually, all the examples will be fully documented, - but sometimes we include an example before we have time to write - about it, because someone might need it right now. - - Categories: - - \tableofcontents - - \section1 ActiveQt - - \list - \o \l{activeqt/comapp}{COM App}\raisedaster - \o \l{Dot Net Example (ActiveQt)}{Dot Net}\raisedaster - \o \l{activeqt/hierarchy}{Hierarchy}\raisedaster - \o \l{activeqt/menus}{Menus}\raisedaster - \o \l{activeqt/multiple}{Multiple}\raisedaster - \o \l{activeqt/opengl}{OpenGL}\raisedaster - \o \l{activeqt/qutlook}{Qutlook}\raisedaster - \o \l{activeqt/simple}{Simple}\raisedaster - \o \l{activeqt/webbrowser}{Web Browser}\raisedaster - \o \l{activeqt/wrapper}{Wrapper}\raisedaster - \endlist - - \section1 Animation - - \list - \o \l{animation/moveblocks}{Move Blocks}\raisedaster - \o \l{animation/stickman}{Stick man}\raisedaster - \endlist - - \section1 Concurrent Programming - - \list - \o \l{qtconcurrent/imagescaling}{QtConcurrent Asynchronous Image Scaling} - \o \l{qtconcurrent/map}{QtConcurrent Map} - \o \l{qtconcurrent/progressdialog}{QtConcurrent Progress Dialog} - \o \l{qtconcurrent/runfunction}{QtConcurrent Run Function} - \o \l{qtconcurrent/wordcount}{QtConcurrent Word Count} - \endlist - - \section1 D-Bus - \list - \o \l{dbus/dbus-chat}{Chat} - \o \l{dbus/complexpingpong}{Complex Ping Pong} - \o \l{dbus/listnames}{List Names} - \o \l{dbus/pingpong}{Ping Pong} - \o \l{dbus/remotecontrolledcar}{Remote Controlled Car} - \endlist - - \section1 Desktop - - \list - \o \l{desktop/screenshot}{Screenshot}\raisedaster - \o \l{desktop/systray}{System Tray}\raisedaster - \endlist - - \section1 Dialogs - - \list - \o \l{dialogs/classwizard}{Class Wizard}\raisedaster - \o \l{dialogs/configdialog}{Config Dialog} - \o \l{dialogs/extension}{Extension}\raisedaster - \o \l{dialogs/findfiles}{Find Files}\raisedaster - \o \l{dialogs/licensewizard}{License Wizard}\raisedaster - \o \l{dialogs/standarddialogs}{Standard Dialogs} - \o \l{dialogs/tabdialog}{Tab Dialog}\raisedaster - \o \l{dialogs/trivialwizard}{Trivial Wizard} - \endlist - - \section1 Drag and Drop - - \list - \o \l{draganddrop/delayedencoding}{Delayed Encoding}\raisedaster - \o \l{draganddrop/draggableicons}{Draggable Icons} - \o \l{draganddrop/draggabletext}{Draggable Text} - \o \l{draganddrop/dropsite}{Drop Site} - \o \l{draganddrop/fridgemagnets}{Fridge Magnets}\raisedaster - \o \l{draganddrop/puzzle}{Drag and Drop Puzzle} - \endlist - - \section1 Graphics View - - \list - \o \l{graphicsview/collidingmice}{Colliding Mice}\raisedaster - \o \l{graphicsview/diagramscene}{Diagram Scene}\raisedaster - \o \l{graphicsview/dragdroprobot}{Drag and Drop Robot} - \o \l{graphicsview/elasticnodes}{Elastic Nodes} - \o \l{graphicsview/portedasteroids}{Ported Asteroids} - \o \l{graphicsview/portedcanvas}{Ported Canvas} - \endlist - - \section1 Help System - - \list - \o \l{help/simpletextviewer}{Simple Text Viewer}\raisedaster - \endlist - - \section1 Item Views - - \list - \o \l{itemviews/addressbook}{Address Book}\raisedaster - \o \l{itemviews/basicsortfiltermodel}{Basic Sort/Filter Model} - \o \l{itemviews/chart}{Chart} - \o \l{itemviews/coloreditorfactory}{Color Editor Factory}\raisedaster - \o \l{itemviews/combowidgetmapper}{Combo Widget Mapper}\raisedaster - \o \l{itemviews/customsortfiltermodel}{Custom Sort/Filter Model}\raisedaster - \o \l{itemviews/dirview}{Dir View} - \o \l{itemviews/editabletreemodel}{Editable Tree Model}\raisedaster - \o \l{itemviews/fetchmore}{Fetch More}\raisedaster - \o \l{itemviews/frozencolumn}{Frozen Column}\raisedaster - \o \l{itemviews/pixelator}{Pixelator}\raisedaster - \o \l{itemviews/puzzle}{Puzzle} - \o \l{itemviews/simpledommodel}{Simple DOM Model}\raisedaster - \o \l{itemviews/simpletreemodel}{Simple Tree Model}\raisedaster - \o \l{itemviews/simplewidgetmapper}{Simple Widget Mapper}\raisedaster - \o \l{itemviews/spinboxdelegate}{Spin Box Delegate}\raisedaster - \o \l{itemviews/stardelegate}{Star Delegate}\raisedaster - \endlist - - \section1 Layouts - - \list - \o \l{layouts/basiclayouts}{Basic Layouts}\raisedaster - \o \l{layouts/borderlayout}{Border Layout} - \o \l{layouts/dynamiclayouts}{Dynamic Layouts} - \o \l{layouts/flowlayout}{Flow Layout} - \endlist - - \section1 Main Windows - - \list - \o \l{mainwindows/application}{Application}\raisedaster - \o \l{mainwindows/dockwidgets}{Dock Widgets}\raisedaster - \o \l{mainwindows/mdi}{MDI} - \o \l{mainwindows/menus}{Menus}\raisedaster - \o \l{mainwindows/recentfiles}{Recent Files} - \o \l{mainwindows/sdi}{SDI} - \endlist - - \section1 Network - - \list - \o \l{network/blockingfortuneclient}{Blocking Fortune Client}\raisedaster - \o \l{network/broadcastreceiver}{Broadcast Receiver} - \o \l{network/broadcastsender}{Broadcast Sender} - \o \l{network/network-chat}{Network Chat} - \o \l{network/fortuneclient}{Fortune Client}\raisedaster - \o \l{network/fortuneserver}{Fortune Server}\raisedaster - \o \l{network/ftp}{FTP}\raisedaster - \o \l{network/http}{HTTP} - \o \l{network/loopback}{Loopback} - \o \l{network/threadedfortuneserver}{Threaded Fortune Server}\raisedaster - \o \l{network/torrent}{Torrent} - \o \l{network/googlesuggest}{Google Suggest} - \endlist - - \section1 OpenGL - - \list - \o \l{opengl/2dpainting}{2D Painting}\raisedaster - \o \l{opengl/framebufferobject}{Framebuffer Object} - \o \l{opengl/framebufferobject2}{Framebuffer Object 2} - \o \l{opengl/grabber}{Grabber} - \o \l{opengl/hellogl}{Hello GL}\raisedaster - \o \l{opengl/overpainting}{Overpainting}\raisedaster - \o \l{opengl/pbuffers}{Pixel Buffers} - \o \l{opengl/pbuffers2}{Pixel Buffers 2} - \o \l{opengl/samplebuffers}{Sample Buffers} - \o \l{opengl/textures}{Textures} - \endlist - - \section1 Painting - - \list - \o \l{painting/basicdrawing}{Basic Drawing}\raisedaster - \o \l{painting/concentriccircles}{Concentric Circles}\raisedaster - \o \l{painting/fontsampler}{Font Sampler} - \o \l{painting/imagecomposition}{Image Composition}\raisedaster - \o \l{painting/painterpaths}{Painter Paths}\raisedaster - \o \l{painting/svggenerator}{SVG Generator}\raisedaster - \o \l{painting/svgviewer}{SVG Viewer} - \o \l{painting/transformations}{Transformations}\raisedaster - \endlist - - \section1 Phonon Multimedia Framework - - \list - \o \l{phonon/capabilities}{Capabilities}\raisedaster - \o \l{phonon/musicplayer}{Music Player}\raisedaster - \endlist - - \section1 Multimedia - - \list - \o \l{multimedia/audio/audiodevices}{Audio Devices}\raisedaster - \o \l{multimedia/audio/audiooutput}{Audio Output}\raisedaster - \o \l{multimedia/audio/audioinput}{Audio Input}\raisedaster - \endlist - - \section1 Qt Designer - - \list - \o \l{designer/calculatorbuilder}{Calculator Builder}\raisedaster - \o \l{designer/calculatorform}{Calculator Form}\raisedaster - \o \l{designer/customwidgetplugin}{Custom Widget Plugin}\raisedaster - \o \l{designer/taskmenuextension}{Task Menu Extension}\raisedaster - \o \l{designer/containerextension}{Container Extension}\raisedaster - \o \l{designer/worldtimeclockbuilder}{World Time Clock Builder}\raisedaster - \o \l{designer/worldtimeclockplugin}{World Time Clock Plugin}\raisedaster - \endlist - - \section1 Qt Linguist - - \list - \o \l{linguist/hellotr}{Hello tr()}\raisedaster - \o \l{linguist/arrowpad}{Arrow Pad}\raisedaster - \o \l{linguist/trollprint}{Troll Print}\raisedaster - \endlist - - \section1 Qt for Embedded Linux - - \list - \o \l{qws/svgalib}{Accelerated Graphics Driver}\raisedaster - \o \l{qws/dbscreen}{Double Buffered Graphics Driver}\raisedaster - \o \l{qws/mousecalibration}{Mouse Calibration}\raisedaster - \o \l{qws/ahigl}{OpenGL for Embedded Systems}\raisedaster - \o \l{qws/simpledecoration}{Simple Decoration}\raisedaster - \endlist - - \section1 Qt Script - - \list - \o \l{script/calculator}{Calculator}\raisedaster - \o \l{script/context2d}{Context2D}\raisedaster - \o \l{script/defaultprototypes}{Default Prototypes}\raisedaster - \o \l{script/helloscript}{Hello Script}\raisedaster - \o \l{script/qstetrix}{Qt Script Tetrix}\raisedaster - \o \l{script/customclass}{Custom Script Class}\raisedaster - \endlist - - \section1 Rich Text - - \list - \o \l{richtext/calendar}{Calendar}\raisedaster - \o \l{richtext/orderform}{Order Form}\raisedaster - \o \l{richtext/syntaxhighlighter}{Syntax Highlighter}\raisedaster - \o \l{richtext/textobject}{Text Object}\raisedaster - \endlist - - \section1 SQL - - \list - \o \l{sql/cachedtable}{Cached Table}\raisedaster - \o \l{sql/drilldown}{Drill Down}\raisedaster - \o \l{sql/querymodel}{Query Model} - \o \l{sql/relationaltablemodel}{Relational Table Model} - \o \l{sql/tablemodel}{Table Model} - \o \l{sql/sqlwidgetmapper}{SQL Widget Mapper}\raisedaster - \endlist - - \section1 State Machine - - \list - \o \l{statemachine/eventtransitions}{Event Transitions}\raisedaster - \o \l{statemachine/factorial}{Factorial States}\raisedaster - \o \l{statemachine/pingpong}{Ping Pong States}\raisedaster - \o \l{statemachine/rogue}{Rogue}\raisedaster - \o \l{statemachine/trafficlight}{Traffic Light}\raisedaster - \o \l{statemachine/twowaybutton}{Two-way Button}\raisedaster - \endlist - - \section1 Threads - - \list - \o \l{threads/queuedcustomtype}{Queued Custom Type}\raisedaster - \o \l{threads/mandelbrot}{Mandelbrot}\raisedaster - \o \l{threads/semaphores}{Semaphores}\raisedaster - \o \l{threads/waitconditions}{Wait Conditions}\raisedaster - \endlist - - \section1 Tools - - \list - \o \l{tools/codecs}{Codecs} - \o \l{tools/completer}{Completer}\raisedaster - \o \l{tools/customcompleter}{Custom Completer}\raisedaster - \o \l{tools/customtype}{Custom Type}\raisedaster - \o \l{tools/customtypesending}{Custom Type Sending}\raisedaster - \o \l{tools/echoplugin}{Echo Plugin}\raisedaster - \o \l{tools/i18n}{I18N} - \o \l{tools/plugandpaint}{Plug & Paint}\raisedaster - \o Plug & Paint Plugins: \l{tools/plugandpaintplugins/basictools}{Basic Tools}\raisedaster - and \l{tools/plugandpaintplugins/extrafilters}{Extra Filters}\raisedaster - \o \l{tools/regexp}{RegExp} - \o \l{tools/settingseditor}{Settings Editor} - \o \l{tools/styleplugin}{Style Plugin}\raisedaster - \o \l{tools/treemodelcompleter}{Tree Model Completer}\raisedaster - \o \l{tools/undoframework}{Undo Framework}\raisedaster - \endlist - - \section1 UiTools - - \list - \o \l{uitools/multipleinheritance}{Multiple Inheritance}\raisedaster - \o \l{uitools/textfinder}{Text Finder}\raisedaster - \endlist - - \section1 WebKit - - \list - \o \l{webkit/previewer}{Previewer}\raisedaster - \o \l{webkit/formextractor}{Form Extractor} - \o \l{webkit/googlechat}{Google Chat} - \o \l{webkit/fancybrowser}{Fancy Browser} - \endlist - - \section1 Widgets - - \list - \o \l{widgets/analogclock}{Analog Clock}\raisedaster - \o \l{widgets/calculator}{Calculator}\raisedaster - \o \l{widgets/calendarwidget}{Calendar Widget}\raisedaster - \o \l{widgets/charactermap}{Character Map}\raisedaster - \o \l{widgets/codeeditor}{Code Editor}\raisedaster - \o \l{widgets/digitalclock}{Digital Clock}\raisedaster - \o \l{widgets/groupbox}{Group Box}\raisedaster - \o \l{widgets/icons}{Icons}\raisedaster - \o \l{widgets/imageviewer}{Image Viewer}\raisedaster - \o \l{widgets/lineedits}{Line Edits}\raisedaster - \o \l{widgets/movie}{Movie} - \o \l{widgets/scribble}{Scribble}\raisedaster - \o \l{widgets/shapedclock}{Shaped Clock}\raisedaster - \o \l{widgets/sliders}{Sliders}\raisedaster - \o \l{widgets/spinboxes}{Spin Boxes}\raisedaster - \o \l{widgets/styles}{Styles}\raisedaster - \o \l{widgets/stylesheet}{Style Sheet}\raisedaster - \o \l{widgets/tablet}{Tablet}\raisedaster - \o \l{widgets/tetrix}{Tetrix}\raisedaster - \o \l{widgets/tooltips}{Tooltips}\raisedaster - \o \l{widgets/wiggly}{Wiggly}\raisedaster - \o \l{widgets/windowflags}{Window Flags}\raisedaster - \endlist - - \section1 XML - - \list - \o \l{xml/dombookmarks}{DOM Bookmarks} - \o \l{xml/htmlinfo}{HTML Info} - \o \l{xml/saxbookmarks}{SAX Bookmarks} - \o \l{xml/streambookmarks}{QXmlStream Bookmarks}\raisedaster - \o \l{xml/rsslisting}{RSS-Listing} - \o \l{xml/xmlstreamlint}{XML Stream Lint Example}\raisedaster - \endlist - - \section1 XQuery, XPath - - \list - \o \l{xmlpatterns/recipes}{Recipes} - \o \l{xmlpatterns/filetree}{File System Example} - \o \l{xmlpatterns/qobjectxmlmodel}{QObject XML Model Example} - \o \l{xmlpatterns/xquery/globalVariables}{C++ Source Code Analyzer Example} - \o \l{xmlpatterns/trafficinfo}{Traffic Info}\raisedaster - \o \l{xmlpatterns/schema}{XML Schema Validation}\raisedaster - \endlist - - \section1 Inter-Process Communication - \list - \o \l{ipc/localfortuneclient}{Local Fortune Client}\raisedaster - \o \l{ipc/localfortuneserver}{Local Fortune Server}\raisedaster - \o \l{ipc/sharedmemory}{Shared Memory}\raisedaster - \endlist -*/ diff --git a/doc/src/examples/application.qdoc b/doc/src/examples/application.qdoc index 7b7b881..dcab9e7 100644 --- a/doc/src/examples/application.qdoc +++ b/doc/src/examples/application.qdoc @@ -289,7 +289,7 @@ When restoring the position and size of a window, it's important to call QWidget::resize() before QWidget::move(). The reason why - is given in the \l{geometry.html}{Window Geometry} overview. + is given in the \l{Window Geometry} overview. \snippet examples/mainwindows/application/mainwindow.cpp 37 \snippet examples/mainwindows/application/mainwindow.cpp 39 diff --git a/doc/src/examples/drilldown.qdoc b/doc/src/examples/drilldown.qdoc index fff3b60..b62ecc5 100644 --- a/doc/src/examples/drilldown.qdoc +++ b/doc/src/examples/drilldown.qdoc @@ -389,9 +389,7 @@ the item's hover events, animating the item when the mouse cursor is hovering over the image (by default, no items accept hover events). Please see the \l{The Graphics View Framework} - documentation and the - \l{Qt Examples#Graphics View}{Graphics View examples} for more - details. + documentation and the \l{Graphics View Examples} for more details. \snippet examples/sql/drilldown/view.cpp 5 diff --git a/doc/src/examples/qtscriptcalculator.qdoc b/doc/src/examples/qtscriptcalculator.qdoc index e9156b3..0e6e153 100644 --- a/doc/src/examples/qtscriptcalculator.qdoc +++ b/doc/src/examples/qtscriptcalculator.qdoc @@ -42,7 +42,6 @@ /*! \example script/calculator \title QtScript Calculator Example - \ingroup scripting In this simple QtScript example, we show how to implement the functionality of a calculator widget. diff --git a/doc/src/examples/trafficinfo.qdoc b/doc/src/examples/trafficinfo.qdoc index 76d0810..500cf31 100644 --- a/doc/src/examples/trafficinfo.qdoc +++ b/doc/src/examples/trafficinfo.qdoc @@ -159,5 +159,5 @@ The rest of the code in this example is just for representing the time and station information to the user, and uses techniques described in the - \l{Qt Examples#Widgets}{Widgets examples}. + \l{Widgets Examples}. */ diff --git a/doc/src/datastreamformat.qdoc b/doc/src/files-and-resources/datastreamformat.qdoc index eac550c..4226d0b 100644 --- a/doc/src/datastreamformat.qdoc +++ b/doc/src/files-and-resources/datastreamformat.qdoc @@ -39,22 +39,9 @@ ** ****************************************************************************/ -/**************************************************************************** -** -** Documentation of the Format of the QDataStream operators. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - /*! \page datastreamformat.html \title Format of the QDataStream Operators - \ingroup architecture \brief Representations of data types that can be serialized by QDataStream. The \l QDataStream allows you to serialize some of the Qt data types. diff --git a/doc/src/resources.qdoc b/doc/src/files-and-resources/resources.qdoc index f8e9124..a799646 100644 --- a/doc/src/resources.qdoc +++ b/doc/src/files-and-resources/resources.qdoc @@ -40,9 +40,20 @@ ****************************************************************************/ /*! + \group io + \title Input/Output and Networking + \ingroup groups + + \brief Classes providing file input and output along with directory and + network handling. + + These classes are used to handle input and output to and from external + devices, processes, files etc. as well as manipulating files and directories. +*/ + +/*! \page resources.html \title The Qt Resource System - \ingroup buildsystem \keyword resource system diff --git a/doc/src/accessible.qdoc b/doc/src/frameworks-technologies/accessible.qdoc index 8daff5a..7f1a2b1 100644 --- a/doc/src/accessible.qdoc +++ b/doc/src/frameworks-technologies/accessible.qdoc @@ -40,9 +40,15 @@ ****************************************************************************/ /*! + \group accessibility + \title Accessibility Classes +*/ + +/*! \page accessible.html \title Accessibility - \ingroup accessibility + + \ingroup frameworks-technologies \tableofcontents @@ -90,6 +96,10 @@ accessibility. \section2 Accessibility in Qt + + These classes provide support for accessible applications. + + \annotatedlist accessibility When we communicate with the assistive technologies, we need to describe Qt's user interface in a way that they can understand. Qt @@ -249,6 +259,19 @@ produce interfaces. We will give examples of both approaches later. + \section2 Enabling Accessibility Support + + By default, Qt applications are run with accessibility support + enabled on Windows and Mac OS X. On Unix/X11 platforms, applications + must be launched in an environment with the \c QT_ACCESSIBILITY + variable set to 1. For example, this is set in the following way with + the bash shell: + + \snippet doc/src/snippets/code/doc_src_qt4-accessibility.qdoc environment + + Accessibility features are built into Qt by default when the libraries + are configured and built. + \section1 Implementing Accessibility To provide accessibility support for a widget or other user @@ -274,9 +297,10 @@ \endlist In general, it is recommended that you are somewhat familiar with - MSAA, which Qt originally was built for. You should also study - the enum values of QAccessible, which describe the roles, actions, - relationships, and events that you need to consider. + MSAA, which Qt's accessibility support originally was built for. + You should also study the enum values of QAccessible, which + describe the roles, actions, relationships, and events that you + need to consider. Note that you can examine how Qt's widgets implement their accessibility. One major problem with the MSAA standard is that diff --git a/doc/src/qaxcontainer.qdoc b/doc/src/frameworks-technologies/activeqt-container.qdoc index 59f059f..47be4be 100644 --- a/doc/src/qaxcontainer.qdoc +++ b/doc/src/frameworks-technologies/activeqt-container.qdoc @@ -40,12 +40,8 @@ ****************************************************************************/ /*! - \module QAxContainer - \title QAxContainer Module - \contentspage Qt's Modules - \previouspage QtTest - \nextpage QAxServer - \ingroup modules + \page activeqt-container.html + \title Using ActiveX controls and COM objects in Qt \brief The QAxContainer module is a Windows-only extension for accessing ActiveX controls and COM objects. @@ -69,7 +65,7 @@ interface to the Windows Script Host. \endlist - Some \l{Qt Examples#ActiveQt}{example applications} that use + Some \l{ActiveQt Examples}{example applications} that use standard ActiveX controls to provide high-level user interface functionality are provided. @@ -219,42 +215,4 @@ that doesn't provide introspection (ie. ActivePython or ActivePerl). You need to call the function directly on the respective QAxScript object. - - \section1 License Information - - The QAxContainer module is not covered by the \l{GNU General Public License (GPL)}, - the \l{GNU Lesser General Public License (LGPL)}, or the - \l{Qt Commercial Editions}{Qt Commercial License}. Instead, it is distributed under - the following license. - - \legalese - Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).\br - All rights reserved. - - Contact: Nokia Corporation (qt-info@nokia.com)\br - - You may use this file under the terms of the BSD license as follows:\br - - "Redistribution and use in source and binary forms, with or without modification, - are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this list - of conditions and the following disclaimer.\br - * Redistributions in binary form must reproduce the above copyright notice, this - list of conditions and the following disclaimer in the documentation and/or other - materials provided with the distribution.\br - * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor the names of - its contributors may be used to endorse or promote products derived from this - software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT - SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, - INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED - TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." - \endlegalese */ diff --git a/doc/src/qaxserver.qdoc b/doc/src/frameworks-technologies/activeqt-server.qdoc index 63c1e13..4491be3 100644 --- a/doc/src/qaxserver.qdoc +++ b/doc/src/frameworks-technologies/activeqt-server.qdoc @@ -40,15 +40,11 @@ ****************************************************************************/ /*! - \module QAxServer - \title QAxServer Module - \contentspage Qt's Modules - \previouspage QAxContainer - \nextpage QtDBus module - \ingroup modules + \page activeqt-server.html + \title Building ActiveX servers and controls with Qt \brief The QAxServer module is a Windows-only static library that - you can use to turn a standard Qt binary into a COM server. + you can use to turn a standard Qt binary into a COM server. The QAxServer module is part of the \l ActiveQt framework. It consists of three classes: @@ -60,7 +56,7 @@ \o QAxAggregated can be subclassed to implement additional COM interfaces. \endlist - Some \l{Qt Examples#ActiveQt}{example implementations} of ActiveX + Some \l{ActiveQt Examples}{example implementations} of ActiveX controls and COM objects are provided. \sa {ActiveQt Framework} @@ -625,8 +621,8 @@ If the web browser supports scripting use JavaScript, VBScript and forms to script the control. The - \l{Qt Examples#ActiveQt}{ActiveQt examples} include demonstration - HTML pages for the example controls. + \l{ActiveQt Examples} include demonstration HTML pages for the example + controls. \section2 Supported and Unsupported ActiveX Clients @@ -857,42 +853,4 @@ QAxAggregated subclass. \snippet doc/src/snippets/code/doc_src_qaxserver.qdoc 20 - - \section1 License Information - - The QAxContainer module is not covered by the \l{GNU General Public License (GPL)}, - the \l{GNU Lesser General Public License (LGPL)}, or the - \l{Qt Commercial Editions}{Qt Commercial License}. Instead, it is distributed under - the following license. - - \legalese - Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).\br - All rights reserved. - - Contact: Nokia Corporation (qt-info@nokia.com)\br - - You may use this file under the terms of the BSD license as follows:\br - - "Redistribution and use in source and binary forms, with or without modification, - are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this list - of conditions and the following disclaimer.\br - * Redistributions in binary form must reproduce the above copyright notice, this - list of conditions and the following disclaimer in the documentation and/or other - materials provided with the distribution.\br - * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor the names of - its contributors may be used to endorse or promote products derived from this - software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT - SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, - INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED - TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." - \endlegalese */ diff --git a/doc/src/activeqt.qdoc b/doc/src/frameworks-technologies/activeqt.qdoc index b3f0856..75c598a 100644 --- a/doc/src/activeqt.qdoc +++ b/doc/src/frameworks-technologies/activeqt.qdoc @@ -40,11 +40,23 @@ ****************************************************************************/ /*! + \group activeqt-tools + \title Tools for ActiveQt + \brief Tools to help integrate Qt applications with ActiveX components. + + These tools provide support for integrating Qt with ActiveX components. + + \generatelist{related} + + \sa {ActiveQt Framework} +*/ + +/*! \page activeqt.html \title ActiveQt Framework \brief An overview of Qt's ActiveX and COM integration on Windows. - \ingroup platform-notes + \ingroup platform-specific \keyword ActiveQt Qt's ActiveX and COM support allows Qt for Windows developers to: diff --git a/doc/src/animation.qdoc b/doc/src/frameworks-technologies/animation.qdoc index 7fd7850..d495aeb 100644 --- a/doc/src/animation.qdoc +++ b/doc/src/frameworks-technologies/animation.qdoc @@ -40,12 +40,18 @@ ****************************************************************************/ /*! + \group animation + \title Animation Framework +*/ + +/*! \page animation-overview.html \title The Animation Framework - \ingroup architecture - \ingroup animation + \brief An overview of the Animation Framework + \ingroup frameworks-technologies + \keyword Animation The animation framework is part of the Kinetic project, and aims @@ -108,6 +114,13 @@ For detailed descriptions of the classes' function and roles in the framework, please look up their class descriptions. + \section1 Classes in the Animation Framework + + These classes provide a framework for creating both simple and complex + animations. + + \annotatedlist animation + \section1 Animating Qt Properties As mentioned in the previous section, the QPropertyAnimation class diff --git a/doc/src/containers.qdoc b/doc/src/frameworks-technologies/containers.qdoc index 49dae63..2d19b7e 100644 --- a/doc/src/containers.qdoc +++ b/doc/src/frameworks-technologies/containers.qdoc @@ -40,9 +40,25 @@ ****************************************************************************/ /*! - \group containers + \group tools + \title Non-GUI Classes + \ingroup groups + + \brief Collection classes such as list, queue, stack and string, along + with other classes that can be used without needing QApplication. + + The non-GUI classes are general-purpose collection and string classes + that may be used independently of the GUI classes. + + In particular, these classes do not depend on QApplication at all, + and so can be used in non-GUI programs. + +*/ + +/*! + \page containers.html \title Generic Containers - \ingroup architecture + \ingroup frameworks-technologies \ingroup groups \keyword container class \keyword container classes @@ -82,7 +98,23 @@ \section1 The Container Classes - Qt provides the following container classes: + Qt provides the following sequential containers: QList, + QLinkedList, QVector, QStack, and QQueue. For most + applications, QList is the best type to use. Although it is + implemented as an array-list, it provides very fast prepends and + appends. If you really need a linked-list, use QLinkedList; if you + want your items to occupy consecutive memory locations, use QVector. + QStack and QQueue are convenience classes that provide LIFO and + FIFO semantics. + + Qt also provides these associative containers: QMap, + QMultiMap, QHash, QMultiHash, and QSet. The "Multi" containers + conveniently support multiple values associated with a single + key. The "Hash" containers provide faster lookup by using a hash + function instead of a binary search on a sorted set. + + As special cases, the QCache and QContiguousCache classes provide + efficient hash-lookup of objects in a limited cache storage. \table \header \o Class \o Summary @@ -607,6 +639,9 @@ \o QCache<Key, T> provides a cache to store objects of a certain type T associated with keys of type Key. + \o QContiguousCache<T> provides an efficient way of caching data + that is typically accessed in a contiguous way. + \o QPair<T1, T2> stores a pair of elements. \endlist diff --git a/doc/src/qdbusadaptors.qdoc b/doc/src/frameworks-technologies/dbus-adaptors.qdoc index 92a618d..0a4dea7 100644 --- a/doc/src/qdbusadaptors.qdoc +++ b/doc/src/frameworks-technologies/dbus-adaptors.qdoc @@ -39,50 +39,12 @@ ** ****************************************************************************/ -/** -*- mode: C++ -*- -** 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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - /*! \page usingadaptors.html \title Using QtDBus Adaptors + \ingroup best-practices + Adaptors are special classes that are attached to any QObject-derived class and provide the interface to the external world using D-Bus. Adaptors are intended to be lightweight classes whose main purpose is to relay calls to @@ -129,6 +91,9 @@ \page qdbusadaptorexample.html \title D-Bus Adaptor Example + \previouspage The QtDBus Type System + \contentspage Using QtDBus Adaptors + The following example code shows how a D-Bus interface can be implemented using an adaptor. @@ -246,6 +211,9 @@ \page qdbusdeclaringslots.html \title Declaring Slots in D-Bus Adaptors + \contentspage Using QtDBus Adaptors + \nextpage Declaring Signals in D-Bus Adaptors + Slots in D-Bus adaptors are declared just like normal, public slots, but their parameters must follow certain rules (see \l{The QtDBus Type System} for more information). Slots whose parameters do not follow those rules or that are not @@ -374,6 +342,10 @@ \page qdbusdeclaringsignals.html \title Declaring Signals in D-Bus Adaptors + \previouspage Declaring Slots in D-Bus Adaptors + \contentspage Using QtDBus Adaptors + \nextpage The QtDBus Type System + Any signal in a class derived from QDBusAbstractAdaptor will be automatically relayed into D-Bus, provided that the signal's parameters conform to certain rules (see \l{The QtDBus Type System} for more information). No special code @@ -399,6 +371,10 @@ \page qdbustypesystem.html \title The QtDBus Type System + \previouspage Declaring Signals in D-Bus Adaptors + \contentspage Using QtDBus Adaptors + \nextpage D-Bus Adaptor Example + D-Bus has an extensible type system based on a few primitives and composition of the primitives in arrays and structures. QtDBus implements the interface to that type system through the diff --git a/doc/src/introtodbus.qdoc b/doc/src/frameworks-technologies/dbus-intro.qdoc index bd1aefc..b1fcc44 100644 --- a/doc/src/introtodbus.qdoc +++ b/doc/src/frameworks-technologies/dbus-intro.qdoc @@ -42,10 +42,10 @@ /*! \page intro-to-dbus.html \title Introduction to D-Bus + \brief An introduction to Inter-Process Communication and Remote Procedure Calling with D-Bus. \keyword QtDBus - \ingroup architecture - \brief An introduction to Inter-Process Communication and Remote Procedure Calling with D-Bus. + \ingroup frameworks-technologies \section1 Introduction diff --git a/doc/src/frameworks-technologies/desktop-integration.qdoc b/doc/src/frameworks-technologies/desktop-integration.qdoc new file mode 100644 index 0000000..73a810f --- /dev/null +++ b/doc/src/frameworks-technologies/desktop-integration.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group desktop + \title Desktop Integration Classes +*/ + +/*! + \page desktop-integration.html + \title Desktop Integration + \brief Integrating with the user's desktop environment. + + \ingroup best-practices + + Qt applications behave well in the user's desktop environment, but certain + integrations require additional, and sometimes platform specific, techniques. + + \tableofcontents + + \section1 Useful Classes + + Various classes in Qt are designed to help developers integrate applications into + users' desktop environments. These classes enable developers to take advantage + of native services while still using a cross-platform API. + + \annotatedlist desktop + + \section1 Setting the Application Icon + + In order to change the icon of the executable application file + itself, as it is presented on the desktop (i.e., prior to + application execution), it is necessary to employ another, + platform-dependent technique. + + \tableofcontents {1 Setting the Application Icon} + + \section1 Opening External Resources + + Although Qt provides facilities to handle and display resources, such as + \l{QImageIOHandler}{common image formats} and \l{QTextDocument}{HTML}, + it is sometimes necessary to open files and external resources using external + applications. + + QDesktopServices provides an interface to services offered by the user's desktop + environment. In particular, the \l{QDesktopServices::}{openUrl()} function is + used to open resources using the appropriate application, which may have been + specifically configured by the user. + + \section1 System Tray Icons + + Many modern desktop environments feature docks or panels with \e{system trays} + in which applications can install icons. Applications often use system tray icons + to display status information, either by updating the icon itself or by showing + information in "balloon messages". Additionally, many applications provide + pop-up menus that can be accessed via their system tray icons. + + The QSystemTrayIcon class exposes all of the above features via an intuitive + Qt-style API that can be used on all desktop platforms. + + \section1 Desktop Widgets + + On systems where the user's desktop is displayed using more than one screen, + certain types of applications may need to obtain information about the + configuration of the user's workspace to ensure that new windows and dialogs + are opened in appropriate locations. + + The QDesktopWidget class can be used to monitor the positions of widgets and + notify applications about changes to the way the desktop is split over the + available screens. This enables applications to implement policies for + positioning new windows so that, for example, they do not distract a user + who is working on a specific task. +*/ diff --git a/doc/src/dnd.qdoc b/doc/src/frameworks-technologies/dnd.qdoc index 661c621..5815a1d 100644 --- a/doc/src/dnd.qdoc +++ b/doc/src/frameworks-technologies/dnd.qdoc @@ -40,11 +40,19 @@ ****************************************************************************/ /*! + \group draganddrop + \title Drag And Drop Classes + + \brief Classes dealing with drag and drop and mime type encoding and decoding. +*/ + +/*! \page dnd.html \title Drag and Drop - \ingroup architecture \brief An overview of the drag and drop system provided by Qt. + \ingroup frameworks-technologies + Drag and drop provides a simple visual mechanism which users can use to transfer information between and within applications. (In the literature this is referred to as a "direct manipulation model".) Drag @@ -60,6 +68,13 @@ \l{Using Drag and Drop with Item Views} and \l{The Graphics View Framework} documents. + \section1 Drag and Drop Classes + + These classes deal with drag and drop and the necessary mime type + encoding and decoding. + + \annotatedlist draganddrop + \section1 Configuration The QApplication object provides some properties that are related @@ -432,115 +447,3 @@ request data in response to e.g. a QDragMoveEvent, an empty QByteArray is returned. */ - -/*! - \page porting4-dnd.html - \title Porting to Qt 4 - Drag and Drop - \contentspage {Porting Guides}{Contents} - \previouspage Porting to Qt 4 - Virtual Functions - \nextpage Porting UI Files to Qt 4 - \ingroup porting - \brief An overview of the porting process for applications that use drag and drop. - - Qt 4 introduces a new set of classes to handle drag and drop operations - that aim to be easier to use than their counterparts in Qt 3. As a result, - the way that drag and drop is performed is quite different to the way - developers of Qt 3 applications have come to expect. In this guide, we - show the differences between the old and new APIs and indicate where - applications need to be changed when they are ported to Qt 4. - - \tableofcontents - - \section1 Dragging - - In Qt 3, drag operations are encapsulated by \c QDragObject (see Q3DragObject) - and its subclasses. These objects are typically constructed on the heap in - response to mouse click or mouse move events, and ownership of them is - transferred to Qt so that they can be deleted when the corresponding drag and - drop operations have been completed. The drag source has no control over how - the drag and drop operation is performed once the object's - \l{Q3DragObject::}{drag()} function is called, and it receives no information - about how the operation ended. - - \snippet doc/src/snippets/code/doc_src_dnd.qdoc 0 - - Similarly, in Qt 4, drag operations are also initiated when a QDrag object - is constructed and its \l{QDrag::}{exec()} function is called. In contrast, - these objects are typically constructed on the stack rather than the heap - since each drag and drop operation is performed synchronously as far as the - drag source is concerned. One key benefit of this is that the drag source - can receive information about how the operation ended from the value returned - by \l{QDrag::}{exec()}. - - \snippet doc/src/snippets/porting4-dropevents/window.cpp 2 - \snippet doc/src/snippets/porting4-dropevents/window.cpp 3 - \dots 8 - \snippet doc/src/snippets/porting4-dropevents/window.cpp 4 - \snippet doc/src/snippets/porting4-dropevents/window.cpp 5 - - A key difference in the above code is the use of the QMimeData class to hold - information about the data that is transferred. Qt 3 relies on subclasses - of \c QDragObject to provide support for specific MIME types; in Qt 4, the - use of QMimeData as a generic container for data makes the relationship - between MIME type and data more tranparent. QMimeData is described in more - detail later in this document. - - \section1 Dropping - - In both Qt 3 and Qt 4, it is possible to prepare a custom widget to accept - dropped data by enabling the \l{QWidget::}{acceptDrops} property of a widget, - usually in the widget's constructor. As a result, the widget will receive - drag enter events that can be handled by its \l{QWidget::}{dragEnterEvent()} - function. - As in Qt 3, custom widgets in Qt 4 handle these events by determining - whether the data supplied by the drag and drop operation can be dropped onto - the widget. Since the classes used to encapsulate MIME data are different in - Qt 3 and Qt 4, the exact implementations differ. - - In Qt 3, the drag enter event is handled by checking whether each of the - standard \c QDragObject subclasses can decode the data supplied, and - indicating success or failure of these checks via the event's - \l{QDragEnterEvent::}{accept()} function, as shown in this simple example: - - \snippet doc/src/snippets/code/doc_src_dnd.qdoc 1 - - In Qt 4, you can examine the MIME type describing the data to determine - whether the widget should accept the event or, for common data types, you - can use convenience functions: - - \snippet doc/src/snippets/porting4-dropevents/window.cpp 0 - - The widget has some control over the type of drag and drop operation to be - performed. In the above code, the action proposed by the drag source is - accepted, but - \l{Drag and Drop#Overriding Proposed Actions}{this can be overridden} if - required. - - In both Qt 3 and Qt 4, it is necessary to accept a given drag event in order - to receive the corresponding drop event. A custom widget in Qt 3 that can - accept dropped data in the form of text or images might provide an - implementation of \l{QWidget::}{dropEvent()} that looks like the following: - - \snippet doc/src/snippets/code/doc_src_dnd.qdoc 2 - - In Qt 4, the event is handled in a similar way: - - \snippet doc/src/snippets/porting4-dropevents/window.cpp 1 - - It is also possible to extract data stored for a particular MIME type if it - was specified by the drag source. - - \section1 MIME Types and Data - - In Qt 3, data to be transferred in drag and drop operations is encapsulated - in instances of \c QDragObject and its subclasses, representing specific - data formats related to common MIME type and subtypes. - - In Qt 4, only the QMimeData class is used to represent data, providing a - container for data stored in multiple formats, each associated with - a relevant MIME type. Since arbitrary MIME types can be specified, there is - no need for an extensive class hierarchy to represent different kinds of - information. Additionally, QMimeData it provides some convenience functions - to allow the most common data formats to be stored and retrieved with less - effort than for arbitrary MIME types. -*/ diff --git a/doc/src/eventsandfilters.qdoc b/doc/src/frameworks-technologies/eventsandfilters.qdoc index a67e523..0430bcd 100644 --- a/doc/src/eventsandfilters.qdoc +++ b/doc/src/frameworks-technologies/eventsandfilters.qdoc @@ -40,11 +40,25 @@ ****************************************************************************/ /*! + \group events + \title Event Classes + \ingroup groups + + \brief Classes used to create and handle events. + + These classes are used to create and handle events. + + For more information see the \link object.html Object model\endlink + and \link signalsandslots.html Signals and Slots\endlink. +*/ + +/*! \page eventsandfilters.html \title Events and Event Filters - \ingroup architecture \brief A guide to event handling in Qt. + \ingroup frameworks-technologies + In Qt, events are objects, derived from the abstract QEvent class, that represent things that have happened either within an application or as a result of outside activity that the application needs to know diff --git a/doc/src/frameworks-technologies/gestures.qdoc b/doc/src/frameworks-technologies/gestures.qdoc new file mode 100644 index 0000000..316d74d --- /dev/null +++ b/doc/src/frameworks-technologies/gestures.qdoc @@ -0,0 +1,170 @@ +/**************************************************************************** +** +** 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.example.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gestures-overview.html + \startpage index.html Qt Reference Documentation + + \title Gestures Programming + \ingroup howto + \brief An overview of the Qt support for Gesture programming. + + The QGesture class provides the ability to form gestures from a series + of events independent of the input method. A gesture could be a particular + movement of a mouse, a touch screen action, or a series of events from + some other source. The nature of the input, the interpretation + of the gesture and the action taken are the choice of the implementing + developer. + + \tableofcontents + + + \section1 Creating Your Own Gesture Recognizer + + QGesture is a base class for a user defined gesture recognizer class. In + order to implement the recognizer you will need to subclass the + QGesture class and implement the pure virtual function \l{QGesture::filterEvent()}{filterEvent()}. Once + you have implemented the \l{QGesture::filterEvent()}{filterEvent()} function to + make your own recognizer you can process events. A sequence of events may, + according to your own rules, represent a gesture. The events can be singly + passed to the recognizer via the \l{QGesture::filterEvent()}{filterEvent()} function or as a stream of + events by specifying a parent source of events. The events can be from any + source and could result in any action as defined by the user. The source + and action need not be graphical though that would be the most likely + scenario. To find how to connect a source of events to automatically feed into the recognizer see QGesture. + + Recognizers based on QGesture can emit any of the following signals: + + \snippet doc/src/snippets/gestures/qgesture.h qgesture-signals + + These signals are emitted when the state changes with the call to + \l{QGesture::updateState()}{updateState()}, more than one signal may + be emitted when a change of state occurs. There are four GestureStates + + \table + \header \o New State \o Description \o QGesture Actions on Entering this State + \row \o Qt::NoGesture \o Initial value \o emit \l {QGesture::cancelled()}{cancelled()} + \row \o Qt::GestureStarted \o A continuous gesture has started \o emit \l{QGesture::started()}{started()} and emit \l{QGesture::triggered()}{triggered()} + \row \o Qt::GestureUpdated \o A gesture continues \o emit \l{QGesture::triggered()}{triggered()} + \row \o Qt::GestureFinished \o A gesture has finished. \o emit \l{QGesture::finished()}{finished()} + \endtable + + \note \l{QGesture::started()}{started()} can be emitted if entering any + state greater than NoGesture if NoGesture was the previous state. This + means that your state machine does not need to explicitly use the + Qt::GestureStarted state, you can simply proceed from NoGesture to + Qt::GestureUpdated to emit a \l{QGesture::started()}{started()} signal + and a \l{QGesture::triggered()}{triggered()} signal. + + You may use some or all of these states when implementing the pure + virtual function \l{QGesture::filterEvent()}{filterEvent()}. + \l{QGesture::filterEvent()}{filterEvent()} will usually implement a + state machine using the GestureState enums, but the details of which + states are used is up to the developer. + + You may also need to reimplement the virtual function \l{QGesture::reset()}{reset()} + if internal data or objects need to be re-initialized. The function must + conclude with a call to \l{QGesture::updateState()}{updateState()} to + change the current state to Qt::NoGesture. + + \section1 An Example, ImageViewer + + To illustrate how to use QGesture we will look at the ImageViewer + example. This example uses QPanGesture, standard gesture, and an + implementation of TapAndHoldGesture. Note that TapAndHoldGesture is + platform dependent. + + \snippet doc/src/snippets/gestures/imageviewer/tapandholdgesture.cpp tapandhold-reset + + In ImageViewer we see that the ImageWidget class uses two gestures: + \l QPanGesture and TapAndHoldGesture. The + QPanGesture is a standard gesture which is part of Qt. + TapAndHoldGesture is defined and implemented as part of the example. + The ImageWidget listens for signals from the gestures, but is not + interested in the \l{QGesture::started()}{started()} signal. + + \snippet doc/src/snippets/gestures/imageviewer/imagewidget.h imagewidget-slots + + TapAndHoldGesture uses QTouchEvent events and mouse events to detect + start, update and end events that can be mapped onto the GestureState + changes. The implementation in this case uses a timer as well. If the + timeout event occurs a given number of times after the start of the gesture + then the gesture is considered to have finished whether or not the + appropriate touch or mouse event has occurred. Also if a large jump in + the position of the event occurs, as calculated by the \l {QPoint::manhattanLength()}{manhattanLength()} + call, then the gesture is cancelled by calling \l{QGesture::reset()}{reset()} + which tidies up and uses \l{QGesture::updateState()}{updateState()} to + change state to NoGesture which will result in the \l{QGesture::cancelled()}{cancelled()} + signal being emitted by the recognizer. + + ImageWidget handles the signals by connecting the slots to the signals, + although \c cancelled() is not connected here. + + \snippet doc/src/snippets/gestures/imageviewer/imagewidget.cpp imagewidget-connect + + These functions in turn will have to be aware of which gesture + object was the source of the signal since we have more than one source + per slot. This is easily done by using the QObject::sender() function + as shown here + + \snippet doc/src/snippets/gestures/imageviewer/imagewidget.cpp imagewidget-triggered-1 + + As \l{QGesture::triggered()}{triggered()} signals are handled by + gestureTriggered() there may be position updates invoking calls to, + for example, goNextImage(), this will cause a change in the image + handling logic of ImageWidget and a call to updateImage() to display + the changed state. + + Following the logic of how the QEvent is processed we can summmarize + it as follows: + \list + \o filterEvent() becomes the event filter of the parent ImageWidget object for a QPanGesture object and a + TapAndHoldGesture object. + \o filterEvent() then calls updateState() to change states + \o updateState() emits the appropriate signal(s) for the state change. + \o The signals are caught by the defined slots in ImageWidget + \o The widget logic changes and an update() results in a paint event. + \endlist + + + +*/ + diff --git a/doc/src/graphicsview.qdoc b/doc/src/frameworks-technologies/graphicsview.qdoc index b1c6b6c..8d7ea2c 100644 --- a/doc/src/graphicsview.qdoc +++ b/doc/src/frameworks-technologies/graphicsview.qdoc @@ -40,13 +40,18 @@ ****************************************************************************/ /*! + \group graphicsview-api + \title Graphics View Classes +*/ + +/*! \page graphicsview.html \title The Graphics View Framework - \ingroup architecture - \ingroup multimedia \brief An overview of the Graphics View framework for interactive 2D graphics. + \ingroup frameworks-technologies + \keyword Graphics View \keyword GraphicsView \keyword Graphics @@ -193,6 +198,12 @@ \img graphicsview-items.png + \section1 Classes in the Graphics View Framework + + These classes provide a framework for creating interactive applications. + + \annotatedlist graphicsview-api + \section1 The Graphics View Coordinate System Graphics View is based on the Cartesian coordinate system; items' diff --git a/doc/src/implicit-sharing.qdoc b/doc/src/frameworks-technologies/implicit-sharing.qdoc index cc0b28b..4eb9443 100644 --- a/doc/src/implicit-sharing.qdoc +++ b/doc/src/frameworks-technologies/implicit-sharing.qdoc @@ -45,10 +45,14 @@ /*! \group shared \title Implicitly Shared Classes - \ingroup architecture - \ingroup groups +*/ + +/*! + \page implicit-sharing.html + \title Implicit Sharing + \ingroup frameworks-technologies - \brief Classes that use reference counting for fast copying. + \brief Reference counting for fast copying. \keyword implicit data sharing \keyword implicit sharing @@ -98,7 +102,8 @@ 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}. + \l{Thread-Support in Qt Modules#Threads and Implicitly Shared Classes} + {Threads and Implicitly Shared Classes}. When implementing your own implicitly shared classes, use the QSharedData and QSharedDataPointer classes. @@ -141,4 +146,7 @@ \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}. + + \keyword implicitly shared classes + \annotatedlist shared */ diff --git a/doc/src/ipc.qdoc b/doc/src/frameworks-technologies/ipc.qdoc index 9ca8a0d..f253643 100644 --- a/doc/src/ipc.qdoc +++ b/doc/src/frameworks-technologies/ipc.qdoc @@ -40,25 +40,15 @@ ****************************************************************************/ /*! - \group ipc + \page ipc.html \title Inter-Process Communication in Qt - \ingroup groups - \ingroup architecture \brief Inter-Process communication in Qt applications. + \ingroup frameworks-technologies + Qt provides several ways to implement Inter-Process Communication (IPC) in Qt applications. - \section1 D-Bus - - The \l{QtDBus} module is a Unix-only library - you can use to implement IPC using the D-Bus protocol. It extends - Qt's \l{signalsandslots.html} {Signals and Slots} mechanism to the - IPC level, allowing a signal emitted by one process to be - connected to a slot in another process. This \l {Introduction to - D-Bus} page has detailed information on how to use the \l{QtDBus} - module. - \section1 TCP/IP The cross-platform \l{QtNetwork} module provides classes that make @@ -77,6 +67,16 @@ access to resources shared by the system, as well as to communicate between processes. + \section1 D-Bus + + The \l{QtDBus} module is a Unix-only library + you can use to implement IPC using the D-Bus protocol. It extends + Qt's \l{signalsandslots.html} {Signals and Slots} mechanism to the + IPC level, allowing a signal emitted by one process to be + connected to a slot in another process. This \l {Introduction to + D-Bus} page has detailed information on how to use the \l{QtDBus} + module. + \section1 Qt COmmunications Protocol (QCOP) The QCopChannel class implements a protocol for transferring messages @@ -86,6 +86,4 @@ IPC level, allowing a signal emitted by one process to be connected to a slot in another process, but unlike QtDBus, QCOP does not depend on a third party library. - */ - diff --git a/doc/src/model-view-programming.qdoc b/doc/src/frameworks-technologies/model-view-programming.qdoc index 49214e0..b38edd8 100644 --- a/doc/src/model-view-programming.qdoc +++ b/doc/src/frameworks-technologies/model-view-programming.qdoc @@ -40,15 +40,21 @@ ****************************************************************************/ /*! + \group model-view + \title Model/View Classes +*/ + +/*! \page model-view-programming.html \nextpage An Introduction to Model/View Programming \startpage index.html Qt Reference Documentation \title Model/View Programming - \ingroup architecture \brief A guide to the extensible model/view architecture used by Qt's item view classes. + \ingroup frameworks-technologies + \list \o \l{An Introduction to Model/View Programming} \tableofcontents{1 An Introduction to Model/View Programming} @@ -74,7 +80,14 @@ \tableofcontents{1 Model Subclassing Reference} \endlist - See also the list of \l{Model/View Classes}. + \keyword Model/View Classes + \section1 All Model/View Classes + + These classes use the model/view design pattern in which the + underlying data (in the model) is kept separate from the way the data + is presented and manipulated by the user (in the view). + + \annotatedlist model-view \section1 Related Examples @@ -2148,6 +2161,8 @@ need to supply data for Qt::DisplayRole and any application-specific user roles, but it is also good practice to provide data for Qt::ToolTipRole, Qt::AccessibleTextRole, and Qt::AccessibleDescriptionRole. + See the Qt::ItemDataRole enum documentation for information about the types + associated with each role. \row \o \l{QAbstractItemModel::headerData()}{headerData()} \o Provides views with information to show in their headers. The information is only retrieved by views that can display header information. diff --git a/doc/src/phonon.qdoc b/doc/src/frameworks-technologies/phonon.qdoc index 610ad30..48c09b8 100644 --- a/doc/src/phonon.qdoc +++ b/doc/src/frameworks-technologies/phonon.qdoc @@ -42,7 +42,7 @@ /*! \page phonon-overview.html \title Phonon Overview - \ingroup multimedia + \ingroup frameworks-technologies \tableofcontents @@ -556,88 +556,3 @@ output as a single audio stream. */ -/*! - \namespace Phonon - \brief The Phonon namespace contains classes and functions for multimedia applications. - \since 4.4 - - This namespace contains classes to access multimedia functions for - audio and video playback. Those classes are not dependent on any specific - framework, but rather use exchangeable backends to do the work. - - See the \l{Phonon Module} page for general information about the - framework and the \l{Phonon Overview} for an introductory tour of its - features. -*/ - -/*! - \page phonon-module.html - \module Phonon - \title Phonon Module - \contentspage Qt's Modules - \previouspage QtXmlPatterns - \nextpage Qt3Support - \ingroup modules - - \brief The Phonon module contains namespaces and classes for multimedia functionality. - - \generatelist{classesbymodule Phonon} - - Phonon is a cross-platform multimedia framework that enables the use of - audio and video content in Qt applications. The \l{Phonon Overview} - document provides an introduction to the architecture and features included - in Phonon. The \l{Phonon} namespace contains a list of all classes, functions - and namespaces provided by the module. - - Applications that use Phonon's classes need to - be configured to be built against the Phonon module. - The following declaration in a \c qmake project file ensures that - an application is compiled and linked appropriately: - - \snippet doc/src/snippets/code/doc_src_phonon.qdoc 1 - - The Phonon module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. - - \section1 Qt Backends - - Qt Backends are currently developed for Phonon version 4.1. The Phonon - project has moved on and introduced new features that the Qt Backends do not - implement. We have chosen not to document the part of Phonon that we do not - support. Any class or function not appearing in our documentation can be - considered unsupported. - - \section1 License Information - - Qt Commercial Edition licensees that wish to distribute applications that - use the Phonon module need to be aware of their obligations under the - GNU Lesser General Public License (LGPL). - - Developers using the Open Source Edition can choose to redistribute - the module under the appropriate version of the GNU LGPL; version 2.1 - for applications and libraries licensed under the GNU GPL version 2, - or version 3 for applications and libraries licensed under the GNU - GPL version 2. - - \legalese - This file is part of the KDE project - - Copyright (C) 2005-2007 Matthias Kretz <kretz@kde.org> \BR - 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. - \endlegalese -*/ diff --git a/doc/src/plugins-howto.qdoc b/doc/src/frameworks-technologies/plugins-howto.qdoc index 9fd1f28..4d6896c 100644 --- a/doc/src/plugins-howto.qdoc +++ b/doc/src/frameworks-technologies/plugins-howto.qdoc @@ -40,10 +40,27 @@ ****************************************************************************/ /*! + \group plugins + \title Plugin Classes + \ingroup groups + + \brief Plugin related classes. + + These classes deal with shared libraries, (e.g. .so and DLL files), + and with Qt plugins. + + See the \link plugins-howto.html plugins documentation\endlink. + + See also the \l{ActiveQt framework} for Windows. +*/ + +/*! \page plugins-howto.html \title How to Create Qt Plugins - \brief A guide to creating plugins to extend Qt applications and functionality provided by Qt. - \ingroup howto + \brief A guide to creating plugins to extend Qt applications and + functionality provided by Qt. + + \ingroup frameworks-technologies \keyword QT_DEBUG_PLUGINS \keyword QT_NO_PLUGIN_CHECK @@ -99,27 +116,6 @@ \row \o QTextCodecPlugin \o \c codecs \o Case Sensitive \endtable - But where is the \c{plugins} directory? When the application - is run, Qt will first treat the application's executable directory - as the \c{pluginsbase}. For example if the application is in - \c{C:\Program Files\MyApp} and has a style plugin, Qt will look in - \c{C:\Program Files\MyApp\styles}. (See - QCoreApplication::applicationDirPath() for how to find out where - the application's executable is.) Qt will also look in the - directory specified by - QLibraryInfo::location(QLibraryInfo::PluginsPath), which typically - is located in \c QTDIR/plugins (where \c QTDIR is the directory - where Qt is installed). If you want Qt to look in additional - places you can add as many paths as you need with calls to - QCoreApplication::addLibraryPath(). And if you want to set your - own path or paths you can use QCoreApplication::setLibraryPaths(). - You can also use a \c qt.conf file to override the hard-coded - paths that are compiled into the Qt library. For more information, - see the \l {Using qt.conf} documentation. Yet another possibility - is to set the \c QT_PLUGIN_PATH environment variable before running - the application. If set, Qt will look for plugins in the - paths (separated by the system path separator) specified in the variable. - Suppose that you have a new style class called \c MyStyle that you want to make available as a plugin. The required code is straightforward, here is the class definition (\c @@ -150,56 +146,9 @@ virtual functions that must be reimplemented for each type of plugin. - Qt applications automatically know which plugins are available, - because plugins are stored in the standard plugin subdirectories. - Because of this applications don't require any code to find and load - plugins, since Qt handles them automatically. - - The default directory for plugins is \c{QTDIR/plugins} (where \c - QTDIR is the directory where Qt is installed), with each type of - plugin in a subdirectory for that type, e.g. \c styles. If you - want your applications to use plugins and you don't want to use - the standard plugins path, have your installation process - determine the path you want to use for the plugins, and save the - path, e.g. using QSettings, for the application to read when it - runs. The application can then call - QCoreApplication::addLibraryPath() with this path and your - plugins will be available to the application. Note that the final - part of the path (e.g., \c styles) cannot be changed. - - The normal way to include a plugin with an application is either - to \l{Static Plugins}{compile it in with the application} or to - compile it into a dynamic library and use it like any other - library. - - If you want the plugin to be loadable then one approach is to - create a subdirectory under the application and place the plugin - in that directory. If you distribute any of the plugins that come - with Qt (the ones located in the \c plugins directory), you must - copy the sub-directory under \c plugins where the plugin is - located to your applications root folder (i.e., do not include the - \c plugins directory). - - For more information about deployment, - see the \l {Deploying Qt Applications} documentation. - The \l{Style Plugin Example} shows how to implement a plugin that extends the QStylePlugin base class. - \note In Symbian all binaries must be located in the directory \\sys\\bin, - so each Qt plugin has a stub with the same basename as the plugin dll - and suffix ".qtplugin" to make Qt extension plugins work similarly to - other platforms. - When trying to locate the plugin, Qt actually looks for the stub - instead of the plugin binary. While plugin stub files have the - suffix ".qtplugin", they can still be loaded also by specifying a filename - with the normal library suffix ".dll" for QPluginLoader, so normally application - developer doesn't need to care about the different suffix of the stub. - In Symbian the default plugin stubs path is \\resource\\qt\\plugins. - Because of the way applications can be installed - on ROM or various other drives in Symbian, all available drives are - searched for that path when looking for plugins. - \section1 The Lower-Level API: Extending Qt Applications Not only Qt itself but also Qt application can be extended @@ -250,110 +199,49 @@ that extends Qt applications. Please note that a QCoreApplication must have been initialized before plugins can be loaded. - \section1 Loading and Verifying Plugins Dynamically - - When loading plugins, the Qt library does some sanity checking to - determine whether or not the plugin can be loaded and used. This - provides the ability to have multiple versions and configurations of - the Qt library installed side by side. - - \list - \o Plugins linked with a Qt library that has a higher version number - will not be loaded by a library with a lower version number. - - \br - \bold{Example:} Qt 4.3.0 will \e{not} load a plugin built with Qt 4.3.1. - - \o Plugins linked with a Qt library that has a lower major version - number will not be loaded by a library with a higher major version - number. - - \br - \bold{Example:} Qt 4.3.1 will \e{not} load a plugin built with Qt 3.3.1. - \br - \bold{Example:} Qt 4.3.1 will load plugins built with Qt 4.3.0 and Qt 4.2.3. - - \o The Qt library and all plugins are built using a \e {build - key}. The build key in the Qt library is examined against the build - key in the plugin, and if they match, the plugin is loaded. If the - build keys do not match, then the Qt library refuses to load the - plugin. - - \br \bold{Rationale:} See the \l{#The Build Key}{The Build Key} section below. - \endlist - - When building plugins to extend an application, it is important to ensure - that the plugin is configured in the same way as the application. This means - that if the application was built in release mode, plugins should be built - in release mode, too. - - If you configure Qt to be built in both debug and release modes, - but only build applications in release mode, you need to ensure that your - plugins are also built in release mode. By default, if a debug build of Qt is - available, plugins will \e only be built in debug mode. To force the - plugins to be built in release mode, add the following line to the plugin's - project file: + \section1 Locating Plugins - \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 3 - - This will ensure that the plugin is compatible with the version of the library - used in the application. - - \section2 The Build Key + Qt applications automatically know which plugins are available, + because plugins are stored in the standard plugin subdirectories. + Because of this applications don't require any code to find and load + plugins, since Qt handles them automatically. - When loading plugins, Qt checks the build key of each plugin against its - own configuration to ensure that only compatible plugins are loaded; any - plugins that are configured differently are not loaded. + During development, the directory for plugins is \c{QTDIR/plugins} + (where \c QTDIR is the directory where Qt is installed), with each + type of plugin in a subdirectory for that type, e.g. \c styles. If + you want your applications to use plugins and you don't want to use + the standard plugins path, have your installation process + determine the path you want to use for the plugins, and save the + path, e.g. using QSettings, for the application to read when it + runs. The application can then call + QCoreApplication::addLibraryPath() with this path and your + plugins will be available to the application. Note that the final + part of the path (e.g., \c styles) cannot be changed. - The build key contains the following information: - \list - \o Architecture, operating system and compiler. - - \e {Rationale:} - In cases where different versions of the same compiler do not - produce binary compatible code, the version of the compiler is - also present in the build key. - - \o Configuration of the Qt library. The configuration is a list - of the missing features that affect the available API in the - library. - - \e {Rationale:} - Two different configurations of the same version of - the Qt library are not binary compatible. The Qt library that - loads the plugin uses the list of (missing) features to - determine if the plugin is binary compatible. - - \e {Note:} There are cases where a plugin can use features that are - available in two different configurations. However, the - developer writing plugins would need to know which features are - in use, both in their plugin and internally by the utility - classes in Qt. The Qt library would require complex feature - and dependency queries and verification when loading plugins. - Requiring this would place an unnecessary burden on the developer, and - increase the overhead of loading a plugin. To reduce both - development time and application runtime costs, a simple string - comparision of the build keys is used. - - \o Optionally, an extra string may be specified on the configure - script command line. - - \e {Rationale:} - When distributing binaries of the Qt library with an - application, this provides a way for developers to write - plugins that can only be loaded by the library with which the - plugins were linked. - \endlist + If you want the plugin to be loadable then one approach is to + create a subdirectory under the application and place the plugin + in that directory. If you distribute any of the plugins that come + with Qt (the ones located in the \c plugins directory), you must + copy the sub-directory under \c plugins where the plugin is + located to your applications root folder (i.e., do not include the + \c plugins directory). - For debugging purposes, it is possible to override the run-time build key - checks by configuring Qt with the \c QT_NO_PLUGIN_CHECK preprocessor macro - defined. + For more information about deployment, + see the \l {Deploying Qt Applications} and \l {Deploying Plugins} + documentation. \section1 Static Plugins + The normal and most flexible way to include a plugin with an + application is to compile it into a dynamic library that is shipped + separately, and detected and loaded at runtime. + Plugins can be linked statically against your application. If you build the static version of Qt, this is the only option for - including Qt's predefined plugins. + including Qt's predefined plugins. Using static plugins makes the + deployment less error-prone, but has the disadvantage that no + functionality from plugins can be added without a complete rebuild + and redistribution of the application. When compiled as a static library, Qt provides the following static plugins: @@ -420,65 +308,4 @@ defined. \sa QPluginLoader, QLibrary, {Plug & Paint Example} - - \section1 The Plugin Cache - - In order to speed up loading and validation of plugins, some of - the information that is collected when plugins are loaded is cached - through QSettings. This includes information about whether or not - a plugin was successfully loaded, so that subsequent load operations - don't try to load an invalid plugin. However, if the "last modified" - timestamp of a plugin has changed, the plugin's cache entry is - invalidated and the plugin is reloaded regardless of the values in - the cache entry, and the cache entry itself is updated with the new - result. - - This also means that the timestamp must be updated each time the - plugin or any dependent resources (such as a shared library) is - updated, since the dependent resources might influence the result - of loading a plugin. - - Sometimes, when developing plugins, it is necessary to remove entries - from the plugin cache. Since Qt uses QSettings to manage the plugin - cache, the locations of plugins are platform-dependent; see - \l{QSettings#Platform-Specific Notes}{the QSettings documentation} - for more information about each platform. - - For example, on Windows the entries are stored in the registry, and the - paths for each plugin will typically begin with either of these two strings: - - \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 6 - - \section1 Debugging Plugins - - There are a number of issues that may prevent correctly-written plugins from - working with the applications that are designed to use them. Many of these - are related to differences in the way that plugins and applications have been - built, often arising from separate build systems and processes. - - The following table contains descriptions of the common causes of problems - developers experience when creating plugins: - - \table - \header \o Problem \o Cause \o Solution - \row \o Plugins sliently fail to load even when opened directly by the - application. \QD shows the plugin libraries in its - \gui{Help|About Plugins} dialog, but no plugins are listed under each - of them. - \o The application and its plugins are built in different modes. - \o Either share the same build information or build the plugins in both - debug and release modes by appending the \c debug_and_release to - the \l{qmake Variable Reference#CONFIG}{CONFIG} variable in each of - their project files. - \row \o A valid plugin that replaces an invalid (or broken) plugin fails to load. - \o The entry for the plugin in the plugin cache indicates that the original - plugin could not be loaded, causing Qt to ignore the replacement. - \o Either ensure that the plugin's timestamp is updated, or delete the - entry in the \l{#The Plugin Cache}{plugin cache}. - \endtable - - You can also use the \c QT_DEBUG_PLUGINS environment variable to obtain - diagnostic information from Qt about each plugin it tries to load. Set this - variable to a non-zero value in the environment from which your application is - launched. */ diff --git a/doc/src/qthelp.qdoc b/doc/src/frameworks-technologies/qthelp.qdoc index 3cffa39..2529631 100644 --- a/doc/src/qthelp.qdoc +++ b/doc/src/frameworks-technologies/qthelp.qdoc @@ -40,29 +40,36 @@ ****************************************************************************/ /*! - \module QtHelp - \title QtHelp Module - \contentspage Qt's Modules - \previouspage QtUiTools - \nextpage QtAssistant - \ingroup modules + \group helpsystem + \title Help System + \ingroup groups - \brief The QtHelp module provides classes for integrating - online documentation in applications. + \brief Classes used to provide online-help for applications. - To include the definitions of the module's classes, use the - following directive: + \keyword help system - \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 0 + These classes provide for all forms of online-help in your application, + with three levels of detail: - To link against the module, add this line to your \l qmake \c - .pro file: + \list 1 + \o Tool Tips and Status Bar message - flyweight help, extremely brief, + entirely integrated in the user interface, requiring little + or no user interaction to invoke. + \o What's This? - lightweight, but can be + a three-paragraph explanation. + \o Online Help - can encompass any amount of information, + but is typically slower to call up, somewhat separated + from the user's work, and often users feel that using online + help is a digression from their real task. + \endlist - \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 1 +*/ - \note These classes are part of the \l{Open Source Versions of Qt} and - \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial - users. +/*! + \page qthelp-framework.html + \title The Qt Help Framework + \brief Integrating Documentation in Applications + \ingroup frameworks-technologies \section1 Topics @@ -229,41 +236,6 @@ For further information on how to use the API, have a look at the QHelpEngine class reference. - - \section1 License Information - - The QtHelp module uses the CLucene indexing library to provide full-text - searching capabilities for Qt Assistant and applications that use the - features of QtHelp. - - Qt Commercial Edition licensees that wish to distribute applications that - use these features of the QtHelp module need to be aware of their - obligations under the GNU Lesser General Public License (LGPL). - - Developers using the Open Source Edition can choose to redistribute - the module under the appropriate version of the GNU LGPL; version 2.1 - for applications and libraries licensed under the GNU GPL version 2, - or version 3 for applications and libraries licensed under the GNU - GPL version 3. - - \legalese - Copyright (C) 2003-2006 Ben van Klinken and the CLucene Team \BR - Changes are Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). - - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - 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 - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - \endlegalese */ /*! diff --git a/doc/src/frameworks-technologies/qundo.qdoc b/doc/src/frameworks-technologies/qundo.qdoc new file mode 100644 index 0000000..7b6cae7 --- /dev/null +++ b/doc/src/frameworks-technologies/qundo.qdoc @@ -0,0 +1,113 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qundo.html + \title Overview of Qt's Undo Framework + \keyword Undo framework + \ingroup frameworks-technologies + + \section1 Introduction + + Qt's Undo Framework is an implementation of the Command pattern, for + implementing undo/redo functionality in applications. + + The Command pattern is based on the idea that all editing in + an application is done by creating instances of command objects. + Command objects apply changes to the document and are stored + on a command stack. Furthermore, each command knows how to undo its + changes to bring the document back to its previous state. As long + as the application only uses command objects to change the state of + the document, it is possible to undo a sequence of commands by + traversing the stack downwards and calling undo + on each command in turn. It is also possible to redo a sequence of + commands by traversing the stack upwards and calling + redo on each command. + + \section1 Classes + + The framework consists of four classes: + + \list + \i \l QUndoCommand is the base class of all commands stored on an + undo stack. It can apply (redo) or undo a single change in the document. + \i \l QUndoStack is a list of QUndoCommand objects. It contains all the + commands executed on the document and can roll the document's state + backwards or forwards by undoing or redoing them. + \i \l QUndoGroup is a group of undo stacks. It is useful when an application + contains more than one undo stack, typically one for each opened + document. QUndoGroup provides a single pair of undo/redo slots for all + the stacks in the group. It forwards undo and redo requests to + the active stack, which is the stack associated with the document that + is currently being edited by the user. + \i \l QUndoView is a widget which shows the contents of an undo stack. Clicking + on a command in the view rolls the document's state backwards or + forwards to that command. + \endlist + + \section1 Concepts + + The following concepts are supported by the framework: + + \list + \i \bold{Clean state:} Used to signal when the document enters and leaves a + state that has been saved to disk. This is typically used to disable or + enable the save actions, and to update the document's title bar. + \i \bold{Command compression:} Used to compress sequences of commands into a + single command. + For example: In a text editor, the commands that insert individual + characters into the document can be compressed into a single command that + inserts whole sections of text. These bigger changes are more convenient + for the user to undo and redo. + \i \bold{Command macros:} A sequence of commands, all of which are undone or + redone in one step. + These simplify the task of writing an application, since a set of simpler + commands can be composed into more complex commands. For example, a command + that moves a set of selected objects in a document can be created by + combining a set of commands, each of which moves a single object. + \endlist + + QUndoStack provides convenient undo and redo QAction objects that + can be inserted into a menu or a toolbar. The text properties of these + actions always reflect what command will be undone or redone when + they are triggered. Similarly, QUndoGroup provides undo and redo actions + that always behave like the undo and redo actions of the active stack. +*/ diff --git a/doc/src/frameworks-technologies/richtext.qdoc b/doc/src/frameworks-technologies/richtext.qdoc new file mode 100644 index 0000000..7125b81 --- /dev/null +++ b/doc/src/frameworks-technologies/richtext.qdoc @@ -0,0 +1,1226 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group richtext-processing + \title Rich Text Processing APIs +*/ + +/*! + \page richtext.html + \title Rich Text Processing + \brief An overview of Qt's rich text processing, editing and display features. + + \ingroup frameworks-technologies + + \nextpage Rich Text Document Structure + + The Scribe framework provides a set of classes for reading and manipulating + structured rich text documents. Unlike previous rich text support in Qt, the + new classes are centered around the QTextDocument class rather than raw + textual information. This enables the developer to create and modify + structured rich text documents without having to prepare content in an + intermediate markup format. + + The information within a document can be accessed via two complementary + interfaces: A cursor-based interface is used for editing, and a read-only + hierarchical interface provides a high level overview of the document + structure. The main advantage of the cursor-based interface is that the + text can be edited using operations that mimic a user's interaction with + an editor, without losing the underlying structure of the document. The + read-only hierarchical interface is most useful when performing operations + such as searching and document export. + + This document is divided up into chapters for convenient reference: + + \list + \i \l{Rich Text Document Structure} outlines + the different kinds of elements in a QTextDocument, and describes how + they are arranged in a document structure. + \i \l{The QTextCursor Interface} explains how rich + text documents can be edited using the cursor-based interface. + \i \l{Document Layouts} briefly explains the role of document layouts. + \i \l{Common Rich Text Editing Tasks} examines some + common tasks that involve reading or manipulating rich text documents. + \i \l{Advanced Rich Text Processing} examines advanced rich text editing tasks. + \i \l{Supported HTML Subset} lists the HTML tags supported by QTextDocument. + \endlist + + \section1 Rich Text Processing APIs + + Qt provides an extensive collection of classes for parsing, rendering + manipulating and editing rich text. + + \annotatedlist richtext-processing +*/ + +/*! + \page richtext-structure.html + \contentspage richtext.html Contents + \previouspage Rich Text Processing + \nextpage The QTextCursor Interface + + \title Rich Text Document Structure + + \tableofcontents + + Text documents are represented by the QTextDocument class, which + contains information about the document's internal representation, its + structure, and keeps track of modifications to provide undo/redo + facilities. + + The structured representation of a text document presents its contents as + a hierarchy of text blocks, frames, tables, and other objects. These provide + a logical structure to the document and describe how their contents will be + displayed. Generally, frames and tables are used to group other + structures while text blocks contain the actual textual information. + + New elements are created and inserted into the document programmatically + \l{richtext-cursor.html}{with a QTextCursor} or by using an editor + widget, such as QTextEdit. Elements can be given a particular format when + they are created; otherwise they take the cursor's current format for the + element. + + \table + \row + \i \inlineimage richtext-document.png + \i \bold{Basic structure} + + The "top level" of a document might be populated in the way shown. + Each document always contains a root frame, and this always contains + at least one text block. + + For documents with some textual content, the root + frame usually contains a sequence of blocks and other elements. + + Sequences of frames and tables are always separated by text blocks in a + document, even if the text blocks contain no information. This ensures that + new elements can always be inserted between existing structures. + \endtable + + In this chapter, we look at each of the structural elements + used in a rich text document, outline their features and uses, and show + how to examine their contents. Document editing is described in + \l{richtext-cursor.html}{The QTextCursor Interface}. + + \section1 Rich Text Documents + + QTextDocument objects contain all the information required to construct + rich text documents. + Text documents can be accessed in two complementary ways: as a linear + buffer for editors to use, and as an object hierarchy that is useful to + layout engines. + In the hierarchical document model, objects generally correspond to + visual elements such as frames, tables, and lists. At a lower level, + these elements describe properties such as the text style and alignment. + The linear representation of the document is used for editing and + manipulation of the document's contents. + + Although QTextEdit makes it easy to display and edit rich text, documents + can also be used independently of any editor widget, for example: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 0 + + Alternatively, they can be extracted from an existing editor: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 1 + + This flexibility enables applications to handle multiple rich text + documents without the overhead of multiple editor widgets, or requiring + documents to be stored in some intermediate format. + + An empty document contains a root frame which itself contains a single + empty text block. Frames provide logical separation between parts of the document, but + also have properties that determine how they will appear when rendered. + A table is a specialized type of frame that consists of a number of + cells, arranged into rows and columns, each of which can contain + further structure and text. Tables provide management and layout + features that allow flexible configurations of cells to be created. + + Text blocks contain text fragments, each of which specifies text and + character format information. Textual properties are defined both at + the character level and at the block level. At the character level, + properties such as font family, text color, and font weight can be + specified. The block level properties control the higher level + appearance and behavior of the text, such as the direction of text + flow, alignment, and background color. + + The document structure is not manipulated directly. Editing is + performed through a cursor-based interface. + The \l{richtext-cursor.html}{text cursor interface} + automatically inserts new document elements into the root frame, and + ensures that it is padded with empty blocks where necessary. + + We obtain the root frame in the following manner: + + \snippet doc/src/snippets/textdocument-frames/xmlwriter.h 0 + \snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 0 + + When navigating the document structure, it is useful to begin at the + root frame because it provides access to the entire document structure. + + + \section1 Document Elements + + Rich text documents usually consist of common elements such as paragraphs, + frames, tables, and lists. These are represented in a QTextDocument + by the QTextBlock, QTextFrame, QTextTable, and QTextList classes. + Unlike the other elements in a document, images are represented by + specially formatted text fragments. This enables them to be placed + formatted inline with the surrounding text. + + The basic structural building blocks in documents are QTextBlock and + QTextFrame. Blocks themselves contain fragments of rich text + (QTextFragment), but these do not directly influence the high level + structure of a document. + + Elements which can group together other document elements are typically + subclasses of QTextObject, and fall into two categories: Elements that + group together text blocks are subclasses of QTextBlockGroup, and those + that group together frames and other elements are subclasses of QTextFrame. + + \section2 Text Blocks + + Text blocks are provided by the QTextBlock class. + + Text blocks group together fragments of text with different character formats, + and are used to represent paragraphs in the document. Each block + typically contains a number of text fragments with different styles. + Fragments are created when text is inserted into the document, and more + of them are added when the document is edited. The document splits, merges, + and removes fragments to efficiently represent the different styles + of text in the block. + + The fragments within a given block can be examined by using a + QTextBlock::iterator to traverse the block's internal structure: + + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 3 + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 5 + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 6 + + Blocks are also used to represent list items. As a result, blocks can + define their own character formats which contain information about + block-level decoration, such as the type of bullet points used for + list items. The formatting for the block itself is described by the + QTextBlockFormat class, and describes properties such as text alignment, + indentation, and background color. + + Although a given document may contain complex structures, once we have a + reference to a valid block in the document, we can navigate between each + of the text blocks in the order in which they were written: + + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 0 + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 1 + \snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 2 + + This method is useful for when you want to extract just the rich text from a + document because it ignores frames, tables, and other types of structure. + + QTextBlock provides comparison operators that make it easier to manipulate + blocks: \l{QTextBlock::operator==()}{operator==()} and + \l{QTextBlock::operator!=()}{operator!=()} are used to test whether two + blocks are the same, and \l{QTextBlock::operator<()}{operator<()} is used + to determine which one occurs first in a document. + + \section2 Frames + + Frames are provided by the QTextFrame class. + + Text frames group together blocks of text and child frames, creating + document structures that are larger than paragraphs. The format of a frame + specifies how it is rendered and positioned on the page. Frames are + either inserted into the text flow, or they float on the left or right + hand side of the page. + Each document contains a root frame that contains all the other document + elements. As a result, all frames except the root frame have a parent + frame. + + Since text blocks are used to separate other document elements, each + frame will always contain at least one text block, and zero or more + child frames. We can inspect the contents of a frame by using a + QTextFrame::iterator to traverse the frame's child elements: + + \snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 1 + \snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 2 + + Note that the iterator selects both frames and blocks, so it is necessary + to check which it is referring to. This allows us to navigate the document + structure on a frame-by-frame basis yet still access text blocks if + required. Both the QTextBlock::iterator and QTextFrame::iterator classes + can be used in complementary ways to extract the required structure from + a document. + + \section2 Tables + + Tables are provided by the QTextTable class. + + Tables are collections of cells that are arranged in rows and columns. + Each table cell is a document element with its own character format, but it + can also contain other elements, such as frames and text blocks. Table cells + are automatically created when the table is constructed, or when extra rows + or columns are added. They can also be moved between tables. + + QTextTable is a subclass of QTextFrame, so tables are treated like frames + in the document structure. For each frame that we encounter in the + document, we can test whether it represents a table, and deal with it in a + different way: + + \snippet doc/src/snippets/textdocument-tables/xmlwriter.cpp 0 + \snippet doc/src/snippets/textdocument-tables/xmlwriter.cpp 1 + + The cells within an existing table can be examined by iterating through + the rows and columns. + + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 9 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 10 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 11 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 12 + + + \section2 Lists + + Lists are provided by the QTextList class. + + Lists are sequences of text blocks that are formatted in the usual way, but + which also provide the standard list decorations such as bullet points and + enumerated items. Lists can be nested, and will be indented if the list's + format specifies a non-zero indentation. + + We can refer to each list item by its index in the list: + + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 0 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 1 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 2 + + Since QTextList is a subclass of QTextBlockGroup, it does not group the + list items as child elements, but instead provides various functions for + managing them. This means that any text block we find when traversing a + document may actually be a list item. We can ensure that list items are + correctly identified by using the following code: + + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 3 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 4 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 5 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 6 + \snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 7 + + + \section2 Images + + Images in QTextDocument are represented by text fragments that reference + external images via the resource mechanism. Images are created using the + cursor interface, and can be modified later by changing the character + format of the image's text fragment: + + \snippet doc/src/snippets/textdocument-imageformat/main.cpp 0 + \snippet doc/src/snippets/textdocument-imageformat/main.cpp 1 + \snippet doc/src/snippets/textdocument-imageformat/main.cpp 2 + + The fragment that represents the image can be found by iterating over + the fragments in the text block that contains the image. +*/ + +/*! + \page richtext-cursor.html + \contentspage richtext.html Contents + \previouspage Rich Text Document Structure + \nextpage Document Layouts + + \title The QTextCursor Interface + + \tableofcontents + + Documents can be edited via the interface provided by the QTextCursor + class; cursors are either created using a constructor or obtained from + an editor widget. The cursor is used to perform editing operations that + correspond exactly to those the user is able to make themselves in an + editor. As a result, information about the document structure is also + available through the cursor, and this allows the structure to be + modified. The use of a cursor-oriented interface for editing makes the + process of writing a custom editor simpler for developers, since the + editing operations can be easily visualized. + + The QTextCursor class also maintains information about any text it + has selected in the document, again following a model that is + conceptually similar to the actions made by the user to select text + in an editor. + + Rich text documents can have multiple cursors + associated with them, and each of these contains information about their + position in the document and any selections that they may hold. This + cursor-based paradigm makes common operations, such as cutting and pasting + text, simple to implement programmatically, yet it also allows more complex + editing operations to be performed on the document. + + This chapter describes most of the common editing operations that you + will need to perform using a cursor, from basic insertion of text and + document elements to more complex manipulation of document structures. + + \section1 Cursor-Based Editing + + At the simplest level, text documents are made up of a string of characters, + marked up in some way to represent the block structure of the text within the + document. QTextCursor provides a cursor-based interface that allows the + contents of a QTextDocument to be manipulated at the character level. Since + the elements (blocks, frames, tables, etc.) are also encoded in the character + stream, the document structure can itself be changed by the cursor. + + The cursor keeps track of its location within its parent document, and can + report information about the surrounding structure, such as the enclosing + text block, frame, table, or list. The formats of the enclosing structures + can also be directly obtained through the cursor. + + \section2 Using a Cursor + + The main use of a cursor is to insert or modify text within a block. + We can use a text editor's cursor to do this: + + \snippet doc/src/snippets/textblock-formats/main.cpp 0 + + Alternatively, we can obtain a cursor directly from a document: + + \snippet doc/src/snippets/textdocument-images/main.cpp 0 + + The cursor is positioned at the start of the document so that we can write + into the first (empty) block in the document. + + \section2 Grouping Cursor Operations + + A series of editing operations can be packaged together so that they can + be replayed, or undone together in a single action. This is achieved by + using the \c beginEditBlock() and \c endEditBlock() functions in the + following way, as in the following example where we select the word that + contains the cursor: + + \snippet doc/src/snippets/textdocument-selections/mainwindow.cpp 0 + + If editing operations are not grouped, the document automatically records + the individual operations so that they can be undone later. Grouping + operations into larger packages can make editing more efficient both for + the user and for the application, but care has to be taken not to group too + many operations together as the user may want find-grained control over the + undo process. + + \section2 Multiple Cursors + + Multiple cursors can be used to simultaneously edit the same document, + although only one will be visible to the user in a QTextEdit widget. + The QTextDocument ensures that each cursor writes text correctly and + does not interfere with any of the others. + + \omit + \snippet doc/src/snippets/textdocument-cursors/main.cpp 0 + \snippet doc/src/snippets/textdocument-cursors/main.cpp 1 + \endomit + + \section1 Inserting Document Elements + + QTextCursor provides several functions that can be used to change the + structure of a rich text document. Generally, these functions allow + document elements to be created with relevant formatting information, + and they are inserted into the document at the cursor's position. + + The first group of functions insert block-level elements, and update the + cursor position, but they do not return the element that was inserted: + + \list + \i \l{QTextCursor::insertBlock()}{insertBlock()} inserts a new text block + (paragraph) into a document at the cursor's position, and moves the + cursor to the start of the new block. + \i \l{QTextCursor::insertFragment()}{insertFragment()} inserts an existing + text fragment into a document at the cursor's position. + \i \l{QTextCursor::insertImage()}{insertImage()} inserts an image into a + document at the cursor's position. + \i \l{QTextCursor::insertText()}{insertText()} inserts text into the + document at the cursor's position. + \endlist + + You can examine the contents of the element that was inserted through the + cursor interface. + + The second group of functions insert elements that provide structure to + the document, and return the structure that was inserted: + + \list + \i \l{QTextCursor::insertFrame()}{insertFrame()} inserts a frame into the + document \e after the cursor's current block, and moves the cursor to + the start of the empty block in the new frame. + \i \l{QTextCursor::insertList()}{insertList()} inserts a list into the + document at the cursor's position, and moves the cursor to the start + of the first item in the list. + \i \l{QTextCursor::insertTable()}{insertTable()} inserts a table into + the document \e after the cursor's current block, and moves the cursor + to the start of the block following the table. + \endlist + + These elements either contain or group together other elements in the + document. + + \section2 Text and Text Fragments + + Text can be inserted into the current block in the current character + format, or in a custom format that is specified with the text: + + \snippet doc/src/snippets/textdocument-charformats/main.cpp 0 + + Once the character format has been used with a cursor, that format becomes + the default format for any text inserted with that cursor until another + character format is specified. + + If a cursor is used to insert text without specifying a character format, + the text will be given the character format used at that position in the + document. + + \section2 Blocks + + Text blocks are inserted into the document with the + \l{QTextCursor::insertBlock()}{insertBlock()} function. + + \snippet doc/src/snippets/textblock-formats/main.cpp 1 + + The cursor is positioned at the start of the new block. + + \section2 Frames + + Frames are inserted into a document using the cursor, and will be placed + within the cursor's current frame \e after the current block. + The following code shows how a frame can be inserted between two text + blocks in a document's root frame. We begin by finding the cursor's + current frame: + + \snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 0 + + We insert some text in this frame then set up a frame format for the + child frame: + + \snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 1 + + The frame format will give the frame an external margin of 32 pixels, + internal padding of 8 pixels, and a border that is 4 pixels wide. + See the QTextFrameFormat documentation for more information about + frame formats. + + The frame is inserted into the document after the preceding text: + + \snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 2 + + We add some text to the document immediately after we insert the frame. + Since the text cursor is positioned \e{inside the frame} when it is inserted + into the document, this text will also be inserted inside the frame. + + Finally, we position the cursor outside the frame by taking the last + available cursor position inside the frame we recorded earlier: + + \snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 3 + + The text that we add last is inserted after the child frame in the + document. Since each frame is padded with text blocks, this ensures that + more elements can always be inserted with a cursor. + + \section2 Tables + + Tables are inserted into the document using the cursor, and will be + placed within the cursor's current frame \e after the current block: + + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 0 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 3 + + Tables can be created with a specific format that defines the overall + properties of the table, such as its alignment, background color, and + the cell spacing used. It can also determine the constraints on each + column, allowing each of them to have a fixed width, or resize according + to the available space. + + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 2 + + The columns in the table created above will each take up a certain + percentage of the available width. Note that the table format is + optional; if you insert a table without a format, some sensible + default values will be used for the table's properties. + + Since cells can contain other document elements, they too can be + formatted and styled as necessary. + + Text can be added to the table by navigating to each cell with the cursor + and inserting text. + + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 4 + + We can create a simple timetable by following this approach: + + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 5 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 6 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 7 + \snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 8 + + \section2 Lists + + Lists of block elements can be automatically created and inserted into the + document at the current cursor position. Each list that is created in this + way requires a list format to be specified: + + \snippet doc/src/snippets/textdocument-lists/mainwindow.cpp 0 + + The above code first checks whether the cursor is within an existing list + and, if so, gives the list format for the new list a suitable level of + indentation. This allows nested lists to be created with increasing + levels of indentation. A more sophisticated implementation would also use + different kinds of symbol for the bullet points in each level of the list. + + \section2 Images + + Inline images are added to documents through the cursor in the usual manner. + Unlike many other elements, all of the image properties are specified by the + image's format. This means that a QTextImageFormat object has to be + created before an image can be inserted: + + \snippet doc/src/snippets/textdocument-images/main.cpp 1 + + The image name refers to an entry in the application's resource file. + The method used to derive this name is described in + \l{resources.html}{The Qt Resource System}. + + \section1 Examples + + Rich text is stored in text documents that can either be created by + importing HTML from an external source, or generated using a QTextCursor. + + \section2 Manipulating Rich Text + + The easiest way to use a rich text document is through + the QTextEdit class, providing an editable view onto a document. The code + below imports HTML into a document, and displays the document using a + text edit widget. + + \snippet doc/src/snippets/scribe-overview/main.cpp 1 + + You can retrieve the document from the text edit using the + document() function. The document can then be edited programmatically + using the QTextCursor class. This class is modeled after a screen + cursor, and editing operations follow the same semantics. The following + code changes the first line of the document to a bold font, leaving all + other font properties untouched. The editor will be automatically + updated to reflect the changes made to the underlying document data. + + \snippet doc/src/snippets/scribe-overview/main.cpp 0 + + Note that the cursor was moved from the start of the first line to the + end, but that it retained an anchor at the start of the line. This + demonstrates the cursor-based selection facilities of the + QTextCursor class. + + \section2 Generating a Calendar + + Rich text can be generated very quickly using the cursor-based + approach. The following example shows a simple calendar in a + QTextEdit widget with bold headers for the days of the week: + + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 0 + \codeline + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 1 + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 2 + \snippet doc/src/snippets/textdocument-blocks/mainwindow.cpp 3 + + The above example demonstrates how simple it is to quickly generate new + rich text documents using a minimum amount of code. Although we have + generated a crude fixed-pitch calendar to avoid quoting too much code, + Scribe provides much more sophisticated layout and formatting features. +*/ + +/*! + \page richtext-layouts.html + \contentspage richtext.html Contents + \previouspage The QTextCursor Interface + \nextpage Common Rich Text Editing Tasks + + \title Document Layouts + + \tableofcontents + + The layout of a document is only relevant when it is to be displayed on + a device, or when some information is requested that requires a visual + representation of the document. Until this occurs, the document does + not need to be formatted and prepared for a device. + + \section1 Overview + + Each document's layout is managed by a subclass of the + QAbstractTextDocumentLayout class. This class provides a common + interface for layout and rendering engines. The default rendering + behavior is currently implemented in a private class. This approach + makes it possible to create custom layouts, and provides the + mechanism used when preparing pages for printing or exporting to + Portable Document Format (PDF) files. + + \section1 Example - Shaped Text Layout + + Sometimes it is important to be able to format plain text within an + irregularly-shaped region, perhaps when rendering a custom widget, for + example. Scribe provides generic features, such as those provided by + the QTextLayout class, to help developers perform word-wrapping and + layout tasks without the need to create a document first. + + \img plaintext-layout.png + + Formatting and drawing a paragraph of plain text is straightforward. + The example below will lay out a paragraph of text, using a single + font, around the right hand edge of a circle. + + \snippet doc/src/snippets/plaintextlayout/window.cpp 0 + + We create a text layout, specifying the text string we want to display + and the font to use. We ensure that the text we supplied is formatted + correctly by obtaining text lines from the text format, and wrapping + the remaining text using the available space. The lines are positioned + as we move down the page. + + The formatted text can be drawn onto a paint device; in the above code, + the text is drawn directly onto a widget. + */ + + /*! + \page richtext-common-tasks.html + \contentspage richtext.html Contents + \previouspage Document Layouts + \nextpage Advanced Rich Text Processing + + \title Common Rich Text Editing Tasks + + \tableofcontents + + There are a number of tasks that are often performed by developers + when editing and processing text documents using Qt. These include the use + of display widgets such as QTextBrowser and QTextEdit, creation of + documents with QTextDocument, editing using a QTextCursor, and + exporting the document structure. + This document outlines some of the more common ways of using the rich + text classes to perform these tasks, showing convenient patterns that can + be reused in your own applications. + + \section1 Using QTextEdit + + A text editor widget can be constructed and used to display HTML in the + following way: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 2 + + By default, the text editor contains a document with a root frame, inside + which is an empty text block. This document can be obtained so that it can + be modified directly by the application: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 3 + + The text editor's cursor may also be used to edit a document: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 4 + + Although a document can be edited using many cursors at once, a QTextEdit + only displays a single cursor at a time. Therefore, if we want to update the + editor to display a particular cursor or its selection, we need to set the + editor's cursor after we have modified the document: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 5 + + \section1 Selecting Text + + Text is selected by moving the cursor using operations that are similar to + those performed by a user in a text editor. To select text between two + points in the document, we need to position the cursor at the first point + then move it using a special mode (\l{QTextCursor::MoveMode}) with a + move operation (\l{QTextCursor::MoveOperation}). + When we select the text, we leave the selection anchor at the old cursor + position just as the user might do by holding down the Shift key when + selecting text: + + \snippet doc/src/snippets/textdocument-selections/mainwindow.cpp 1 + + In the above code, a whole word is selected using this method. QTextCursor + provides a number of common move operations for selecting individual + characters, words, lines, and whole blocks. + + \section1 Finding Text + + QTextDocument provides a cursor-based interface for searching, making + it easy to find and modify text in the style of a text editor. The following + code finds all the instances of a particular word in a document, and changes + the color of each: + + \snippet doc/src/snippets/textdocument-find/main.cpp 0 + \snippet doc/src/snippets/textdocument-find/main.cpp 1 + + Note that the cursor does not have to be moved after each search and replace + operation; it is always positioned at the end of the word that was just + replaced. + + \section1 Printing Documents + + QTextEdit is designed for the display of large rich text documents that are + read on screen, rendering them in the same way as a web browser. As a result, + it does not automatically break the contents of the document into page-sized + pieces that are suitable for printing. + + QTextDocument provides a \l{QTextDocument::print()}{print()} function to + allow documents to be printed using the QPrinter class. The following code + shows how to prepare a document in a QTextEdit for printing with a QPrinter: + + \snippet doc/src/snippets/textdocument-printing/mainwindow.cpp 0 + + The document is obtained from the text editor, and a QPrinter is constructed + then configured using a QPrintDialog. If the user accepts the printer's + configuration then the document is formatted and printed using the + \l{QTextDocument::print()}{print()} function. +*/ + +/*! + \page richtext-advanced-processing.html + \contentspage richtext.html Contents + \previouspage Common Rich Text Editing Tasks + \nextpage Supported HTML Subset + + \title Advanced Rich Text Processing + + \section1 Handling Large Files + + Qt does not limit the size of files that are used for text + processing. In most cases, this will not present a problem. For + especially large files, however, you might experience that your + application will become unresponsive or that you will run out of + memory. The size of the files you can load depends on your + hardware and on Qt's and your own application's implementation. + + If you are faced with this problem, we recommend that you address the + following issues: + + \list + \o You should consider breaking up large paragraphs into smaller + ones as Qt handles small paragraphs better. You could also + insert line breaks at regular intervals, which will look the + same as one large paragraph in a QTextEdit. + \o You can reduce the amount of blocks in a QTextDocument with + \l{QTextDocument::}{maximumBlockCount()}. The document is only + as large as the number of blocks as far as QTextEdit is concerned. + \o When adding text to a text edit, it is an advantage to add it + in an edit block (see example below). The result is that the + text edit does not need to build the entire document structure at once. + \endlist + + We give an example of the latter technique from the list. We assume that + the text edit is visible. + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 6 + + \omit + Ideas for other sections: + + * Hiding QTextBlock elements. + * Changing the word wrapping mode in QTextEdit. Custom word wrapping? + \endomit +*/ + +/*! + \page richtext-html-subset.html + \title Supported HTML Subset + \brief Describes the support for HTML markup in text widgets. + + \contentspage richtext.html Contents + \previouspage Common Rich Text Editing Tasks + + Qt's text widgets are able to display rich text, specified using a subset of \l{HTML 4} + markup. Widgets that use QTextDocument, such as QLabel and QTextEdit, are able to display + rich text specified in this way. + + \tableofcontents + + \section1 Using HTML Markup in Text Widgets + + Widgets automatically detect HTML markup and display rich text accordingly. For example, + setting a label's \l{QLabel::}{text} property with the string \c{"<b>Hello</b> <i>Qt!</i>"} + will result in the label displaying text like this: \bold{Hello} \e{Qt!} + + When HTML markup is used for text, Qt follows the rules defined by the \l{HTML 4} + specification. This includes default properties for text layout, such as the + direction of the text flow (left-to-right) which can be changed by applying the + \l{#Block Attributes}{\c dir} attribute to blocks of text. + + \section1 Supported Tags + + The following table lists the HTML tags supported by Qt's + \l{Rich Text Processing}{rich text} engine: + + \table + \header \o Tag + \o Description + \o Comment + \row \o \c a + \o Anchor or link + \o Supports the \c href and \c name attributes. + \row \o \c address + \o Address + \o + \row \o \c b + \o Bold + \o + \row \o \c big + \o Larger font + \o + \row \o \c blockquote + \o Indented paragraph + \o + \row \o \c body + \o Document body + \o Supports the \c bgcolor attribute, which + can be a Qt \l{QColor::setNamedColor()}{color name} + or a \c #RRGGBB color specification. + \row \o \c br + \o Line break + \o + \row \o \c center + \o Centered paragraph + \o + \row \o \c cite + \o Inline citation + \o Same as \c i. + \row \o \c code + \o Code + \o Same as \c tt. + \row \o \c dd + \o Definition data + \o + \row \o \c dfn + \o Definition + \o Same as \c i. + \row \o \c div + \o Document division + \o Supports the standard \l{block attributes}. + \row \o \c dl + \o Definition list + \o Supports the standard \l{block attributes}. + \row \o \c dt + \o Definition term + \o Supports the standard \l{block attributes}. + \row \o \c em + \o Emphasized + \o Same as \c i. + \row \o \c font + \o Font size, family, and/or color + \o Supports the following attributes: + \c size, \c face, and \c color (Qt + \l{QColor::setNamedColor()}{color names} or + \c #RRGGBB). + \row \o \c h1 + \o Level 1 heading + \o Supports the standard \l{block attributes}. + \row \o \c h2 + \o Level 2 heading + \o Supports the standard \l{block attributes}. + \row \o \c h3 + \o Level 3 heading + \o Supports the standard \l{block attributes}. + \row \o \c h4 + \o Level 4 heading + \o Supports the standard \l{block attributes}. + \row \o \c h5 + \o Level 5 heading + \o Supports the standard \l{block attributes}. + \row \o \c h6 + \o Level 6 heading + \o Supports the standard \l{block attributes}. + \row \o \c head + \o Document header + \o + \row \o \c hr + \o Horizontal line + \o Supports the \c width attribute, which can + be specified as an absolute or relative (\c %) value. + \row \o \c html + \o HTML document + \o + \row \o \c i + \o Italic + \o + \row \o \c img + \o Image + \o Supports the \c src, \c source + (for Qt 3 compatibility), \c width, and \c height + attributes. + \row \o \c kbd + \o User-entered text + \o + \row \o \c meta + \o Meta-information + \o If a text encoding is specified using the \c{meta} tag, + it is picked up by Qt::codecForHtml(). + Likewise, if an encoding is specified to + QTextDocument::toHtml(), the encoding is stored using + a \c meta tag, for example: + + \snippet doc/src/snippets/code/doc_src_richtext.qdoc 7 + + \row \o \c li + \o List item + \o + \row \o \c nobr + \o Non-breakable text + \o + \row \o \c ol + \o Ordered list + \o Supports the standard \l{list attributes}. + \row \o \c p + \o Paragraph + \o Left-aligned by default. Supports the standard + \l{block attributes}. + \row \o \c pre + \o Preformated text + \o + \row \o \c qt + \o Qt rich-text document + \o Synonym for \c html. Provided for compatibility with + earlier versions of Qt. + \row \o \c s + \o Strikethrough + \o + \row \o \c samp + \o Sample code + \o Same as \c tt. + \row \o \c small + \o Small font + \o + \row \o \c span + \o Grouped elements + \o + \row \o \c strong + \o Strong + \o Same as \c b. + \row \o \c sub + \o Subscript + \o + \row \o \c sup + \o Superscript + \o + \row \o \c table + \o Table + \o Supports the following attributes: \c border, + \c bgcolor (Qt \l{QColor::setNamedColor()}{color names} + or \c #RRGGBB), \c cellspacing, \c cellpadding, + \c width (absolute or relative), and \c height. + \row \o \c tbody + \o Table body + \o Does nothing. + \row \o \c td + \o Table data cell + \o Supports the standard \l{table cell attributes}. + \row \o \c tfoot + \o Table footer + \o Does nothing. + \row \o \c th + \o Table header cell + \o Supports the standard \l{table cell attributes}. + \row \o \c thead + \o Table header + \o If the \c thead tag is specified, it is used when printing tables + that span multiple pages. + \row \o \c title + \o Document title + \o The value specified using the \c + title tag is available through + QTextDocument::metaInformation(). + \row \o \c tr + \o Table row + \o Supports the \c bgcolor attribute, which + can be a Qt \l{QColor::setNamedColor()}{color name} + or a \c #RRGGBB color specification. + \row \o \c tt + \o Typewrite font + \o + \row \o \c u + \o Underlined + \o + \row \o \c ul + \o Unordered list + \o Supports the standard \l{list attributes}. + \row \o \c var + \o Variable + \o Same as \c i. + \endtable + + \section1 Block Attributes + + The following attributes are supported by the \c div, \c dl, \c + dt, \c h1, \c h2, \c h3, \c h4, \c h5, \c h6, \c p tags: + + \list + \o \c align (\c left, \c right, \c center, \c justify) + \o \c dir (\c ltr, \c rtl) + \endlist + + \section1 List Attributes + + The following attribute is supported by the \c ol and \c ul tags: + + \list + \o \c type (\c 1, \c a, \c A, \c square, \c disc, \c circle) + \endlist + + \section1 Table Cell Attributes + + The following attributes are supported by the \c td and \c th + tags: + + \list + \o \c width (absolute, relative, or no-value) + \o \c bgcolor (Qt \l{QColor::setNamedColor()}{color names} or \c #RRGGBB) + \o \c colspan + \o \c rowspan + \o \c align (\c left, \c right, \c center, \c justify) + \o \c valign (\c top, \c middle, \c bottom) + \endlist + + \section1 CSS Properties + The following table lists the CSS properties supported by Qt's + \l{Rich Text Processing}{rich text} engine: + + \table + \header \o Property + \o Values + \o Description + \row + \o \c background-color + \o <color> + \o Background color for elements + \row + \o \c background-image + \o <uri> + \o Background image for elements + \row \o \c color + \o <color> + \o Text foreground color + \row \o \c font-family + \o <family name> + \o Font family name + \row \o \c font-size + \o [ small | medium | large | x-large | xx-large ] | <size>pt | <size>px + \o Font size relative to the document font, or specified in points or pixels + \row \o \c font-style + \o [ normal | italic | oblique ] + \o + \row \o \c font-weight + \o [ normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 ] + \o Specifies the font weight used for text, where \c normal and \c bold + are mapped to the corresponding QFont weights. Numeric values are + 8 times the equivalent QFont weight values. + \row \o \c text-decoration + \o none | [ underline || overline || line-through ] + \o Additional text effects + \row \o \c font + \o [ [ <'font-style'> || <'font-weight'> ]? <'font-size'> <'font-family'> ] + \o Font shorthand property + \row \o \c text-indent + \o <length>px + \o First line text indentation in pixels + \row \o \c white-space + \o normal | pre | nowrap | pre-wrap + \o Declares how whitespace in HTML is handled. + \row \o \c margin-top + \o <length>px + \o Top paragraph margin in pixels + \row \o \c margin-bottom + \o <length>px + \o Bottom paragraph margin in pixels + \row \o \c margin-left + \o <length>px + \o Left paragraph margin in pixels + \row \o \c margin-right + \o <length>px + \o Right paragraph margin in pixels + \row \o \c padding-top + \o <length>px + \o Top table cell padding in pixels + \row \o \c padding-bottom + \o <length>px + \o Bottom table cell padding in pixels + \row \o \c padding-left + \o <length>px + \o Left table cell padding in pixels + \row \o \c padding-right + \o <length>px + \o Right table cell padding in pixels + \row \o \c padding + \o <length>px + \o Shorthand for setting all the padding properties at once. + \row \o \c vertical-align + \o baseline | sub | super | middle | top | bottom + \o Vertical text alignment. For vertical alignment in text table cells only middle, top, and bottom apply. + \row \o \c border-color + \o <color> + \o Border color for text tables. + \row \o \c border-style + \o none | dotted | dashed | dot-dash | dot-dot-dash | solid | double | groove | ridge | inset | outset + \o Border style for text tables. + \row \o \c background + \o [ <'background-color'> || <'background-image'> ] + \o Background shorthand property + \row \o \c page-break-before + \o [ auto | always ] + \o Make it possible to enforce a page break before the paragraph/table + \row \o \c page-break-after + \o [ auto | always ] + \o Make it possible to enforce a page break after the paragraph/table + \row \o float + \o [ left | right | none ] + \o Specifies where an image or a text will be placed in another element. Note that the \c float property is + only supported for tables and images. + \row \o \c text-transform + \o [ uppercase | lowercase ] + \o Select the transformation that will be performed on the text prior to displaying it. + \row \o \c font-variant + \o small-caps + \o Perform the smallcaps transformation on the text prior to displaying it. + \row \o \c word-spacing + \o <width>px + \o Specifies an alternate spacing between each word. + \endtable + + \section1 Supported CSS Selectors + + All CSS 2.1 selector classes are supported except pseudo-class selectors such + as \c{:first-child}, \c{:visited} and \c{:hover}. + +*/ diff --git a/doc/src/statemachine.qdoc b/doc/src/frameworks-technologies/statemachine.qdoc index f479c77..3513199 100644 --- a/doc/src/statemachine.qdoc +++ b/doc/src/frameworks-technologies/statemachine.qdoc @@ -40,10 +40,16 @@ ****************************************************************************/ /*! + \group statemachine + \title State Machine Classes +*/ + +/*! \page statemachine-api.html \title The State Machine Framework \brief An overview of the State Machine framework for constructing and executing state graphs. - \ingroup architecture + + \ingroup frameworks-technologies \tableofcontents @@ -69,6 +75,12 @@ states can be configured to set properties and invoke methods on QObjects. Qt's event system is used to drive the state machines. + \section1 Classes in the State Machine Framework + + These classes are provided by qt for creating event-driven state machines. + + \annotatedlist statemachine + \section1 A Simple State Machine To demonstrate the core functionality of the State Machine API, let's look diff --git a/doc/src/templates.qdoc b/doc/src/frameworks-technologies/templates.qdoc index 4705d09..39d76ee 100644 --- a/doc/src/templates.qdoc +++ b/doc/src/frameworks-technologies/templates.qdoc @@ -42,7 +42,6 @@ /*! \page templates.html \title Why Doesn't Qt Use Templates for Signals and Slots? - \ingroup architecture \brief The reasoning behind Qt's implementation of signals and slots. Templates are a builtin mechanism in C++ that allows the compiler to diff --git a/doc/src/threads.qdoc b/doc/src/frameworks-technologies/threads.qdoc index 351113a..bc65daf 100644 --- a/doc/src/threads.qdoc +++ b/doc/src/frameworks-technologies/threads.qdoc @@ -40,11 +40,19 @@ ****************************************************************************/ /*! + \group thread + \title Threading Classes +*/ + +/*! \page threads.html \title Thread Support in Qt - \ingroup architecture \brief A detailed discussion of thread handling in Qt. + \ingroup frameworks-technologies + + \nextpage Starting Threads with QThread + Qt provides thread support in the form of platform-independent threading classes, a thread-safe way of posting events, and signal-slot connections across threads. This makes it easy to @@ -56,18 +64,39 @@ Earlier versions of Qt offered an option to build the library without thread support. Since Qt 4.0, threads are always enabled. + \section1 Topics: + + \list + \o \l{Recommended Reading} + \o \l{The Threading Classes} + \o \l{Starting Threads with QThread} + \o \l{Synchronizing Threads} + \o \l{Reentrancy and Thread-Safety} + \o \l{Threads and QObjects} + \o \l{Concurrent Programming} + \o \l{Thread-Support in Qt Modules} + \endlist + + \section1 Recommended Reading + This document is intended for an audience that has knowledge of, and experience with, multithreaded applications. If you are new - to threading see our \l{#reading}{Recommended Reading} list. + to threading see our Recommended Reading list: - Topics: - - \tableofcontents + \list + \o \l{Threads Primer: A Guide to Multithreaded Programming} + \o \l{Thread Time: The Multithreaded Programming Guide} + \o \l{Pthreads Programming: A POSIX Standard for Better Multiprocessing} + \o \l{Win32 Multithreaded Programming} + \endlist \section1 The Threading Classes - Qt includes the following thread classes: + These classes are relevant to threaded applications. + + \annotatedlist thread +\omit \list \o QThread provides the means to start a new thread. \o QThreadStorage provides per-thread data storage. @@ -85,12 +114,30 @@ \o QAtomicInt provides atomic operations on integers. \o QAtomicPointer provides atomic operations on pointers. \endlist +\endomit \note Qt's threading classes are implemented with native threading APIs; e.g., Win32 and pthreads. Therefore, they can be used with threads of the same native API. +*/ - \section2 Creating a Thread +/*! + \page threads-starting.html + \title Starting Threads with QThread + + \contentspage Thread Support in Qt + \nextpage Synchronizing Threads + + A QThread instance represents a thread and provides the means to + \l{QThread::start()}{start()} a thread, which will then execute the + reimplementation of QThread::run(). The \c run() implementation is for a + thread what the \c main() entry point is for the application. All code + executed in a call stack that starts in the \c run() function is executed + by the new thread, and the thread finishes when the function returns. + QThread emits signals to indicate that the thread started or finished + executing. + + \section1 Creating a Thread To create a thread, subclass QThread and reimplement its \l{QThread::run()}{run()} function. For example: @@ -102,22 +149,34 @@ \dots \snippet doc/src/snippets/threads/threads.cpp 2 + \section1 Starting a Thread + Then, create an instance of the thread object and call - QThread::start(). The code that appears in the + QThread::start(). Note that you must create the QApplication (or + QCoreApplication) object before you can create a QThread. + + The function will return immediately and the + main thread will continue. The code that appears in the \l{QThread::run()}{run()} reimplementation will then be executed - in a separate thread. Creating threads is explained in more - detail in the QThread documentation. + in a separate thread. + + Creating threads is explained in more detail in the QThread + documentation. Note that QCoreApplication::exec() must always be called from the main thread (the thread that executes \c{main()}), not from a QThread. In GUI applications, the main thread is also called the GUI thread because it's the only thread that is allowed to perform GUI-related operations. +*/ - In addition, you must create the QApplication (or - QCoreApplication) object before you can create a QThread. - - \section2 Synchronizing Threads +/*! + \page threads-synchronizing.html + \title Synchronizing Threads + + \previouspage Starting Threads with QThread + \contentspage Thread Support in Qt + \nextpage Reentrancy and Thread-Safety The QMutex, QReadWriteLock, QSemaphore, and QWaitCondition classes provide means to synchronize threads. While the main idea @@ -162,105 +221,18 @@ Note that Qt's synchronization classes rely on the use of properly aligned pointers. For instance, you cannot use packed classes with MSVC. +*/ - \target qtconcurrent intro - \section1 QtConcurrent - - The QtConcurrent namespace provides high-level APIs that make it - possible to write multi-threaded programs without using low-level - threading primitives such as mutexes, read-write locks, wait - conditions, or semaphores. Programs written with QtConcurrent - automatically adjust the number of threads used according to the - number of processor cores available. This means that applications - written today will continue to scale when deployed on multi-core - systems in the future. - - QtConcurrent includes functional programming style APIs for - parallel list processing, including a MapReduce and FilterReduce - implementation for shared-memory (non-distributed) systems, and - classes for managing asynchronous computations in GUI - applications: - - \list - - \o QtConcurrent::map() applies a function to every item in a container, - modifying the items in-place. - - \o QtConcurrent::mapped() is like map(), except that it returns a new - container with the modifications. - - \o QtConcurrent::mappedReduced() is like mapped(), except that the - modified results are reduced or folded into a single result. - - \o QtConcurrent::filter() removes all items from a container based on the - result of a filter function. - - \o QtConcurrent::filtered() is like filter(), except that it returns a new - container with the filtered results. - - \o QtConcurrent::filteredReduced() is like filtered(), except that the - filtered results are reduced or folded into a single result. - - \o QtConcurrent::run() runs a function in another thread. - - \o QFuture represents the result of an asynchronous computation. - - \o QFutureIterator allows iterating through results available via QFuture. - - \o QFutureWatcher allows monitoring a QFuture using signals-and-slots. - - \o QFutureSynchronizer is a convenience class that automatically - synchronizes several QFutures. - - \endlist - - Qt Concurrent supports several STL-compatible container and iterator types, - but works best with Qt containers that have random-access iterators, such as - QList or QVector. The map and filter functions accept both containers and begin/end iterators. - - STL Iterator support overview: - - \table - \header - \o Iterator Type - \o Example classes - \o Support status - \row - \o Input Iterator - \o - \o Not Supported - \row - \o Output Iterator - \o - \o Not Supported - \row - \o Forward Iterator - \o std::slist - \o Supported - \row - \o Bidirectional Iterator - \o QLinkedList, std::list - \o Supported - \row - \o Random Access Iterator - \o QList, QVector, std::vector - \o Supported and Recommended - \endtable +/*! + \page threads-reentrancy.html + \title Reentrancy and Thread-Safety - Random access iterators can be faster in cases where Qt Concurrent is iterating - over a large number of lightweight items, since they allow skipping to any point - in the container. In addition, using random access iterators allows Qt Concurrent - to provide progress information trough QFuture::progressValue() and QFutureWatcher:: - progressValueChanged(). - - The non in-place modifying functions such as mapped() and filtered() makes a - copy of the container when called. If you are using STL containers this copy operation - might take some time, in this case we recommend specifying the begin and end iterators - for the container instead. - \keyword reentrant \keyword thread-safe - \section1 Reentrancy and Thread-Safety + + \previouspage Synchronizing Threads + \contentspage Thread Support in Qt + \nextpage Threads and QObjects Throughout the documentation, the terms \e{reentrant} and \e{thread-safe} are used to mark classes and functions to indicate @@ -346,8 +318,15 @@ that are somewhat different for its C APIs. When using other object-oriented C++ class libraries with Qt, be sure the definitions are understood. +*/ + +/*! + \page threads-qobject.html + \title Threads and QObjects - \section1 Threads and QObjects + \previouspage Reentrancy and Thread Safety + \contentspage Thread Support in Qt + \nextpage Concurrent Programming QThread inherits QObject. It emits signals to indicate that the thread started or finished executing, and provides a few slots as @@ -358,8 +337,12 @@ post events to objects that "live" in other threads. This is possible because each thread is allowed to have its own event loop. + + Topics: + + \tableofcontents - \section2 QObject Reentrancy + \section1 QObject Reentrancy QObject is reentrant. Most of its non-GUI subclasses, such as QTimer, QTcpSocket, QUdpSocket, QFtp, and QProcess, are also @@ -402,7 +385,7 @@ the \l{network/blockingfortuneclient}{Blocking Fortune Client} example. - \section2 Per-Thread Event Loop + \section1 Per-Thread Event Loop Each thread can have its own event loop. The initial thread starts its event loops using QCoreApplication::exec(); other @@ -463,7 +446,7 @@ be used to dispatch events to objects living in the thread from which the function is called. - \section2 Accessing QObject Subclasses from Other Threads + \section1 Accessing QObject Subclasses from Other Threads QObject and all of its subclasses are not thread-safe. This includes the entire event delivery system. It is important to keep @@ -487,7 +470,7 @@ QThread::run() implementation, because signal emission is thread-safe. - \section2 Signals and Slots Across Threads + \section1 Signals and Slots Across Threads Qt supports three types of signal-slot connections: @@ -529,37 +512,117 @@ Similarly, the \l{network/blockingfortuneclient}{Blocking Fortune Client} example uses a separate thread for communicating with a TCP server asynchronously. +*/ - \section1 Threads and Implicit Sharing +/*! + \page threads-qtconcurrent.html + \title Concurrent Programming - Qt uses an optimization called \l{implicit sharing} for many of - its value class, notably QImage and QString. Beginning with Qt 4, - implicit shared classes can safely be copied across threads, like - any other value classes. They are fully - \l{#reentrant}{reentrant}. The implicit sharing is really - \e implicit. + \previouspage Threads and QObjects + \contentspage Thread Support in Qt + \nextpage Thread-Support in Qt Modules - In many people's minds, implicit sharing and multithreading are - incompatible concepts, because of the way the reference counting - is typically done. Qt, however, uses atomic reference counting to - ensure the integrity of the shared data, avoiding potential - corruption of the reference counter. + \target qtconcurrent intro - Note that atomic reference counting does not guarantee - \l{#thread-safe}{thread-safety}. Proper locking should be used - when sharing an instance of an implicitly shared class between - threads. This is the same requirement placed on all - \l{#reentrant}{reentrant} classes, shared or not. Atomic reference - counting does, however, guarantee that a thread working on its - own, local instance of an implicitly shared class is safe. We - recommend using \l{Signals and Slots Across Threads}{signals and - slots} to pass data between threads, as this can be done without - the need for any explicit locking. + The QtConcurrent namespace provides high-level APIs that make it + possible to write multi-threaded programs without using low-level + threading primitives such as mutexes, read-write locks, wait + conditions, or semaphores. Programs written with QtConcurrent + automatically adjust the number of threads used according to the + number of processor cores available. This means that applications + written today will continue to scale when deployed on multi-core + systems in the future. - To sum it up, implicitly shared classes in Qt 4 are really \e - implicitly shared. Even in multithreaded applications, you can - safely use them as if they were plain, non-shared, reentrant - value-based classes. + QtConcurrent includes functional programming style APIs for + parallel list processing, including a MapReduce and FilterReduce + implementation for shared-memory (non-distributed) systems, and + classes for managing asynchronous computations in GUI + applications: + + \list + + \o QtConcurrent::map() applies a function to every item in a container, + modifying the items in-place. + + \o QtConcurrent::mapped() is like map(), except that it returns a new + container with the modifications. + + \o QtConcurrent::mappedReduced() is like mapped(), except that the + modified results are reduced or folded into a single result. + + \o QtConcurrent::filter() removes all items from a container based on the + result of a filter function. + + \o QtConcurrent::filtered() is like filter(), except that it returns a new + container with the filtered results. + + \o QtConcurrent::filteredReduced() is like filtered(), except that the + filtered results are reduced or folded into a single result. + + \o QtConcurrent::run() runs a function in another thread. + + \o QFuture represents the result of an asynchronous computation. + + \o QFutureIterator allows iterating through results available via QFuture. + + \o QFutureWatcher allows monitoring a QFuture using signals-and-slots. + + \o QFutureSynchronizer is a convenience class that automatically + synchronizes several QFutures. + + \endlist + + Qt Concurrent supports several STL-compatible container and iterator types, + but works best with Qt containers that have random-access iterators, such as + QList or QVector. The map and filter functions accept both containers and begin/end iterators. + + STL Iterator support overview: + + \table + \header + \o Iterator Type + \o Example classes + \o Support status + \row + \o Input Iterator + \o + \o Not Supported + \row + \o Output Iterator + \o + \o Not Supported + \row + \o Forward Iterator + \o std::slist + \o Supported + \row + \o Bidirectional Iterator + \o QLinkedList, std::list + \o Supported + \row + \o Random Access Iterator + \o QList, QVector, std::vector + \o Supported and Recommended + \endtable + + Random access iterators can be faster in cases where Qt Concurrent is iterating + over a large number of lightweight items, since they allow skipping to any point + in the container. In addition, using random access iterators allows Qt Concurrent + to provide progress information trough QFuture::progressValue() and QFutureWatcher:: + progressValueChanged(). + + The non in-place modifying functions such as mapped() and filtered() makes a + copy of the container when called. If you are using STL containers this copy operation + might take some time, in this case we recommend specifying the begin and end iterators + for the container instead. +*/ + +/*! + \page threads-modules.html + \title Thread-Support in Qt Modules + + \previouspage Concurrent Programming + \contentspage Thread Support in Qt \section1 Threads and the SQL Module @@ -573,8 +636,8 @@ \section1 Painting in Threads - QPainter can be used to paint onto QImage, QPrinter, and QPicture - paint devices. Painting onto QPixmaps and QWidgets is \e not + QPainter can be used in a thread to paint onto QImage, QPrinter, and + QPicture paint devices. Painting onto QPixmaps and QWidgets is \e not supported. On Mac OS X the automatic progress dialog will not be displayed if you are printing from outside the GUI thread. @@ -601,16 +664,37 @@ \section1 Threads and the SVG module - The QSvgGenerator and QSvgRenderer classes in the QtSvg module - are reentrant. + The QSvgGenerator and QSvgRenderer classes in the QtSvg module + are reentrant. - \target reading - \section1 Recommended Reading + \section1 Threads and Implicitly Shared Classes - \list - \o \l{Threads Primer: A Guide to Multithreaded Programming} - \o \l{Thread Time: The Multithreaded Programming Guide} - \o \l{Pthreads Programming: A POSIX Standard for Better Multiprocessing} - \o \l{Win32 Multithreaded Programming} - \endlist + Qt uses an optimization called \l{implicit sharing} for many of + its value class, notably QImage and QString. Beginning with Qt 4, + implicit shared classes can safely be copied across threads, like + any other value classes. They are fully + \l{Reentrancy and Thread-Safety}{reentrant}. The implicit sharing + is really \e implicit. + + In many people's minds, implicit sharing and multithreading are + incompatible concepts, because of the way the reference counting + is typically done. Qt, however, uses atomic reference counting to + ensure the integrity of the shared data, avoiding potential + corruption of the reference counter. + + Note that atomic reference counting does not guarantee + \l{Reentrancy and Thread-Safety}{thread-safety}. Proper locking should be used + when sharing an instance of an implicitly shared class between + threads. This is the same requirement placed on all + \l{Reentrancy and Thread-Safety}{reentrant} classes, shared or not. Atomic reference + counting does, however, guarantee that a thread working on its + own, local instance of an implicitly shared class is safe. We + recommend using \l{Signals and Slots Across Threads}{signals and + slots} to pass data between threads, as this can be done without + the need for any explicit locking. + + To sum it up, implicitly shared classes in Qt 4 are really \e + implicitly shared. Even in multithreaded applications, you can + safely use them as if they were plain, non-shared, reentrant + value-based classes. */ diff --git a/doc/src/unicode.qdoc b/doc/src/frameworks-technologies/unicode.qdoc index 439070a..2daefc5 100644 --- a/doc/src/unicode.qdoc +++ b/doc/src/frameworks-technologies/unicode.qdoc @@ -39,20 +39,41 @@ ** ****************************************************************************/ +/*! + \group string-processing + \title Classes for String Data + + \brief Classes for working with string data. + + These classes are relevant when working with string data. See the + \l{Unicode in Qt}{information about support for Unicode in Qt} for + more information. +*/ + + /*! \page unicode.html - \title Unicode - \ingroup architecture - \ingroup text-processing + \title Unicode in Qt \brief Information about support for Unicode in Qt. + \keyword Unicode + + \ingroup frameworks-technologies + Unicode is a multi-byte character set, portable across all major computing platforms and with decent coverage over most of the world. It is also single-locale; it includes no code pages or other complexities that make software harder to write and test. There is no competing character set that's reasonably cross-platform. For these reasons, Unicode 4.0 is used as the native character set for Qt. + + \section1 Qt's Classes for Working with Strings + + These classes are relevant when working with string data. For information + about rendering text, see the \l{Rich Text Processing} overview, and if + your string data is in XML, see the \l{XML Processing} overview. + \annotatedlist string-processing \section1 Information about Unicode on the Web @@ -71,22 +92,18 @@ \section1 The Standard - The current version of the standard is 4.0.0. + The current version of the standard is \l{http://www.unicode.org/versions/Unicode5.1.0/}{Unicode 5.1.0}. - \list - - \i \link http://www.amazon.com/exec/obidos/ASIN/0321185781/trolltech/t - The Unicode Standard, version 4.0.\endlink See also - \link http://www.unicode.org/unicode/standard/versions/ - its home page.\endlink - \i \link http://www.amazon.com/exec/obidos/ASIN/0201616335/trolltech/t - The Unicode Standard, version 3.2.\endlink - \i \link http://www.amazon.com/exec/obidos/ASIN/0201473459/trolltech/t - The Unicode Standard, version 2.0.\endlink See also the - \link http://www.unicode.org/unicode/reports/tr8.html 2.1 - update\endlink and - \link http://www.unicode.org/unicode/standard/versions/enumeratedversions.html#Unicode 2.1.9 the 2.1.9 data files\endlink at www.unicode.org. + Previous printed versions of the specification: + \list + \o \l{http://www.amazon.com/Unicode-Standard-Version-5-0-5th/dp/0321480910/trolltech/t}{The Unicode Standard, Version 5.0} + \o \l{http://www.amazon.com/exec/obidos/ASIN/0321185781/trolltech/t}{The Unicode Standard, version 4.0} + \o \l{http://www.amazon.com/exec/obidos/ASIN/0201616335/trolltech/t}{The Unicode Standard, version 3.2} + \o \l{http://www.amazon.com/exec/obidos/ASIN/0201473459/trolltech/t}{The Unicode Standard, version 2.0} \mdash + see also the \l{http://www.unicode.org/unicode/reports/tr8.html}{2.1 update} and + \l{http://www.unicode.org/unicode/standard/versions/enumeratedversions.html#Unicode 2.1.9}{the 2.1.9 data files} at + \l{http://www.unicode.org}. \endlist \section1 Unicode in Qt diff --git a/doc/src/geometry.qdoc b/doc/src/geometry.qdoc deleted file mode 100644 index 9143548..0000000 --- a/doc/src/geometry.qdoc +++ /dev/null @@ -1,150 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page geometry.html - \title Window Geometry - \ingroup architecture - \brief An overview of window geometry handling and management. - - QWidget provides several functions that deal with a widget's - geometry. Some of these functions operate on the pure client area - (i.e. the window excluding the window frame), others include the - window frame. The differentiation is done in a way that covers the - most common usage transparently. - - \list - \o \bold{Including the window frame:} - \l{QWidget::x()}{x()}, - \l{QWidget::y()}{y()}, - \l{QWidget::frameGeometry()}{frameGeometry()}, - \l{QWidget::pos()}{pos()}, and - \l{QWidget::move()}{move()}. - \o \bold{Excluding the window frame:} - \l{QWidget::geometry()}{geometry()}, - \l{QWidget::width()}{width()}, - \l{QWidget::height()}{height()}, - \l{QWidget::rect()}{rect()}, and - \l{QWidget::size()}{size()}. - \endlist - - Note that the distinction only matters for decorated top-level - widgets. For all child widgets, the frame geometry is equal to the - widget's client geometry. - - This diagram shows most of the functions in use: - \img geometry.png Geometry diagram - - Topics: - - \tableofcontents - - \section1 X11 Peculiarities - - On X11, a window does not have a frame until the window manager - decorates it. This happens asynchronously at some point in time - after calling QWidget::show() and the first paint event the - window receives, or it does not happen at all. Bear in mind that - X11 is policy-free (others call it flexible). Thus you cannot - make any safe assumption about the decoration frame your window - will get. Basic rule: There's always one user who uses a window - manager that breaks your assumption, and who will complain to - you. - - Furthermore, a toolkit cannot simply place windows on the screen. All - Qt can do is to send certain hints to the window manager. The window - manager, a separate process, may either obey, ignore or misunderstand - them. Due to the partially unclear Inter-Client Communication - Conventions Manual (ICCCM), window placement is handled quite - differently in existing window managers. - - X11 provides no standard or easy way to get the frame geometry - once the window is decorated. Qt solves this problem with nifty - heuristics and clever code that works on a wide range of window - managers that exist today. Don't be surprised if you find one - where QWidget::frameGeometry() returns wrong results though. - - Nor does X11 provide a way to maximize a window. - QWidget::showMaximized() has to emulate the feature. Its result - depends on the result of QWidget::frameGeometry() and the - capability of the window manager to do proper window placement, - neither of which can be guaranteed. - - \section1 Restoring a Window's Geometry - - Since version 4.2, Qt provides functions that saves and restores a - window's geometry and state for you. QWidget::saveGeometry() - saves the window geometry and maximized/fullscreen state, while - QWidget::restoreGeometry() restores it. The restore function also - checks if the restored geometry is outside the available screen - geometry, and modifies it as appropriate if it is. - - The rest of this document describes how to save and restore the - geometry using the geometry properties. On Windows, this is - basically storing the result of QWidget::geometry() and calling - QWidget::setGeometry() in the next session before calling - \l{QWidget::show()}{show()}. On X11, this won't work because an - invisible window doesn't have a frame yet. The window manager - will decorate the window later. When this happens, the window - shifts towards the bottom/right corner of the screen depending on - the size of the decoration frame. Although X provides a way to - avoid this shift, most window managers fail to implement this - feature. - - A workaround is to call \l{QWidget::setGeometry()}{setGeometry()} - after \l{QWidget::show()}{show()}. This has the two disadvantages - that the widget appears at a wrong place for a millisecond - (results in flashing) and that currently only every second window - manager gets it right. A safer solution is to store both - \l{QWidget::pos()}{pos()} and \l{QWidget::size()}{size()} and to - restore the geometry using \l{QWidget::resize()} and - \l{QWidget::move()}{move()} before calling - \l{QWidget::show()}{show()}, as demonstrated in the following - code snippets (from the \l{mainwindows/application}{Application} - example): - - \snippet examples/mainwindows/application/mainwindow.cpp 35 - \codeline - \snippet examples/mainwindows/application/mainwindow.cpp 38 - - This method works on Windows, Mac OS X, and most X11 window - managers. -*/ diff --git a/doc/src/demos.qdoc b/doc/src/getting-started/demos.qdoc index 69a943a..1eac06f 100644 --- a/doc/src/demos.qdoc +++ b/doc/src/getting-started/demos.qdoc @@ -43,13 +43,28 @@ \page demos.html \title Qt Demonstrations \brief Information about the demonstration programs provided with Qt. - \ingroup howto + + \previouspage Qt Examples + \contentspage How to Learn Qt + \nextpage What's New in Qt 4.5 This is the list of demonstrations in Qt's \c demos directory. These are larger and more complicated programs than the \l{Qt Examples} and are used to highlight certain features of - Qt. You can launch any of these programs from the - \l{Examples and Demos Launcher} application. + Qt. + + \table 50% + \header + \o {2,1} Getting an Overview + \row + \o \inlineimage qtdemo-small.png + \o + If you run the \l{Examples and Demos Launcher}, you'll see many of Qt's + widgets in action. + + The \l{Qt Widget Gallery} also provides overviews of selected Qt + widgets in each of the styles used on various supported platforms. + \endtable If you are new to Qt, and want to start developing applications, you should probably start by going through the \l{Tutorials}. diff --git a/doc/src/getting-started/examples.qdoc b/doc/src/getting-started/examples.qdoc new file mode 100644 index 0000000..253a4e4 --- /dev/null +++ b/doc/src/getting-started/examples.qdoc @@ -0,0 +1,1108 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page examples-overview.html + \raw HTML + <script> + document.location.href = "examples.html"; + </script> + \endraw + Click this \l{Qt Examples}{link} if you don't get redirected. +*/ + +/*! + \page examples.html + \title Qt Examples + \brief The example programs provided with Qt. + + \previouspage Tutorials + \contentspage How to Learn Qt + \nextpage Qt Demonstrations + + Qt is supplied with a variety of examples that cover almost every aspect + of development. They are not all designed to be impressive when you run + them, but their source code is carefully written to show good Qt + programming practices. You can launch any of these programs from the + \l{Examples and Demos Launcher} application. + + These examples are ordered by functional area, but many examples often + use features from many parts of Qt to highlight one area in particular. + If you are new to Qt, you should probably start by going through the + \l{Tutorials} before you have a look at the + \l{mainwindows/application}{Application} example. + + In addition to the examples and the tutorial, Qt includes a + \l{Qt Demonstrations}{selection of demos} that deliberately show off + Qt's features. You might want to look at these as well. + + \table + \row + \o{2,1} \l{Widgets Examples}{\bold Widgets} + \o{2,1} \l{Dialog Examples}{\bold Dialogs} + \row + \i \image widget-examples.png + \i + Qt comes with a large range of standard widgets that users of modern + applications have come to expect. You can also develop your own custom + widgets and controls, and use them alongside standard widgets. + + It is even possible to provide custom styles and themes for widgets that can + be used to change the appearance of standard widgets and appropriately + written custom widgets. + + \i \image dialog-examples.png Dialogs + \i + Qt includes standard dialogs for many common operations, such as file + selection, printing, and color selection. + + Custom dialogs can also be created for specialized modal or modeless + interactions with users. + + \row + \o{2,1} \l{Main Window Examples}{\bold{Main Windows}} + \o{2,1} \l{Layout Examples}{\bold Layouts} + + \row + \i \image mainwindow-examples.png MainWindows + \i All the standard features of application main windows are provided by Qt. + + Main windows can have pull down menus, tool bars, and dock windows. These + separate forms of user input are unified in an integrated action system that + also supports keyboard shortcuts and accelerator keys in menu items. + + \i \image layout-examples.png Layouts + \i + Qt uses a layout-based approach to widget management. Widgets are arranged in + the optimal positions in windows based on simple layout rules, leading to a + consistent look and feel. + + Custom layouts can be used to provide more control over the positions and + sizes of child widgets. + + \row + \o{2,1} \l{Item Views Examples}{\bold{Item Views}} + \o{2,1} \l{Graphics View Examples}{\bold{Graphics View}} + \row + \o \image itemview-examples.png ItemViews + \o + Item views are widgets that typically display data sets. Qt 4's model/view + framework lets you handle large data sets by separating the underlying data + from the way it is represented to the user, and provides support for + customized rendering through the use of delegates. + + \o \image graphicsview-examples.png GraphicsView + \o + Qt is provided with a comprehensive canvas through the GraphicsView + classes. + + \row + \o{2,1} \l{Painting Examples}{\bold{Painting}} + \o{2,1} \l{Rich Text Examples}{\bold{Rich Text}} + \row + \o \image painting-examples.png Painting + \o + Qt's painting system is able to render vector graphics, images, and outline + font-based text with sub-pixel accuracy accuracy using anti-aliasing to + improve rendering quality. + + \o \image richtext-examples.png RichText + \o + Qt provides powerful document-oriented rich text engine that supports Unicode + and right-to-left scripts. Documents can be manipulated using a cursor-based + API, and their contents can be imported and exported as both HTML and in a + custom XML format. + + \row + \o{2,1} \l{Desktop Examples}{\bold Desktop} + \o{2,1} \l{Drag and Drop Examples}{\bold{Drag and Drop}} + \row + \o \image desktop-examples.png + \o + Qt provides features to enable applications to integrate with the user's + preferred desktop environment. + + Features such as system tray icons, access to the desktop widget, and + support for desktop services can be used to improve the appearance of + applications and take advantage of underlying desktop facilities. + + \o \image draganddrop-examples.png DragAndDrop + \o + Qt supports native drag and drop on all platforms via an extensible + MIME-based system that enables applications to send data to each other in the + most appropriate formats. + + Drag and drop can also be implemented for internal use by applications. + + \row + \o{2,1} \l{Threading and Concurrent Programming Examples}{\bold{Threading and Concurrent Programming}} + \o{2,1} \l{Tools Examples}{\bold{Tools}} + \row + \o \image thread-examples.png + \o + Qt 4 makes it easier than ever to write multithreaded applications. More + classes have been made usable from non-GUI threads, and the signals and slots + mechanism can now be used to communicate between threads. + + The QtConcurrent namespace includes a collection of classes and functions + for straightforward concurrent programming. + + \o \image tool-examples.png Tools + \o + Qt is equipped with a range of capable tool classes, from containers and + iterators to classes for string handling and manipulation. + + Other classes provide application infrastructure support, handling plugin + loading and managing configuration files. + + \row + \o{2,1} \l{Network Examples}{\bold{Network}} + \o{2,1} \l{Inter-Process Communication Examples}{\bold{Inter-Process Communication}} + \row + \o \image network-examples.png Network + \o + Qt is provided with an extensive set of network classes to support both + client-based and server side network programming. + + \o \image ipc-examples.png IPC + \o + + \row + \o{2,1} \l{OpenGL Examples}{\bold OpenGL} + \o{2,1} \l{Multimedia Examples}{\bold{Multimedia Framework}} + \row + \o \image opengl-examples.png OpenGL + \o + Qt provides support for integration with OpenGL implementations on all + platforms, giving developers the opportunity to display hardware accelerated + 3D graphics alongside a more conventional user interface. + + \o \image phonon-examples.png + \o + Qt provides low-level audio support on linux,windows and mac platforms by default and + an audio plugin API to allow developers to implement there own audio support for + custom devices and platforms. + + The Phonon Multimedia Framework brings multimedia support to Qt applications. + + \row + \o{2,1} \l{SQL Examples}{\bold{SQL}} + \o{2,1} \l{XML Examples}{\bold{XML}} + \row + \o \image sql-examples.png SQL + \o + Qt provides extensive database interoperability, with support for products + from both open source and proprietary vendors. + + SQL support is integrated with Qt's model/view architecture, making it easier + to provide GUI integration for your database applications. + + \o \image xml-examples.png XML + \o + XML parsing and handling is supported through SAX and DOM compliant APIs + as well as streaming classes. + + The XQuery/XPath and XML Schema engines in the QtXmlPatterns modules + provide classes for querying XML files and custom data models. + + \row + \o{2,1} \l{Qt Designer Examples}{\bold{Qt Designer}} + \o{2,1} \l{UiTools Examples}{\bold UiTools} + \row + \o \image designer-examples.png Designer + \o + Qt Designer is a capable graphical user interface designer that lets you + create and configure forms without writing code. GUIs created with + Qt Designer can be compiled into an application or created at run-time. + + \o \image uitools-examples.png UiTools + \o + + \row + \o{2,1} \l{Qt Linguist Examples}{\bold{Qt Linguist}} + \o{2,1} \l{Qt Script Examples}{\bold{Qt Script}} + \row + \o \image linguist-examples.png QtLinguist + \o + Internationalization is a core feature of Qt. + + \o \image qtscript-examples.png + \o + Qt is provided with a powerful embedded scripting environment through the QtScript + classes. + + \row + \o{2,1} \l{WebKit Examples}{\bold WebKit} + \o{2,1} \l{Help System Examples}{\bold{Help System}} + \row + \o \image webkit-examples.png + \o + Qt provides an integrated Web browser component based on WebKit, the popular + open source browser engine. + + \o \image assistant-examples.png HelpSystem + \o + Support for interactive help is provided by the Qt Assistant application. + Developers can take advantages of the facilities it offers to display + specially-prepared documentation to users of their applications. + + \row + \o{2,1} \l{State Machine Examples}{\bold{State Machine}} + \o{2,1} \l{Animation Framework Examples}{\bold{Animation Framework}} + \row + \o \image statemachine-examples.png + \o + Qt provides a powerful hierarchical finite state machine through the Qt State + Machine classes. + + \o \image animation-examples.png + \o + + \row + \o{2,1} \l{Qt for Embedded Linux Examples}{\bold{Qt for Embedded Linux}} + \o{2,1} \l{ActiveQt Examples}{\bold ActiveQt} + \row + \o \image qt-embedded-examples.png + \o + Systems with limited resources, specialized hardware, and small + screens require special attention. + + \o \image activeqt-examples.png ActiveQt + \o + + \row + \o{2,1} \l{D-Bus Examples}{\bold{D-Bus}} + \o{2,1} \l{Qt Quarterly}{\bold{Qt Quarterly}} + \row + \o \image dbus-examples.png D-Bus + \o + + \o \image qq-thumbnail.png QtQuarterly + \o + One more valuable source for examples and explanations of Qt + features is the archive of the \l {Qt Quarterly}. + + \endtable + +\omit + In the list below, examples marked with an asterisk (*) are fully + documented. Eventually, all the examples will be fully documented, + but sometimes we include an example before we have time to write + about it. +\endomit +*/ + +/*! + \page examples-widgets.html + \title Widgets Examples + + \contentspage Qt Examples + \nextpage Dialog Examples + + \image widget-examples.png + + Qt comes with a large range of standard widgets that users of modern + applications have come to expect. + + You can also develop your own custom widgets and controls, and use them + alongside standard widgets. + + It is even possible to provide custom styles and themes for widgets that can + be used to change the appearance of standard widgets and appropriately + written custom widgets. + + \list + \o \l{widgets/analogclock}{Analog Clock}\raisedaster + \o \l{widgets/calculator}{Calculator}\raisedaster + \o \l{widgets/calendarwidget}{Calendar Widget}\raisedaster + \o \l{widgets/charactermap}{Character Map}\raisedaster + \o \l{widgets/codeeditor}{Code Editor}\raisedaster + \o \l{widgets/digitalclock}{Digital Clock}\raisedaster + \o \l{widgets/groupbox}{Group Box}\raisedaster + \o \l{widgets/icons}{Icons}\raisedaster + \o \l{widgets/imageviewer}{Image Viewer}\raisedaster + \o \l{widgets/lineedits}{Line Edits}\raisedaster + \o \l{widgets/movie}{Movie} + \o \l{widgets/scribble}{Scribble}\raisedaster + \o \l{widgets/shapedclock}{Shaped Clock}\raisedaster + \o \l{widgets/sliders}{Sliders}\raisedaster + \o \l{widgets/spinboxes}{Spin Boxes}\raisedaster + \o \l{widgets/styles}{Styles}\raisedaster + \o \l{widgets/stylesheet}{Style Sheet}\raisedaster + \o \l{widgets/tablet}{Tablet}\raisedaster + \o \l{widgets/tetrix}{Tetrix}\raisedaster + \o \l{widgets/tooltips}{Tooltips}\raisedaster + \o \l{widgets/wiggly}{Wiggly}\raisedaster + \o \l{widgets/windowflags}{Window Flags}\raisedaster + \endlist +*/ + +/*! + \page examples-dialogs.html + \title Dialog Examples + + \previouspage Widgets Examples + \contentspage Qt Examples + \nextpage Main Window Examples + + \image dialog-examples.png + + Qt includes standard dialogs for many common operations, such as file + selection, printing, and color selection. + + Custom dialogs can also be created for specialized modal or modeless + interactions with users. + + \list + \o \l{dialogs/classwizard}{Class Wizard}\raisedaster + \o \l{dialogs/configdialog}{Config Dialog} + \o \l{dialogs/extension}{Extension}\raisedaster + \o \l{dialogs/findfiles}{Find Files}\raisedaster + \o \l{dialogs/licensewizard}{License Wizard}\raisedaster + \o \l{dialogs/standarddialogs}{Standard Dialogs} + \o \l{dialogs/tabdialog}{Tab Dialog}\raisedaster + \o \l{dialogs/trivialwizard}{Trivial Wizard} + \endlist +*/ + +/*! + \page examples-mainwindow.html + \title Main Window Examples + + \previouspage Dialog Examples + \contentspage Qt Examples + \nextpage Layout Examples + + \image mainwindow-examples.png + + All the standard features of application main windows are provided by Qt. + + Main windows can have pull down menus, tool bars, and dock windows. These + separate forms of user input are unified in an integrated action system that + also supports keyboard shortcuts and accelerator keys in menu items. + + \list + \o \l{mainwindows/application}{Application}\raisedaster + \o \l{mainwindows/dockwidgets}{Dock Widgets}\raisedaster + \o \l{mainwindows/mdi}{MDI} + \o \l{mainwindows/menus}{Menus}\raisedaster + \o \l{mainwindows/recentfiles}{Recent Files} + \o \l{mainwindows/sdi}{SDI} + \endlist +*/ + +/*! + \page examples-layouts.html + \title Layout Examples + + \previouspage Main Window Examples + \contentspage Qt Examples + \nextpage Item Views Examples + + \image layout-examples.png + + Qt uses a layout-based approach to widget management. Widgets are arranged in + the optimal positions in windows based on simple layout rules, leading to a + consistent look and feel. + + Custom layouts can be used to provide more control over the positions and + sizes of child widgets. + + \list + \o \l{layouts/basiclayouts}{Basic Layouts}\raisedaster + \o \l{layouts/borderlayout}{Border Layout} + \o \l{layouts/dynamiclayouts}{Dynamic Layouts} + \o \l{layouts/flowlayout}{Flow Layout} + \endlist +*/ + +/*! + \page examples-itemviews.html + \title Item Views Examples + + \previouspage Layout Examples + \contentspage Qt Examples + \nextpage Graphics View Examples + + \image itemview-examples.png + + Item views are widgets that typically display data sets. Qt 4's model/view + framework lets you handle large data sets by separating the underlying data + from the way it is represented to the user, and provides support for + customized rendering through the use of delegates. + + \list + \o \l{itemviews/addressbook}{Address Book}\raisedaster + \o \l{itemviews/basicsortfiltermodel}{Basic Sort/Filter Model} + \o \l{itemviews/chart}{Chart} + \o \l{itemviews/coloreditorfactory}{Color Editor Factory}\raisedaster + \o \l{itemviews/combowidgetmapper}{Combo Widget Mapper}\raisedaster + \o \l{itemviews/customsortfiltermodel}{Custom Sort/Filter Model}\raisedaster + \o \l{itemviews/dirview}{Dir View} + \o \l{itemviews/editabletreemodel}{Editable Tree Model}\raisedaster + \o \l{itemviews/fetchmore}{Fetch More}\raisedaster + \o \l{itemviews/frozencolumn}{Frozen Column}\raisedaster + \o \l{itemviews/pixelator}{Pixelator}\raisedaster + \o \l{itemviews/puzzle}{Puzzle} + \o \l{itemviews/simpledommodel}{Simple DOM Model}\raisedaster + \o \l{itemviews/simpletreemodel}{Simple Tree Model}\raisedaster + \o \l{itemviews/simplewidgetmapper}{Simple Widget Mapper}\raisedaster + \o \l{itemviews/spinboxdelegate}{Spin Box Delegate}\raisedaster + \o \l{itemviews/stardelegate}{Star Delegate}\raisedaster + \endlist +*/ + +/*! + \page examples-graphicsview.html + \title Graphics View Examples + + \previouspage Item Views Examples + \contentspage Qt Examples + \nextpage Painting Examples + + \image graphicsview-examples.png + + Qt is provided with a comprehensive canvas through the GraphicsView + classes. + + These examples demonstrate the fundamental aspects of canvas programming + with Qt. + + \list + \o \l{graphicsview/collidingmice}{Colliding Mice}\raisedaster + \o \l{graphicsview/diagramscene}{Diagram Scene}\raisedaster + \o \l{graphicsview/dragdroprobot}{Drag and Drop Robot} + \o \l{graphicsview/elasticnodes}{Elastic Nodes} + \o \l{graphicsview/portedasteroids}{Ported Asteroids} + \o \l{graphicsview/portedcanvas}{Ported Canvas} + \endlist +*/ + +/*! + \page examples-painting.html + \title Painting Examples + + \previouspage Graphics View Examples + \contentspage Qt Examples + \nextpage Rich Text Examples + + \image painting-examples.png + + Qt's painting system is able to render vector graphics, images, and outline + font-based text with sub-pixel accuracy accuracy using anti-aliasing to + improve rendering quality. + + These examples show the most common techniques that are used when painting + with Qt, from basic concepts such as drawing simple primitives to the use of + transformations. + + \list + \o \l{painting/basicdrawing}{Basic Drawing}\raisedaster + \o \l{painting/concentriccircles}{Concentric Circles}\raisedaster + \o \l{painting/fontsampler}{Font Sampler} + \o \l{painting/imagecomposition}{Image Composition}\raisedaster + \o \l{painting/painterpaths}{Painter Paths}\raisedaster + \o \l{painting/svggenerator}{SVG Generator}\raisedaster + \o \l{painting/svgviewer}{SVG Viewer} + \o \l{painting/transformations}{Transformations}\raisedaster + \endlist +*/ + +/*! + \page examples-richtext.html + \title Rich Text Examples + + \previouspage Painting Examples + \contentspage Qt Examples + \nextpage Desktop Examples + + \image richtext-examples.png + + Qt provides powerful document-oriented rich text engine that supports Unicode + and right-to-left scripts. Documents can be manipulated using a cursor-based + API, and their contents can be imported and exported as both HTML and in a + custom XML format. + + \list + \o \l{richtext/calendar}{Calendar}\raisedaster + \o \l{richtext/orderform}{Order Form}\raisedaster + \o \l{richtext/syntaxhighlighter}{Syntax Highlighter}\raisedaster + \o \l{richtext/textobject}{Text Object}\raisedaster + \endlist +*/ + +/*! + \page examples-desktop.html + \title Desktop Examples + + \previouspage Rich Text Examples + \contentspage Qt Examples + \nextpage Drag and Drop Examples + + \image desktop-examples.png + + Qt provides features to enable applications to integrate with the user's + preferred desktop environment. + + Features such as system tray icons, access to the desktop widget, and + support for desktop services can be used to improve the appearance of + applications and take advantage of underlying desktop facilities. + + \list + \o \l{desktop/screenshot}{Screenshot}\raisedaster + \o \l{desktop/systray}{System Tray}\raisedaster + \endlist +*/ + +/*! + \page examples-draganddrop.html + \title Drag and Drop Examples + + \previouspage Desktop Examples + \contentspage Qt Examples + \nextpage Threading and Concurrent Programming Examples + + \image draganddrop-examples.png + + Qt supports native drag and drop on all platforms via an extensible + MIME-based system that enables applications to send data to each other in the + most appropriate formats. + + Drag and drop can also be implemented for internal use by applications. + + \list + \o \l{draganddrop/delayedencoding}{Delayed Encoding}\raisedaster + \o \l{draganddrop/draggableicons}{Draggable Icons} + \o \l{draganddrop/draggabletext}{Draggable Text} + \o \l{draganddrop/dropsite}{Drop Site} + \o \l{draganddrop/fridgemagnets}{Fridge Magnets}\raisedaster + \o \l{draganddrop/puzzle}{Drag and Drop Puzzle} + \endlist +*/ + +/*! + \page examples-threadandconcurrent.html + \title Threading and Concurrent Programming Examples + + \previouspage Drag and Drop Examples + \contentspage Qt Examples + \nextpage Tools Examples + + \image thread-examples.png + + Qt 4 makes it easier than ever to write multithreaded applications. More + classes have been made usable from non-GUI threads, and the signals and slots + mechanism can now be used to communicate between threads. + + Additionally, it is now possible to move objects between threads. + + \list + \o \l{threads/queuedcustomtype}{Queued Custom Type}\raisedaster + \o \l{threads/mandelbrot}{Mandelbrot}\raisedaster + \o \l{threads/semaphores}{Semaphores}\raisedaster + \o \l{threads/waitconditions}{Wait Conditions}\raisedaster + \endlist + + The QtConcurrent namespace includes a collection of classes and functions + for straightforward concurrent programming. + + These examples show how to apply the basic techniques of concurrent + programming to simple problems. + + \list + \o \l{qtconcurrent/imagescaling}{QtConcurrent Asynchronous Image Scaling} + \o \l{qtconcurrent/map}{QtConcurrent Map} + \o \l{qtconcurrent/progressdialog}{QtConcurrent Progress Dialog} + \o \l{qtconcurrent/runfunction}{QtConcurrent Run Function} + \o \l{qtconcurrent/wordcount}{QtConcurrent Word Count} + \endlist +*/ + +/*! + \page examples.tools.html + \title Tools Examples + + \previouspage Threading and Concurrent Programming Examples + \contentspage Qt Examples + \nextpage Network Examples + + \image tool-examples.png + + Qt is equipped with a range of capable tool classes, from containers and + iterators to classes for string handling and manipulation. + + Other classes provide application infrastructure support, handling plugin + loading and managing configuration files. + + \list + \o \l{tools/codecs}{Codecs} + \o \l{tools/completer}{Completer}\raisedaster + \o \l{tools/customcompleter}{Custom Completer}\raisedaster + \o \l{tools/customtype}{Custom Type}\raisedaster + \o \l{tools/customtypesending}{Custom Type Sending}\raisedaster + \o \l{tools/echoplugin}{Echo Plugin}\raisedaster + \o \l{tools/i18n}{I18N} + \o \l{tools/plugandpaint}{Plug & Paint}\raisedaster + \o Plug & Paint Plugins: \l{tools/plugandpaintplugins/basictools}{Basic Tools}\raisedaster + and \l{tools/plugandpaintplugins/extrafilters}{Extra Filters}\raisedaster + \o \l{tools/regexp}{RegExp} + \o \l{tools/settingseditor}{Settings Editor} + \o \l{tools/styleplugin}{Style Plugin}\raisedaster + \o \l{tools/treemodelcompleter}{Tree Model Completer}\raisedaster + \o \l{tools/undoframework}{Undo Framework}\raisedaster + \endlist +*/ + +/*! + \page examples-network.html + \title Network Examples + + \previouspage Tools Examples + \contentspage Qt Examples + \nextpage Inter-Process Communication Examples + + \image network-examples.png + + Qt is provided with an extensive set of network classes to support both + client-based and server side network programming. + + These examples demonstrate the fundamental aspects of network programming + with Qt. + + \list + \o \l{network/blockingfortuneclient}{Blocking Fortune Client}\raisedaster + \o \l{network/broadcastreceiver}{Broadcast Receiver} + \o \l{network/broadcastsender}{Broadcast Sender} + \o \l{network/network-chat}{Network Chat} + \o \l{network/fortuneclient}{Fortune Client}\raisedaster + \o \l{network/fortuneserver}{Fortune Server}\raisedaster + \o \l{network/ftp}{FTP}\raisedaster + \o \l{network/http}{HTTP} + \o \l{network/loopback}{Loopback} + \o \l{network/threadedfortuneserver}{Threaded Fortune Server}\raisedaster + \o \l{network/torrent}{Torrent} + \o \l{network/googlesuggest}{Google Suggest} + \endlist +*/ + +/*! + \page examples-ipc.html + \title Inter-Process Communication Examples + + \previouspage Network Examples + \contentspage Qt Examples + \nextpage OpenGL Examples + + \image ipc-examples.png + + \list + \o \l{ipc/localfortuneclient}{Local Fortune Client}\raisedaster + \o \l{ipc/localfortuneserver}{Local Fortune Server}\raisedaster + \o \l{ipc/sharedmemory}{Shared Memory}\raisedaster + \endlist +*/ + +/*! + \page examples-opengl.html + \title OpenGL Examples + + \previouspage Inter-Process Communication Examples + \contentspage Qt Examples + \nextpage Multimedia Examples + + \image opengl-examples.png + + Qt provides support for integration with OpenGL implementations on all + platforms, giving developers the opportunity to display hardware accelerated + 3D graphics alongside a more conventional user interface. + + These examples demonstrate the basic techniques used to take advantage of + OpenGL in Qt applications. + + \list + \o \l{opengl/2dpainting}{2D Painting}\raisedaster + \o \l{opengl/framebufferobject}{Framebuffer Object} + \o \l{opengl/framebufferobject2}{Framebuffer Object 2} + \o \l{opengl/grabber}{Grabber} + \o \l{opengl/hellogl}{Hello GL}\raisedaster + \o \l{opengl/overpainting}{Overpainting}\raisedaster + \o \l{opengl/pbuffers}{Pixel Buffers} + \o \l{opengl/pbuffers2}{Pixel Buffers 2} + \o \l{opengl/samplebuffers}{Sample Buffers} + \o \l{opengl/textures}{Textures} + \endlist +*/ + +/*! + \page examples-multimedia.html + \title Multimedia Examples + + \previouspage OpenGL Examples + \contentspage Qt Examples + \nextpage SQL Examples + + \image phonon-examples.png + + \section1 Multimedia + + Qt provides low-level audio support on linux,windows and mac platforms by default and + an audio plugin API to allow developers to implement there own audio support for + custom devices and platforms. + + These examples demonstrate the basic techniques used to take advantage of + Audio API in Qt applications. + + \list + \o \l{multimedia/audio/audiodevices}{Audio Devices} + \o \l{multimedia/audio/audiooutput}{Audio Output} + \o \l{multimedia/audio/audioinput}{Audio Input} + \endlist + + \section1 Phonon + + The Phonon Multimedia Framework brings multimedia support to Qt applications. + + The examples and demonstrations provided show how to play music and movies + using the Phonon API. + + \list + \o \l{phonon/capabilities}{Capabilities}\raisedaster + \o \l{phonon/musicplayer}{Music Player}\raisedaster + \endlist +*/ + +/*! + \page examples-sql.html + \title SQL Examples + + \previouspage Multimedia Examples + \contentspage Qt Examples + \nextpage XML Examples + + \image sql-examples.png + + Qt provides extensive database interoperability, with support for products + from both open source and proprietary vendors. + + SQL support is integrated with Qt's model/view architecture, making it easier + to provide GUI integration for your database applications. + + \list + \o \l{sql/cachedtable}{Cached Table}\raisedaster + \o \l{sql/drilldown}{Drill Down}\raisedaster + \o \l{sql/querymodel}{Query Model} + \o \l{sql/relationaltablemodel}{Relational Table Model} + \o \l{sql/tablemodel}{Table Model} + \o \l{sql/sqlwidgetmapper}{SQL Widget Mapper}\raisedaster + \endlist +*/ + + +/*! + \page examples-xml.html + \title XML Examples + + \previouspage SQL Examples + \contentspage Qt Examples + \nextpage Qt Designer Examples + + \image xml-examples.png XML + + XML parsing and handling is supported through SAX and DOM compliant APIs + as well as streaming classes. + + \list + \o \l{xml/dombookmarks}{DOM Bookmarks} + \o \l{xml/saxbookmarks}{SAX Bookmarks} + \o \l{xml/streambookmarks}{QXmlStream Bookmarks}\raisedaster + \o \l{xml/rsslisting}{RSS-Listing} + \o \l{xml/xmlstreamlint}{XML Stream Lint Example}\raisedaster + \endlist + + The XQuery/XPath and XML Schema engines in the QtXmlPatterns modules + provide classes for querying XML files and custom data models. + + \list + \o \l{xmlpatterns/recipes}{Recipes} + \o \l{xmlpatterns/filetree}{File System Example} + \o \l{xmlpatterns/qobjectxmlmodel}{QObject XML Model Example} + \o \l{xmlpatterns/xquery/globalVariables}{C++ Source Code Analyzer Example} + \o \l{xmlpatterns/trafficinfo}{Traffic Info}\raisedaster + \o \l{xmlpatterns/schema}{XML Schema Validation}\raisedaster + \endlist +*/ + +/*! + \page examples-designer.html + \title Qt Designer Examples + + \previouspage XML Examples + \contentspage Qt Examples + \nextpage UiTools Examples + + \image designer-examples.png QtDesigner + + Qt Designer is a capable graphical user interface designer that lets you + create and configure forms without writing code. GUIs created with + Qt Designer can be compiled into an application or created at run-time. + + \list + \o \l{designer/calculatorbuilder}{Calculator Builder}\raisedaster + \o \l{designer/calculatorform}{Calculator Form}\raisedaster + \o \l{designer/customwidgetplugin}{Custom Widget Plugin}\raisedaster + \o \l{designer/taskmenuextension}{Task Menu Extension}\raisedaster + \o \l{designer/containerextension}{Container Extension}\raisedaster + \o \l{designer/worldtimeclockbuilder}{World Time Clock Builder}\raisedaster + \o \l{designer/worldtimeclockplugin}{World Time Clock Plugin}\raisedaster + \endlist +*/ + +/*! + \page examples-uitools.html + \title UiTools Examples + + \previouspage Qt Designer Examples + \contentspage Qt Examples + \nextpage Qt Linguist Examples + + \image uitools-examples.png UiTools + + \list + \o \l{uitools/multipleinheritance}{Multiple Inheritance}\raisedaster + \o \l{uitools/textfinder}{Text Finder}\raisedaster + \endlist +*/ + +/*! + \page examples-linguist.html + \title Qt Linguist Examples + + \previouspage UiTools Examples + \contentspage Qt Examples + \nextpage Qt Script Examples + + \image linguist-examples.png + + Internationalization is a core feature of Qt. These examples show how to + access translation and localization facilities at run-time. + + \list + \o \l{linguist/hellotr}{Hello tr()}\raisedaster + \o \l{linguist/arrowpad}{Arrow Pad}\raisedaster + \o \l{linguist/trollprint}{Troll Print}\raisedaster + \endlist +*/ + +/*! + \page examples-script.html + \title Qt Script Examples + + \previouspage Qt Linguist Examples + \contentspage Qt Examples + \nextpage WebKit Examples + + \image qtscript-examples.png QtScript + + Qt is provided with a powerful embedded scripting environment through the QtScript + classes. + + These examples demonstrate the fundamental aspects of scripting applications + with Qt. + + \list + \o \l{script/calculator}{Calculator}\raisedaster + \o \l{script/context2d}{Context2D}\raisedaster + \o \l{script/defaultprototypes}{Default Prototypes}\raisedaster + \o \l{script/helloscript}{Hello Script}\raisedaster + \o \l{script/qstetrix}{Qt Script Tetrix}\raisedaster + \o \l{script/customclass}{Custom Script Class}\raisedaster + \endlist +*/ + +/*! + \page examples-webkit.html + \title WebKit Examples + + \previouspage Qt Script Examples + \contentspage Qt Examples + \nextpage Help System Examples + + \image webkit-examples.png WebKit + + Qt provides an integrated Web browser component based on WebKit, the popular + open source browser engine. + + These examples and demonstrations show a range of different uses for WebKit, + from displaying Web pages within a Qt user interface to an implementation of + a basic function Web browser. + + \list + \o \l{webkit/previewer}{Previewer}\raisedaster + \o \l{webkit/formextractor}{Form Extractor} + \o \l{webkit/googlechat}{Google Chat} + \o \l{webkit/fancybrowser}{Fancy Browser} + \endlist +*/ + +/*! + \page examples-helpsystem.html + \title Help System Examples + + \previouspage WebKit Examples + \contentspage Qt Examples + \nextpage State Machine Examples + + \image assistant-examples.png HelpSystem + + Support for interactive help is provided by the Qt Assistant application. + Developers can take advantages of the facilities it offers to display + specially-prepared documentation to users of their applications. + + \list + \o \l{help/simpletextviewer}{Simple Text Viewer}\raisedaster + \endlist +*/ + +/*! + \page examples-statemachine.html + \title State Machine Examples + + \previouspage Help System Examples + \contentspage Qt Examples + \nextpage Animation Framework Examples + + \image statemachine-examples.png StateMachine + + Qt provides a powerful hierarchical finite state machine through the Qt State + Machine classes. + + These examples demonstrate the fundamental aspects of implementing + Statecharts with Qt. + + \list + \o \l{statemachine/eventtransitions}{Event Transitions}\raisedaster + \o \l{statemachine/factorial}{Factorial States}\raisedaster + \o \l{statemachine/pingpong}{Ping Pong States}\raisedaster + \o \l{statemachine/rogue}{Rogue}\raisedaster + \o \l{statemachine/trafficlight}{Traffic Light}\raisedaster + \o \l{statemachine/twowaybutton}{Two-way Button}\raisedaster + \endlist +*/ + +/*! + \page examples-animation.html + \title Animation Framework Examples + + \previouspage State Machine Examples + \contentspage Qt Examples + \nextpage Qt for Embedded Linux Examples + + \image animation-examples.png Animation + + \list + \o \l{animation/moveblocks}{Move Blocks}\raisedaster + \o \l{animation/stickman}{Stick man}\raisedaster + \endlist +*/ + +/*! + \page examples-embeddedlinux.html + \title Qt for Embedded Linux Examples + + \previouspage Animation Framework Examples + \contentspage Qt Examples + \nextpage ActiveQt Examples + + \image qt-embedded-examples.png QtEmbedded + + These examples show how to take advantage of features specifically designed + for use on systems with limited resources, specialized hardware, and small + screens. + + \list + \o \l{qws/svgalib}{Accelerated Graphics Driver}\raisedaster + \o \l{qws/dbscreen}{Double Buffered Graphics Driver}\raisedaster + \o \l{qws/mousecalibration}{Mouse Calibration}\raisedaster + \o \l{qws/ahigl}{OpenGL for Embedded Systems}\raisedaster + \o \l{qws/simpledecoration}{Simple Decoration}\raisedaster + \endlist +*/ + +/*! + \page examples-activeqt.html + \title ActiveQt Examples + + \previouspage Qt for Embedded Linux Examples + \contentspage Qt Examples + \nextpage D-Bus Examples + + \image activeqt-examples.png ActiveQt + + \list + \o \l{activeqt/comapp}{COM App}\raisedaster + \o \l{Dot Net Example (ActiveQt)}{Dot Net}\raisedaster + \o \l{activeqt/hierarchy}{Hierarchy}\raisedaster + \o \l{activeqt/menus}{Menus}\raisedaster + \o \l{activeqt/multiple}{Multiple}\raisedaster + \o \l{activeqt/opengl}{OpenGL}\raisedaster + \o \l{activeqt/qutlook}{Qutlook}\raisedaster + \o \l{activeqt/simple}{Simple}\raisedaster + \o \l{activeqt/webbrowser}{Web Browser}\raisedaster + \o \l{activeqt/wrapper}{Wrapper}\raisedaster + \endlist +*/ + +/*! + \page examples-dbus.html + \title D-Bus Examples + + \previouspage ActiveQt Examples + \contentspage Qt Examples + \nextpage Qt Quarterly + + \list + \o \l{dbus/dbus-chat}{Chat} + \o \l{dbus/complexpingpong}{Complex Ping Pong} + \o \l{dbus/listnames}{List Names} + \o \l{dbus/pingpong}{Ping Pong} + \o \l{dbus/remotecontrolledcar}{Remote Controlled Car} + \endlist +*/ diff --git a/doc/src/how-to-learn-qt.qdoc b/doc/src/getting-started/how-to-learn-qt.qdoc index ee23509..2a1e383 100644 --- a/doc/src/how-to-learn-qt.qdoc +++ b/doc/src/getting-started/how-to-learn-qt.qdoc @@ -41,9 +41,10 @@ /*! \page how-to-learn-qt.html - \brief Links to guides and resources for learning Qt. \title How to Learn Qt - \ingroup howto + \brief Links to guides and resources for learning Qt. + + \nextpage Tutorials We assume that you already know C++ and will be using it for Qt development. See the \l{Qt website} for more information about @@ -79,10 +80,12 @@ common with your projects. You can also read Qt's source code since this is supplied. - \table - \row \o \inlineimage qtdemo-small.png - \o \bold{Getting an Overview} - + \table 50% + \header + \o {2,1} Getting an Overview + \row + \o \inlineimage qtdemo-small.png + \o If you run the \l{Examples and Demos Launcher}, you'll see many of Qt's widgets in action. diff --git a/doc/src/installation.qdoc b/doc/src/getting-started/installation.qdoc index ac1d68c..9bf774b 100644 --- a/doc/src/installation.qdoc +++ b/doc/src/getting-started/installation.qdoc @@ -46,8 +46,6 @@ /*! \group installation \title Installation -\ingroup buildsystem -\ingroup topics \brief Installing Qt on supported platforms. The installation procedure is different on each Qt platform. @@ -818,6 +816,20 @@ If you are using pre-built binaries, follow the instructions may cause others to be automatically installed. Other distributions may provide system packages with similar names. + \section1 OpenGL Dependencies + + The configure script will autodetect if OpenGL headers and libraries are + installed on your system, and if so, it will include the QtOpenGL module + in the Qt library. + + If your OpenGL headers or libraries are placed in a non-standard directory, + you may need to change the \c QMAKE_INCDIR_OPENGL and/or + \c QMAKE_LIBDIR_OPENGL in the config file for your system. + + The QGL documentation assumes that you are familiar with OpenGL + programming. If you're new to the subject a good starting point is + \l{http://www.opengl.org/}. + \section1 Phonon Dependencies As described in the \l{Phonon Overview}, Phonon uses the GStreamer multimedia diff --git a/doc/src/known-issues.qdoc b/doc/src/getting-started/known-issues.qdoc index 87955bd..41bdcdf 100644 --- a/doc/src/known-issues.qdoc +++ b/doc/src/getting-started/known-issues.qdoc @@ -42,7 +42,7 @@ /*! \page known-issues.html \title Known Issues in %VERSION% - \ingroup platform-notes + \ingroup platform-specific \brief A summary of known issues in Qt %VERSION% at the time of release. An up-to-date list of known issues with Qt %VERSION% can be found via the @@ -133,6 +133,7 @@ \endlist + \section2 Mac OS X Software Support \list @@ -140,4 +141,34 @@ window will cause it to flash. This behavior has been reported to Apple (bug number 5827676). \endlist + + + \section2 Installing source packages on Unix systems + + \list + \o If you download a Zip source package, you will need to convert + Windows-style line endings (CR/LF) to Unix-style line-endings (LF) when + you uncompress the package. To do this, give the "-a" option when you + run the "unzip' command. + + If you fail to supply the "-a" option when unzipping the package, you + will see the following error message when you attempt to execute the + configure command: + "bash: ./configure: /bin/sh^M: bad interpreter: No such file or directory" + \endlist + + + \section2 Running evaluation packages on Windows XP + + \list + \o If running the qt-win-eval-%VERSION%-vs2008.exe package on a Windows XP + system, you may encounter the following error message: + "The application failed to start because the application configuration + is incorrect. Reinstalling the application may fix this problem.". + + This error occurs because the version of the CRT component on the + system is incorrect. Visual Studio 2008 requires CRT90 while Windows + XP comes with CRT80. To solve this problem, please install the 2008 CRT + redistributable package from Microsoft. + \endlist */ diff --git a/doc/src/getting-started/tutorials.qdoc b/doc/src/getting-started/tutorials.qdoc new file mode 100644 index 0000000..525b6e4 --- /dev/null +++ b/doc/src/getting-started/tutorials.qdoc @@ -0,0 +1,103 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page tutorials.html + \title Tutorials + + \contentspage How to Learn Qt + \nextpage Qt Examples + + \brief Tutorials, guides and overviews to help you learn Qt. + + \nextpage Qt Examples + + A collection of tutorials and "walkthrough" guides are provided with Qt to + help new users get started with Qt development. These documents cover a + range of topics, from basic use of widgets to step-by-step tutorials that + show how an application is put together. + + \table + \row + \o{2,1} \l{Widgets Tutorial}{\bold Widgets} + \o{2,1} \l{Address Book Tutorial}{\bold {Address Book}} + \row + \o \image widget-examples.png Widgets + \o + A beginner's guide to getting started with widgets and layouts to create + GUI applications. + + \o \image addressbook-tutorial.png AddressBook + \o + A seven part guide to creating a fully-functioning address book + application. This tutorial is also available with + \l{Tutoriel "Carnet d'adresses"}{French explanation}. + + \row + \o{2,1} \l{A Quick Start to Qt Designer}{\bold{Qt Designer}} + \o{2,1} \l{Qt Linguist Manual: Programmers#Tutorials}{\bold {Qt Linguist}} + \row + \o \image designer-examples.png QtDesigner + \o + A quick guide through \QD showing the basic steps to create a + form with this interactive tool. + + \o \image linguist-examples.png QtLinguist + \o + A guided tour through the translations process, explaining the + tools provided for developers, translators and release managers. + + \row + \o{2,1} \l{QTestLib Tutorial}{\bold QTestLib} + \o{2,1} \l{qmake Tutorial}{\bold qmake} + \row + \o{2,1} + This tutorial gives a short introduction to how to use some of the + features of Qt's unit-testing framework, QTestLib. It is divided into + four chapters. + + \o{2,1} + This tutorial teaches you how to use \c qmake. We recommend that + you read the \l{qmake Manual}{qmake user guide} after completing + this tutorial. + + \endtable +*/ diff --git a/doc/src/groups.qdoc b/doc/src/groups.qdoc deleted file mode 100644 index 673eff5..0000000 --- a/doc/src/groups.qdoc +++ /dev/null @@ -1,487 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \group advanced - \title Advanced Widgets - \ingroup groups - - \brief Advanced GUI widgets such as tab widgets and progress bars. - - These classes provide more complex user interface widgets (controls). - -*/ - -/*! - \group animation - \ingroup groups - - \title Animation Framework - \brief Classes for animations, states and transitions. - - These classes provide a framework for creating both simple and complex - animations. \l{The Animation Framework} also provides states and animated - transitions, making it easy to create animated stateful forms. -*/ - -/*! - \group abstractwidgets - \title Abstract Widget Classes - \ingroup groups - - \brief Abstract widget classes usable through subclassing. - - These classes are abstract widgets; they are generally not usable in - themselves, but provide functionality that can be used by inheriting - these classes. - -*/ - -/*! - \group accessibility - \title Accessibility Classes - \ingroup groups - \ingroup topics - - \brief Classes that provide support for accessibility. - - Accessible applications are able to be used by users who cannot use - conventional means of interaction. These classes provide support for - accessible applications. - -*/ - -/*! - \group appearance - \title Widget Appearance and Style - \ingroup groups - - \brief Appearance customization with styles, fonts, colors etc. - - These classes are used to customize an application's appearance and - style. - -*/ - -/*! - \group application - \title Main Window and Related Classes - \ingroup groups - - \brief Everything you need for a typical modern main application window, - including menus, toolbars, workspace, etc. - - These classes provide everything you need for a typical modern main - application window, like the main window itself, menu and tool bars, - a status bar, etc. - -*/ - - -/*! - \group basicwidgets - \title Basic Widgets - \ingroup groups - - \brief Basic GUI widgets such as buttons, comboboxes and scroll bars. - - These basic widgets (controls) are designed for direct use. - There are also some \l{Abstract Widget Classes} that are designed for - subclassing, and some more complex \l{Advanced Widgets}. - -*/ - - -/*! - \group database - \title Database Classes - \ingroup groups - - \brief Database related classes, e.g. for SQL databases. - - These classes provide access to SQL databases. -*/ - - -/*! - \group dialogs - \title Standard Dialog Classes - \ingroup groups - - \brief Ready-made dialogs for file, font, color selection and more. - - These classes are complex widgets, composed of simpler widgets; dialog - boxes, generally. -*/ - -/*! - \group desktop - \title Desktop Environment Classes - \ingroup groups - - \brief Classes for interacting with the user's desktop environment. - - These classes provide ways to interact with the user's desktop environment and - take advantage of common services. -*/ - -/*! - \group draganddrop - \title Drag And Drop Classes - \ingroup groups - - \brief Classes dealing with drag and drop and mime type encoding and decoding. - - These classes deal with drag and drop and the necessary mime type - encoding and decoding. See also \link dnd.html Drag and Drop with - Qt. \endlink -*/ - -/*! - \group environment - \title Environment Classes - \ingroup groups - - \brief Classes providing various global services such as event handling, - access to system settings and internationalization. - - These classes providing various global services to your application such as - event handling, access to system settings, internationalization, etc. - -*/ - -/*! - \group events - \title Event Classes - \ingroup groups - - \brief Classes used to create and handle events. - - These classes are used to create and handle events. - - For more information see the \link object.html Object model\endlink - and \link signalsandslots.html Signals and Slots\endlink. -*/ - -/*! - \group geomanagement - \title Layout Classes - \ingroup groups - - \brief Classes handling automatic resizing and moving of widgets, for - composing complex dialogs. - - These classes provide automatic geometry (layout) management of widgets. - -*/ - -/*! - \group graphicsview-api - \title Graphics View Classes - \ingroup groups - - \brief Classes in the Graphics View framework for interactive applications. - - These classes are provided by \l{The Graphics View Framework} for interactive - applications and are part of a larger collection of classes related to - \l{Multimedia, Graphics and Printing}. - - \note These classes are part of the \l{Open Source Versions of Qt} and - \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial users. -*/ - -/*! - \group helpsystem - \title Help System - \ingroup groups - - \brief Classes used to provide online-help for applications. - - \keyword help system - - These classes provide for all forms of online-help in your application, - with three levels of detail: - - \list 1 - \o Tool Tips and Status Bar message - flyweight help, extremely brief, - entirely integrated in the user interface, requiring little - or no user interaction to invoke. - \o What's This? - lightweight, but can be - a three-paragraph explanation. - \o Online Help - can encompass any amount of information, - but is typically slower to call up, somewhat separated - from the user's work, and often users feel that using online - help is a digression from their real task. - \endlist - -*/ - - -/*! - \group io - \title Input/Output and Networking - \ingroup groups - - \brief Classes providing file input and output along with directory and - network handling. - - These classes are used to handle input and output to and from external - devices, processes, files etc. as well as manipulating files and directories. -*/ - -/*! - \group misc - \title Miscellaneous Classes - \ingroup groups - - \brief Various other useful classes. - - These classes are useful classes not fitting into any other category. - -*/ - - -/*! - \group model-view - \title Model/View Classes - \ingroup groups - - \brief Classes that use the model/view design pattern. - - These classes use the model/view design pattern in which the - underlying data (in the model) is kept separate from the way the data - is presented and manipulated by the user (in the view). See also - \link model-view-programming.html Model/View Programming\endlink. - -*/ - -/*! - \group multimedia - \title Multimedia, Graphics and Printing - \ingroup groups - - \brief Classes that provide support for graphics (2D, and with OpenGL, 3D), - image encoding, decoding, and manipulation, sound, animation, - printing, etc. - - These classes provide support for graphics (2D, and with OpenGL, 3D), - image encoding, decoding, and manipulation, sound, animation, printing - etc. - - See also this introduction to the \link coordsys.html Qt - coordinate system. \endlink - -*/ - -/*! - \group objectmodel - \title Object Model - \ingroup groups - - \brief The Qt GUI toolkit's underlying object model. - - These classes form the basis of the \l{Qt Object Model}. - -*/ - -/*! - \group organizers - \title Organizers - \ingroup groups - - \brief User interface organizers such as splitters, tab bars, button groups, etc. - - These classes are used to organize and group GUI primitives into more - complex applications or dialogs. - -*/ - - -/*! - \group plugins - \title Plugin Classes - \ingroup groups - - \brief Plugin related classes. - - These classes deal with shared libraries, (e.g. .so and DLL files), - and with Qt plugins. - - See the \link plugins-howto.html plugins documentation\endlink. - - See also the \l{ActiveQt framework} for Windows. - -*/ - -/*! - \group qws - \title Qt for Embedded Linux Classes - \ingroup groups - - \ingroup qt-embedded-linux - \brief Classes that are specific to Qt for Embedded Linux. - - These classes are relevant to \l{Qt for Embedded Linux} users. -*/ - -/*! - \group ssl - \title Secure Sockets Layer (SSL) Classes - \ingroup groups - - \brief Classes for secure communication over network sockets. - \keyword SSL - - The classes below provide support for secure network communication using - the Secure Sockets Layer (SSL) protocol, using the \l{OpenSSL Toolkit} to - perform encryption and protocol handling. - - See the \l{General Qt Requirements} page for information about the - versions of OpenSSL that are known to work with Qt. - - \note Due to import and export restrictions in some parts of the world, we - are unable to supply the OpenSSL Toolkit with Qt packages. Developers wishing - to use SSL communication in their deployed applications should either ensure - that their users have the appropriate libraries installed, or they should - consult a suitably qualified legal professional to ensure that applications - using code from the OpenSSL project are correctly certified for import - and export in relevant regions of the world. - - When the QtNetwork module is built with SSL support, the library is linked - against OpenSSL in a way that requires OpenSSL license compliance. -*/ - -/*! - \group text - \title Text Processing Classes - \ingroup groups - \ingroup text-processing - - \brief Classes for text processing. (See also \l{XML Classes}.) - - These classes are relevant to text processing. See also the - \l{Rich Text Processing} overview and the - \l{XML classes}. -*/ - -/*! - \group thread - \title Threading Classes - \ingroup groups - - \brief Classes that provide threading support. - - These classes are relevant to threaded applications. See - \l{Thread Support in Qt} for an overview of the features - Qt provides to help with multithreaded programming. -*/ - - -/*! - \group time - \title Date and Time Classes - \ingroup groups - - \brief Classes for handling date and time. - - These classes provide system-independent date and time abstractions. - -*/ - -/*! - \group tools - \title Non-GUI Classes - \ingroup groups - - \brief Collection classes such as list, queue, stack and string, along - with other classes that can be used without needing QApplication. - - The non-GUI classes are general-purpose collection and string classes - that may be used independently of the GUI classes. - - In particular, these classes do not depend on QApplication at all, - and so can be used in non-GUI programs. - -*/ - -/*! - \group xml-tools - \title XML Classes - \ingroup groups - - \brief Classes that support XML, via, for example DOM and SAX. - - These classes are relevant to XML users. -*/ - -/*! - \group script - \title Scripting Classes - \ingroup groups - \ingroup scripting - - \brief Qt Script-related classes and overviews. - - These classes are relevant to Qt Script users. -*/ - -/*! - \group scripttools - \title Script Tools - \ingroup groups - \ingroup scripting - - \brief Classes for managing and debugging scripts. - - These classes are relevant to developers who are working with Qt Script's - debugging features. -*/ - -/*! - \group statemachine - \ingroup groups - - \title State Machine Classes - \brief Classes for constructing and executing state graphs. - - These classes are provided by \l{The State Machine Framework} for creating - event-driven state machines. -*/ diff --git a/doc/src/accelerators.qdoc b/doc/src/howtos/accelerators.qdoc index 4376730..bb1b2d7 100644 --- a/doc/src/accelerators.qdoc +++ b/doc/src/howtos/accelerators.qdoc @@ -42,7 +42,8 @@ /*! \page accelerators.html \title Standard Accelerator Keys - \ingroup gui-programming + + \ingroup best-practices Applications invariably need to define accelerator keys for actions. Qt fully supports accelerators, for example with \l Q3Accel::shortcutKey(). diff --git a/doc/src/appicon.qdoc b/doc/src/howtos/appicon.qdoc index 3948741..2452689 100644 --- a/doc/src/appicon.qdoc +++ b/doc/src/howtos/appicon.qdoc @@ -39,22 +39,11 @@ ** ****************************************************************************/ -/**************************************************************************** -** -** Qt Application Icon Usage Documentation. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - /*! \page appicon.html \title Setting the Application Icon - \ingroup gui-programming + + \ingroup best-practices The application icon, typically displayed in the top-left corner of an application's top-level windows, is set by calling the diff --git a/doc/src/custom-types.qdoc b/doc/src/howtos/custom-types.qdoc index aa7d386..997c8bc 100644 --- a/doc/src/custom-types.qdoc +++ b/doc/src/howtos/custom-types.qdoc @@ -42,9 +42,10 @@ /*! \page custom-types.html \title Creating Custom Qt Types - \ingroup architecture \brief How to create and register new types with Qt. + \ingroup best-practices + \tableofcontents \section1 Overview diff --git a/doc/src/guibooks.qdoc b/doc/src/howtos/guibooks.qdoc index 3e89738..0a7200e 100644 --- a/doc/src/guibooks.qdoc +++ b/doc/src/howtos/guibooks.qdoc @@ -41,9 +41,8 @@ /*! \page guibooks.html - \title Books about GUI Design - \ingroup gui-programming + \ingroup best-practices This is not a comprehensive list -- there are many other books worth buying. Here we mention just a few user interface books that don't diff --git a/doc/src/qtopenvg.qdoc b/doc/src/howtos/openvg.qdoc index 9f0df58..f2049ce 100644 --- a/doc/src/qtopenvg.qdoc +++ b/doc/src/howtos/openvg.qdoc @@ -40,28 +40,26 @@ ****************************************************************************/ /*! - \module QtOpenVG - \title QtOpenVG Module + \page openvg.html + \title OpenVG Rendering in Qt \since 4.6 - \contentspage Qt's Modules - \previouspage QtOpenGL - \nextpage QtScript - \ingroup modules + \ingroup best-practices - \brief The QtOpenVG module provides support classes for OpenVG painting. - - \tableofcontents + \brief Efficient rendering on embedded devices with OpenVG OpenVG is a standard API from the \l{http://www.khronos.org/openvg}{Khronos Group} for accelerated 2D vector graphics that is appearing in an increasing number of - embedded devices. + embedded devices. The QtOpenVG plugin provides support for OpenVG + painting. OpenVG is optimized for 2D vector operations, and closely matches - the functionality in QPainter. It can therefore be an excellent + the functionality in QPainter. It can therefore be an excellent substitute for the default raster-based QPaintEngine on hardware that supports OpenVG. + \tableofcontents + \section1 Building Qt with OpenVG support OpenVG support can be enabled by passing the \c{-openvg} option @@ -319,6 +317,6 @@ QPixmap, and will not be accelerated. This issue may be addressed in a future version of the engine. - ShivaVG support is highly experimental and limited to Qt/X11. It is + ShivaVG support is highly experimental and limited to Qt/X11. It is provided as an example of how to integrate a non-EGL engine. - */ +*/ diff --git a/doc/src/qtdesigner.qdoc b/doc/src/howtos/qtdesigner.qdoc index 00af297..ae84f93 100644 --- a/doc/src/qtdesigner.qdoc +++ b/doc/src/howtos/qtdesigner.qdoc @@ -40,33 +40,9 @@ ****************************************************************************/ /*! - \module QtDesigner - \title QtDesigner Module - \contentspage Qt's Modules - \previouspage Qt3Support - \nextpage QtUiTools - \ingroup modules - - \brief The QtDesigner module provides classes that allow you to - create your own custom widget plugins for Qt Designer, and classes - that enable you to access Qt Designer's components. - - In addition, the QFormBuilder class provides the possibility of - constructing user interfaces from UI files at run-time. - - To include the definitions of the module's classes, use the - following directive: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 0 - - To link against the module, add this line to your \c qmake .pro - file: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 1 - - \note These classes are part of the \l{Open Source Versions of Qt} and - \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial - users. + \page qtdesigner-components.html + \title Creating and Using Components for Qt Designer + \ingroup best-practices \tableofcontents diff --git a/doc/src/howtos/restoring-geometry.qdoc b/doc/src/howtos/restoring-geometry.qdoc new file mode 100644 index 0000000..c9e6f4f --- /dev/null +++ b/doc/src/howtos/restoring-geometry.qdoc @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page restoring-geometry.html + \title Restoring a Window's Geometry + + \ingroup best-practices + + This document describes how to save and restore a window's + geometry using the geometry properties. On Windows, this is + basically storing the result of QWidget::geometry() and calling + QWidget::setGeometry() in the next session before calling + \l{QWidget::show()}{show()}. + + On X11, this won't work because an invisible window doesn't have + a frame yet. The window manager will decorate the window later. + When this happens, the window shifts towards the bottom/right + corner of the screen depending on the size of the decoration frame. + Although X provides a way to avoid this shift, most window managers + fail to implement this feature. + + Since version 4.2, Qt provides functions that saves and restores a + window's geometry and state for you. QWidget::saveGeometry() + saves the window geometry and maximized/fullscreen state, while + QWidget::restoreGeometry() restores it. The restore function also + checks if the restored geometry is outside the available screen + geometry, and modifies it as appropriate if it is. + + If those functions are not available or cannot be used, then a + workaround is to call \l{QWidget::setGeometry()}{setGeometry()} + after \l{QWidget::show()}{show()}. This has the two disadvantages + that the widget appears at a wrong place for a millisecond + (results in flashing) and that currently only every second window + manager gets it right. A safer solution is to store both + \l{QWidget::pos()}{pos()} and \l{QWidget::size()}{size()} and to + restore the geometry using \l{QWidget::resize()} and + \l{QWidget::move()}{move()} before calling + \l{QWidget::show()}{show()}, as demonstrated in the following + code snippets (from the \l{mainwindows/application}{Application} + example): + + \snippet examples/mainwindows/application/mainwindow.cpp 35 + \codeline + \snippet examples/mainwindows/application/mainwindow.cpp 38 + + This method works on Windows, Mac OS X, and most X11 window + managers. +*/ diff --git a/doc/src/session.qdoc b/doc/src/howtos/session.qdoc index 3e4bff3..8e51b6b 100644 --- a/doc/src/session.qdoc +++ b/doc/src/howtos/session.qdoc @@ -42,7 +42,8 @@ /*! \page session.html \title Session Management - \ingroup gui-programming + + \ingroup best-practices A \e session is a group of running applications, each of which has a particular state. The session is controlled by a service called the \e diff --git a/doc/src/sharedlibrary.qdoc b/doc/src/howtos/sharedlibrary.qdoc index de27c43..1e108a6 100644 --- a/doc/src/sharedlibrary.qdoc +++ b/doc/src/howtos/sharedlibrary.qdoc @@ -39,22 +39,12 @@ ** ****************************************************************************/ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - /*! - \group deployment \page sharedlibrary.html - \ingroup buildsystem - \title Creating Shared Libraries + + \ingroup best-practices + The following sections list certain things that should be taken into account when creating shared libraries. diff --git a/doc/src/timers.qdoc b/doc/src/howtos/timers.qdoc index c1e0023..ed46b76 100644 --- a/doc/src/timers.qdoc +++ b/doc/src/howtos/timers.qdoc @@ -42,9 +42,10 @@ /*! \page timers.html \title Timers - \ingroup architecture \brief How to use timers in your application. + \ingroup best-practices + QObject, the base class of all Qt objects, provides the basic timer support in Qt. With QObject::startTimer(), you start a timer with an interval in milliseconds as argument. The function diff --git a/doc/src/unix-signal-handlers.qdoc b/doc/src/howtos/unix-signal-handlers.qdoc index cecd3f9..4e123bc 100644 --- a/doc/src/unix-signal-handlers.qdoc +++ b/doc/src/howtos/unix-signal-handlers.qdoc @@ -42,9 +42,11 @@ /*! \page unix-signals.html \title Calling Qt Functions From Unix Signal Handlers - \ingroup platform-notes \brief You can't. But don't despair, there is a way... + \ingroup platform-specific + \ingroup best-practices + You \e can't call Qt functions from Unix signal handlers. The standard POSIX rule applies: You can only call async-signal-safe functions from signal handlers. See \l diff --git a/doc/src/images/activeqt-examples.png b/doc/src/images/activeqt-examples.png Binary files differnew file mode 100644 index 0000000..bda8eba --- /dev/null +++ b/doc/src/images/activeqt-examples.png diff --git a/doc/src/images/animation-examples.png b/doc/src/images/animation-examples.png Binary files differnew file mode 100644 index 0000000..bfc5990 --- /dev/null +++ b/doc/src/images/animation-examples.png diff --git a/doc/src/images/ipc-examples.png b/doc/src/images/ipc-examples.png Binary files differnew file mode 100644 index 0000000..815aed3 --- /dev/null +++ b/doc/src/images/ipc-examples.png diff --git a/doc/src/images/qq-thumbnail.png b/doc/src/images/qq-thumbnail.png Binary files differnew file mode 100644 index 0000000..295ef13 --- /dev/null +++ b/doc/src/images/qq-thumbnail.png diff --git a/doc/src/images/statemachine-examples.png b/doc/src/images/statemachine-examples.png Binary files differnew file mode 100644 index 0000000..b2ec66e --- /dev/null +++ b/doc/src/images/statemachine-examples.png diff --git a/doc/src/images/webkit-examples.png b/doc/src/images/webkit-examples.png Binary files differindex 55bbd92..23ddf1c 100644 --- a/doc/src/images/webkit-examples.png +++ b/doc/src/images/webkit-examples.png diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index 962e63d..b0695b8 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -41,195 +41,124 @@ /*! \page index.html - \keyword Qt Reference Documentation - \if defined(qtopiacore) - \if defined(opensourceedition) - \title Qt for Embedded Linux Reference Documentation (Open Source Edition) - \endif - - \if defined(desktoplightedition) - \title Qt for Embedded Linux Reference Documentation (GUI Framework Edition) - \endif - - \if defined(desktopedition) - \title Qt for Embedded Linux Reference Documentation (Full Framework Edition) - \endif - - \if !defined(opensourceedition) \ - && !defined(desktoplightedition) \ - && !defined(desktopedition) - \title Qt for Embedded Linux Reference Documentation - \endif - - \subtitle Qt for Embedded Linux + \if defined(opensourceedition) + \title Qt Reference Documentation (Open Source Edition) \endif - \if !defined(qtopiacore) - \if defined(opensourceedition) - \title Qt Reference Documentation (Open Source Edition) - \endif - - \if defined(desktoplightedition) - \title Qt Reference Documentation (GUI Framework Edition) - \endif - \if defined(desktopedition) - \title Qt Reference Documentation (Full Framework Edition) - \endif + \if defined(desktoplightedition) + \title Qt Reference Documentation (GUI Framework Edition) + \endif - \if !defined(opensourceedition) \ - && !defined(desktoplightedition) \ - && !defined(desktopedition) - \title Qt Reference Documentation - \endif + \if defined(desktopedition) + \title Qt Reference Documentation (Full Framework Edition) \endif + \if !defined(opensourceedition) \ + && !defined(desktoplightedition) \ + && !defined(desktopedition) + \title Qt Reference Documentation + \endif + \raw HTML - <table cellpadding="2" cellspacing="1" border="0" width="100%" class="indextable"> + <table cellpadding="2" cellspacing="1" border="0" width="95%" class="indextable" align="center"> <tr> <th class="titleheader" width="33%"> - Getting Started - </th> + Getting Started</th> <th class="titleheader" width="33%"> - General - </th> + API Reference</th> <th class="titleheader" width="33%"> - Developer Resources - </th> + Working with Qt</th> </tr> <tr> <td valign="top"> <ul> - <li><strong><a href="qt4-5-intro.html">What's New in Qt 4.5</a></strong></li> - <li><a href="how-to-learn-qt.html">How to Learn Qt</a></li> - <li><a href="installation.html">Installation</a></li> - <li><a href="tutorials.html">Tutorials</a>, <a href="examples.html">Examples</a> and <a href="demos.html">Demonstrations</a></li> - <li><a href="porting4.html">Porting from Qt 3 to Qt 4</a></li> + <li><a href="installation.html">Installation</a> and <a href="how-to-learn-qt.html">First Steps with Qt</a></li> + <li><a href="tutorials.html">Tutorials</a> and <a href="examples.html">Examples</a></li> + <li><a href="demos.html">Demonstrations</a> and <a href="qt4-5-intro.html"><b>New in Qt 4.5</b></a></li> </ul> </td> <td valign="top"> <ul> - <li><a href="http://qt.nokia.com/products">About Qt</a></li> - <li><a href="http://qt.nokia.com/about">About Us</a></li> - <li><a href="commercialeditions.html">Commercial Edition</a></li> - <li><a href="opensourceedition.html">Open Source Edition</a></li> - <li><a href="supported-platforms.html">Supported Platforms</a></li> + <li><a href="classlists.html">C++ Class Documentation</a></li> + <li><a href="frameworks-technologies.html">Frameworks and Technologies</a></li> + <li><a href="best-practices.html">How-To's and Best Practices</a></li> </ul> </td> <td valign="top"> <ul> - <li><a href="http://qt.nokia.com/developer/faqs/">Frequently Asked Questions</a></li> - <li><a href="http://qt.nokia.com/developer/community/">Qt Community Web Sites</a></li> - <li><a href="http://qt.nokia.com/doc/qq/">Qt Quarterly</a></li> - <li><a href="bughowto.html">How to Report a Bug</a></li> - <li><a href="http://qt.nokia.com/developer/">Other Online Resources</a></li> + <li><a href="developing-with-qt.html">Cross-Platform Development with Qt</a></li> + <li><a href="qtestlib-manual.html">Unit Testing</a> and <a href="debug.html">Debugging</a></li> + <li><a href="deployment.html">Deploying Qt Applications</a></li> </ul> </td> </tr> <tr> - <th class="titleheader"> - API Reference - </th> - <th class="titleheader"> - Core Features - </th> - <th class="titleheader"> - Key Technologies - </th> + <th class="largeheader"> + Fundamentals</th> + <th class="largeheader"> + User Interface Design</th> + <th class="largeheader"> + Technologies</th> </tr> <tr> - <td valign="top"> + <td valign="top" class="largeindex"> <ul> - <li><a href="classes.html">All Classes</a></li> - <li><a href="mainclasses.html">Main Classes</a></li> - <li><a href="groups.html">Grouped Classes</a></li> - <li><a href="annotated.html">Annotated Classes</a></li> - <li><a href="modules.html">Qt Classes by Module</a></li> - <li><a href="namespaces.html">All Namespaces</a></li> - <li><a href="hierarchy.html">Inheritance Hierarchy</a></li> - <li><a href="functions.html">All Functions</a></li> - <li><a href="qt-embedded.html">Qt for Embedded Platforms</a></li> - <li><a href="overviews.html">All Overviews and HOWTOs</a></li> - <li><a href="gallery.html">Qt Widget Gallery</a></li> - <li><a href="qtglobal.html">Qt Global Declarations</a></li> + <li><a href="object.html">The Qt Object Model</a></li> + <li><a href="eventsandfilters.html">Event System</a></li> + <li><a href="threads.html">Threading</a></li> + <li><a href="internationalization.html">Internationalization</a></li> + <li><a href="platform-specific.html">Platform Specifics</a></li> </ul> </td> - <td valign="top"> + <td valign="top" class="largeindex"> <ul> - <li><a href="signalsandslots.html">Signals and Slots</a></li> - <li><a href="object.html">Object Model</a></li> - <li><a href="layout.html">Layout Management</a></li> - <li><a href="qt4-mainwindow.html">Main Window Architecture</a></li> - <li><a href="paintsystem.html">Paint System</a></li> - <li><a href="graphicsview.html">Graphics View</a></li> - <li><a href="accessible.html">Accessibility</a></li> - <li><a href="containers.html">Tool and Container Classes</a></li> - <li><a href="richtext.html">Rich Text Processing</a></li> - <li><a href="i18n.html">Internationalization</a></li> - <li><a href="plugins-howto.html">Plugin System</a></li> - <li><a href="threads.html">Multithreaded Programming</a></li> - <li><a href="ipc.html">Inter-Process Communication (IPC)</a></li> - <li><a href="qtestlib-manual.html">Unit Testing Framework</a></li> + <li><a href="widgets-and-layouts.html">Widgets and Layouts</a></li> + <li><a href="application-windows.html">Application Windows</a></li> + <li><a href="paintsystem.html">Painting and Printing</a></li> + <li><a href="graphicsview.html">Canvas UI with Graphics View</a></li> + <li><a href="webintegration.html">Integrating Web Content</a></li> </ul> </td> - <td valign="top"> + <td valign="top" class="largeindex"> <ul> - <li><a href="model-view-programming.html">Model/View Programming</a></li> - <li><a href="stylesheet.html">Style Sheets</a></li> - <li><a href="qthelp.html">Help Module</a></li> - <li><a href="qtnetwork.html">Network Module</a></li> - <li><a href="qtopengl.html">OpenGL Module</a></li> - <li><a href="qtopenvg.html">OpenVG Module</a></li> - <li><a href="qtscript.html">Script Module</a></li> - <li><a href="qtsql.html">SQL Module</a></li> - <li><a href="qtsvg.html">SVG Module</a></li> - <li><a href="qtwebkit.html">WebKit Integration</a></li> - <li><a href="qtxml.html">XML Module</a></li> - <li><a href="qtxmlpatterns.html">XML Patterns: XQuery & XPath</a></li> - <li><a href="phonon-module.html">Phonon Multimedia Framework</a></li> - <li><a href="qtscripttools.html">Script Tools Module</a></li> - <li><a href="activeqt.html">ActiveQt Framework</a></li> + <li><a href="io.html">Input/Output</a> and <a href="resources.html">Resources</a></li> + <li><a href="network-programming.html">Network Programming</a></li> + <li><a href="sql-programming.html">SQL Development</a></li> + <li><a href="xml-processing.html">XML Processing</a></li> + <li><a href="scripting.html">Scripting</a></li> </ul> </td> </tr> <tr> <th class="titleheader"> - Add-ons & Services - </th> + Community and Resources</th> <th class="titleheader"> - Tools - </th> + Contributing</th> <th class="titleheader"> - Licenses & Credits - </th> + Licenses</th> </tr> <tr> <td valign="top"> <ul> - <li><a href="http://qt.nokia.com/products/add-on-products">Qt Solutions</a></li> - <li><a href="http://qt.nokia.com/products/appdev">Partner Add-ons</a></li> - <li><a href="http://qt-apps.org">Third-Party Qt Components (qt-apps.org)</a></li> - <li><a href="http://qt.nokia.com/support-services/support-services/">Support</a></li> - <li><a href="http://qt.nokia.com/support-services/training/">Training</a></li> + <li><a href="http://qt.nokia.com/developer">Online Resources</a></li> + <li><a href="http://labs.qt.nokia.com/blogs">Developer Blogs</a></li> + <li><a href="http://qt.nokia.com/support-services">Support</a>, <a href="http://qt.nokia.com/services-partners">Training and Services</a></li> </ul> </td> <td valign="top"> <ul> - <li><a href="designer-manual.html">Qt Designer</a></li> - <li><a href="assistant-manual.html">Qt Assistant</a></li> - <li><a href="linguist-manual.html">Qt Linguist</a></li> - <li><a href="qmake-manual.html">qmake</a></li> - <li><a href="qttools.html">All Tools</a></li> + <li><a href="bughowto.html">Report Bugs and Make Suggestions</a></li> + <li><a href="http://qt.gitorious.org">Open Repository</a></li> + <li><a href="credits.html">Credits</a></li> </ul> </td> <td valign="top"> <ul> - <li><a href="gpl.html">GNU GPL</a>, <a href="lgpl.html">GNU LGPL</a></li> - <li><a href="3rdparty.html">Third-Party Licenses Used in Qt</a></li> - <li><a href="licenses.html">Other Licenses Used in Qt</a></li> - <li><a href="trademarks.html">Trademark Information</a></li> - <li><a href="credits.html">Credits</a></li> + <li><a href="gpl.html">GNU GPL</a>, <a href="lgpl.html">GNU LGPL</a></li> + <li><a href="commercialeditions.html">Commercial Editions</a></li> + <li><a href="licensing.html">Licenses Used in Qt</a></li> </ul> </td> </tr> diff --git a/doc/src/i18n.qdoc b/doc/src/internationalization/i18n.qdoc index 22f82be..25c35c7 100644 --- a/doc/src/i18n.qdoc +++ b/doc/src/internationalization/i18n.qdoc @@ -41,9 +41,12 @@ /*! \group i18n - \title Internationalization with Qt - \ingroup topics + \title Qt Classes for Internationalization +*/ +/*! + \page internationalization.html + \title Internationalization with Qt \brief Information about Qt's support for internationalization and multiple languages. \keyword internationalization @@ -53,6 +56,14 @@ the application usable by people in countries other than one's own. \tableofcontents + + \section1 Relevant Qt Classes and APIs + + These classes support internationalizing of Qt applications. + + \annotatedlist i18n + + \section1 Languages and Writing Systems In some cases internationalization is simple, for example, making a US application accessible to Australian or British users may require @@ -501,8 +512,4 @@ For details on Mac-specific translation, refer to the Qt/Mac Specific Issues document \l{Qt for Mac OS X - Specific Issues#Translating the Application Menu and Native Dialogs}{here}. - - \section1 Relevant Qt Classes - - These classes are relevant to internationalizing Qt applications. */ diff --git a/doc/src/linguist-manual.qdoc b/doc/src/internationalization/linguist-manual.qdoc index a67d65a..a67d65a 100644 --- a/doc/src/linguist-manual.qdoc +++ b/doc/src/internationalization/linguist-manual.qdoc diff --git a/doc/src/legal/commercialeditions.qdoc b/doc/src/legal/commercialeditions.qdoc index 93c1bc0..761a53b 100644 --- a/doc/src/legal/commercialeditions.qdoc +++ b/doc/src/legal/commercialeditions.qdoc @@ -54,8 +54,7 @@ If you want to develop Free or Open Source software for release using a recognized Open Source license, you can use the \l{Open Source Versions of Qt}. - The table below summarizes the differences between the three - commercial editions: + The table below summarizes the differences between the two commercial editions: \table 75% \header \o{1,2} Features \o{2,1} Editions diff --git a/doc/src/legal/editions.qdoc b/doc/src/legal/editions.qdoc index cf1534d..f29322d 100644 --- a/doc/src/legal/editions.qdoc +++ b/doc/src/legal/editions.qdoc @@ -39,18 +39,6 @@ ** ****************************************************************************/ -/**************************************************************************** -** -** Documentation of Qt editions. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - /*! \page editions.html \title Qt Editions diff --git a/doc/src/legal/licenses.qdoc b/doc/src/legal/licenses.qdoc index 7414667..7a15f31 100644 --- a/doc/src/legal/licenses.qdoc +++ b/doc/src/legal/licenses.qdoc @@ -42,7 +42,6 @@ /*! \group licensing \title Licensing Information - \ingroup topics \brief Information about licenses and licensing issues. These documents include information about Qt's licenses and the licenses diff --git a/doc/src/modules.qdoc b/doc/src/modules.qdoc index 9b0e58a..2fc6eaf 100644 --- a/doc/src/modules.qdoc +++ b/doc/src/modules.qdoc @@ -44,15 +44,17 @@ \title Qt's Modules \startpage index.html Qt Reference Documentation \nextpage QtCore + + \ingroup classlists Qt 4 consists of several modules, each of which lives in a separate library. - Modules for general software development: - \table 80% + \header \o {2,1} \bold{Modules for general software development} \row \o \l{QtCore} \o Core non-graphical classes used by other modules \row \o \l{QtGui} \o Graphical user interface (GUI) components + \row \o \l{QtMultimedia} \o Classes for low-level multimedia functionality \row \o \l{QtNetwork} \o Classes for network programming \row \o \l{QtOpenGL} \o OpenGL support classes \row \o \l{QtOpenVG} \o OpenVG support classes @@ -65,30 +67,15 @@ \row \o \l{QtXmlPatterns} \o An XQuery & XPath engine for XML and custom data models \row \o \l{Phonon Module}{Phonon} \o Multimedia framework classes \row \o \l{Qt3Support} \o Qt 3 compatibility classes - \endtable - - Modules for working with Qt's tools: - - \table 80% + \header \o {2,1} \bold{Modules for working with Qt's tools} \row \o \l{QtDesigner} \o Classes for extending \QD \row \o \l{QtUiTools} \o Classes for handling \QD forms in applications \row \o \l{QtHelp} \o Classes for online help - \row \o \l{QtAssistant} \o Support for online help \row \o \l{QtTest} \o Tool classes for unit testing - \endtable - - The following extension modules are available in the \l{Qt - Commercial Editions} on Windows: - - \table 80% + \header \o {2,1} \bold{Modules for Windows developers} \row \o \l{QAxContainer} \o Extension for accessing ActiveX controls \row \o \l{QAxServer} \o Extension for writing ActiveX servers - \endtable - - The following extension module is available in all \l {Qt Editions} - on Unix platforms: - - \table 80% + \header \o {2,1} \bold{Modules for Unix developers} \row \o \l{QtDBus} \o Classes for Inter-Process Communication using the D-Bus \endtable @@ -98,9 +85,928 @@ \snippet doc/src/snippets/code/doc_src_modules.qdoc 0 - On Windows, if you do not use \l qmake, the \l{Visual Studio Integration} - available to \l{Qt Commercial Editions}{commercial licensees}, or other - build tools such as CMake, you also need to link against the \c qtmain library. + On Windows, if you do not use \l qmake + or other build tools such as CMake, you also need to link against + the \c qtmain library. \sa {Qt's Classes} */ + +/*! + \module QtCore + \title QtCore Module + \contentspage Qt's Modules + \previouspage Qt's Modules + \nextpage QtGui + \ingroup modules + + \keyword QtCore + + \brief The QtCore module contains core non-GUI functionality. + + All other Qt modules rely on this module. To include the + definitions of the module's classes, use the following directive: + + \snippet doc/src/snippets/code/doc_src_qtcore.qdoc 0 + + The QtCore module is part of all \l{Qt editions}. +*/ + + +/*! + \module QtGui + \title QtGui Module + \contentspage Qt's Modules + \previouspage QtCore + \nextpage QtNetwork + \ingroup modules + + \brief The QtGui module extends QtCore with GUI functionality. + + To include the definitions of both modules' classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qtgui.qdoc 0 + + The QtGui module is part of the \l{Qt GUI Framework Edition}, + the \l{Qt Full Framework Edition}, and the \l{Open Source Versions of Qt}. +*/ + +/*! + \module QtMultimedia + \title QtMultimedia Module + \contentspage Qt's Modules + \previouspage QtCore + \nextpage QtNetwork + \ingroup modules + + \brief The QtMultimedia module provides low-level multimedia functionality. + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qtmultimedia.qdoc 1 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc/src/snippets/code/doc_src_qtmultimedia.qdoc 0 + + The functionality provided by the \l{Phonon Module} is on a higher level + and in many cases more suitable for application developers. +*/ + +/*! + \module QtNetwork + \title QtNetwork Module + \contentspage Qt's Modules + \previouspage QtMultimedia + \nextpage QtOpenGL + \ingroup modules + + \brief The QtNetwork module provides classes to make network programming + easier and portable. + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qtnetwork.qdoc 1 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc/src/snippets/code/doc_src_qtnetwork.qdoc 0 + + The QtNetwork module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. +*/ + +/*! + \module QtOpenGL + \title QtOpenGL Module + \contentspage Qt's Modules + \previouspage QtNetwork + \nextpage QtOpenVG + \ingroup modules + + \brief The QtOpenGL module offers classes that make it easy to + use OpenGL in Qt applications. + + OpenGL is a standard API for rendering 3D graphics. OpenGL only + deals with 3D rendering and provides little or no support for GUI + programming issues. The user interface for an OpenGL application + must be created with another toolkit, such as Motif on the X + platform, Microsoft Foundation Classes (MFC) under Windows, or Qt + on both platforms. + + \note OpenGL is a trademark of Silicon Graphics, Inc. in + the United States and other countries. + + The Qt OpenGL module makes it easy to use OpenGL in Qt applications. + It provides an OpenGL widget class that can be used just like any + other Qt widget, except that it opens an OpenGL display buffer where + you can use the OpenGL API to render the contents. + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qtopengl.qdoc 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc/src/snippets/code/doc_src_qtopengl.qdoc 1 + + The Qt OpenGL module is implemented as a platform-independent Qt/C++ + wrapper around the platform-dependent GLX (version 1.3 or later), + WGL, or AGL C APIs. Although the basic functionality provided is very + similar to Mark Kilgard's GLUT library, applications using the Qt + OpenGL module can take advantage of the whole Qt API for + non-OpenGL-specific GUI functionality. + + The QtOpenGL module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. It is available on Windows, X11, and Mac OS X. + \l{Qt for Embedded Linux} supports OpenGL ES (OpenGL for Embedded Systems). + To be able to use the OpenGL API in \l{Qt for Embedded Linux}, it must be + integrated with the Q Window System (QWS). See the + \l{Qt for Embedded Linux and OpenGL} documentation for details. +*/ + +/*! + \module QtOpenVG + \title QtOpenVG Module + \since 4.6 + \contentspage Qt's Modules + \previouspage QtOpenGL + \nextpage QtScript + \ingroup modules + + \brief The QtOpenVG module is a plugin that provides support for + OpenVG painting. + + OpenVG is a standard API from the + \l{http://www.khronos.org/openvg}{Khronos Group} for accelerated + 2D vector graphics that is appearing in an increasing number of + embedded devices. + + OpenVG support can be enabled by passing the \c{-openvg} option + to configure. It is assumed that the following qmake variables + are set to appropriate values in the qmake.conf file for your + platform: + + \list + \o QMAKE_INCDIR_OPENVG + \o QMAKE_LIBDIR_OPENVG + \o QMAKE_LIBS_OPENVG + \endlist + + Most OpenVG implementations are based on EGL, so the following + variables may also need to be set: + + \list + \o QMAKE_INCDIR_EGL + \o QMAKE_LIBDIR_EGL + \o QMAKE_LIBS_EGL + \endlist + + See \l{qmake Variable Reference} for more information on these variables. + + Two kinds of OpenVG engines are currently supported: EGL based, + and engines built on top of OpenGL such as + \l{http://sourceforge.net/projects/shivavg}{ShivaVG}. + EGL based engines are preferred. + + Once the graphics system plugin has been built and installed, + applications can be run as follows to use the plugin: + + \code + app -graphicssystem OpenVG + \endcode + + If ShivaVG is being used, then substitute \c ShivaVG instead of + \c OpenVG in the line above. +*/ + +/*! + \module QtScript + \title QtScript Module + \since 4.3 + \contentspage Qt's Modules + \previouspage QtOpenVG + \nextpage QtScriptTools + \ingroup modules + + \brief The QtScript module provides classes for making Qt applications scriptable. + + The QtScript module only provides core scripting facilities; the + QtScriptTools module provides additional Qt Script-related + components that application developers may find useful. + + \tableofcontents + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 0 + + To link against the module, add this line to your \l qmake \c .pro file: + + \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 1 + + The QtScript module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. +*/ + +/*! + \module QtScriptTools + \title QtScriptTools Module + \since 4.5 + \contentspage Qt's Modules + \previouspage QtScript + \nextpage QtSql + \ingroup modules + + \brief The QtScriptTools module provides additional components for applications that use Qt Script. + + \tableofcontents + + \section1 Configuring the Build Process + + Applications that use the Qt Script Tools classes need to + be configured to be built against the QtScriptTools module. + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc.src.qtscripttools.qdoc 0 + + To link against the module, add this line to your \l qmake \c .pro file: + + \snippet doc/src/snippets/code/doc.src.qtscripttools.qdoc 1 + + The QtScriptTools module is part of the \l{Qt Full Framework Edition} and + the \l{Open Source Versions of Qt}. +*/ + +/*! + \module QtSql + \title QtSql Module + \contentspage Qt's Modules + \previouspage QtScript + \nextpage QtSvg + \ingroup modules + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qtsql.qdoc 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc/src/snippets/code/doc_src_qtsql.qdoc 1 + + The QtSql module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. +*/ + +/*! + \module QtSvg + \title QtSvg Module + \since 4.1 + \contentspage Qt's Modules + \previouspage QtSql + \nextpage QtWebKit + \ingroup modules + + \brief The QtSvg module provides classes for displaying the contents of SVG + files. + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qtsvg.qdoc 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc/src/snippets/code/doc_src_qtsvg.qdoc 1 + + The QtSvg module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. + + \section1 License Information + + Some code for arc handling in this module is derived from code with + the following license: + + \legalese + Copyright 2002 USC/Information Sciences Institute + + Permission to use, copy, modify, distribute, and sell this software + and its documentation for any purpose is hereby granted without + fee, provided that the above copyright notice appear in all copies + and that both that copyright notice and this permission notice + appear in supporting documentation, and that the name of + Information Sciences Institute not be used in advertising or + publicity pertaining to distribution of the software without + specific, written prior permission. Information Sciences Institute + makes no representations about the suitability of this software for + any purpose. It is provided "as is" without express or implied + warranty. + + INFORMATION SCIENCES INSTITUTE DISCLAIMS ALL WARRANTIES WITH REGARD + TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL INFORMATION SCIENCES + INSTITUTE BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL + DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA + OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER + TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR + PERFORMANCE OF THIS SOFTWARE. + \endlegalese +*/ + +/*! + \module QtXml + \title QtXml Module + \contentspage Qt's Modules + \previouspage QtSvg + \nextpage QtXmlPatterns + \ingroup modules + + \brief The QtXml module provides a stream reader and writer for + XML documents, and C++ implementations of SAX and DOM. + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 1 + + Further XML support is provided by the \l{Qt Solutions} group who + provide, for example, classes that support SOAP and MML with the + Qt XML classes. + + This module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. +*/ + +/*! + \module QtXmlPatterns + \title QtXmlPatterns Module + \since 4.4 + \contentspage Qt's Modules + \previouspage QtXml + \nextpage Phonon Module + \ingroup modules + + \brief The QtXmlPatterns module provides support for XPath, + XQuery, XSLT and XML schema-validation. + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 1 + + This module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. + + \section1 License Information + + The XML Schema implementation provided by this module contains the \c xml.xsd file + (located in \c{src/xmlpatterns/schema/schemas}) which is licensed under the terms + given below. This module is always built with XML Schema support enabled. + + \legalese + W3C\copyright SOFTWARE NOTICE AND LICENSE + + This license came from: http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 + + This work (and included software, documentation such as READMEs, or other + related items) is being provided by the copyright holders under the following + license. By obtaining, using and/or copying this work, you (the licensee) + agree that you have read, understood, and will comply with the following + terms and conditions. + + Permission to copy, modify, and distribute this software and its + documentation, with or without modification, for any purpose and without + fee or royalty is hereby granted, provided that you include the following on + ALL copies of the software and documentation or portions thereof, including + modifications: + + 1. The full text of this NOTICE in a location viewable to users of the + redistributed or derivative work.\br + 2. Any pre-existing intellectual property disclaimers, notices, or terms + and conditions. If none exist, the W3C Software Short Notice should be + included (hypertext is preferred, text is permitted) + within the body of any redistributed or derivative code.\br + 3. Notice of any changes or modifications to the files, including the date + changes were made. (We recommend you provide URIs to the location from + which the code is derived.) + + THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS + MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT + LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR + PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE + ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. + + COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR + CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR + DOCUMENTATION. + + The name and trademarks of copyright holders may NOT be used in + advertising or publicity pertaining to the software without specific, written + prior permission. Title to copyright in this software and any associated + documentation will at all times remain with copyright holders. + \endlegalese +*/ + +/*! + \page phonon-module.html + \module Phonon + \title Phonon Module + \contentspage Qt's Modules + \previouspage QtXmlPatterns + \nextpage Qt3Support + \ingroup modules + + \brief The Phonon module contains namespaces and classes for multimedia functionality. + + \generatelist{classesbymodule Phonon} + + Phonon is a cross-platform multimedia framework that enables the use of + audio and video content in Qt applications. The \l{Phonon Overview} + document provides an introduction to the architecture and features included + in Phonon. The \l{Phonon} namespace contains a list of all classes, functions + and namespaces provided by the module. + + Applications that use Phonon's classes need to + be configured to be built against the Phonon module. + The following declaration in a \c qmake project file ensures that + an application is compiled and linked appropriately: + + \snippet doc/src/snippets/code/doc_src_phonon.qdoc 1 + + The Phonon module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. + + \section1 Qt Backends + + Qt Backends are currently developed for Phonon version 4.1. The Phonon + project has moved on and introduced new features that the Qt Backends do not + implement. We have chosen not to document the part of Phonon that we do not + support. Any class or function not appearing in our documentation can be + considered unsupported. + + \section1 License Information + + Qt Commercial Edition licensees that wish to distribute applications that + use the Phonon module need to be aware of their obligations under the + GNU Lesser General Public License (LGPL). + + Developers using the Open Source Edition can choose to redistribute + the module under the appropriate version of the GNU LGPL; version 2.1 + for applications and libraries licensed under the GNU GPL version 2, + or version 3 for applications and libraries licensed under the GNU + GPL version 2. + + \legalese + This file is part of the KDE project + + Copyright (C) 2005-2007 Matthias Kretz <kretz@kde.org> \BR + 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. + \endlegalese +*/ + +/*! + \module Qt3Support + \title Qt3Support Module + \contentspage Qt's Modules + \previouspage Phonon Module + \nextpage QtDesigner + \ingroup modules + + \keyword Qt3Support + \brief The Qt3Support module provides classes that ease porting + from Qt 3 to Qt 4. + + \warning The classes in this module are intended to be used in + intermediate stages of a porting process and are not intended + to be used in production code. + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qt3support.qdoc 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc/src/snippets/code/doc_src_qt3support.qdoc 1 + + \note Since this module provides compatibility classes for + diverse parts of the Qt 3 API, it has dependencies on the QtCore, + QtGui, QtNetwork, QtSql, and QtXml modules. + + This module is part of the \l{Qt Full Framework Edition} and the + \l{Open Source Versions of Qt}. Most classes offered by this module are + also part of the \l{Qt GUI Framework Edition}. +\if defined(opensourceedition) || defined(desktoplightedition) + Classes that are not available for \l{Qt GUI Framework Edition} + users are marked as such in the class documentation. +\endif + + \sa {Porting to Qt 4} +*/ + +/*! + \module QtDesigner + \title QtDesigner Module + \contentspage Qt's Modules + \previouspage Qt3Support + \nextpage QtUiTools + \ingroup modules + + \brief The QtDesigner module provides classes that allow you to + create your own custom widget plugins for Qt Designer, and classes + that enable you to access Qt Designer's components. + + In addition, the QFormBuilder class provides the possibility of + constructing user interfaces from UI files at run-time. + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 0 + + To link against the module, add this line to your \c qmake .pro + file: + + \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 1 + + \note These classes are part of the \l{Open Source Versions of Qt} and + \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial + users. +*/ + +/*! + \module QtUiTools + \title QtUiTools Module + \since 4.1 + \contentspage Qt's Modules + \previouspage QtDesigner + \nextpage QtHelp + \ingroup modules + + \brief The QtUiTools module provides classes to handle forms created + with Qt Designer. + + These forms are processed at run-time to produce dynamically-generated + user interfaces. In order to generate a form at run-time, a resource + file containing a UI file is needed. Applications that use the + form handling classes need to be configured to be built against the + QtUiTools module. This is done by including the following declaration + in a \c qmake project file to ensure that the application is compiled + and linked appropriately. + + \snippet doc/src/snippets/code/doc_src_qtuiloader.qdoc 0 + + A form loader object, provided by the QUiLoader class, is used to + construct the user interface. This user interface can + be retrieved from any QIODevice; for example, a QFile object can be + used to obtain a form stored in a project's resources. The + QUiLoader::load() function takes the user interface description + contained in the file and constructs the form widget. + + To include the definitions of the module's classes, use the following + directive: + + \snippet doc/src/snippets/code/doc_src_qtuiloader.qdoc 1 + + \note These classes are part of the \l{Open Source Versions of Qt} and + \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial + users. + + \sa{Calculator Builder Example}, {World Time Clock Builder Example} +*/ + +/*! + \module QtHelp + \title QtHelp Module + \contentspage Qt's Modules + \previouspage QtUiTools + \nextpage QtTest + \ingroup modules + + \brief The QtHelp module provides classes for integrating + online documentation in applications. + + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 1 + + These classes are part of the \l{Open Source Versions of Qt} and + \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial + users. + + \section1 License Information + + The QtHelp module uses the CLucene indexing library to provide full-text + searching capabilities for Qt Assistant and applications that use the + features of QtHelp. + + Qt Commercial Edition licensees that wish to distribute applications that + use these features of the QtHelp module need to be aware of their + obligations under the GNU Lesser General Public License (LGPL). + + Developers using the Open Source Edition can choose to redistribute + the module under the appropriate version of the GNU LGPL; version 2.1 + for applications and libraries licensed under the GNU GPL version 2, + or version 3 for applications and libraries licensed under the GNU + GPL version 3. + + \legalese + Copyright (C) 2003-2006 Ben van Klinken and the CLucene Team \BR + Changes are Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + 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 + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + \endlegalese + + \sa {The Qt Help Framework} +*/ + +/*! + \module QtTest + \title QtTest Module + \contentspage Qt's Modules + \previouspage QtHelp + \nextpage QAxContainer + \ingroup modules + + \keyword QtTest + + \brief The QtTest module provides classes for unit testing Qt applications and libraries. + + Applications that use Qt's unit testing classes need to + be configured to be built against the QtTest module. + To include the definitions of the module's classes, use the + following directive: + + \snippet doc/src/snippets/code/doc_src_qttest.qdoc 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet doc/src/snippets/code/doc_src_qttest.qdoc 1 + + See the \l{QTestLib Manual} for a detailed introduction on how to use + Qt's unit testing features with your applications. + + The QtTest module is part of all \l{Qt editions}. +*/ + +/*! + \module QAxContainer + \title QAxContainer Module + \contentspage Qt's Modules + \previouspage QtTest + \nextpage QAxServer + \ingroup modules + + \brief The QAxContainer module is a Windows-only extension for + accessing ActiveX controls and COM objects. + + \section1 License Information + + The QAxContainer module is not covered by the \l{GNU General Public License (GPL)}, + the \l{GNU Lesser General Public License (LGPL)}, or the + \l{Qt Commercial Editions}{Qt Commercial License}. Instead, it is distributed under + the following license. + + \legalese + Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).\br + All rights reserved. + + Contact: Nokia Corporation (qt-info@nokia.com)\br + + You may use this file under the terms of the BSD license as follows:\br + + "Redistribution and use in source and binary forms, with or without modification, + are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, this list + of conditions and the following disclaimer.\br + * Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or other + materials provided with the distribution.\br + * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor the names of + its contributors may be used to endorse or promote products derived from this + software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT + SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." + \endlegalese +*/ + +/*! + \module QAxServer + \title QAxServer Module + \contentspage Qt's Modules + \previouspage QAxContainer + \nextpage QtDBus module + \ingroup modules + + \brief The QAxServer module is a Windows-only static library that + you can use to turn a standard Qt binary into a COM server. + + \section1 License Information + + The QAxContainer module is not covered by the \l{GNU General Public License (GPL)}, + the \l{GNU Lesser General Public License (LGPL)}, or the + \l{Qt Commercial Editions}{Qt Commercial License}. Instead, it is distributed under + the following license. + + \legalese + Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).\br + All rights reserved. + + Contact: Nokia Corporation (qt-info@nokia.com)\br + + You may use this file under the terms of the BSD license as follows:\br + + "Redistribution and use in source and binary forms, with or without modification, + are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, this list + of conditions and the following disclaimer.\br + * Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or other + materials provided with the distribution.\br + * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor the names of + its contributors may be used to endorse or promote products derived from this + software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT + SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." + \endlegalese +*/ + +/*! + \module QtDBus + \title QtDBus module + \contentspage Qt's Modules + \previouspage QAxServer + \ingroup modules + + \keyword QtDBus + \target The QDBus compiler + + \brief The QtDBus module is a Unix-only library that you can use + to make Inter-Process Communication using the \l {Introduction to + D-Bus} {D-Bus} protocol. + + Applications using the QtDBus module can provide services to + other, remote applications by exporting objects, as well as use + services exported by those applications by placing calls and + accessing properties. + + The QtDBus module provides an interface that extends the Qt \l + {signalsandslots.html}{Signals and Slots} mechanism, allowing one + to connect to a signal emitted remotely as well as to connect a + local signal to remote slot. + + To use this module, use the following code in your application: + + \snippet doc/src/snippets/code/doc_src_qtdbus.qdoc 0 + + If you're using qmake to build your application, you can add this + line to your .pro file to make it link against the QtDBus + libraries: + + \snippet doc/src/snippets/code/doc_src_qtdbus.qdoc 1 + + \note The source code for this module is located in the \c{src/qdbus} + directory. When installing Qt from source, this module is built when Qt's + tools are built. + + See the \l {Introduction to D-Bus} page for detailed information on + how to use this module. + + This module is part of all \l{Qt editions}. +*/ + +/*! + \page qtmain.html + \title The qtmain Library + \ingroup licensing + \ingroup platform-specific + \brief Describes the use and license of the qtmain helper library. + + qtmain is a helper library that enables the developer to write a + cross-platform main() function on Windows. If you do not use \l qmake + or other build tools such as CMake, then you need to link against + the \c qtmain library. + + \section1 License Information + + The QAxContainer module is not covered by the \l{GNU General Public License (GPL)}, + the \l{GNU Lesser General Public License (LGPL)}, or the + \l{Qt Commercial Editions}{Qt Commercial License}. Instead, it is distributed under + the following license. + + \legalese + Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).\br + All rights reserved. + + Contact: Nokia Corporation (qt-info@nokia.com)\br + + You may use this file under the terms of the BSD license as follows:\br + + "Redistribution and use in source and binary forms, with or without modification, + are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, this list + of conditions and the following disclaimer.\br + * Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or other + materials provided with the distribution.\br + * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor the names of + its contributors may be used to endorse or promote products derived from this + software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT + SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." + \endlegalese +*/ + +/*! + \page qtassistant.html + \title QtAssistant + + This module is no longer needed. Use the QtHelp module to integrate documentation + into your application. + + \sa {QtHelp} +*/ diff --git a/doc/src/qtnetwork.qdoc b/doc/src/network-programming/qtnetwork.qdoc index 7af99bf..0b2e6f9 100644 --- a/doc/src/qtnetwork.qdoc +++ b/doc/src/network-programming/qtnetwork.qdoc @@ -40,46 +40,32 @@ ****************************************************************************/ /*! - \module QtNetwork - \title QtNetwork Module - \contentspage Qt's Modules - \previouspage QtGui - \nextpage QtOpenGL - \ingroup modules + \group network + \title Network Programming API + \brief Classes for Network Programming - \brief The QtNetwork module offers classes that allow you to - write TCP/IP clients and servers. - - The network module provides classes to make network programming - easier and portable. It offers classes such as QFtp that - implement specific application-level protocols, lower-level classes - such as QTcpSocket, QTcpServer and QUdpSocket that represent low - level network concepts, and high level classes such as QNetworkRequest, - QNetworkReply and QNetworkAccessManager to perform network operations using common protocols. + \ingroup groups +*/ - The QtNetwork module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. +/*! + \page network-programming.html + \title Network Programming + \brief An Introduction to Network Programming with Qt - Topics: + The QtNetwork module offers classes that allow you to write TCP/IP clients + and servers. it offers classes such as QFtp that implement specific + application-level protocols, lower-level classes such as QTcpSocket, + QTcpServer and QUdpSocket that represent low level network concepts, + and high level classes such as QNetworkRequest, QNetworkReply and + QNetworkAccessManager to perform network operations using common protocols. \tableofcontents - \section1 Configuring the Build Process - - Applications that use Qt's networking classes need to - be configured to be built against the QtNetwork module. - The following declaration in a \c qmake project file ensures that - an application is compiled and linked appropriately: - - \snippet doc/src/snippets/code/doc_src_qtnetwork.qdoc 0 - - This line is necessary because only the QtCore and QtGui modules - are used in the default build process. + \section1 Qt's Classes for Network Programming - To include the definitions of the module's classes, use the - following directive: + The following classes provide support for network programming in Qt. - \snippet doc/src/snippets/code/doc_src_qtnetwork.qdoc 1 + \annotatedlist network \section1 High Level Network Operations for HTTP and FTP diff --git a/doc/src/classes/qpagesetupdialog.qdoc b/doc/src/network-programming/ssl.qdoc index 5715fa8..44d4196 100644 --- a/doc/src/classes/qpagesetupdialog.qdoc +++ b/doc/src/network-programming/ssl.qdoc @@ -40,45 +40,28 @@ ****************************************************************************/ /*! - \class QPageSetupDialog + \group ssl + \title Secure Sockets Layer (SSL) Classes + \ingroup groups - \brief The QPageSetupDialog class provides a configuration dialog - for the page-related options on a printer. + \brief Classes for secure communication over network sockets. + \keyword SSL - On Windows and Mac OS X the page setup dialog is implemented using - the native page setup dialogs. + The classes below provide support for secure network communication using + the Secure Sockets Layer (SSL) protocol, using the \l{OpenSSL Toolkit} to + perform encryption and protocol handling. - 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. + See the \l{General Qt Requirements} page for information about the + versions of OpenSSL that are known to work with Qt. - \sa QPrinter, QPrintDialog -*/ - - -/*! - \fn QPageSetupDialog::QPageSetupDialog(QPrinter *printer, QWidget *parent) + \note Due to import and export restrictions in some parts of the world, we + are unable to supply the OpenSSL Toolkit with Qt packages. Developers wishing + to use SSL communication in their deployed applications should either ensure + that their users have the appropriate libraries installed, or they should + consult a suitably qualified legal professional to ensure that applications + using code from the OpenSSL project are correctly certified for import + and export in relevant regions of the world. - Constructs a page setup dialog that configures \a printer with \a - parent as the parent widget. + When the QtNetwork module is built with SSL support, the library is linked + against OpenSSL in a way that requires OpenSSL license compliance. */ - -/*! - \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/metaobjects.qdoc b/doc/src/objectmodel/metaobjects.qdoc index c11cf4d..961a4c6 100644 --- a/doc/src/metaobjects.qdoc +++ b/doc/src/objectmodel/metaobjects.qdoc @@ -43,7 +43,6 @@ \page metaobjects.html \title Meta-Object System \brief An overview of Qt's meta-object system and introspection capabilities. - \ingroup architecture \keyword meta-object Qt's meta-object system provides the signals and slots mechanism for diff --git a/doc/src/object.qdoc b/doc/src/objectmodel/object.qdoc index 35d2ba3..a3c2292 100644 --- a/doc/src/object.qdoc +++ b/doc/src/objectmodel/object.qdoc @@ -42,9 +42,10 @@ /*! \page object.html \title Qt Object Model - \ingroup architecture \brief A description of the powerful features made possible by Qt's dynamic object model. + \ingroup frameworks-technologies + The standard C++ object model provides very efficient runtime support for the object paradigm. But its static nature is inflexibile in certain problem domains. Graphical user interface @@ -85,6 +86,12 @@ templates; see \l{Why Doesn't Qt Use Templates for Signals and Slots?} + \section1 Important Classes + + These classes form the basis of the Qt Object Model. + + \annotatedlist objectmodel + \target Identity vs Value \section1 Qt Objects: Identity vs Value diff --git a/doc/src/objectmodel/objecttrees.qdoc b/doc/src/objectmodel/objecttrees.qdoc new file mode 100644 index 0000000..bc5353f --- /dev/null +++ b/doc/src/objectmodel/objecttrees.qdoc @@ -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 documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page objecttrees.html + \title Object Trees and Object Ownership + \brief Information about the parent-child pattern used to describe + object ownership in Qt. + + \section1 Overview + + \link QObject QObjects\endlink organize themselves in object trees. + When you create a QObject with another object as parent, it's added to + the parent's \link QObject::children() children() \endlink list, and + is deleted when the parent is. It turns out that this approach fits + the needs of GUI objects very well. For example, a \l QShortcut + (keyboard shortcut) is a child of the relevant window, so when the + user closes that window, the shorcut is deleted too. + + \l QWidget, the base class of everything that appears on the screen, + extends the parent-child relationship. A child normally also becomes a + child widget, i.e. it is displayed in its parent's coordinate system + and is graphically clipped by its parent's boundaries. For example, + when the application deletes a message box after it has been + closed, the message box's buttons and label are also deleted, just as + we'd want, because the buttons and label are children of the message + box. + + You can also delete child objects yourself, and they will remove + themselves from their parents. For example, when the user removes a + toolbar it may lead to the application deleting one of its \l QToolBar + objects, in which case the tool bar's \l QMainWindow parent would + detect the change and reconfigure its screen space accordingly. + + The debugging functions \l QObject::dumpObjectTree() and \l + QObject::dumpObjectInfo() are often useful when an application looks or + acts strangely. + + \target note on the order of construction/destruction of QObjects + \section1 Construction/Destruction Order of QObjects + + When \l {QObject} {QObjects} are created on the heap (i.e., created + with \e new), a tree can be constructed from them in any order, and + later, the objects in the tree can be destroyed in any order. When any + QObject in the tree is deleted, if the object has a parent, the + destructor automatically removes the object from its parent. If the + object has children, the destructor automatically deletes each + child. No QObject is deleted twice, regardless of the order of + destruction. + + When \l {QObject} {QObjects} are created on the stack, the same + behavior applies. Normally, the order of destruction still doesn't + present a problem. Consider the following snippet: + + \snippet doc/src/snippets/code/doc_src_objecttrees.qdoc 0 + + The parent, \c window, and the child, \c quit, are both \l {QObject} + {QObjects} because QPushButton inherits QWidget, and QWidget inherits + QObject. This code is correct: the destructor of \c quit is \e not + called twice because the C++ language standard \e {(ISO/IEC 14882:2003)} + specifies that destructors of local objects are called in the reverse + order of their constructors. Therefore, the destructor of + the child, \c quit, is called first, and it removes itself from its + parent, \c window, before the destructor of \c window is called. + + But now consider what happens if we swap the order of construction, as + shown in this second snippet: + + \snippet doc/src/snippets/code/doc_src_objecttrees.qdoc 1 + + In this case, the order of destruction causes a problem. The parent's + destructor is called first because it was created last. It then calls + the destructor of its child, \c quit, which is incorrect because \c + quit is a local variable. When \c quit subsequently goes out of scope, + its destructor is called again, this time correctly, but the damage has + already been done. +*/ diff --git a/doc/src/properties.qdoc b/doc/src/objectmodel/properties.qdoc index cc28497..f640e31 100644 --- a/doc/src/properties.qdoc +++ b/doc/src/objectmodel/properties.qdoc @@ -42,7 +42,6 @@ /*! \page properties.html \title Qt's Property System - \ingroup architecture \brief An overview of Qt's property system. Qt provides a sophisticated property system similar to the ones diff --git a/doc/src/signalsandslots.qdoc b/doc/src/objectmodel/signalsandslots.qdoc index 07e0ef8..6bdd4bc 100644 --- a/doc/src/signalsandslots.qdoc +++ b/doc/src/objectmodel/signalsandslots.qdoc @@ -42,7 +42,6 @@ /*! \page signalsandslots.html \title Signals and Slots - \ingroup architecture \brief An overview of Qt's signals and slots inter-object communication mechanism. diff --git a/doc/src/objecttrees.qdoc b/doc/src/objecttrees.qdoc deleted file mode 100644 index 183f7cd..0000000 --- a/doc/src/objecttrees.qdoc +++ /dev/null @@ -1,117 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page objecttrees.html -\title Object Trees and Object Ownership -\ingroup architecture -\brief Information about the parent-child pattern used to describe -object ownership in Qt. - -\section1 Overview - -\link QObject QObjects\endlink organize themselves in object trees. -When you create a QObject with another object as parent, it's added to -the parent's \link QObject::children() children() \endlink list, and -is deleted when the parent is. It turns out that this approach fits -the needs of GUI objects very well. For example, a \l QShortcut -(keyboard shortcut) is a child of the relevant window, so when the -user closes that window, the shorcut is deleted too. - -\l QWidget, the base class of everything that appears on the screen, -extends the parent-child relationship. A child normally also becomes a -child widget, i.e. it is displayed in its parent's coordinate system -and is graphically clipped by its parent's boundaries. For example, -when the application deletes a message box after it has been -closed, the message box's buttons and label are also deleted, just as -we'd want, because the buttons and label are children of the message -box. - -You can also delete child objects yourself, and they will remove -themselves from their parents. For example, when the user removes a -toolbar it may lead to the application deleting one of its \l QToolBar -objects, in which case the tool bar's \l QMainWindow parent would -detect the change and reconfigure its screen space accordingly. - -The debugging functions \l QObject::dumpObjectTree() and \l -QObject::dumpObjectInfo() are often useful when an application looks or -acts strangely. - -\target note on the order of construction/destruction of QObjects -\section1 Construction/Destruction Order of QObjects - -When \l {QObject} {QObjects} are created on the heap (i.e., created -with \e new), a tree can be constructed from them in any order, and -later, the objects in the tree can be destroyed in any order. When any -QObject in the tree is deleted, if the object has a parent, the -destructor automatically removes the object from its parent. If the -object has children, the destructor automatically deletes each -child. No QObject is deleted twice, regardless of the order of -destruction. - -When \l {QObject} {QObjects} are created on the stack, the same -behavior applies. Normally, the order of destruction still doesn't -present a problem. Consider the following snippet: - -\snippet doc/src/snippets/code/doc_src_objecttrees.qdoc 0 - -The parent, \c window, and the child, \c quit, are both \l {QObject} -{QObjects} because QPushButton inherits QWidget, and QWidget inherits -QObject. This code is correct: the destructor of \c quit is \e not -called twice because the C++ language standard \e {(ISO/IEC 14882:2003)} -specifies that destructors of local objects are called in the reverse -order of their constructors. Therefore, the destructor of -the child, \c quit, is called first, and it removes itself from its -parent, \c window, before the destructor of \c window is called. - -But now consider what happens if we swap the order of construction, as -shown in this second snippet: - -\snippet doc/src/snippets/code/doc_src_objecttrees.qdoc 1 - -In this case, the order of destruction causes a problem. The parent's -destructor is called first because it was created last. It then calls -the destructor of its child, \c quit, which is incorrect because \c -quit is a local variable. When \c quit subsequently goes out of scope, -its destructor is called again, this time correctly, but the damage has -already been done. - -*/ diff --git a/doc/src/overviews.qdoc b/doc/src/overviews.qdoc index f4085f5..8b986fc 100644 --- a/doc/src/overviews.qdoc +++ b/doc/src/overviews.qdoc @@ -46,3 +46,28 @@ \generatelist overviews */ + +/*! + \group frameworks-technologies + \title Frameworks and Technologies + + \brief Documentation about the frameworks and technologies in Qt + + These documents dive into the frameworks of classes that Qt provides, + and provide background information about the technical solutions used + in Qt's architecture. + + \generatelist{related} +*/ + +/*! + \group best-practices + \title How-To's and Best Practices + + \brief How-To Guides and Best Practices + + These documents provide guidelines and best practices explaining + how to use Qt to solve specific technical problems. + + \generatelist{related} +*/ diff --git a/doc/src/coordsys.qdoc b/doc/src/painting-and-printing/coordsys.qdoc index 6042300..5269ea2 100644 --- a/doc/src/coordsys.qdoc +++ b/doc/src/painting-and-printing/coordsys.qdoc @@ -39,25 +39,16 @@ ** ****************************************************************************/ -/**************************************************************************** -** -** Qt Coordinate System Documentation. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - /*! \page coordsys.html \title The Coordinate System - \ingroup architecture \brief Information about the coordinate system used by the paint system. + \previouspage Drawing and Filling + \contentspage The Paint System + \nextpage Reading and Writing Image Files + The coordinate system is controlled by the QPainter class. Together with the QPaintDevice and QPaintEngine classes, QPainter form the basis of Qt's painting system, Arthur. QPainter diff --git a/doc/src/paintsystem.qdoc b/doc/src/painting-and-printing/paintsystem.qdoc index 23b5685..4fd29d5 100644 --- a/doc/src/paintsystem.qdoc +++ b/doc/src/painting-and-printing/paintsystem.qdoc @@ -40,9 +40,28 @@ ****************************************************************************/ /*! - \page paintsystem.html + \group painting + \title Painting Classes + \ingroup groups + + \brief Classes that provide support for painting. + + See also this introduction to the \link coordsys.html Qt + coordinate system. \endlink +*/ + +/*! + \group painting-3D + \title Rendering in 3D + \ingroup groups + + \brief Classes that provide support for rendering in 3D. +*/ +/*! + \page paintsystem.html \title The Paint System + \ingroup frameworks-technologies Qt's paint system enables painting on screen and print devices using the same API, and is primarily based on the QPainter, @@ -62,14 +81,211 @@ same painting pipeline making it easy to add support for new features and providing default implementations for unsupported ones. + + \section1 Topics + \list + \o \l{Classes for Painting} + \o \l{Paint Devices and Backends} + \o \l{Drawing and Filling} + \o \l{The Coordinate System} + \o \l{Reading and Writing Image Files} + \o \l{Styling} + \o \l{Printing with Qt} + \endlist + + \section1 Classes for Painting + + These classes provide support for painting onto a paint device. + + \annotatedlist painting Alternatively, Qt provides the QtOpenGL module, offering classes that makes it easy to use OpenGL in Qt applications. Among others, the module provides an OpenGL widget class that can be used just like any other Qt widget, except that it opens an OpenGL display buffer where the OpenGL API can be used to render the contents. +*/ + + +/*! + \page paintsystem-devices.html + \title Paint Devices and Backends + + \contentspage The Paint System + \nextpage Drawing and Filling + + \section1 Creating a Paint Device + + The QPaintDevice class is the base class of objects that can be + painted, i.e. QPainter can draw on any QPaintDevice + subclass. QPaintDevice's drawing capabilities are currently + implemented by the QWidget, QImage, QPixmap, QGLWidget, + QGLPixelBuffer, QPicture and QPrinter subclasses. + + \image paintsystem-devices.png + + \table 100% + \row \o \bold Widget + + The QWidget class is the base class of all user interface + objects. The widget is the atom of the user interface: it receives + mouse, keyboard and other events from the window system, and + paints a representation of itself on the screen. + + \row \o \bold Image + + The QImage class provides a hardware-independent image + representation which is designed and optimized for I/O, and for + direct pixel access and manipulation. QImage supports several + image formats including monochrome, 8-bit, 32-bit and + alpha-blended images. + + One advantage of using QImage as a paint device is that it is + possible to guarantee the pixel exactness of any drawing operation + in a platform-independent way. Another benefit is that the + painting can be performed in another thread than the current GUI + thread. + + \row \o \bold Pixmap + + The QPixmap class is an off-screen image representation which is + designed and optimized for showing images on screen. Unlike + QImage, the pixel data in a pixmap is internal and is managed by + the underlying window system, i.e. pixels can only be accessed + through QPainter functions or by converting the QPixmap to a + QImage. + + To optimize drawing with QPixmap, Qt provides the QPixmapCache + class which can be used to store temporary pixmaps that are + expensive to generate without using more storage space than the + cache limit. + + Qt also provides the QBitmap convenience class, inheriting + QPixmap. QBitmap guarantees monochrome (1-bit depth) pixmaps, and + is mainly used for creating custom QCursor and QBrush objects, + constructing QRegion objects, and for setting masks for pixmaps + and widgets. + + \row \o \bold {OpenGL Widget} + + As mentioned previously, Qt provides the QtOpenGL module offering + classes that makes it easy to use OpenGL in Qt applications. For + example, the QGLWidget enables the OpenGL API for + rendering. + + But QGLWidget is also a QWidget subclass, and can be used by + QPainter as any other paint device. One huge benefit from this is + that it enables Qt to utilize the high performance of OpenGL for + most drawing operations, such as transformations and pixmap + drawing. + + \row \o \bold {Pixel Buffer} + + The QtOpenGL module also provides the QGLPixelBuffer class which + inherits QPaintDevice directly. + + QGLPixelBuffer encapsulates an OpenGL pbuffer. Rendering into a + pbuffer is normally done using full hardware acceleration which + can be significantly faster than rendering into a QPixmap. - \tableofcontents section1 + \row \o \bold {Framebuffer Object} + + The QtOpenGL module also provides the QGLFramebufferObject class + which inherits QPaintDevice directly. + + QGLFramebufferObject encapsulates an OpenGL framebuffer object. + Framebuffer objects can also be used for off-screen rendering, and + offer several advantages over pixel buffers for this purpose. + These are described in the QGLFramebufferObject class documentation. + + \row \o \bold {Picture} + + The QPicture class is a paint device that records and replays + QPainter commands. A picture serializes painter commands to an IO + device in a platform-independent format. QPicture is also + resolution independent, i.e. a QPicture can be displayed on + different devices (for example svg, pdf, ps, printer and screen) + looking the same. + + Qt provides the QPicture::load() and QPicture::save() functions + as well as streaming operators for loading and saving pictures. + + \row \o \bold {Printer} + + The QPrinter class is a paint device that paints on a printer. On + Windows or Mac OS X, QPrinter uses the built-in printer + drivers. On X11, QPrinter generates postscript and sends that to + lpr, lp, or another print program. QPrinter can also print to any + other QPrintEngine object. + + The QPrintEngine class defines an interface for how QPrinter + interacts with a given printing subsystem. The common case when + creating your own print engine, is to derive from both + QPaintEngine and QPrintEngine. + + The output format is by default determined by the platform the + printer is running on, but by explicitly setting the output format + to QPrinter::PdfFormat, QPrinter will generate its output as a PDF + file. + + \row \o \bold {Custom Backends} + + Support for a new backend can be implemented by deriving from the + QPaintDevice class and reimplementing the virtual + QPaintDevice::paintEngine() function to tell QPainter which paint + engine should be used to draw on this particular device. To + actually be able to draw on the device, this paint engine must be + a custom paint engine created by deriving from the QPaintEngine + class. + + \endtable + + \section1 Selecting the Painting Backend + + Since Qt 4.5, it is possible to replace the paint engines and paint + devices used for widgets, pixmaps and the offscreen double buffer. By + default the backends are: + + \table + \row + \o Windows + \o Software Rasterizer + \row + \o X11 + \o X11 + \row + \o Mac OS X + \o CoreGraphics + \row + \o Embedded + \o Software Rasterizer + \endtable + + Passing a command line parameter to the application, such as, + \c{-graphicssystem raster}, specifies that Qt should use the software + rasterizer for this application. The Software rasterizer is fully + supported on all platforms. + + \code + > analogclock -graphicssystem raster + \endcode + + There is also a \c{-graphicssystem opengl} mode that uses OpenGL for + all drawing. Currently, this engine is experimental as it does not draw + everything correctly. + + Qt also supports being configured using \c {-graphicssystem + raster|opengl} in which case all applications will use the + specified graphics system for its graphics. +*/ + +/*! + \page paintsystem-drawing.html + \title Drawing and Filling + + \previouspage Paint Devices and Backends + \contentspage The Paint System + \nextpage The Coordinate System \section1 Drawing @@ -185,134 +401,15 @@ colors around a center point. \endtable +*/ - \section1 Creating a Paint Device - - The QPaintDevice class is the base class of objects that can be - painted, i.e. QPainter can draw on any QPaintDevice - subclass. QPaintDevice's drawing capabilities are currently - implemented by the QWidget, QImage, QPixmap, QGLWidget, - QGLPixelBuffer, QPicture and QPrinter subclasses. - - \image paintsystem-devices.png - - \table 100% - \row \o \bold {Custom Backends} - - Support for a new backend can be implemented by deriving from the - QPaintDevice class and reimplementing the virtual - QPaintDevice::paintEngine() function to tell QPainter which paint - engine should be used to draw on this particular device. To - actually be able to draw on the device, this paint engine must be - a custom paint engine created by deriving from the QPaintEngine - class. - - \endtable - - \section2 Widget - - The QWidget class is the base class of all user interface - objects. The widget is the atom of the user interface: it receives - mouse, keyboard and other events from the window system, and - paints a representation of itself on the screen. - - \section2 Image - - The QImage class provides a hardware-independent image - representation which is designed and optimized for I/O, and for - direct pixel access and manipulation. QImage supports several - image formats including monochrome, 8-bit, 32-bit and - alpha-blended images. - - One advantage of using QImage as a paint device is that it is - possible to guarantee the pixel exactness of any drawing operation - in a platform-independent way. Another benefit is that the - painting can be performed in another thread than the current GUI - thread. - - \section2 Pixmap - - The QPixmap class is an off-screen image representation which is - designed and optimized for showing images on screen. Unlike - QImage, the pixel data in a pixmap is internal and is managed by - the underlying window system, i.e. pixels can only be accessed - through QPainter functions or by converting the QPixmap to a - QImage. - - To optimize drawing with QPixmap, Qt provides the QPixmapCache - class which can be used to store temporary pixmaps that are - expensive to generate without using more storage space than the - cache limit. - - Qt also provides the QBitmap convenience class, inheriting - QPixmap. QBitmap guarantees monochrome (1-bit depth) pixmaps, and - is mainly used for creating custom QCursor and QBrush objects, - constructing QRegion objects, and for setting masks for pixmaps - and widgets. - - \section2 OpenGL Widget - - As mentioned above, Qt provides the QtOpenGL module offering - classes that makes it easy to use OpenGL in Qt applications. For - example, the QGLWidget enables the OpenGL API for - rendering. - - But QGLWidget is also a QWidget subclass, and can be used by - QPainter as any other paint device. One huge benefit from this is - that it enables Qt to utilize the high performance of OpenGL for - most drawing operations, such as transformations and pixmap - drawing. - - \section2 Pixel Buffer - - The QtOpenGL module also provides the QGLPixelBuffer class which - inherits QPaintDevice directly. - - QGLPixelBuffer encapsulates an OpenGL pbuffer. Rendering into a - pbuffer is normally done using full hardware acceleration which - can be significantly faster than rendering into a QPixmap. - - \section2 Framebuffer Object - - The QtOpenGL module also provides the QGLFramebufferObject class - which inherits QPaintDevice directly. - - QGLFramebufferObject encapsulates an OpenGL framebuffer object. - Framebuffer objects can also be used for off-screen rendering, and - offer several advantages over pixel buffers for this purpose. - These are described in the QGLFramebufferObject class documentation. - - \section2 Picture - - The QPicture class is a paint device that records and replays - QPainter commands. A picture serializes painter commands to an IO - device in a platform-independent format. QPicture is also - resolution independent, i.e. a QPicture can be displayed on - different devices (for example svg, pdf, ps, printer and screen) - looking the same. - - Qt provides the QPicture::load() and QPicture::save() functions - as well as streaming operators for loading and saving pictures. - - \section2 Printer - - The QPrinter class is a paint device that paints on a printer. On - Windows or Mac OS X, QPrinter uses the built-in printer - drivers. On X11, QPrinter generates postscript and sends that to - lpr, lp, or another print program. QPrinter can also print to any - other QPrintEngine object. - - The QPrintEngine class defines an interface for how QPrinter - interacts with a given printing subsystem. The common case when - creating your own print engine, is to derive from both - QPaintEngine and QPrintEngine. - - The output format is by default determined by the platform the - printer is running on, but by explicitly setting the output format - to QPrinter::PdfFormat, QPrinter will generate its output as a PDF - file. +/*! + \page paintsystem-images.html + \title Reading and Writing Image Files - \section1 Reading and Writing Image Files + \previouspage The Coordinate System + \contentspage The Paint System + \nextpage Styling The most common way to read images is through QImage and QPixmap's constructors, or by calling the QImage::load() and QPixmap::load() @@ -359,30 +456,57 @@ QImageReader and QImageWriter will automatically load the plugin and start using it. + \section1 Rendering SVG files + \table 100% \row \o \image paintsystem-svg.png \o \bold {SVG Rendering} - Scalable Vector Graphics (SVG) is an language for describing both - static and animated two-dimensional vector graphics. Qt includes - support for the static features of SVG 1.2 Tiny. + Scalable Vector Graphics (SVG) is a language for describing two-dimensional + graphics and graphical applications in XML. SVG 1.1 is a W3C Recommendation + and forms the core of the current SVG developments in Qt. SVG 1.2 is the + specification currently being developed by the \l{SVG Working Group}, and it + is \l{http://www.w3.org/TR/SVG12/}{available in draft form}. + The \l{Mobile SVG Profiles} (SVG Basic and SVG Tiny) are aimed at + resource-limited devices and are part of the 3GPP platform for third generation + mobile phones. You can read more about SVG at \l{About SVG}. + + Qt supports the \l{SVG 1.2 Tiny Static Features}{static features} of + \l{SVG 1.2 Tiny}. ECMA scripts and DOM manipulation are currently not + supported. - SVG drawings can be rendered onto any QPaintDevice subclass. This + SVG drawings can be rendered onto any QPaintDevice subclass. This approach gives developers the flexibility to experiment, in order to find the best solution for each application. - The easiest way to render SVG files is to construct a QSvgWidget - and load an SVG file using one of the QSvgWidget::load() - functions. The rendering is performed by the QSvgRenderer class - which also can be used directly to provide SVG support for custom - widgets. + The easiest way to render SVG files is to construct a QSvgWidget and + load an SVG file using one of the QSvgWidget::load() functions. - For more information, see the QtSvg module documentation. + QSvgRenderer is the class responsible for rendering SVG files for + QSvgWidget, and it can be used directly to provide SVG support for + custom widgets. + To load an SVG file, construct a QSvgRenderer with a file name or the + contents of a file, or call QSvgRenderer::load() on an existing + renderer. If the SVG file has been loaded successfully the + QSvgRenderer::isValid() will return true. + + Once you have loaded the SVG file successfully, you can render it + with the QSvgRenderer::render() function. Note that this scheme allows + you to render SVG files on all paint devices supported by Qt, including + QWidget, QGLWidget, and QImage. See the \l{SVG Viewer Example}{SVG Viewer} + example for more details. \endtable +*/ - \section1 Styling +/*! + \page paintsystem-styling.html + \title Styling + + \previouspage Reading and Writing Image Files + \contentspage The Paint System + \nextpage Printing with Qt Qt's built-in widgets use the QStyle class to perform nearly all of their drawing. QStyle is an abstract base class that @@ -440,44 +564,7 @@ state. \endtable - - \section1 Selecting the Painting Backend - - Since Qt 4.5, it is possible to replace the paint engines and paint - devices used for widgets, pixmaps and the offscreen double buffer. By - default the backends are: - - \table - \row - \o Windows - \o Software Rasterizer - \row - \o X11 - \o X11 - \row - \o Mac OS X - \o CoreGraphics - \row - \o Embedded - \o Software Rasterizer - \endtable - - Passing a command line parameter to the application, such as, - \c{-graphicssystem raster}, specifies that Qt should use the software - rasterizer for this application. The Software rasterizer is fully - supported on all platforms. - - \code - > analogclock -graphicssystem raster - \endcode - - There is also a \c{-graphicssystem opengl} mode that uses OpenGL for - all drawing. Currently, this engine is experimental as it does not draw - everything correctly. - - Qt also supports being configured using \c {-graphicssystem - raster|opengl} in which case all applications will use the - specified graphics system for its graphics. - - */ - + + For more information about widget styling and appearance, see the + documentation about \l{Implementing Styles and Style Aware Widgets}. +*/ diff --git a/doc/src/printing.qdoc b/doc/src/painting-and-printing/printing.qdoc index 0472827..291286e 100644 --- a/doc/src/printing.qdoc +++ b/doc/src/painting-and-printing/printing.qdoc @@ -40,10 +40,19 @@ ****************************************************************************/ /*! + \group printing + \title Printer and Printing APIs + \brief Classes for producing printed output + \ingroup groups +*/ + +/*! \page printing.html \title Printing with Qt - \ingroup multimedia - \ingroup text-processing + + \previouspage Styling + \contentspage The Paint System + \brief A guide to producing printed output with Qt's paint system and widgets. Qt provides extensive cross-platform support for printing. Using the printing @@ -53,6 +62,13 @@ generation facilities. \tableofcontents + + \section1 Classes Supporting Printing + + The following classes support the selecting and setting up of printers and + printing output. + + \annotatedlist printing \section1 Paint Devices and Printing diff --git a/doc/src/atomic-operations.qdoc b/doc/src/platforms/atomic-operations.qdoc index d0f5978..19fbea6 100644 --- a/doc/src/atomic-operations.qdoc +++ b/doc/src/platforms/atomic-operations.qdoc @@ -42,19 +42,20 @@ /*! \page atomic-operations.html \title Implementing Atomic Operations - \ingroup architecture - \ingroup qt-embedded-linux \brief A guide to implementing atomic operations on new architectures. + \ingroup best-practices + \ingroup qt-embedded-linux + Qt uses an optimization called \l {Implicitly Shared Classes}{implicit sharing} for many of its value classes. Starting with Qt 4, all of Qt's implicitly shared classes can safely be copied across threads like any other value classes, - i.e., they are fully \l {Thread Support in Qt#Reentrancy and - Thread-Safety}{reentrant}. This is accomplished by implementing - reference counting operations using atomic hardware instructions - on all the different platforms supported by Qt. + i.e., they are fully \l {Reentrancy and Thread-Safety}{reentrant}. + This is accomplished by implementing reference counting + operations using atomic hardware instructions on all the + different platforms supported by Qt. To support a new architecture, it is important to ensure that these platform-specific atomic operations are implemented in a diff --git a/doc/src/compiler-notes.qdoc b/doc/src/platforms/compiler-notes.qdoc index 4873cf5..f4e9805 100644 --- a/doc/src/compiler-notes.qdoc +++ b/doc/src/platforms/compiler-notes.qdoc @@ -41,7 +41,7 @@ /*! \page compiler-notes.html - \ingroup platform-notes + \ingroup platform-specific \title Compiler Notes \brief Information about the C++ compilers and tools used to build Qt. diff --git a/doc/src/emb-accel.qdoc b/doc/src/platforms/emb-accel.qdoc index 818538a..818538a 100644 --- a/doc/src/emb-accel.qdoc +++ b/doc/src/platforms/emb-accel.qdoc diff --git a/doc/src/qtopiacore-architecture.qdoc b/doc/src/platforms/emb-architecture.qdoc index 06ffac6..06ffac6 100644 --- a/doc/src/qtopiacore-architecture.qdoc +++ b/doc/src/platforms/emb-architecture.qdoc diff --git a/doc/src/emb-charinput.qdoc b/doc/src/platforms/emb-charinput.qdoc index 5ceb6a4..5ceb6a4 100644 --- a/doc/src/emb-charinput.qdoc +++ b/doc/src/platforms/emb-charinput.qdoc diff --git a/doc/src/emb-crosscompiling.qdoc b/doc/src/platforms/emb-crosscompiling.qdoc index 2e0ba4b..2e0ba4b 100644 --- a/doc/src/emb-crosscompiling.qdoc +++ b/doc/src/platforms/emb-crosscompiling.qdoc diff --git a/doc/src/emb-deployment.qdoc b/doc/src/platforms/emb-deployment.qdoc index 9a83dcf..9a83dcf 100644 --- a/doc/src/emb-deployment.qdoc +++ b/doc/src/platforms/emb-deployment.qdoc diff --git a/doc/src/emb-differences.qdoc b/doc/src/platforms/emb-differences.qdoc index cf3ab75..cf3ab75 100644 --- a/doc/src/emb-differences.qdoc +++ b/doc/src/platforms/emb-differences.qdoc diff --git a/doc/src/qtopiacore-displaymanagement.qdoc b/doc/src/platforms/emb-displaymanagement.qdoc index 8a743b1..8a743b1 100644 --- a/doc/src/qtopiacore-displaymanagement.qdoc +++ b/doc/src/platforms/emb-displaymanagement.qdoc diff --git a/doc/src/emb-envvars.qdoc b/doc/src/platforms/emb-envvars.qdoc index c423fef..c423fef 100644 --- a/doc/src/emb-envvars.qdoc +++ b/doc/src/platforms/emb-envvars.qdoc diff --git a/doc/src/emb-features.qdoc b/doc/src/platforms/emb-features.qdoc index fdd2e46..fdd2e46 100644 --- a/doc/src/emb-features.qdoc +++ b/doc/src/platforms/emb-features.qdoc diff --git a/doc/src/emb-fonts.qdoc b/doc/src/platforms/emb-fonts.qdoc index 70fddbf..70fddbf 100644 --- a/doc/src/emb-fonts.qdoc +++ b/doc/src/platforms/emb-fonts.qdoc diff --git a/doc/src/emb-framebuffer-howto.qdoc b/doc/src/platforms/emb-framebuffer-howto.qdoc index 14400c2..14400c2 100644 --- a/doc/src/emb-framebuffer-howto.qdoc +++ b/doc/src/platforms/emb-framebuffer-howto.qdoc diff --git a/doc/src/emb-install.qdoc b/doc/src/platforms/emb-install.qdoc index 9cd3fad..9cd3fad 100644 --- a/doc/src/emb-install.qdoc +++ b/doc/src/platforms/emb-install.qdoc diff --git a/doc/src/emb-kmap2qmap.qdoc b/doc/src/platforms/emb-kmap2qmap.qdoc index 291a553..291a553 100644 --- a/doc/src/emb-kmap2qmap.qdoc +++ b/doc/src/platforms/emb-kmap2qmap.qdoc diff --git a/doc/src/emb-makeqpf.qdoc b/doc/src/platforms/emb-makeqpf.qdoc index dc1196a..dc1196a 100644 --- a/doc/src/emb-makeqpf.qdoc +++ b/doc/src/platforms/emb-makeqpf.qdoc diff --git a/doc/src/qtopiacore-opengl.qdoc b/doc/src/platforms/emb-opengl.qdoc index e61ccde..e61ccde 100644 --- a/doc/src/qtopiacore-opengl.qdoc +++ b/doc/src/platforms/emb-opengl.qdoc diff --git a/doc/src/emb-performance.qdoc b/doc/src/platforms/emb-performance.qdoc index 9bc373b..9bc373b 100644 --- a/doc/src/emb-performance.qdoc +++ b/doc/src/platforms/emb-performance.qdoc diff --git a/doc/src/emb-pointer.qdoc b/doc/src/platforms/emb-pointer.qdoc index 39a8482..39a8482 100644 --- a/doc/src/emb-pointer.qdoc +++ b/doc/src/platforms/emb-pointer.qdoc diff --git a/doc/src/emb-porting.qdoc b/doc/src/platforms/emb-porting.qdoc index 1afd1be..1afd1be 100644 --- a/doc/src/emb-porting.qdoc +++ b/doc/src/platforms/emb-porting.qdoc diff --git a/doc/src/emb-qvfb.qdoc b/doc/src/platforms/emb-qvfb.qdoc index 48e0d35..48e0d35 100644 --- a/doc/src/emb-qvfb.qdoc +++ b/doc/src/platforms/emb-qvfb.qdoc diff --git a/doc/src/emb-running.qdoc b/doc/src/platforms/emb-running.qdoc index cb7a7ae..cb7a7ae 100644 --- a/doc/src/emb-running.qdoc +++ b/doc/src/platforms/emb-running.qdoc diff --git a/doc/src/emb-vnc.qdoc b/doc/src/platforms/emb-vnc.qdoc index c8289f8..c8289f8 100644 --- a/doc/src/emb-vnc.qdoc +++ b/doc/src/platforms/emb-vnc.qdoc diff --git a/doc/src/mac-differences.qdoc b/doc/src/platforms/mac-differences.qdoc index ee77125..b911510 100644 --- a/doc/src/mac-differences.qdoc +++ b/doc/src/platforms/mac-differences.qdoc @@ -43,7 +43,7 @@ \page mac-differences.html \title Qt for Mac OS X - Specific Issues \brief A description of issues with Qt that are specific to Mac OS X. - \ingroup platform-notes + \ingroup platform-specific This file outlines known issues and possible workarounds when using Qt on Mac OS X. Contact Qt's technical support team if you find diff --git a/doc/src/platform-notes-rtos.qdoc b/doc/src/platforms/platform-notes-rtos.qdoc index 8a52d84..8a52d84 100644 --- a/doc/src/platform-notes-rtos.qdoc +++ b/doc/src/platforms/platform-notes-rtos.qdoc diff --git a/doc/src/platform-notes.qdoc b/doc/src/platforms/platform-notes.qdoc index 349abf8..e79b2f4 100644 --- a/doc/src/platform-notes.qdoc +++ b/doc/src/platforms/platform-notes.qdoc @@ -40,8 +40,19 @@ ****************************************************************************/ /*! - \page platform-notes-platforms.html - \ingroup platform-notes + \group platform-specific + \title Platform-Specific Documentation + \brief Documents describing platform-specific features of Qt. + + These documents describe platform-specific features provided by Qt, and + discuss issues related to particular platforms and environments. + + \generatelist{related} +*/ + +/*! + \page platform-notes.html + \ingroup platform-specific \title Platform Notes \brief Information about the platforms on which Qt can be used. diff --git a/doc/src/qtopiacore.qdoc b/doc/src/platforms/qt-embedded-linux.qdoc index c8fccf1..5329218 100644 --- a/doc/src/qtopiacore.qdoc +++ b/doc/src/platforms/qt-embedded-linux.qdoc @@ -40,8 +40,20 @@ ****************************************************************************/ /*! + \group qws + \title Qt for Embedded Linux Classes + \ingroup groups + \ingroup qt-embedded-linux + \ingroup platform-specific + + \brief Classes that are specific to Qt for Embedded Linux. + + These classes are relevant to \l{Qt for Embedded Linux} users. +*/ + + +/*! \group qt-embedded-linux - \ingroup topics \ingroup qt-embedded \title Qt for Embedded Linux \brief Documents specifically about Qt for Embedded Linux. @@ -71,7 +83,7 @@ \o \l {Qt for Embedded Linux Architecture}{Architecture Overview} \o \l {Installing Qt for Embedded Linux}{Installation} \o \l {Running Qt for Embedded Linux Applications}{Running Applications} - \o \l {Qt Examples#Qt for Embedded Linux}{Examples} + \o \l {Qt for Embedded Linux Examples}{Examples} \endlist \o \list diff --git a/doc/src/qt-embedded.qdoc b/doc/src/platforms/qt-embedded.qdoc index be9a458..22cba80 100644 --- a/doc/src/qt-embedded.qdoc +++ b/doc/src/platforms/qt-embedded.qdoc @@ -41,9 +41,9 @@ /*! \group qt-embedded - \ingroup topics \title Qt for Embedded Platforms \brief Documents related to Qt for Embedded Platforms. + \ingroup platform-specific Qt is available for embedded platforms and devices as well as for a number of desktop platforms. The features provided for each platform depend on the diff --git a/doc/src/qtmac-as-native.qdoc b/doc/src/platforms/qtmac-as-native.qdoc index 61c2143..265d222 100644 --- a/doc/src/qtmac-as-native.qdoc +++ b/doc/src/platforms/qtmac-as-native.qdoc @@ -86,7 +86,7 @@ \page qtmac-as-native.html \title Qt is Mac OS X Native \brief An explanation of Qt's native features on Mac OS X. - \ingroup platform-notes + \ingroup platform-specific This document explains what makes an application native on Mac OS X. It shows the areas where Qt is compliant, and the grey areas where diff --git a/doc/src/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc index 6f63c87..8aec1e2 100644 --- a/doc/src/supported-platforms.qdoc +++ b/doc/src/platforms/supported-platforms.qdoc @@ -43,7 +43,7 @@ \page supported-platforms.html \title Supported Platforms \brief The platforms supported by Nokia for Qt. - \ingroup platform-notes + \ingroup platform-specific The Qt team strives to provide support for the platforms most frequently used by Qt users. We have designed our internal testing procedure to diff --git a/doc/src/wince-customization.qdoc b/doc/src/platforms/wince-customization.qdoc index 06de1c8..06de1c8 100644 --- a/doc/src/wince-customization.qdoc +++ b/doc/src/platforms/wince-customization.qdoc diff --git a/doc/src/wince-introduction.qdoc b/doc/src/platforms/wince-introduction.qdoc index 9a2c672..29f880e 100644 --- a/doc/src/wince-introduction.qdoc +++ b/doc/src/platforms/wince-introduction.qdoc @@ -40,11 +40,43 @@ ****************************************************************************/ /*! + \group qtce + \title Qt for Windows CE + \ingroup qt-embedded + \brief Documents related to Qt on Windows CE + + Qt for Windows CE is a C++ framework for GUI and application development + for embedded devices running Windows CE. It runs on a variety of processors, + including ARM, Intel x86, MIPS and SH-4. + + \table 100% + \header \o Getting Started \o Reference \o Performance and Optimization + \row + \o + \list + \o \l {Qt for Windows CE Requirements} + \o \l {Installing Qt on Windows CE} + \o \l {Windows CE - Introduction to using Qt}{Introduction to using Qt} + \endlist + \o + \list + \o \l {Windows CE - Using shadow builds}{Using shadow builds} + \o \l {Windows CE - Working with Custom SDKs}{Working with Custom SDKs} + \endlist + \o + \list + \o \l {Windows CE OpenGL ES}{OpenGL ES} + \o \l {Qt Performance Tuning} + \o \l {Fine-Tuning Features in Qt} + \endlist + \endtable +*/ + +/*! \page wince-with-qt-introduction.html \title Windows CE - Introduction to using Qt \brief An introduction to Qt for Windows CE developers. - \ingroup howto \ingroup qtce \tableofcontents diff --git a/doc/src/wince-opengl.qdoc b/doc/src/platforms/wince-opengl.qdoc index 3c7e22f..3c7e22f 100644 --- a/doc/src/wince-opengl.qdoc +++ b/doc/src/platforms/wince-opengl.qdoc diff --git a/doc/src/winsystem.qdoc b/doc/src/platforms/winsystem.qdoc index 8bb295d..5afa1f7 100644 --- a/doc/src/winsystem.qdoc +++ b/doc/src/platforms/winsystem.qdoc @@ -42,8 +42,7 @@ /*! \page winsystem.html \title Window System Specific Notes - \ingroup buildsystem - \ingroup deployment + \ingroup platform-specific Qt is a cross-platform GUI toolkit, so almost the entire API is the same on all platforms and window systems. If you wish to use diff --git a/doc/src/qtopengl.qdoc b/doc/src/platforms/x11overlays.qdoc index bb2f4e7..7d7a776 100644 --- a/doc/src/qtopengl.qdoc +++ b/doc/src/platforms/x11overlays.qdoc @@ -40,73 +40,8 @@ ****************************************************************************/ /*! - \module QtOpenGL - \title QtOpenGL Module - \contentspage Qt's Modules - \previouspage QtNetwork - \nextpage QtOpenVG - \ingroup modules - - \brief The QtOpenGL module offers classes that make it easy to - use OpenGL in Qt applications. - - OpenGL is a standard API for rendering 3D graphics. OpenGL only - deals with 3D rendering and provides little or no support for GUI - programming issues. The user interface for an OpenGL application - must be created with another toolkit, such as Motif on the X - platform, Microsoft Foundation Classes (MFC) under Windows, or Qt - on both platforms. - - \bold{Note:} OpenGL is a trademark of Silicon Graphics, Inc. in - the United States and other countries. - - The Qt OpenGL module makes it easy to use OpenGL in Qt applications. - It provides an OpenGL widget class that can be used just like any - other Qt widget, except that it opens an OpenGL display buffer where - you can use the OpenGL API to render the contents. - - To include the definitions of the module's classes, use the - following directive: - - \snippet doc/src/snippets/code/doc_src_qtopengl.qdoc 0 - - To link against the module, add this line to your \l qmake \c - .pro file: - - \snippet doc/src/snippets/code/doc_src_qtopengl.qdoc 1 - - The Qt OpenGL module is implemented as a platform-independent Qt/C++ - wrapper around the platform-dependent GLX (version 1.3 or later), - WGL, or AGL C APIs. Although the basic functionality provided is very - similar to Mark Kilgard's GLUT library, applications using the Qt - OpenGL module can take advantage of the whole Qt API for - non-OpenGL-specific GUI functionality. - - \warning The QtOpenGL module is part of the \l{Qt Full Framework Edition} - and the \l{Open Source Versions of Qt}. It is available on Windows, - X11, and Mac OS X. \l{Qt for Embedded Linux} supports OpenGL ES (OpenGL for - Embedded Systems). To be able to use the OpenGL API in \l{Qt for Embedded Linux}, - it must be integrated with the Q Window System (QWS). See the - \l{Qt for Embedded Linux and OpenGL} documentation for details. - - \section1 Installation - - When you install Qt for X11, the configure script will autodetect if - OpenGL headers and libraries are installed on your system, and if so, - it will include the QtOpenGL module in the Qt library. (If your - OpenGL headers or libraries are placed in a non-standard directory, - you may need to change the \c QMAKE_INCDIR_OPENGL and/or - \c QMAKE_LIBDIR_OPENGL in the config file for your system). - - When you install Qt for Windows and Mac OS X, the QtOpenGL - module is always included. X11 users might like to read the notes - on overlays below. - - The QGL documentation assumes that you are familiar with OpenGL - programming. If you're new to the subject a good starting point is - \l{http://www.opengl.org/}. - - \section1 How to Use X11 Overlays with Qt + \page x11overlays.html + \title How to Use X11 Overlays with Qt X11 overlays are a powerful mechanism for drawing annotations etc., on top of an image without destroying it, thus saving diff --git a/doc/src/porting-qsa.qdoc b/doc/src/porting/porting-qsa.qdoc index d22e2db..d22e2db 100644 --- a/doc/src/porting-qsa.qdoc +++ b/doc/src/porting/porting-qsa.qdoc diff --git a/doc/src/porting4-canvas.qdoc b/doc/src/porting/porting4-canvas.qdoc index ce68d56..5435723 100644 --- a/doc/src/porting4-canvas.qdoc +++ b/doc/src/porting/porting4-canvas.qdoc @@ -46,7 +46,6 @@ \previouspage Porting UI Files to Qt 4 \nextpage qt3to4 - The Qt 3 to 4 Porting Tool \ingroup porting - \ingroup multimedia \brief Hints and tips to assist with porting canvas applications to the Graphics View framework. diff --git a/doc/src/porting4-designer.qdoc b/doc/src/porting/porting4-designer.qdoc index d356392..d356392 100644 --- a/doc/src/porting4-designer.qdoc +++ b/doc/src/porting/porting4-designer.qdoc diff --git a/doc/src/porting/porting4-dnd.qdoc b/doc/src/porting/porting4-dnd.qdoc new file mode 100644 index 0000000..2eb2d01 --- /dev/null +++ b/doc/src/porting/porting4-dnd.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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page porting4-dnd.html + \title Porting to Qt 4 - Drag and Drop + \contentspage {Porting Guides}{Contents} + \previouspage Porting to Qt 4 - Virtual Functions + \nextpage Porting UI Files to Qt 4 + \ingroup porting + \brief An overview of the porting process for applications that use drag and drop. + + Qt 4 introduces a new set of classes to handle drag and drop operations + that aim to be easier to use than their counterparts in Qt 3. As a result, + the way that drag and drop is performed is quite different to the way + developers of Qt 3 applications have come to expect. In this guide, we + show the differences between the old and new APIs and indicate where + applications need to be changed when they are ported to Qt 4. + + \tableofcontents + + \section1 Dragging + + In Qt 3, drag operations are encapsulated by \c QDragObject (see Q3DragObject) + and its subclasses. These objects are typically constructed on the heap in + response to mouse click or mouse move events, and ownership of them is + transferred to Qt so that they can be deleted when the corresponding drag and + drop operations have been completed. The drag source has no control over how + the drag and drop operation is performed once the object's + \l{Q3DragObject::}{drag()} function is called, and it receives no information + about how the operation ended. + + \snippet doc/src/snippets/code/doc_src_dnd.qdoc 0 + + Similarly, in Qt 4, drag operations are also initiated when a QDrag object + is constructed and its \l{QDrag::}{exec()} function is called. In contrast, + these objects are typically constructed on the stack rather than the heap + since each drag and drop operation is performed synchronously as far as the + drag source is concerned. One key benefit of this is that the drag source + can receive information about how the operation ended from the value returned + by \l{QDrag::}{exec()}. + + \snippet doc/src/snippets/porting4-dropevents/window.cpp 2 + \snippet doc/src/snippets/porting4-dropevents/window.cpp 3 + \dots 8 + \snippet doc/src/snippets/porting4-dropevents/window.cpp 4 + \snippet doc/src/snippets/porting4-dropevents/window.cpp 5 + + A key difference in the above code is the use of the QMimeData class to hold + information about the data that is transferred. Qt 3 relies on subclasses + of \c QDragObject to provide support for specific MIME types; in Qt 4, the + use of QMimeData as a generic container for data makes the relationship + between MIME type and data more tranparent. QMimeData is described in more + detail later in this document. + + \section1 Dropping + + In both Qt 3 and Qt 4, it is possible to prepare a custom widget to accept + dropped data by enabling the \l{QWidget::}{acceptDrops} property of a widget, + usually in the widget's constructor. As a result, the widget will receive + drag enter events that can be handled by its \l{QWidget::}{dragEnterEvent()} + function. + As in Qt 3, custom widgets in Qt 4 handle these events by determining + whether the data supplied by the drag and drop operation can be dropped onto + the widget. Since the classes used to encapsulate MIME data are different in + Qt 3 and Qt 4, the exact implementations differ. + + In Qt 3, the drag enter event is handled by checking whether each of the + standard \c QDragObject subclasses can decode the data supplied, and + indicating success or failure of these checks via the event's + \l{QDragEnterEvent::}{accept()} function, as shown in this simple example: + + \snippet doc/src/snippets/code/doc_src_dnd.qdoc 1 + + In Qt 4, you can examine the MIME type describing the data to determine + whether the widget should accept the event or, for common data types, you + can use convenience functions: + + \snippet doc/src/snippets/porting4-dropevents/window.cpp 0 + + The widget has some control over the type of drag and drop operation to be + performed. In the above code, the action proposed by the drag source is + accepted, but + \l{Drag and Drop#Overriding Proposed Actions}{this can be overridden} if + required. + + In both Qt 3 and Qt 4, it is necessary to accept a given drag event in order + to receive the corresponding drop event. A custom widget in Qt 3 that can + accept dropped data in the form of text or images might provide an + implementation of \l{QWidget::}{dropEvent()} that looks like the following: + + \snippet doc/src/snippets/code/doc_src_dnd.qdoc 2 + + In Qt 4, the event is handled in a similar way: + + \snippet doc/src/snippets/porting4-dropevents/window.cpp 1 + + It is also possible to extract data stored for a particular MIME type if it + was specified by the drag source. + + \section1 MIME Types and Data + + In Qt 3, data to be transferred in drag and drop operations is encapsulated + in instances of \c QDragObject and its subclasses, representing specific + data formats related to common MIME type and subtypes. + + In Qt 4, only the QMimeData class is used to represent data, providing a + container for data stored in multiple formats, each associated with + a relevant MIME type. Since arbitrary MIME types can be specified, there is + no need for an extensive class hierarchy to represent different kinds of + information. Additionally, QMimeData it provides some convenience functions + to allow the most common data formats to be stored and retrieved with less + effort than for arbitrary MIME types. +*/ diff --git a/doc/src/porting4-modifiedvirtual.qdocinc b/doc/src/porting/porting4-modifiedvirtual.qdocinc index 1164238..1164238 100644 --- a/doc/src/porting4-modifiedvirtual.qdocinc +++ b/doc/src/porting/porting4-modifiedvirtual.qdocinc diff --git a/doc/src/porting4-obsoletedmechanism.qdocinc b/doc/src/porting/porting4-obsoletedmechanism.qdocinc index 584b910..584b910 100644 --- a/doc/src/porting4-obsoletedmechanism.qdocinc +++ b/doc/src/porting/porting4-obsoletedmechanism.qdocinc diff --git a/doc/src/porting4-overview.qdoc b/doc/src/porting/porting4-overview.qdoc index 5eff1ba..5eff1ba 100644 --- a/doc/src/porting4-overview.qdoc +++ b/doc/src/porting/porting4-overview.qdoc diff --git a/doc/src/porting4-removedenumvalues.qdocinc b/doc/src/porting/porting4-removedenumvalues.qdocinc index fe38d0e..fe38d0e 100644 --- a/doc/src/porting4-removedenumvalues.qdocinc +++ b/doc/src/porting/porting4-removedenumvalues.qdocinc diff --git a/doc/src/porting4-removedtypes.qdocinc b/doc/src/porting/porting4-removedtypes.qdocinc index 9d7c519..9d7c519 100644 --- a/doc/src/porting4-removedtypes.qdocinc +++ b/doc/src/porting/porting4-removedtypes.qdocinc diff --git a/doc/src/porting4-removedvariantfunctions.qdocinc b/doc/src/porting/porting4-removedvariantfunctions.qdocinc index dfaa8f3..dfaa8f3 100644 --- a/doc/src/porting4-removedvariantfunctions.qdocinc +++ b/doc/src/porting/porting4-removedvariantfunctions.qdocinc diff --git a/doc/src/porting4-removedvirtual.qdocinc b/doc/src/porting/porting4-removedvirtual.qdocinc index 1af4fa6..1af4fa6 100644 --- a/doc/src/porting4-removedvirtual.qdocinc +++ b/doc/src/porting/porting4-removedvirtual.qdocinc diff --git a/doc/src/porting4-renamedclasses.qdocinc b/doc/src/porting/porting4-renamedclasses.qdocinc index ef315a1..ef315a1 100644 --- a/doc/src/porting4-renamedclasses.qdocinc +++ b/doc/src/porting/porting4-renamedclasses.qdocinc diff --git a/doc/src/porting4-renamedenumvalues.qdocinc b/doc/src/porting/porting4-renamedenumvalues.qdocinc index 9519da1..9519da1 100644 --- a/doc/src/porting4-renamedenumvalues.qdocinc +++ b/doc/src/porting/porting4-renamedenumvalues.qdocinc diff --git a/doc/src/porting4-renamedfunctions.qdocinc b/doc/src/porting/porting4-renamedfunctions.qdocinc index 3e59a82..3e59a82 100644 --- a/doc/src/porting4-renamedfunctions.qdocinc +++ b/doc/src/porting/porting4-renamedfunctions.qdocinc diff --git a/doc/src/porting4-renamedstatic.qdocinc b/doc/src/porting/porting4-renamedstatic.qdocinc index 156ab73..156ab73 100644 --- a/doc/src/porting4-renamedstatic.qdocinc +++ b/doc/src/porting/porting4-renamedstatic.qdocinc diff --git a/doc/src/porting4-renamedtypes.qdocinc b/doc/src/porting/porting4-renamedtypes.qdocinc index fc8f604..fc8f604 100644 --- a/doc/src/porting4-renamedtypes.qdocinc +++ b/doc/src/porting/porting4-renamedtypes.qdocinc diff --git a/doc/src/porting4.qdoc b/doc/src/porting/porting4.qdoc index 4efb7be..f4bcfcc 100644 --- a/doc/src/porting4.qdoc +++ b/doc/src/porting/porting4.qdoc @@ -40,6 +40,19 @@ ****************************************************************************/ /*! + \group porting + \title Porting Guides + \brief Guides related to porting Qt applications and libraries. + \ingroup best-practices + + A number of guides and documents are available that cover porting issues, + from detailed coverage of API differences between Qt 3 and Qt 4 to + platform and tool-specific documentation. + + \generatelist{related} +*/ + +/*! \page porting4.html \title Porting to Qt 4 \contentspage {Porting Guides}{Contents} @@ -267,7 +280,7 @@ \table \header \o Qt 3 class name \o Qt 4 class name - \input porting4-renamedclasses.qdocinc + \input porting/porting4-renamedclasses.qdocinc \endtable The table below lists the enums and typedefs that have been @@ -281,7 +294,7 @@ \table \header \o Qt 3 type name \o Qt 4 type name - \input porting4-renamedtypes.qdocinc + \input porting/porting4-renamedtypes.qdocinc \endtable \omit @@ -301,7 +314,7 @@ \table \header \o Qt 3 enum value name \o Qt 4 enum value name - \input porting4-renamedenumvalues.qdocinc + \input porting/porting4-renamedenumvalues.qdocinc \endtable In addition, the following \l{Qt::WindowFlags}{window flags} have @@ -722,7 +735,7 @@ The \c QAsyncIO class was used internally in Qt 2.x in conjunction with QImageConsumer. It was obsoleted in Qt 3.0. - \input porting4-obsoletedmechanism.qdocinc + \input porting/porting4-obsoletedmechanism.qdocinc \section1 QBackInsertIterator @@ -1220,20 +1233,20 @@ The \c QDataPump class was used internally in Qt 2.x in conjunction with QImageConsumer. It was obsoleted in Qt 3.0. - \input porting4-obsoletedmechanism.qdocinc + \input porting/porting4-obsoletedmechanism.qdocinc \section1 QDataSink The \c QDataSink class was used internally in Qt 2.x in conjunction with QImageConsumer. It was obsoleted in Qt 3.0. - \input porting4-obsoletedmechanism.qdocinc + \input porting/porting4-obsoletedmechanism.qdocinc \section1 QDataSource The \c QDataSource class was used internally in Qt 2.x in conjunction with QImageConsumer. It was obsoleted in Qt 3.0. - \input porting4-obsoletedmechanism.qdocinc + \input porting/porting4-obsoletedmechanism.qdocinc \section1 QDataTable @@ -2116,7 +2129,7 @@ The QIODeviceSource class was used internally in Qt 2.x in conjunction with QImageConsumer. It was obsoleted in Qt 3.0. - \input porting4-obsoletedmechanism.qdocinc + \input porting/porting4-obsoletedmechanism.qdocinc \section1 QLabel @@ -2553,7 +2566,7 @@ If you need to manage a set of actions created for a particular menu, we suggest that you construct a QActionGroup and add them to that. - The \l{Qt Examples#Main Windows}{Main Window examples} provided + The \l{Main Window Examples} provided show how to use Qt's action system to construct menus, toolbars, and other common user interface elements. @@ -3974,7 +3987,7 @@ \table \header \o Qt 3 function \o Qt 4 function - \input porting4-removedvariantfunctions.qdocinc + \input porting/porting4-removedvariantfunctions.qdocinc \endtable See the QVariant::Type enum for a list of types supported by QVariant. @@ -4219,13 +4232,13 @@ \table \header \o Qt 3 function signature \o Qt 4 function signature - \input porting4-modifiedvirtual.qdocinc + \input porting/porting4-modifiedvirtual.qdocinc \endtable Virtual functions that are not virtual in Qt 4: \table \header \o Qt 3 function \o Comment - \input porting4-removedvirtual.qdocinc + \input porting/porting4-removedvirtual.qdocinc \endtable */ diff --git a/doc/src/qt3to4.qdoc b/doc/src/porting/qt3to4.qdoc index d788f67..d788f67 100644 --- a/doc/src/qt3to4.qdoc +++ b/doc/src/porting/qt3to4.qdoc diff --git a/doc/src/qt4-accessibility.qdoc b/doc/src/porting/qt4-accessibility.qdoc index 747ca8d..1b985c1 100644 --- a/doc/src/qt4-accessibility.qdoc +++ b/doc/src/porting/qt4-accessibility.qdoc @@ -42,7 +42,6 @@ /*! \page qt4-accessibility.html \title Cross-Platform Accessibility Support in Qt 4 - \ingroup accessibility \contentspage {What's New in Qt 4}{Home} \previouspage The New Qt Designer diff --git a/doc/src/qt4-arthur.qdoc b/doc/src/porting/qt4-arthur.qdoc index b253d06..b253d06 100644 --- a/doc/src/qt4-arthur.qdoc +++ b/doc/src/porting/qt4-arthur.qdoc diff --git a/doc/src/qt4-designer.qdoc b/doc/src/porting/qt4-designer.qdoc index 0bfe034..0bfe034 100644 --- a/doc/src/qt4-designer.qdoc +++ b/doc/src/porting/qt4-designer.qdoc diff --git a/doc/src/qt4-interview.qdoc b/doc/src/porting/qt4-interview.qdoc index 158de87..158de87 100644 --- a/doc/src/qt4-interview.qdoc +++ b/doc/src/porting/qt4-interview.qdoc diff --git a/doc/src/qt4-mainwindow.qdoc b/doc/src/porting/qt4-mainwindow.qdoc index 7c48b95..7c48b95 100644 --- a/doc/src/qt4-mainwindow.qdoc +++ b/doc/src/porting/qt4-mainwindow.qdoc diff --git a/doc/src/qt4-network.qdoc b/doc/src/porting/qt4-network.qdoc index 36fd46a..36fd46a 100644 --- a/doc/src/qt4-network.qdoc +++ b/doc/src/porting/qt4-network.qdoc diff --git a/doc/src/qt4-scribe.qdoc b/doc/src/porting/qt4-scribe.qdoc index 64037cf..64037cf 100644 --- a/doc/src/qt4-scribe.qdoc +++ b/doc/src/porting/qt4-scribe.qdoc diff --git a/doc/src/qt4-sql.qdoc b/doc/src/porting/qt4-sql.qdoc index 3425e96..3425e96 100644 --- a/doc/src/qt4-sql.qdoc +++ b/doc/src/porting/qt4-sql.qdoc diff --git a/doc/src/qt4-styles.qdoc b/doc/src/porting/qt4-styles.qdoc index 4134962..4134962 100644 --- a/doc/src/qt4-styles.qdoc +++ b/doc/src/porting/qt4-styles.qdoc diff --git a/doc/src/qt4-threads.qdoc b/doc/src/porting/qt4-threads.qdoc index 1800d6a..1800d6a 100644 --- a/doc/src/qt4-threads.qdoc +++ b/doc/src/porting/qt4-threads.qdoc diff --git a/doc/src/qt4-tulip.qdoc b/doc/src/porting/qt4-tulip.qdoc index 9354651..9354651 100644 --- a/doc/src/qt4-tulip.qdoc +++ b/doc/src/porting/qt4-tulip.qdoc diff --git a/doc/src/qsql.qdoc b/doc/src/qsql.qdoc deleted file mode 100644 index 601a629..0000000 --- a/doc/src/qsql.qdoc +++ /dev/null @@ -1,139 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \namespace QSql - \inmodule QtSql - \brief The QSql namespace contains miscellaneous identifiers used throughout - the Qt SQL library. - - \inheaderfile QtSql - \ingroup database - \mainclass - - \sa {QtSql Module} -*/ - -/*! - \enum QSql::Confirm - \compat - - This enum type describes edit confirmations. - - \value Yes - \value No - \value Cancel -*/ - -/*! - \enum QSql::Op - \compat - - This enum type describes edit operations. - - \value None - \value Insert - \value Update - \value Delete -*/ - - -/*! - \enum QSql::Location - - This enum type describes special SQL navigation locations: - - \value BeforeFirstRow Before the first record. - \value AfterLastRow After the last record. - - \omitvalue BeforeFirst - \omitvalue AfterLast - - \sa QSqlQuery::at() -*/ - -/*! - \enum QSql::ParamTypeFlag - - This enum is used to specify the type of a bind parameter. - - \value In The bind parameter is used to put data into the database. - \value Out The bind parameter is used to receive data from the database. - \value InOut The bind parameter is used to put data into the - database; it will be overwritten with output data on executing - a query. - \value Binary This must be OR'd with one of the other flags if - you want to indicate that the data being transferred is - raw binary data. -*/ - -/*! - \enum QSql::TableType - - This enum type describes types of SQL tables. - - \value Tables All the tables visible to the user. - \value SystemTables Internal tables used by the database. - \value Views All the views visible to the user. - \value AllTables All of the above. -*/ - -/*! - \enum QSql::NumericalPrecisionPolicy - - This enum type describes at which precision levels numercial values are read from - a database. - - Some databases support numerical values with a precision that is not storable in a - C++ basic data type. The default behavior is to bind these values as a QString. - This enum can be used to override this behavior. - - \value LowPrecisionInt32 Force 32bit integer values. In case of floating point numbers, - the fractional part is silently discarded. - \value LowPrecisionInt64 Force 64bit integer values. In case of floating point numbers, - the fractional part is silently discarded. - \value LowPrecisionDouble Force \c double values. - \value HighPrecision The default behavior - try to preserve maximum precision. - - Note: The actual behaviour if an overflow occurs is driver specific. The Oracle database - just returns an error in this case. -*/ - diff --git a/doc/src/trolltech-webpages.qdoc b/doc/src/qt-webpages.qdoc index 20e6c66..20e6c66 100644 --- a/doc/src/trolltech-webpages.qdoc +++ b/doc/src/qt-webpages.qdoc diff --git a/doc/src/qt3support.qdoc b/doc/src/qt3support.qdoc deleted file mode 100644 index 59698e1..0000000 --- a/doc/src/qt3support.qdoc +++ /dev/null @@ -1,81 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \module Qt3Support - \title Qt3Support Module - \contentspage Qt's Modules - \previouspage Phonon Module - \nextpage QtDesigner - \ingroup modules - - \keyword Qt3Support - \brief The Qt3Support module provides classes that ease porting - from Qt 3 to Qt 4. - - \warning The classes in this module are intended to be used in - intermediate stages of a porting process and are not intended - to be used in production code. - - To include the definitions of the module's classes, use the - following directive: - - \snippet doc/src/snippets/code/doc_src_qt3support.qdoc 0 - - To link against the module, add this line to your \l qmake \c - .pro file: - - \snippet doc/src/snippets/code/doc_src_qt3support.qdoc 1 - - \note Since this module provides compatibility classes for - diverse parts of the Qt 3 API, it has dependencies on the QtCore, - QtGui, QtNetwork, QtSql, and QtXml modules. - - This module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. Most classes offered by this module are - also part of the \l{Qt GUI Framework Edition}. -\if defined(opensourceedition) || defined(desktoplightedition) - Classes that are not available for \l{Qt GUI Framework Edition} - users are marked as such in the class documentation. -\endif - - \sa {Porting to Qt 4} -*/ diff --git a/doc/src/qt4-intro.qdoc b/doc/src/qt4-intro.qdoc index 45a95b2..5c2642e 100644 --- a/doc/src/qt4-intro.qdoc +++ b/doc/src/qt4-intro.qdoc @@ -87,8 +87,8 @@ \o \l{QtXmlPatterns Module}{XQuery and XPath} support, providing facilities for XML processing beyond that supported by the QtXml module. \o Support for embedded widgets in \l{Graphics View} scenes. - \o The \l{Threading and Concurrent Programming}{QtConcurrent framework} for - concurrent programming using Qt paradigms and threading features. + \o The \l{QtConcurrent} framework for concurrent programming using Qt paradigms and + threading features. \o An \l{QtHelp Module}{improved help system} that can be used in conjunction with Qt Assistant or as an independent help resource manager. \o Printing system improvements, including the QPrinterInfo, QPrintPreviewWidget @@ -563,7 +563,7 @@ \section1 Improved Network Proxy Support Qt's networking classes have been updated with - \l{QtNetwork Module#Support for Network Proxies}{improved proxy support}. + \l{Network Programming#Support for Network Proxies}{improved proxy support}. This includes improved integration with system proxy settings and the added ability to handle non-trivial proxy cases. diff --git a/doc/src/qtdbus.qdoc b/doc/src/qtdbus.qdoc deleted file mode 100644 index d4a6908..0000000 --- a/doc/src/qtdbus.qdoc +++ /dev/null @@ -1,124 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/** -*- mode: C++ -*- -** 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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \module QtDBus - \title QtDBus module - \contentspage Qt's Modules - \previouspage QAxServer - \ingroup modules - - \keyword QtDBus - \target The QDBus compiler - - \brief The QtDBus module is a Unix-only library that you can use - to make Inter-Process Communication using the \l {Introduction to - D-Bus} {D-Bus} protocol. - - Applications using the QtDBus module can provide services to - other, remote applications by exporting objects, as well as use - services exported by those applications by placing calls and - accessing properties. - - The QtDBus module provides an interface that extends the Qt \l - {signalsandslots.html}{Signals and Slots} mechanism, allowing one - to connect to a signal emitted remotely as well as to connect a - local signal to remote slot. - - To use this module, use the following code in your application: - - \snippet doc/src/snippets/code/doc_src_qtdbus.qdoc 0 - - If you're using qmake to build your application, you can add this - line to your .pro file to make it link against the QtDBus - libraries: - - \snippet doc/src/snippets/code/doc_src_qtdbus.qdoc 1 - - \note The source code for this module is located in the \c{src/qdbus} - directory. When installing Qt from source, this module is built when Qt's - tools are built. - - See the \l {Introduction to D-Bus} page for detailed information on - how to use this module. - - This module is part of all \l{Qt editions}. -*/ diff --git a/doc/src/qtgui.qdoc b/doc/src/qtgui.qdoc deleted file mode 100644 index 63e544c..0000000 --- a/doc/src/qtgui.qdoc +++ /dev/null @@ -1,59 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \module QtGui - \title QtGui Module - \contentspage Qt's Modules - \previouspage QtCore - \nextpage QtNetwork - \ingroup modules - - \brief The QtGui module extends QtCore with GUI functionality. - - To include the definitions of both modules' classes, use the - following directive: - - \snippet doc/src/snippets/code/doc_src_qtgui.qdoc 0 - - The QtGui module is part of the \l{Qt GUI Framework Edition}, - the \l{Qt Full Framework Edition}, and the \l{Open Source Versions of Qt}. -*/ diff --git a/doc/src/qtmain.qdoc b/doc/src/qtmain.qdoc deleted file mode 100644 index 5f1f273..0000000 --- a/doc/src/qtmain.qdoc +++ /dev/null @@ -1,93 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qtmain.html - \title The qtmain Library - \ingroup licensing - \ingroup platform-notes - \brief Describes the use and license of the qtmain helper library. - - qtmain is a helper library that enables the developer to write a - cross-platform main() function on Windows. - - If you do not use \l qmake or the \l{Visual Studio Integration} - available to \l{Qt Commercial Editions}{commercial licensees}, you also - need to link against the \c qtmain library. - - \section1 License Information - - The QAxContainer module is not covered by the \l{GNU General Public License (GPL)}, - the \l{GNU Lesser General Public License (LGPL)}, or the - \l{Qt Commercial Editions}{Qt Commercial License}. Instead, it is distributed under - the following license. - - \legalese - Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).\br - All rights reserved. - - Contact: Nokia Corporation (qt-info@nokia.com)\br - - You may use this file under the terms of the BSD license as follows:\br - - "Redistribution and use in source and binary forms, with or without modification, - are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this list - of conditions and the following disclaimer.\br - * Redistributions in binary form must reproduce the above copyright notice, this - list of conditions and the following disclaimer in the documentation and/or other - materials provided with the distribution.\br - * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor the names of - its contributors may be used to endorse or promote products derived from this - software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT - SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, - INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED - TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." - \endlegalese -*/ diff --git a/doc/src/qtsvg.qdoc b/doc/src/qtsvg.qdoc deleted file mode 100644 index 18db387..0000000 --- a/doc/src/qtsvg.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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \module QtSvg - \title QtSvg Module - \since 4.1 - \contentspage Qt's Modules - \previouspage QtSql - \nextpage QtWebKit - \ingroup modules - - \brief The QtSvg module provides classes for displaying the contents of SVG - files. - - Scalable Vector Graphics (SVG) is a language for describing two-dimensional - graphics and graphical applications in XML. SVG 1.1 is a W3C Recommendation - and forms the core of the current SVG developments in Qt. SVG 1.2 is the - specification currently being developed by the \l{SVG Working Group}, and it - is \l{http://www.w3.org/TR/SVG12/}{available in draft form}. - The \l{Mobile SVG Profiles} (SVG Basic and SVG Tiny) are aimed at - resource-limited devices and are part of the 3GPP platform for third generation - mobile phones. You can read more about SVG at \l{About SVG}. - - \tableofcontents - - \section1 SVG Support - Qt supports the \l{SVG 1.2 Tiny Static Features}{static features} of - \l{SVG 1.2 Tiny}. ECMA scripts and DOM manipulation are currently not - supported. - - \section1 Configuring the Build Process - - Applications that use Qt's SVG classes need to - be configured to be built against the QtSvg module. - To include the definitions of the module's classes, use the - following directive: - - \snippet doc/src/snippets/code/doc_src_qtsvg.qdoc 0 - - To link against the module, add this line to your \l qmake \c - .pro file: - - \snippet doc/src/snippets/code/doc_src_qtsvg.qdoc 1 - - The QtSvg module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. - - \section1 Rendering SVG files - - The easiest way to render SVG files is to construct a QSvgWidget and - load an SVG file using one of the QSvgWidget::load() functions. - - QSvgRenderer is the class responsible for rendering SVG files for - QSvgWidget, and it can be used directly to provide SVG support for - custom widgets. - To load an SVG file, construct a QSvgRenderer with a file name or the - contents of a file, or call QSvgRenderer::load() on an existing - renderer. If the SVG file has been loaded successfully the - QSvgRenderer::isValid() will return true. - - Once you have loaded the SVG file successfully, you can render it - with the QSvgRenderer::render() function. Note that this scheme allows - you to render SVG files on all paint devices supported by Qt, including - QWidget, QGLWidget, and QImage. See the \l{SVG Viewer Example}{SVG Viewer} - example for more details. - - \section1 Additional Information - - Some code for arc handling in this module is derived from code with - the following license: - - \legalese - Copyright 2002 USC/Information Sciences Institute - - Permission to use, copy, modify, distribute, and sell this software - and its documentation for any purpose is hereby granted without - fee, provided that the above copyright notice appear in all copies - and that both that copyright notice and this permission notice - appear in supporting documentation, and that the name of - Information Sciences Institute not be used in advertising or - publicity pertaining to distribution of the software without - specific, written prior permission. Information Sciences Institute - makes no representations about the suitability of this software for - any purpose. It is provided "as is" without express or implied - warranty. - - INFORMATION SCIENCES INSTITUTE DISCLAIMS ALL WARRANTIES WITH REGARD - TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL INFORMATION SCIENCES - INSTITUTE BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL - DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA - OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER - TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. - \endlegalese -*/ diff --git a/doc/src/qttest.qdoc b/doc/src/qttest.qdoc deleted file mode 100644 index 5bb2626..0000000 --- a/doc/src/qttest.qdoc +++ /dev/null @@ -1,70 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \module QtTest - \title QtTest Module - \contentspage Qt's Modules - \previouspage QtAssistant - \nextpage QAxContainer - \ingroup modules - - \keyword QtTest - - \brief The QtTest module provides classes for unit testing Qt applications and libraries. - - Applications that use Qt's unit testing classes need to - be configured to be built against the QtTest module. - To include the definitions of the module's classes, use the - following directive: - - \snippet doc/src/snippets/code/doc_src_qttest.qdoc 0 - - To link against the module, add this line to your \l qmake \c - .pro file: - - \snippet doc/src/snippets/code/doc_src_qttest.qdoc 1 - - See the \l{QTestLib Manual} for a detailed introduction on how to use - Qt's unit testing features with your applications. - - The QtTest module is part of all \l{Qt editions}. -*/ diff --git a/doc/src/qtuiloader.qdoc b/doc/src/qtuiloader.qdoc deleted file mode 100644 index ba621a8..0000000 --- a/doc/src/qtuiloader.qdoc +++ /dev/null @@ -1,82 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \module QtUiTools - \title QtUiTools Module - \since 4.1 - \contentspage Qt's Modules - \previouspage QtDesigner - \nextpage QtHelp - \ingroup modules - - \brief The QtUiTools module provides classes to handle forms created - with Qt Designer. - - These forms are processed at run-time to produce dynamically-generated - user interfaces. In order to generate a form at run-time, a resource - file containing a UI file is needed. Applications that use the - form handling classes need to be configured to be built against the - QtUiTools module. This is done by including the following declaration - in a \c qmake project file to ensure that the application is compiled - and linked appropriately. - - \snippet doc/src/snippets/code/doc_src_qtuiloader.qdoc 0 - - A form loader object, provided by the QUiLoader class, is used to - construct the user interface. This user interface can - be retrieved from any QIODevice; for example, a QFile object can be - used to obtain a form stored in a project's resources. The - QUiLoader::load() function takes the user interface description - contained in the file and constructs the form widget. - - To include the definitions of the module's classes, use the following - directive: - - \snippet doc/src/snippets/code/doc_src_qtuiloader.qdoc 1 - - \note These classes are part of the \l{Open Source Versions of Qt} and - \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial - users. - - \sa{Calculator Builder Example}, {World Time Clock Builder Example} -*/ - diff --git a/doc/src/qundo.qdoc b/doc/src/qundo.qdoc deleted file mode 100644 index 9de2aa9..0000000 --- a/doc/src/qundo.qdoc +++ /dev/null @@ -1,113 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qundo.html -\title Overview of Qt's Undo Framework -\keyword Undo framework -\ingroup architecture - -\section1 Introduction - -Qt's Undo Framework is an implementation of the Command pattern, for -implementing undo/redo functionality in applications. - -The Command pattern is based on the idea that all editing in -an application is done by creating instances of command objects. -Command objects apply changes to the document and are stored -on a command stack. Furthermore, each command knows how to undo its -changes to bring the document back to its previous state. As long -as the application only uses command objects to change the state of -the document, it is possible to undo a sequence of commands by -traversing the stack downwards and calling undo -on each command in turn. It is also possible to redo a sequence of -commands by traversing the stack upwards and calling -redo on each command. - -\section1 Classes - -The framework consists of four classes: - -\list -\i \l QUndoCommand is the base class of all commands stored on an - undo stack. It can apply (redo) or undo a single change in the document. -\i \l QUndoStack is a list of QUndoCommand objects. It contains all the - commands executed on the document and can roll the document's state - backwards or forwards by undoing or redoing them. -\i \l QUndoGroup is a group of undo stacks. It is useful when an application - contains more than one undo stack, typically one for each opened - document. QUndoGroup provides a single pair of undo/redo slots for all - the stacks in the group. It forwards undo and redo requests to - the active stack, which is the stack associated with the document that - is currently being edited by the user. -\i \l QUndoView is a widget which shows the contents of an undo stack. Clicking - on a command in the view rolls the document's state backwards or - forwards to that command. -\endlist - -\section1 Concepts - -The following concepts are supported by the framework: - -\list -\i \bold{Clean state:} Used to signal when the document enters and leaves a - state that has been saved to disk. This is typically used to disable or - enable the save actions, and to update the document's title bar. -\i \bold{Command compression:} Used to compress sequences of commands into a - single command. - For example: In a text editor, the commands that insert individual - characters into the document can be compressed into a single command that - inserts whole sections of text. These bigger changes are more convenient - for the user to undo and redo. -\i \bold{Command macros:} A sequence of commands, all of which are undone or - redone in one step. - These simplify the task of writing an application, since a set of simpler - commands can be composed into more complex commands. For example, a command - that moves a set of selected objects in a document can be created by - combining a set of commands, each of which moves a single object. -\endlist - -QUndoStack provides convenient undo and redo QAction objects that -can be inserted into a menu or a toolbar. The text properties of these -actions always reflect what command will be undone or redone when -they are triggered. Similarly, QUndoGroup provides undo and redo actions -that always behave like the undo and redo actions of the active stack. -*/ diff --git a/doc/src/richtext.qdoc b/doc/src/richtext.qdoc deleted file mode 100644 index 405afd1..0000000 --- a/doc/src/richtext.qdoc +++ /dev/null @@ -1,1076 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page richtext.html -\nextpage Rich Text Document Structure - -\title Rich Text Processing -\ingroup architecture -\ingroup text-processing -\brief An overview of Qt's rich text processing, editing and display features. - -The Scribe framework provides a set of classes for reading and manipulating -structured rich text documents. Unlike previous rich text support in Qt, the -new classes are centered around the QTextDocument class rather than raw -textual information. This enables the developer to create and modify -structured rich text documents without having to prepare content in an -intermediate markup format. - -The information within a document can be accessed via two complementary -interfaces: A cursor-based interface is used for editing, and a read-only -hierarchical interface provides a high level overview of the document -structure. The main advantage of the cursor-based interface is that the -text can be edited using operations that mimic a user's interaction with -an editor, without losing the underlying structure of the document. The -read-only hierarchical interface is most useful when performing operations -such as searching and document export. - -This document is divided up into chapters for convenient reference: - -\list -\i \l{Rich Text Document Structure} outlines - the different kinds of elements in a QTextDocument, and describes how - they are arranged in a document structure. -\i \l{The QTextCursor Interface} explains how rich - text documents can be edited using the cursor-based interface. -\i \l{Common Rich Text Editing Tasks} examines some - common tasks that involve reading or manipulating rich text documents. -\i \l{Advanced Rich Text Processing} examines advanced rich text editing tasks. -\i \l{Supported HTML Subset} lists the HTML tags supported by QTextDocument. -\endlist - -See also the list of \l{Text Processing Classes}. - -*/ - -/*! -\page richtext-structure.html -\contentspage richtext.html Contents -\previouspage Rich Text Processing -\nextpage The QTextCursor Interface - -\title Rich Text Document Structure - -\tableofcontents - -The structured representation of a text document presents its contents as -a hierarchy of text blocks, frames, tables, and other objects. These provide -a logical structure to the document and describe how their contents will be -displayed. Generally, frames and tables are used to group other -structures while text blocks contain the actual textual information. - -New elements are created and inserted into the document programmatically -\l{richtext-cursor.html}{with a QTextCursor} or by using an editor -widget, such as QTextEdit. Elements can be given a particular format when -they are created; otherwise they take the cursor's current format for the -element. - -\table -\row -\i \inlineimage richtext-document.png -\i \bold{Basic structure} - -The "top level" of a document might be populated in the way shown. -Each document always contains a root frame, and this always contains -at least one text block. - -For documents with some textual content, the root -frame usually contains a sequence of blocks and other elements. - -Sequences of frames and tables are always separated by text blocks in a -document, even if the text blocks contain no information. This ensures that -new elements can always be inserted between existing structures. -\endtable - -In this chapter, we look at each of the structural elements -used in a rich text document, outline their features and uses, and show -how to examine their contents. Document editing is described in -\l{richtext-cursor.html}{The QTextCursor Interface}. - -\section1 Rich Text Documents - -QTextDocument objects contain all the information required to construct -rich text documents for use with a QTextEdit widget or in a custom editor. -Although QTextEdit makes it easy to display and edit rich text, documents -can also be used independently of any editor widget, for example: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 0 - -Alternatively, they can be extracted from an existing editor: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 1 - -This flexibility enables applications to handle multiple rich text -documents without the overhead of multiple editor widgets, or requiring -documents to be stored in some intermediate format. - -An empty document contains a root frame which itself contains a single -empty text block. The \l{richtext-cursor.html}{text cursor interface} -automatically inserts new document elements into the root frame, and -ensures that it is padded with empty blocks where necessary. - -We obtain the root frame in the following manner: - -\snippet doc/src/snippets/textdocument-frames/xmlwriter.h 0 -\snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 0 - -When navigating the document structure, it is useful to begin at the -root frame because it provides access to the entire document structure. - -\section1 Document Elements - -Rich text documents usually consist of common elements such as paragraphs, -frames, tables, and lists. These are represented in a QTextDocument -by the QTextBlock, QTextFrame, QTextTable, and QTextList classes. -Unlike the other elements in a document, images are represented by -specially formatted text fragments. This enables them to be placed -formatted inline with the surrounding text. - -The basic structural building blocks in documents are QTextBlock and -QTextFrame. Blocks themselves contain fragments of rich text -(QTextFragment), but these do not directly influence the high level -structure of a document. - -Elements which can group together other document elements are typically -subclasses of QTextObject, and fall into two categories: Elements that -group together text blocks are subclasses of QTextBlockGroup, and those -that group together frames and other elements are subclasses of QTextFrame. - -\section2 Text Blocks - -Text blocks are provided by the QTextBlock class. - -Text blocks group together fragments of text with different character formats, -and are used to represent paragraphs in the document. Each block -typically contains a number of text fragments with different styles. -Fragments are created when text is inserted into the document, and more -of them are added when the document is edited. The document splits, merges, -and removes fragments to efficiently represent the different styles -of text in the block. - -The fragments within a given block can be examined by using a -QTextBlock::iterator to traverse the block's internal structure: - -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 3 -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 5 -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 6 - -Blocks are also used to represent list items. As a result, blocks can -define their own character formats which contain information about -block-level decoration, such as the type of bullet points used for -list items. The formatting for the block itself is described by the -QTextBlockFormat class, and describes properties such as text alignment, -indentation, and background color. - -Although a given document may contain complex structures, once we have a -reference to a valid block in the document, we can navigate between each -of the text blocks in the order in which they were written: - -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 0 -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 1 -\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 2 - -This method is useful for when you want to extract just the rich text from a -document because it ignores frames, tables, and other types of structure. - -QTextBlock provides comparison operators that make it easier to manipulate -blocks: \l{QTextBlock::operator==()}{operator==()} and -\l{QTextBlock::operator!=()}{operator!=()} are used to test whether two -blocks are the same, and \l{QTextBlock::operator<()}{operator<()} is used -to determine which one occurs first in a document. - -\section2 Frames - -Frames are provided by the QTextFrame class. - -Text frames group together blocks of text and child frames, creating -document structures that are larger than paragraphs. The format of a frame -specifies how it is rendered and positioned on the page. Frames are -either inserted into the text flow, or they float on the left or right -hand side of the page. -Each document contains a root frame that contains all the other document -elements. As a result, all frames except the root frame have a parent -frame. - -Since text blocks are used to separate other document elements, each -frame will always contain at least one text block, and zero or more -child frames. We can inspect the contents of a frame by using a -QTextFrame::iterator to traverse the frame's child elements: - -\snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 1 -\snippet doc/src/snippets/textdocument-frames/xmlwriter.cpp 2 - -Note that the iterator selects both frames and blocks, so it is necessary -to check which it is referring to. This allows us to navigate the document -structure on a frame-by-frame basis yet still access text blocks if -required. Both the QTextBlock::iterator and QTextFrame::iterator classes -can be used in complementary ways to extract the required structure from -a document. - -\section2 Tables - -Tables are provided by the QTextTable class. - -Tables are collections of cells that are arranged in rows and columns. -Each table cell is a document element with its own character format, but it -can also contain other elements, such as frames and text blocks. Table cells -are automatically created when the table is constructed, or when extra rows -or columns are added. They can also be moved between tables. - -QTextTable is a subclass of QTextFrame, so tables are treated like frames -in the document structure. For each frame that we encounter in the -document, we can test whether it represents a table, and deal with it in a -different way: - -\snippet doc/src/snippets/textdocument-tables/xmlwriter.cpp 0 -\snippet doc/src/snippets/textdocument-tables/xmlwriter.cpp 1 - -The cells within an existing table can be examined by iterating through -the rows and columns. - -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 9 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 10 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 11 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 12 - - -\section2 Lists - -Lists are provided by the QTextList class. - -Lists are sequences of text blocks that are formatted in the usual way, but -which also provide the standard list decorations such as bullet points and -enumerated items. Lists can be nested, and will be indented if the list's -format specifies a non-zero indentation. - -We can refer to each list item by its index in the list: - -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 0 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 1 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 2 - -Since QTextList is a subclass of QTextBlockGroup, it does not group the -list items as child elements, but instead provides various functions for -managing them. This means that any text block we find when traversing a -document may actually be a list item. We can ensure that list items are -correctly identified by using the following code: - -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 3 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 4 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 5 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 6 -\snippet doc/src/snippets/textdocument-listitems/mainwindow.cpp 7 - - -\section2 Images - -Images in QTextDocument are represented by text fragments that reference -external images via the resource mechanism. Images are created using the -cursor interface, and can be modified later by changing the character -format of the image's text fragment: - -\snippet doc/src/snippets/textdocument-imageformat/main.cpp 0 -\snippet doc/src/snippets/textdocument-imageformat/main.cpp 1 -\snippet doc/src/snippets/textdocument-imageformat/main.cpp 2 - -The fragment that represents the image can be found by iterating over -the fragments in the text block that contains the image. -*/ - -/*! -\page richtext-cursor.html -\contentspage richtext.html Contents -\previouspage Rich Text Document Structure -\nextpage Common Rich Text Editing Tasks - -\title The QTextCursor Interface - -\tableofcontents - -The QTextCursor interface allows documents and their structure to be -edited in a way that should be familiar to most users of text editors and -document editing software. Rich text documents can have multiple cursors -associated with them, and each of these contains information about their -position in the document and any selections that they may hold. This -cursor-based paradigm makes common operations, such as cutting and pasting -text, simple to implement programmatically, yet it also allows more complex -editing operations to be performed on the document. - -This chapter describes most of the common editing operations that you -will need to perform using a cursor, from basic insertion of text and -document elements to more complex manipulation of document structures. - -\section1 Cursor-Based Editing - -At the simplest level, text documents are made up of a string of characters, -marked up in some way to represent the block structure of the text within the -document. QTextCursor provides a cursor-based interface that allows the -contents of a QTextDocument to be manipulated at the character level. Since -the elements (blocks, frames, tables, etc.) are also encoded in the character -stream, the document structure can itself be changed by the cursor. - -The cursor keeps track of its location within its parent document, and can -report information about the surrounding structure, such as the enclosing -text block, frame, table, or list. The formats of the enclosing structures -can also be directly obtained through the cursor. - -\section2 Using a Cursor - -The main use of a cursor is to insert or modify text within a block. -We can use a text editor's cursor to do this: - -\snippet doc/src/snippets/textblock-formats/main.cpp 0 - -Alternatively, we can obtain a cursor directly from a document: - -\snippet doc/src/snippets/textdocument-images/main.cpp 0 - -The cursor is positioned at the start of the document so that we can write -into the first (empty) block in the document. - -\section2 Grouping Cursor Operations - -A series of editing operations can be packaged together so that they can -be replayed, or undone together in a single action. This is achieved by -using the \c beginEditBlock() and \c endEditBlock() functions in the -following way, as in the following example where we select the word that -contains the cursor: - -\snippet doc/src/snippets/textdocument-selections/mainwindow.cpp 0 - -If editing operations are not grouped, the document automatically records -the individual operations so that they can be undone later. Grouping -operations into larger packages can make editing more efficient both for -the user and for the application, but care has to be taken not to group too -many operations together as the user may want find-grained control over the -undo process. - -\section2 Multiple Cursors - -Multiple cursors can be used to simultaneously edit the same document, -although only one will be visible to the user in a QTextEdit widget. -The QTextDocument ensures that each cursor writes text correctly and -does not interfere with any of the others. - -\omit -\snippet doc/src/snippets/textdocument-cursors/main.cpp 0 -\snippet doc/src/snippets/textdocument-cursors/main.cpp 1 -\endomit - -\section1 Inserting Document Elements - -QTextCursor provides several functions that can be used to change the -structure of a rich text document. Generally, these functions allow -document elements to be created with relevant formatting information, -and they are inserted into the document at the cursor's position. - -The first group of functions insert block-level elements, and update the -cursor position, but they do not return the element that was inserted: - -\list -\i \l{QTextCursor::insertBlock()}{insertBlock()} inserts a new text block - (paragraph) into a document at the cursor's position, and moves the - cursor to the start of the new block. -\i \l{QTextCursor::insertFragment()}{insertFragment()} inserts an existing - text fragment into a document at the cursor's position. -\i \l{QTextCursor::insertImage()}{insertImage()} inserts an image into a - document at the cursor's position. -\i \l{QTextCursor::insertText()}{insertText()} inserts text into the - document at the cursor's position. -\endlist - -You can examine the contents of the element that was inserted through the -cursor interface. - -The second group of functions insert elements that provide structure to -the document, and return the structure that was inserted: - -\list -\i \l{QTextCursor::insertFrame()}{insertFrame()} inserts a frame into the - document \e after the cursor's current block, and moves the cursor to - the start of the empty block in the new frame. -\i \l{QTextCursor::insertList()}{insertList()} inserts a list into the - document at the cursor's position, and moves the cursor to the start - of the first item in the list. -\i \l{QTextCursor::insertTable()}{insertTable()} inserts a table into - the document \e after the cursor's current block, and moves the cursor - to the start of the block following the table. -\endlist - -These elements either contain or group together other elements in the -document. - -\section2 Text and Text Fragments - -Text can be inserted into the current block in the current character -format, or in a custom format that is specified with the text: - -\snippet doc/src/snippets/textdocument-charformats/main.cpp 0 - -Once the character format has been used with a cursor, that format becomes -the default format for any text inserted with that cursor until another -character format is specified. - -If a cursor is used to insert text without specifying a character format, -the text will be given the character format used at that position in the -document. - -\section2 Blocks - -Text blocks are inserted into the document with the -\l{QTextCursor::insertBlock()}{insertBlock()} function. - -\snippet doc/src/snippets/textblock-formats/main.cpp 1 - -The cursor is positioned at the start of the new block. - -\section2 Frames - -Frames are inserted into a document using the cursor, and will be placed -within the cursor's current frame \e after the current block. -The following code shows how a frame can be inserted between two text -blocks in a document's root frame. We begin by finding the cursor's -current frame: - -\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 0 - -We insert some text in this frame then set up a frame format for the -child frame: - -\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 1 - -The frame format will give the frame an external margin of 32 pixels, -internal padding of 8 pixels, and a border that is 4 pixels wide. -See the QTextFrameFormat documentation for more information about -frame formats. - -The frame is inserted into the document after the preceding text: - -\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 2 - -We add some text to the document immediately after we insert the frame. -Since the text cursor is positioned \e{inside the frame} when it is inserted -into the document, this text will also be inserted inside the frame. - -Finally, we position the cursor outside the frame by taking the last -available cursor position inside the frame we recorded earlier: - -\snippet doc/src/snippets/textdocument-frames/mainwindow.cpp 3 - -The text that we add last is inserted after the child frame in the -document. Since each frame is padded with text blocks, this ensures that -more elements can always be inserted with a cursor. - -\section2 Tables - -Tables are inserted into the document using the cursor, and will be -placed within the cursor's current frame \e after the current block: - -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 0 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 3 - -Tables can be created with a specific format that defines the overall -properties of the table, such as its alignment, background color, and -the cell spacing used. It can also determine the constraints on each -column, allowing each of them to have a fixed width, or resize according -to the available space. - -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 2 - -The columns in the table created above will each take up a certain -percentage of the available width. Note that the table format is -optional; if you insert a table without a format, some sensible -default values will be used for the table's properties. - -Since cells can contain other document elements, they too can be -formatted and styled as necessary. - -Text can be added to the table by navigating to each cell with the cursor -and inserting text. - -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 4 - -We can create a simple timetable by following this approach: - -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 5 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 6 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 7 -\snippet doc/src/snippets/textdocument-tables/mainwindow.cpp 8 - -\section2 Lists - -Lists of block elements can be automatically created and inserted into the -document at the current cursor position. Each list that is created in this -way requires a list format to be specified: - -\snippet doc/src/snippets/textdocument-lists/mainwindow.cpp 0 - -The above code first checks whether the cursor is within an existing list -and, if so, gives the list format for the new list a suitable level of -indentation. This allows nested lists to be created with increasing -levels of indentation. A more sophisticated implementation would also use -different kinds of symbol for the bullet points in each level of the list. - -\section2 Images - -Inline images are added to documents through the cursor in the usual manner. -Unlike many other elements, all of the image properties are specified by the -image's format. This means that a QTextImageFormat object has to be -created before an image can be inserted: - -\snippet doc/src/snippets/textdocument-images/main.cpp 1 - -The image name refers to an entry in the application's resource file. -The method used to derive this name is described in -\l{resources.html}{The Qt Resource System}. - -*/ - -/*! -\page richtext-common-tasks.html -\contentspage richtext.html Contents -\previouspage The QTextCursor Interface -\nextpage Advanced Rich Text Processing - -\title Common Rich Text Editing Tasks - -\tableofcontents - -There are a number of tasks that are often performed by developers -when editing and processing text documents using Qt. These include the use -of display widgets such as QTextBrowser and QTextEdit, creation of -documents with QTextDocument, editing using a QTextCursor, and -exporting the document structure. -This document outlines some of the more common ways of using the rich -text classes to perform these tasks, showing convenient patterns that can -be reused in your own applications. - -\section1 Using QTextEdit - -A text editor widget can be constructed and used to display HTML in the -following way: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 2 - -By default, the text editor contains a document with a root frame, inside -which is an empty text block. This document can be obtained so that it can -be modified directly by the application: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 3 - -The text editor's cursor may also be used to edit a document: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 4 - -Although a document can be edited using many cursors at once, a QTextEdit -only displays a single cursor at a time. Therefore, if we want to update the -editor to display a particular cursor or its selection, we need to set the -editor's cursor after we have modified the document: - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 5 - -\section1 Selecting Text - -Text is selected by moving the cursor using operations that are similar to -those performed by a user in a text editor. To select text between two -points in the document, we need to position the cursor at the first point -then move it using a special mode (\l{QTextCursor::MoveMode}) with a -move operation (\l{QTextCursor::MoveOperation}). -When we select the text, we leave the selection anchor at the old cursor -position just as the user might do by holding down the Shift key when -selecting text: - -\snippet doc/src/snippets/textdocument-selections/mainwindow.cpp 1 - -In the above code, a whole word is selected using this method. QTextCursor -provides a number of common move operations for selecting individual -characters, words, lines, and whole blocks. - -\section1 Finding Text - -QTextDocument provides a cursor-based interface for searching, making -it easy to find and modify text in the style of a text editor. The following -code finds all the instances of a particular word in a document, and changes -the color of each: - -\snippet doc/src/snippets/textdocument-find/main.cpp 0 -\snippet doc/src/snippets/textdocument-find/main.cpp 1 - -Note that the cursor does not have to be moved after each search and replace -operation; it is always positioned at the end of the word that was just -replaced. - -\section1 Printing Documents - -QTextEdit is designed for the display of large rich text documents that are -read on screen, rendering them in the same way as a web browser. As a result, -it does not automatically break the contents of the document into page-sized -pieces that are suitable for printing. - -QTextDocument provides a \l{QTextDocument::print()}{print()} function to -allow documents to be printed using the QPrinter class. The following code -shows how to prepare a document in a QTextEdit for printing with a QPrinter: - -\snippet doc/src/snippets/textdocument-printing/mainwindow.cpp 0 - -The document is obtained from the text editor, and a QPrinter is constructed -then configured using a QPrintDialog. If the user accepts the printer's -configuration then the document is formatted and printed using the -\l{QTextDocument::print()}{print()} function. - -*/ - -/*! -\page richtext-advanced-processing.html -\contentspage richtext.html Contents -\previouspage Common Rich Text Editing Tasks -\nextpage Supported HTML Subset - -\title Advanced Rich Text Processing - -\section1 Handling Large Files - -Qt does not limit the size of files that are used for text -processing. In most cases, this will not present a problem. For -especially large files, however, you might experience that your -application will become unresponsive or that you will run out of -memory. The size of the files you can load depends on your -hardware and on Qt's and your own application's implementation. - -If you are faced with this problem, we recommend that you address the -following issues: - -\list - \o You should consider breaking up large paragraphs into smaller - ones as Qt handles small paragraphs better. You could also - insert line breaks at regular intervals, which will look the - same as one large paragraph in a QTextEdit. - \o You can reduce the amount of blocks in a QTextDocument with - \l{QTextDocument::}{maximumBlockCount()}. The document is only - as large as the number of blocks as far as QTextEdit is concerned. - \o When adding text to a text edit, it is an advantage to add it - in an edit block (see example below). The result is that the - text edit does not need to build the entire document structure at once. -\endlist - -We give an example of the latter technique from the list. We assume that -the text edit is visible. - -\snippet doc/src/snippets/code/doc_src_richtext.qdoc 6 - -\omit -Ideas for other sections: - - * Hiding QTextBlock elements. - * Changing the word wrapping mode in QTextEdit. Custom word wrapping? -\endomit -*/ - -/*! - \page richtext-html-subset.html - \title Supported HTML Subset - \brief Describes the support for HTML markup in text widgets. - - \contentspage richtext.html Contents - \previouspage Common Rich Text Editing Tasks - - Qt's text widgets are able to display rich text, specified using a subset of \l{HTML 4} - markup. Widgets that use QTextDocument, such as QLabel and QTextEdit, are able to display - rich text specified in this way. - - \tableofcontents - - \section1 Using HTML Markup in Text Widgets - - Widgets automatically detect HTML markup and display rich text accordingly. For example, - setting a label's \l{QLabel::}{text} property with the string \c{"<b>Hello</b> <i>Qt!</i>"} - will result in the label displaying text like this: \bold{Hello} \e{Qt!} - - When HTML markup is used for text, Qt follows the rules defined by the \l{HTML 4} - specification. This includes default properties for text layout, such as the - direction of the text flow (left-to-right) which can be changed by applying the - \l{#Block Attributes}{\c dir} attribute to blocks of text. - - \section1 Supported Tags - - The following table lists the HTML tags supported by Qt's - \l{Rich Text Processing}{rich text} engine: - - \table - \header \o Tag - \o Description - \o Comment - \row \o \c a - \o Anchor or link - \o Supports the \c href and \c name attributes. - \row \o \c address - \o Address - \o - \row \o \c b - \o Bold - \o - \row \o \c big - \o Larger font - \o - \row \o \c blockquote - \o Indented paragraph - \o - \row \o \c body - \o Document body - \o Supports the \c bgcolor attribute, which - can be a Qt \l{QColor::setNamedColor()}{color name} - or a \c #RRGGBB color specification. - \row \o \c br - \o Line break - \o - \row \o \c center - \o Centered paragraph - \o - \row \o \c cite - \o Inline citation - \o Same as \c i. - \row \o \c code - \o Code - \o Same as \c tt. - \row \o \c dd - \o Definition data - \o - \row \o \c dfn - \o Definition - \o Same as \c i. - \row \o \c div - \o Document division - \o Supports the standard \l{block attributes}. - \row \o \c dl - \o Definition list - \o Supports the standard \l{block attributes}. - \row \o \c dt - \o Definition term - \o Supports the standard \l{block attributes}. - \row \o \c em - \o Emphasized - \o Same as \c i. - \row \o \c font - \o Font size, family, and/or color - \o Supports the following attributes: - \c size, \c face, and \c color (Qt - \l{QColor::setNamedColor()}{color names} or - \c #RRGGBB). - \row \o \c h1 - \o Level 1 heading - \o Supports the standard \l{block attributes}. - \row \o \c h2 - \o Level 2 heading - \o Supports the standard \l{block attributes}. - \row \o \c h3 - \o Level 3 heading - \o Supports the standard \l{block attributes}. - \row \o \c h4 - \o Level 4 heading - \o Supports the standard \l{block attributes}. - \row \o \c h5 - \o Level 5 heading - \o Supports the standard \l{block attributes}. - \row \o \c h6 - \o Level 6 heading - \o Supports the standard \l{block attributes}. - \row \o \c head - \o Document header - \o - \row \o \c hr - \o Horizontal line - \o Supports the \c width attribute, which can - be specified as an absolute or relative (\c %) value. - \row \o \c html - \o HTML document - \o - \row \o \c i - \o Italic - \o - \row \o \c img - \o Image - \o Supports the \c src, \c source - (for Qt 3 compatibility), \c width, and \c height - attributes. - \row \o \c kbd - \o User-entered text - \o - \row \o \c meta - \o Meta-information - \o If a text encoding is specified using the \c{meta} tag, - it is picked up by Qt::codecForHtml(). - Likewise, if an encoding is specified to - QTextDocument::toHtml(), the encoding is stored using - a \c meta tag, for example: - - \snippet doc/src/snippets/code/doc_src_richtext.qdoc 7 - - \row \o \c li - \o List item - \o - \row \o \c nobr - \o Non-breakable text - \o - \row \o \c ol - \o Ordered list - \o Supports the standard \l{list attributes}. - \row \o \c p - \o Paragraph - \o Left-aligned by default. Supports the standard - \l{block attributes}. - \row \o \c pre - \o Preformated text - \o - \row \o \c qt - \o Qt rich-text document - \o Synonym for \c html. Provided for compatibility with - earlier versions of Qt. - \row \o \c s - \o Strikethrough - \o - \row \o \c samp - \o Sample code - \o Same as \c tt. - \row \o \c small - \o Small font - \o - \row \o \c span - \o Grouped elements - \o - \row \o \c strong - \o Strong - \o Same as \c b. - \row \o \c sub - \o Subscript - \o - \row \o \c sup - \o Superscript - \o - \row \o \c table - \o Table - \o Supports the following attributes: \c border, - \c bgcolor (Qt \l{QColor::setNamedColor()}{color names} - or \c #RRGGBB), \c cellspacing, \c cellpadding, - \c width (absolute or relative), and \c height. - \row \o \c tbody - \o Table body - \o Does nothing. - \row \o \c td - \o Table data cell - \o Supports the standard \l{table cell attributes}. - \row \o \c tfoot - \o Table footer - \o Does nothing. - \row \o \c th - \o Table header cell - \o Supports the standard \l{table cell attributes}. - \row \o \c thead - \o Table header - \o If the \c thead tag is specified, it is used when printing tables - that span multiple pages. - \row \o \c title - \o Document title - \o The value specified using the \c - title tag is available through - QTextDocument::metaInformation(). - \row \o \c tr - \o Table row - \o Supports the \c bgcolor attribute, which - can be a Qt \l{QColor::setNamedColor()}{color name} - or a \c #RRGGBB color specification. - \row \o \c tt - \o Typewrite font - \o - \row \o \c u - \o Underlined - \o - \row \o \c ul - \o Unordered list - \o Supports the standard \l{list attributes}. - \row \o \c var - \o Variable - \o Same as \c i. - \endtable - - \section1 Block Attributes - - The following attributes are supported by the \c div, \c dl, \c - dt, \c h1, \c h2, \c h3, \c h4, \c h5, \c h6, \c p tags: - - \list - \o \c align (\c left, \c right, \c center, \c justify) - \o \c dir (\c ltr, \c rtl) - \endlist - - \section1 List Attributes - - The following attribute is supported by the \c ol and \c ul tags: - - \list - \o \c type (\c 1, \c a, \c A, \c square, \c disc, \c circle) - \endlist - - \section1 Table Cell Attributes - - The following attributes are supported by the \c td and \c th - tags: - - \list - \o \c width (absolute, relative, or no-value) - \o \c bgcolor (Qt \l{QColor::setNamedColor()}{color names} or \c #RRGGBB) - \o \c colspan - \o \c rowspan - \o \c align (\c left, \c right, \c center, \c justify) - \o \c valign (\c top, \c middle, \c bottom) - \endlist - - \section1 CSS Properties - The following table lists the CSS properties supported by Qt's - \l{Rich Text Processing}{rich text} engine: - - \table - \header \o Property - \o Values - \o Description - \row - \o \c background-color - \o <color> - \o Background color for elements - \row - \o \c background-image - \o <uri> - \o Background image for elements - \row \o \c color - \o <color> - \o Text foreground color - \row \o \c font-family - \o <family name> - \o Font family name - \row \o \c font-size - \o [ small | medium | large | x-large | xx-large ] | <size>pt | <size>px - \o Font size relative to the document font, or specified in points or pixels - \row \o \c font-style - \o [ normal | italic | oblique ] - \o - \row \o \c font-weight - \o [ normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 ] - \o Specifies the font weight used for text, where \c normal and \c bold - are mapped to the corresponding QFont weights. Numeric values are - 8 times the equivalent QFont weight values. - \row \o \c text-decoration - \o none | [ underline || overline || line-through ] - \o Additional text effects - \row \o \c font - \o [ [ <'font-style'> || <'font-weight'> ]? <'font-size'> <'font-family'> ] - \o Font shorthand property - \row \o \c text-indent - \o <length>px - \o First line text indentation in pixels - \row \o \c white-space - \o normal | pre | nowrap | pre-wrap - \o Declares how whitespace in HTML is handled. - \row \o \c margin-top - \o <length>px - \o Top paragraph margin in pixels - \row \o \c margin-bottom - \o <length>px - \o Bottom paragraph margin in pixels - \row \o \c margin-left - \o <length>px - \o Left paragraph margin in pixels - \row \o \c margin-right - \o <length>px - \o Right paragraph margin in pixels - \row \o \c padding-top - \o <length>px - \o Top table cell padding in pixels - \row \o \c padding-bottom - \o <length>px - \o Bottom table cell padding in pixels - \row \o \c padding-left - \o <length>px - \o Left table cell padding in pixels - \row \o \c padding-right - \o <length>px - \o Right table cell padding in pixels - \row \o \c padding - \o <length>px - \o Shorthand for setting all the padding properties at once. - \row \o \c vertical-align - \o baseline | sub | super | middle | top | bottom - \o Vertical text alignment. For vertical alignment in text table cells only middle, top, and bottom apply. - \row \o \c border-color - \o <color> - \o Border color for text tables. - \row \o \c border-style - \o none | dotted | dashed | dot-dash | dot-dot-dash | solid | double | groove | ridge | inset | outset - \o Border style for text tables. - \row \o \c background - \o [ <'background-color'> || <'background-image'> ] - \o Background shorthand property - \row \o \c page-break-before - \o [ auto | always ] - \o Make it possible to enforce a page break before the paragraph/table - \row \o \c page-break-after - \o [ auto | always ] - \o Make it possible to enforce a page break after the paragraph/table - \row \o float - \o [ left | right | none ] - \o Specifies where an image or a text will be placed in another element. Note that the \c float property is - only supported for tables and images. - \row \o \c text-transform - \o [ uppercase | lowercase ] - \o Select the transformation that will be performed on the text prior to displaying it. - \row \o \c font-variant - \o small-caps - \o Perform the smallcaps transformation on the text prior to displaying it. - \row \o \c word-spacing - \o <width>px - \o Specifies an alternate spacing between each word. - \endtable - - \section1 Supported CSS Selectors - - All CSS 2.1 selector classes are supported except pseudo-class selectors such - as \c{:first-child}, \c{:visited} and \c{:hover}. - -*/ diff --git a/doc/src/ecmascript.qdoc b/doc/src/scripting/ecmascript.qdoc index a13f55d..e6c36d1 100644 --- a/doc/src/ecmascript.qdoc +++ b/doc/src/scripting/ecmascript.qdoc @@ -42,7 +42,6 @@ /*! \page ecmascript.html \title ECMAScript Reference - \ingroup scripting \brief A list of objects, functions and properties supported by QtScript. This reference contains a list of objects, functions and diff --git a/doc/src/qtscriptdebugger-manual.qdoc b/doc/src/scripting/qtscriptdebugger-manual.qdoc index 5c80a7e..1dada93 100644 --- a/doc/src/qtscriptdebugger-manual.qdoc +++ b/doc/src/scripting/qtscriptdebugger-manual.qdoc @@ -42,7 +42,6 @@ /*! \page qtscriptdebugger-manual.html \title Qt Script Debugger Manual - \ingroup scripting \brief A manual describing how to use the Qt Script debugger. The Qt Script debugger is a tool for debugging script execution in diff --git a/doc/src/qtscriptextensions.qdoc b/doc/src/scripting/qtscriptextensions.qdoc index ed09862..d0317ff 100644 --- a/doc/src/qtscriptextensions.qdoc +++ b/doc/src/scripting/qtscriptextensions.qdoc @@ -39,20 +39,9 @@ ** ****************************************************************************/ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - /*! \page qtscriptextensions.html \title Creating QtScript Extensions - \ingroup scripting \brief A guide to creating and using QtScript extensions. QtScript extensions can make additional functionality available to scripts diff --git a/doc/src/qtscript.qdoc b/doc/src/scripting/scripting.qdoc index 33b5691..5fcf8b2 100644 --- a/doc/src/qtscript.qdoc +++ b/doc/src/scripting/scripting.qdoc @@ -40,38 +40,28 @@ ****************************************************************************/ /*! - \module QtScript - \title QtScript Module - \since 4.3 - \contentspage Qt's Modules - \previouspage QtOpenVG - \nextpage QtScriptTools - \ingroup modules - \ingroup scripting + \group script + \title Scripting Classes and Overviews - \brief The QtScript module provides classes for making Qt applications scriptable. + \brief Classes that add scripting capabilities to Qt applications. +*/ - \tableofcontents - - \section1 Configuring the Build Process - - Applications that use Qt's Script classes need to - be configured to be built against the QtScript module. - To include the definitions of the module's classes, use the - following directive: +/*! + \page scripting.html + \title Making Applications Scriptable + \ingroup frameworks-technologies - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 0 + Qt 4.3 and later provides support for application scripting with ECMAScript. + The following guides and references cover aspects of programming with + ECMAScript and Qt. - To link against the module, add this line to your \l qmake \c .pro file: + \tableofcontents - \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 1 + \section1 Scripting Classes - The QtScript module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. + The following classes add scripting capabilities to Qt applications. - The QtScript module only provides core scripting facilities; the - QtScriptTools module provides additional Qt Script-related - components that application developers may find useful. + \annotatedlist script \section1 Language Overview @@ -287,11 +277,15 @@ When a signal or slot is overloaded, QtScript will attempt to pick the right overload based on the actual types of the QScriptValue arguments - involved in the function invocation. For example, if your class has slots \c{myOverloadedSlot(int)} and \c{myOverloadedSlot(QString)}, the following script code will behave reasonably: + involved in the function invocation. For example, if your class has slots + \c{myOverloadedSlot(int)} and \c{myOverloadedSlot(QString)}, the following + script code will behave reasonably: \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 11 - You can specify a particular overload by using array-style property access with the \l{QMetaObject::normalizedSignature()}{normalized signature} of the C++ function as the property name: + You can specify a particular overload by using array-style property access + with the \l{QMetaObject::normalizedSignature()}{normalized signature} of + the C++ function as the property name: \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 12 @@ -1371,8 +1365,7 @@ When experimenting with QtScript objects and inheritance, it can be helpful to use the interactive interpreter included with the - \l{Qt Examples#Qt Script}{Qt Script examples}, located in - \c{examples/script/qscript}. + \l{Qt Script Examples}, located in \c{examples/script/qscript}. \section2 Prototype Objects and Shared Properties @@ -1689,8 +1682,9 @@ doesn't provide any debugging-specific functionality (e.g. setting breakpoints), but it is the basis of tools that do. - The QScriptEngineDebugger class introduced in Qt 4.5 provides a Qt Script - debugger that can be embedded into your application. + The QScriptEngineDebugger class introduced in Qt 4.5 provides a + \l{Qt Script Debugger Manual}{Qt Script debugger} that can be embedded + into your application. \section2 Redefining print() @@ -1721,8 +1715,9 @@ scripts. There are currently no script plugins shipped with Qt. If you are implementing some Qt Script functionality that you want other - Qt application developers to be able to use, developing an extension (e.g. - by subclassing QScriptExtensionPlugin) is worth looking into. + Qt application developers to be able to use, \l{Creating QtScript Extensions} + {developing an extension} (e.g. by subclassing QScriptExtensionPlugin) is + worth looking into. \section1 Internationalization diff --git a/doc/src/snippets/code/doc_src_qalgorithms.qdoc b/doc/src/snippets/code/doc_src_qalgorithms.qdoc index 69d943c..e2126dd 100644 --- a/doc/src/snippets/code/doc_src_qalgorithms.qdoc +++ b/doc/src/snippets/code/doc_src_qalgorithms.qdoc @@ -302,7 +302,7 @@ list.clear(); QList<int> list; list << 33 << 12 << 68 << 6 << 12; qSort(list.begin(), list.end(), qLess<int>()); -// list: [ 68, 33, 12, 12, 6 ] +// list: [ 6, 12, 12, 33, 68 ] //! [24] diff --git a/doc/src/snippets/code/doc_src_qtmultimedia.qdoc b/doc/src/snippets/code/doc_src_qtmultimedia.qdoc new file mode 100644 index 0000000..87a03a4 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtmultimedia.qdoc @@ -0,0 +1,8 @@ +//! [0] +QT += multimedia +//! [0] + + +//! [1] +#include <QtMultimedia> +//! [1] diff --git a/doc/src/snippets/gestures/imageviewer/imagewidget.cpp b/doc/src/snippets/gestures/imageviewer/imagewidget.cpp new file mode 100644 index 0000000..f9d6a77 --- /dev/null +++ b/doc/src/snippets/gestures/imageviewer/imagewidget.cpp @@ -0,0 +1,364 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "imagewidget.h" + +#include <QtGui> + +ImageWidget::ImageWidget(QWidget *parent) + : QWidget(parent) +{ + setAttribute(Qt::WA_AcceptTouchEvents); + setAttribute(Qt::WA_PaintOnScreen); + setAttribute(Qt::WA_OpaquePaintEvent); + setAttribute(Qt::WA_NoSystemBackground); + + setObjectName("ImageWidget"); + + setMinimumSize(QSize(100,100)); + + position = 0; + zoomed = rotated = false; + + zoomedIn = false; + horizontalOffset = 0; + verticalOffset = 0; + +//! [imagewidget-connect] + panGesture = new QPanGesture(this); + connect(panGesture, SIGNAL(triggered()), this, SLOT(gestureTriggered())); + + tapAndHoldGesture = new TapAndHoldGesture(this); + connect(tapAndHoldGesture, SIGNAL(triggered()), this, SLOT(gestureTriggered())); + connect(tapAndHoldGesture, SIGNAL(finished()), this, SLOT(gestureFinished())); +//! [imagewidget-connect] +} + +void ImageWidget::paintEvent(QPaintEvent*) +{ + QPainter p(this); + if (currentImage.isNull()) { + p.fillRect(geometry(), Qt::white); + return; + } + int hoffset = 0; + int voffset = 0; + const int w = pixmap.width(); + const int h = pixmap.height(); + p.save(); + if (zoomedIn) { + hoffset = horizontalOffset; + voffset = verticalOffset; + if (horizontalOffset > 0) + p.fillRect(0, 0, horizontalOffset, height(), Qt::white); + if (verticalOffset > 0) + p.fillRect(0, 0, width(), verticalOffset, Qt::white); + } + p.drawPixmap(hoffset, voffset, pixmap); + if (hoffset + w < width()) + p.fillRect(hoffset + w, 0, width() - w - hoffset, height(), Qt::white); + if (voffset + h < height()) + p.fillRect(0, voffset + h, width(), height() - h - voffset, Qt::white); + + // paint touch feedback + if (touchFeedback.tapped || touchFeedback.doubleTapped) { + p.setPen(QPen(Qt::gray, 2)); + p.drawEllipse(touchFeedback.position, 5, 5); + if (touchFeedback.doubleTapped) { + p.setPen(QPen(Qt::darkGray, 2, Qt::DotLine)); + p.drawEllipse(touchFeedback.position, 15, 15); + } else if (touchFeedback.tapAndHoldState != 0) { + QPoint pts[8] = { + touchFeedback.position + QPoint( 0, -15), + touchFeedback.position + QPoint( 10, -10), + touchFeedback.position + QPoint( 15, 0), + touchFeedback.position + QPoint( 10, 10), + touchFeedback.position + QPoint( 0, 15), + touchFeedback.position + QPoint(-10, 10), + touchFeedback.position + QPoint(-15, 0) + }; + for (int i = 0; i < touchFeedback.tapAndHoldState/5; ++i) + p.drawEllipse(pts[i], 3, 3); + } + } else if (touchFeedback.sliding) { + p.setPen(QPen(Qt::red, 3)); + QPoint endPos = QPoint(touchFeedback.position.x(), touchFeedback.slidingStartPosition.y()); + p.drawLine(touchFeedback.slidingStartPosition, endPos); + int dx = 10; + if (touchFeedback.slidingStartPosition.x() < endPos.x()) + dx = -1*dx; + p.drawLine(endPos, endPos + QPoint(dx, 5)); + p.drawLine(endPos, endPos + QPoint(dx, -5)); + } + + for (int i = 0; i < TouchFeedback::MaximumNumberOfTouches; ++i) { + if (touchFeedback.touches[i].isNull()) + break; + p.drawEllipse(touchFeedback.touches[i], 10, 10); + } + p.restore(); +} + +void ImageWidget::mousePressEvent(QMouseEvent *event) +{ + touchFeedback.tapped = true; + touchFeedback.position = event->pos(); +} + +void ImageWidget::mouseDoubleClickEvent(QMouseEvent *event) +{ + touchFeedback.doubleTapped = true; + const QPoint p = event->pos(); + touchFeedback.position = p; + horizontalOffset = p.x() - currentImage.width()*1.0*p.x()/width(); + verticalOffset = p.y() - currentImage.height()*1.0*p.y()/height(); + setZoomedIn(!zoomedIn); + zoomed = rotated = false; + updateImage(); + + feedbackFadeOutTimer.start(500, this); +} + +//! [imagewidget-triggered-1] +void ImageWidget::gestureTriggered() +{ + if (sender() == panGesture) { +//! [imagewidget-triggered-1] + touchFeedback.tapped = false; + touchFeedback.doubleTapped = false; + QPanGesture *pg = qobject_cast<QPanGesture*>(sender()); + if (zoomedIn) { +#ifndef QT_NO_CURSOR + switch (pg->state()) { + case Qt::GestureStarted: + case Qt::GestureUpdated: + setCursor(Qt::SizeAllCursor); + break; + default: + setCursor(Qt::ArrowCursor); + } +#endif + horizontalOffset += pg->lastOffset().width(); + verticalOffset += pg->lastOffset().height(); + } else { + // only slide gesture should be accepted + if (pg->state() == Qt::GestureFinished) { + touchFeedback.sliding = false; + zoomed = rotated = false; + if (pg->totalOffset().width() > 0) + goNextImage(); + else + goPrevImage(); + updateImage(); + } + } + update(); + feedbackFadeOutTimer.start(500, this); + } else if (sender() == tapAndHoldGesture) { + if (tapAndHoldGesture->state() == Qt::GestureFinished) { + qDebug() << "tap and hold detected"; + touchFeedback.reset(); + update(); + + QMenu menu; + menu.addAction("Action 1"); + menu.addAction("Action 2"); + menu.addAction("Action 3"); + menu.exec(mapToGlobal(tapAndHoldGesture->pos())); + } else { + ++touchFeedback.tapAndHoldState; + update(); + } + feedbackFadeOutTimer.start(500, this); + } +} + +void ImageWidget::gestureFinished() +{ + qDebug() << "gesture finished" << sender(); +} + +void ImageWidget::gestureCancelled() +{ + qDebug() << "gesture cancelled" << sender(); +} + +void ImageWidget::resizeEvent(QResizeEvent*) +{ + updateImage(); +} + +void ImageWidget::updateImage() +{ + // should use qtconcurrent here? + transformation = QTransform(); + if (zoomedIn) { + } else { + if (currentImage.isNull()) + return; + if (zoomed) { + transformation = transformation.scale(zoom, zoom); + } else { + double xscale = (double)width()/currentImage.width(); + double yscale = (double)height()/currentImage.height(); + if (xscale < yscale) + yscale = xscale; + else + xscale = yscale; + transformation = transformation.scale(xscale, yscale); + } + if (rotated) + transformation = transformation.rotate(angle); + } + pixmap = QPixmap::fromImage(currentImage).transformed(transformation); + update(); +} + +void ImageWidget::openDirectory(const QString &path) +{ + this->path = path; + QDir dir(path); + QStringList nameFilters; + nameFilters << "*.jpg" << "*.png"; + files = dir.entryList(nameFilters, QDir::Files|QDir::Readable, QDir::Name); + + position = 0; + goToImage(0); + updateImage(); +} + +QImage ImageWidget::loadImage(const QString &fileName) +{ + QImageReader reader(fileName); + if (!reader.canRead()) { + qDebug() << fileName << ": can't load image"; + return QImage(); + } + QImage image; + if (!reader.read(&image)) { + qDebug() << fileName << ": corrupted image"; + return QImage(); + } + return image; +} + +void ImageWidget::setZoomedIn(bool zoomed) +{ + zoomedIn = zoomed; +} + +void ImageWidget::goNextImage() +{ + if (files.isEmpty()) + return; + if (position < files.size()-1) { + ++position; + prevImage = currentImage; + currentImage = nextImage; + if (position+1 < files.size()) + nextImage = loadImage(path+QLatin1String("/")+files.at(position+1)); + else + nextImage = QImage(); + } + setZoomedIn(false); + updateImage(); +} + +void ImageWidget::goPrevImage() +{ + if (files.isEmpty()) + return; + if (position > 0) { + --position; + nextImage = currentImage; + currentImage = prevImage; + if (position > 0) + prevImage = loadImage(path+QLatin1String("/")+files.at(position-1)); + else + prevImage = QImage(); + } + setZoomedIn(false); + updateImage(); +} + +void ImageWidget::goToImage(int index) +{ + if (files.isEmpty()) + return; + if (index < 0 || index >= files.size()) { + qDebug() << "goToImage: invalid index: " << index; + return; + } + if (index == position+1) { + goNextImage(); + return; + } + if (position > 0 && index == position-1) { + goPrevImage(); + return; + } + position = index; + pixmap = QPixmap(); + if (index > 0) + prevImage = loadImage(path+QLatin1String("/")+files.at(position-1)); + else + prevImage = QImage(); + currentImage = loadImage(path+QLatin1String("/")+files.at(position)); + if (position+1 < files.size()) + nextImage = loadImage(path+QLatin1String("/")+files.at(position+1)); + else + nextImage = QImage(); + setZoomedIn(false); + updateImage(); +} + +void ImageWidget::timerEvent(QTimerEvent *event) +{ + if (event->timerId() == touchFeedback.tapTimer.timerId()) { + touchFeedback.tapTimer.stop(); + } else if (event->timerId() == feedbackFadeOutTimer.timerId()) { + feedbackFadeOutTimer.stop(); + touchFeedback.reset(); + } + update(); +} + +#include "moc_imagewidget.cpp" diff --git a/doc/src/snippets/gestures/imageviewer/imagewidget.h b/doc/src/snippets/gestures/imageviewer/imagewidget.h new file mode 100644 index 0000000..fcad5b9 --- /dev/null +++ b/doc/src/snippets/gestures/imageviewer/imagewidget.h @@ -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 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef IMAGEWIDGET_H +#define IMAGEWIDGET_H + +#include <QWidget> +#include <QImage> +#include <QPixmap> + +#include <QtGui> + +#include "tapandholdgesture.h" + +class ImageWidget : public QWidget +{ + Q_OBJECT + +public: + ImageWidget(QWidget *parent = 0); + + void openDirectory(const QString &path); + +protected: + void paintEvent(QPaintEvent*); + void resizeEvent(QResizeEvent*); + void timerEvent(QTimerEvent*); + void mousePressEvent(QMouseEvent*); + void mouseDoubleClickEvent(QMouseEvent*); + +//! [imagewidget-slots] +private slots: + void gestureTriggered(); + void gestureFinished(); + void gestureCancelled(); +//! [imagewidget-slots] + +private: + void updateImage(); + QImage loadImage(const QString &fileName); + void loadImage(); + void setZoomedIn(bool zoomed); + void goNextImage(); + void goPrevImage(); + void goToImage(int index); + + QPanGesture *panGesture; + TapAndHoldGesture *tapAndHoldGesture; + + QString path; + QStringList files; + int position; + + QImage prevImage, nextImage; + QImage currentImage; + QPixmap pixmap; + QTransform transformation; + + bool zoomedIn; + int horizontalOffset; + int verticalOffset; + + bool zoomed; + qreal zoom; + bool rotated; + qreal angle; + + struct TouchFeedback + { + bool tapped; + QPoint position; + bool sliding; + QPoint slidingStartPosition; + QBasicTimer tapTimer; + int tapState; + bool doubleTapped; + int tapAndHoldState; + + enum { MaximumNumberOfTouches = 5 }; + QPoint touches[MaximumNumberOfTouches]; + + inline TouchFeedback() { reset(); } + inline void reset() + { + tapped = false; + sliding = false; + tapTimer.stop(); + tapState = 0; + doubleTapped = false; + tapAndHoldState = 0; + for (int i = 0; i < MaximumNumberOfTouches; ++i) { + touches[i] = QPoint(); + } + } + } touchFeedback; + QBasicTimer feedbackFadeOutTimer; +}; + +#endif diff --git a/doc/src/snippets/gestures/imageviewer/tapandholdgesture.cpp b/doc/src/snippets/gestures/imageviewer/tapandholdgesture.cpp new file mode 100644 index 0000000..03898dc --- /dev/null +++ b/doc/src/snippets/gestures/imageviewer/tapandholdgesture.cpp @@ -0,0 +1,159 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "tapandholdgesture.h" + +#include <QtGui/qevent.h> + +// #define TAPANDHOLD_USING_MOUSE + +/*! + \class TapAndHoldGesture + \since 4.6 + + \brief The TapAndHoldGesture class represents a Tap-and-Hold gesture, + providing additional information. +*/ + +const int TapAndHoldGesture::iterationCount = 40; +const int TapAndHoldGesture::iterationTimeout = 50; + +/*! + Creates a new Tap and Hold gesture handler object and marks it as a child + of \a parent. + + On some platforms like Windows there is a system-wide tap and hold gesture + that cannot be overriden, hence the gesture might never trigger and default + context menu will be shown instead. +*/ +TapAndHoldGesture::TapAndHoldGesture(QWidget *parent) + : QGesture(parent), iteration(0) +{ +} + +/*! \internal */ +bool TapAndHoldGesture::filterEvent(QEvent *event) +{ + if (!event->spontaneous()) + return false; + const QTouchEvent *ev = static_cast<const QTouchEvent*>(event); + switch (event->type()) { + case QEvent::TouchBegin: { + if (timer.isActive()) + timer.stop(); + timer.start(TapAndHoldGesture::iterationTimeout, this); + const QPoint p = ev->touchPoints().at(0).pos().toPoint(); + position = p; + break; + } + case QEvent::TouchUpdate: + if (ev->touchPoints().size() == 1) { + const QPoint startPos = ev->touchPoints().at(0).startPos().toPoint(); + const QPoint pos = ev->touchPoints().at(0).pos().toPoint(); + if ((startPos - pos).manhattanLength() > 15) + reset(); + } else { + reset(); + } + break; + case QEvent::TouchEnd: + reset(); + break; +#ifdef TAPANDHOLD_USING_MOUSE + case QEvent::MouseButtonPress: { + if (timer.isActive()) + timer.stop(); + timer.start(TapAndHoldGesture::iterationTimeout, this); + const QPoint p = static_cast<QMouseEvent*>(event)->pos(); + position = startPosition = p; + break; + } + case QEvent::MouseMove: { + const QPoint startPos = startPosition; + const QPoint pos = static_cast<QMouseEvent*>(event)->pos(); + if ((startPos - pos).manhattanLength() > 15) + reset(); + break; + } + case QEvent::MouseButtonRelease: + reset(); + break; +#endif // TAPANDHOLD_USING_MOUSE + default: + break; + } + return false; +} + +/*! \internal */ +void TapAndHoldGesture::timerEvent(QTimerEvent *event) +{ + if (event->timerId() != timer.timerId()) + return; + if (iteration == TapAndHoldGesture::iterationCount) { + timer.stop(); + updateState(Qt::GestureFinished); + } else { + updateState(Qt::GestureUpdated); + } + ++iteration; +} + +/*! \internal */ +//! [tapandhold-reset] +void TapAndHoldGesture::reset() +{ + timer.stop(); + iteration = 0; + position = startPosition = QPoint(); + updateState(Qt::NoGesture); +} +//! [tapandhold-reset] + +/*! + \property TapAndHoldGesture::pos + + \brief The position of the gesture. +*/ +QPoint TapAndHoldGesture::pos() const +{ + return position; +} diff --git a/doc/src/qtcore.qdoc b/doc/src/snippets/gestures/imageviewer/tapandholdgesture.h index 7e23c5e..bf0f867 100644 --- a/doc/src/qtcore.qdoc +++ b/doc/src/snippets/gestures/imageviewer/tapandholdgesture.h @@ -3,7 +3,7 @@ ** 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. +** This file is part of the examples of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:LGPL$ ** No Commercial Usage @@ -39,22 +39,36 @@ ** ****************************************************************************/ -/*! - \module QtCore - \title QtCore Module - \contentspage Qt's Modules - \previouspage Qt's Modules - \nextpage QtGui - \ingroup modules +#ifndef TAPANDHOLDGESTURE_H +#define TAPANDHOLDGESTURE_H - \keyword QtCore +#include <QtCore/QBasicTimer> +#include <QtGui/QGesture> +#include <QtGui/QWidget> - \brief The QtCore module contains core non-GUI functionality. +class TapAndHoldGesture : public QGesture +{ + Q_OBJECT + Q_PROPERTY(QPoint pos READ pos) - All other Qt modules rely on this module. To include the - definitions of the module's classes, use the following directive: +public: + TapAndHoldGesture(QWidget *parent); - \snippet doc/src/snippets/code/doc_src_qtcore.qdoc 0 + bool filterEvent(QEvent *event); + void reset(); - The QtCore module is part of all \l{Qt editions}. -*/ + QPoint pos() const; + +protected: + void timerEvent(QTimerEvent *event); + +private: + QBasicTimer timer; + int iteration; + QPoint position; + QPoint startPosition; + static const int iterationCount; + static const int iterationTimeout; +}; + +#endif // TAPANDHOLDGESTURE_H diff --git a/doc/src/snippets/gestures/qgesture.cpp b/doc/src/snippets/gestures/qgesture.cpp new file mode 100644 index 0000000..79dcae1 --- /dev/null +++ b/doc/src/snippets/gestures/qgesture.cpp @@ -0,0 +1,283 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "qgesture.h" +#include <private/qgesture_p.h> +#include "qgraphicsitem.h" + +QT_BEGIN_NAMESPACE + + +class QEventFilterProxyGraphicsItem : public QGraphicsItem +{ +public: + QEventFilterProxyGraphicsItem(QGesture *g) + : gesture(g) + { + } + bool sceneEventFilter(QGraphicsItem *, QEvent *event) + { + return gesture ? gesture->filterEvent(event) : false; + } + QRectF boundingRect() const { return QRectF(); } + void paint(QPainter*, const QStyleOptionGraphicsItem*, QWidget*) { } + +private: + QGesture *gesture; +}; + +/*! + \class QGesture + \since 4.6 + + \brief The QGesture class is the base class for implementing custom + gestures. + + This class represents both an object that recognizes a gesture out of a set + of input events (a gesture recognizer), and a gesture object itself that + can be used to get extended information about the triggered gesture. + + The class has a list of properties that can be queried by the user to get + some gesture-specific parameters (for example, an offset of a Pan gesture). + + Usually gesture recognizer implements a state machine, storing its state + internally in the recognizer object. The recognizer receives input events + through the \l{QGesture::}{filterEvent()} virtual function and decides + whether the event should change the state of the recognizer by emitting an + appropriate signal. + + Input events should be either fed to the recognizer one by one with a + filterEvent() function, or the gesture recognizer should be attached to an + object it filters events for by specifying it as a parent object. The + QGesture object installs itself as an event filter to the parent object + automatically, the unsetObject() function should be used to remove an event + filter from the parent object. To make a + gesture that operates on a QGraphicsItem, both the appropriate QGraphicsView + should be passed as a parent object and setGraphicsItem() functions should + be used to attach a gesture to a graphics item. + + This is a base class, to create a custom gesture type, you should subclass + it and implement its pure virtual functions. + + \sa QPanGesture +*/ + +/*! \fn bool QGesture::filterEvent(QEvent *event) + + Parses input \a event and emits a signal when detects a gesture. + + In your reimplementation of this function, if you want to filter the \a + event out, i.e. stop it being handled further, return true; otherwise + return false; + + This is a pure virtual function that needs to be implemented in subclasses. +*/ + +/*! \fn void QGesture::started() + + The signal is emitted when the gesture is started. Extended information + about the gesture is contained in the signal sender object. + + In addition to started(), a triggered() signal should also be emitted. +*/ + +/*! \fn void QGesture::triggered() + + The signal is emitted when the gesture is detected. Extended information + about the gesture is contained in the signal sender object. +*/ + +/*! \fn void QGesture::finished() + + The signal is emitted when the gesture is finished. Extended information + about the gesture is contained in the signal sender object. +*/ + +/*! \fn void QGesture::cancelled() + + The signal is emitted when the gesture is cancelled, for example the reset() + function is called while the gesture was in the process of emitting a + triggered() signal. Extended information about the gesture is contained in + the sender object. +*/ + + +/*! + Creates a new gesture handler object and marks it as a child of \a parent. + + The \a parent object is also the default event source for the gesture, + meaning that the gesture installs itself as an event filter for the \a + parent. + + \sa setGraphicsItem() +*/ +QGesture::QGesture(QObject *parent) + : QObject(*new QGesturePrivate, parent) +{ + if (parent) + parent->installEventFilter(this); +} + +/*! \internal + */ +QGesture::QGesture(QGesturePrivate &dd, QObject *parent) + : QObject(dd, parent) +{ + if (parent) + parent->installEventFilter(this); +} + +/*! + Destroys the gesture object. +*/ +QGesture::~QGesture() +{ +} + +/*! \internal + */ +bool QGesture::eventFilter(QObject *receiver, QEvent *event) +{ + Q_D(QGesture); + if (d->graphicsItem && receiver == parent()) + return false; + return filterEvent(event); +} + +/*! + \property QGesture::state + + \brief The current state of the gesture. +*/ + +/*! + Returns the gesture recognition state. + */ +Qt::GestureState QGesture::state() const +{ + return d_func()->state; +} + +/*! + Sets this gesture's recognition state to \a state and emits appropriate + signals. + + This functions emits the signals according to the old state and the new + \a state, and it should be called after all the internal properties have been + initialized. + + \sa started(), triggered(), finished(), cancelled() + */ +void QGesture::updateState(Qt::GestureState state) +{ + Q_D(QGesture); + if (d->state == state) { + if (state == Qt::GestureUpdated) + emit triggered(); + return; + } + const Qt::GestureState oldState = d->state; + d->state = state; + if (state != Qt::NoGesture && oldState > state) { + // comparing the state as ints: state should only be changed from + // started to (optionally) updated and to finished. + qWarning("QGesture::updateState: incorrect new state"); + return; + } + if (oldState == Qt::NoGesture) + emit started(); + if (state == Qt::GestureUpdated) + emit triggered(); + else if (state == Qt::GestureFinished) + emit finished(); + else if (state == Qt::NoGesture) + emit cancelled(); + + if (state == Qt::GestureFinished) { + // gesture is finished, so we reset the internal state. + d->state = Qt::NoGesture; + } +} + +/*! + Sets the \a graphicsItem the gesture is filtering events for. + + The gesture will install an event filter to the \a graphicsItem and + redirect them to the filterEvent() function. + + \sa graphicsItem() +*/ +void QGesture::setGraphicsItem(QGraphicsItem *graphicsItem) +{ + Q_D(QGesture); + if (d->graphicsItem && d->eventFilterProxyGraphicsItem) + d->graphicsItem->removeSceneEventFilter(d->eventFilterProxyGraphicsItem); + d->graphicsItem = graphicsItem; + if (!d->eventFilterProxyGraphicsItem) + d->eventFilterProxyGraphicsItem = new QEventFilterProxyGraphicsItem(this); + if (graphicsItem) + graphicsItem->installSceneEventFilter(d->eventFilterProxyGraphicsItem); +} + +/*! + Returns the graphics item the gesture is filtering events for. + + \sa setGraphicsItem() +*/ +QGraphicsItem* QGesture::graphicsItem() const +{ + return d_func()->graphicsItem; +} + +/*! \fn void QGesture::reset() + + Resets the internal state of the gesture. This function might be called by + the filterEvent() implementation in a derived class, or by the user to + cancel a gesture. The base class implementation calls + updateState(Qt::NoGesture) which emits the cancelled() + signal if the state() of the gesture indicated it was active. +*/ +void QGesture::reset() +{ + updateState(Qt::NoGesture); +} + +QT_END_NAMESPACE diff --git a/doc/src/qtscripttools.qdoc b/doc/src/snippets/gestures/qgesture.h index 7a5ffe6..beb3de0 100644 --- a/doc/src/qtscripttools.qdoc +++ b/doc/src/snippets/gestures/qgesture.h @@ -3,7 +3,7 @@ ** 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. +** This file is part of the QtGui module of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:LGPL$ ** No Commercial Usage @@ -39,34 +39,63 @@ ** ****************************************************************************/ -/*! - \module QtScriptTools - \title QtScriptTools Module - \since 4.5 - \contentspage Qt's Modules - \previouspage QtScript - \nextpage QtSql - \ingroup modules - \ingroup scripting +#ifndef QGESTURE_H +#define QGESTURE_H - \brief The QtScriptTools module provides additional components for applications that use Qt Script. +#include <QtCore/qobject.h> +#include <QtCore/qlist.h> +#include <QtCore/qdatetime.h> +#include <QtCore/qpoint.h> +#include <QtCore/qrect.h> +#include <QtCore/qmetatype.h> - \tableofcontents +QT_BEGIN_HEADER - \section1 Configuring the Build Process +QT_BEGIN_NAMESPACE - Applications that use the Qt Script Tools classes need to - be configured to be built against the QtScriptTools module. - To include the definitions of the module's classes, use the - following directive: +QT_MODULE(Gui) - \snippet doc/src/snippets/code/doc.src.qtscripttools.qdoc 0 +class QGraphicsItem; +class QGesturePrivate; +class Q_GUI_EXPORT QGesture : public QObject +{ + Q_OBJECT + Q_DECLARE_PRIVATE(QGesture) - To link against the module, add this line to your \l qmake \c .pro file: + Q_PROPERTY(Qt::GestureState state READ state) - \snippet doc/src/snippets/code/doc.src.qtscripttools.qdoc 1 +public: + explicit QGesture(QObject *parent = 0); + ~QGesture(); - The QtScriptTools module is part of the \l{Qt Full Framework Edition} and - the \l{Open Source Versions of Qt}. + virtual bool filterEvent(QEvent *event) = 0; - */ + void setGraphicsItem(QGraphicsItem *); + QGraphicsItem *graphicsItem() const; + + Qt::GestureState state() const; + +protected: + QGesture(QGesturePrivate &dd, QObject *parent); + bool eventFilter(QObject*, QEvent*); + + virtual void reset(); + void updateState(Qt::GestureState state); + +//! [qgesture-signals] +Q_SIGNALS: + void started(); + void triggered(); + void finished(); + void cancelled(); +//! [qgesture-signals] + +private: + friend class QWidget; +}; + +QT_END_NAMESPACE + +QT_END_HEADER + +#endif // QGESTURE_H diff --git a/doc/src/snippets/gestures/qstandardgestures.cpp b/doc/src/snippets/gestures/qstandardgestures.cpp new file mode 100644 index 0000000..fbeb050 --- /dev/null +++ b/doc/src/snippets/gestures/qstandardgestures.cpp @@ -0,0 +1,483 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "qstandardgestures.h" +#include "qstandardgestures_p.h" + +#include <qabstractscrollarea.h> +#include <qscrollbar.h> +#include <private/qapplication_p.h> +#include <private/qevent_p.h> +#include <private/qwidget_p.h> + +QT_BEGIN_NAMESPACE + +#ifdef Q_WS_WIN +QWidgetPrivate *qt_widget_private(QWidget *widget); +#endif + +/*! + \class QPanGesture + \since 4.6 + + \brief The QPanGesture class represents a Pan gesture, + providing additional information related to panning. +*/ + +/*! + Creates a new Pan gesture handler object and marks it as a child of \a + parent. + + On some platform like Windows it's necessary to provide a non-null widget + as \a parent to get native gesture support. +*/ +QPanGesture::QPanGesture(QWidget *parent) + : QGesture(*new QPanGesturePrivate, parent) +{ + if (parent) { + QApplicationPrivate *qAppPriv = QApplicationPrivate::instance(); + qAppPriv->widgetGestures[parent].pan = this; +#ifdef Q_WS_WIN + qt_widget_private(parent)->winSetupGestures(); +#endif + } +} + +/*! \internal */ +bool QPanGesture::event(QEvent *event) +{ + switch (event->type()) { + case QEvent::ParentAboutToChange: + if (QWidget *w = qobject_cast<QWidget*>(parent())) { + QApplicationPrivate::instance()->widgetGestures[w].pan = 0; +#ifdef Q_WS_WIN + qt_widget_private(w)->winSetupGestures(); +#endif + } + break; + case QEvent::ParentChange: + if (QWidget *w = qobject_cast<QWidget*>(parent())) { + QApplicationPrivate::instance()->widgetGestures[w].pan = this; +#ifdef Q_WS_WIN + qt_widget_private(w)->winSetupGestures(); +#endif + } + break; + default: + break; + } + +#if defined(Q_OS_MAC) && !defined(QT_MAC_USE_COCOA) + Q_D(QPanGesture); + if (event->type() == QEvent::Timer) { + const QTimerEvent *te = static_cast<QTimerEvent *>(event); + if (te->timerId() == d->panFinishedTimer) { + killTimer(d->panFinishedTimer); + d->panFinishedTimer = 0; + d->lastOffset = QSize(0, 0); + updateState(Qt::GestureFinished); + } + } +#endif + + return QObject::event(event); +} + +bool QPanGesture::eventFilter(QObject *receiver, QEvent *event) +{ +#ifdef Q_WS_WIN + Q_D(QPanGesture); + if (receiver->isWidgetType() && event->type() == QEvent::NativeGesture) { + QNativeGestureEvent *ev = static_cast<QNativeGestureEvent*>(event); + QApplicationPrivate *qAppPriv = QApplicationPrivate::instance(); + QApplicationPrivate::WidgetStandardGesturesMap::iterator it; + it = qAppPriv->widgetGestures.find(static_cast<QWidget*>(receiver)); + if (it == qAppPriv->widgetGestures.end()) + return false; + if (this != it.value().pan) + return false; + Qt::GestureState nextState = Qt::NoGesture; + switch(ev->gestureType) { + case QNativeGestureEvent::GestureBegin: + // next we might receive the first gesture update event, so we + // prepare for it. + d->state = Qt::NoGesture; + return false; + case QNativeGestureEvent::Pan: + nextState = Qt::GestureUpdated; + event->accept(); + break; + case QNativeGestureEvent::GestureEnd: + if (state() == Qt::NoGesture) + return false; // some other gesture has ended + nextState = Qt::GestureFinished; + break; + default: + return false; + } + if (state() == Qt::NoGesture) { + d->lastOffset = d->totalOffset = QSize(); + } else { + d->lastOffset = QSize(ev->position.x() - d->lastPosition.x(), + ev->position.y() - d->lastPosition.y()); + d->totalOffset += d->lastOffset; + } + d->lastPosition = ev->position; + updateState(nextState); + return true; + } +#endif + return QGesture::eventFilter(receiver, event); +} + +/*! \internal */ +bool QPanGesture::filterEvent(QEvent *event) +{ + Q_D(QPanGesture); + if (!event->spontaneous()) + return false; + const QTouchEvent *ev = static_cast<const QTouchEvent*>(event); + if (event->type() == QEvent::TouchBegin) { + QTouchEvent::TouchPoint p = ev->touchPoints().at(0); + d->lastPosition = p.pos().toPoint(); + d->lastOffset = d->totalOffset = QSize(); + } else if (event->type() == QEvent::TouchEnd) { + if (state() != Qt::NoGesture) { + if (!ev->touchPoints().isEmpty()) { + QTouchEvent::TouchPoint p = ev->touchPoints().at(0); + const QPoint pos = p.pos().toPoint(); + const QPoint lastPos = p.lastPos().toPoint(); + const QPoint startPos = p.startPos().toPoint(); + d->lastOffset = QSize(pos.x() - lastPos.x(), pos.y() - lastPos.y()); + d->totalOffset = QSize(pos.x() - startPos.x(), pos.y() - startPos.y()); + } + updateState(Qt::GestureFinished); + } + reset(); + } else if (event->type() == QEvent::TouchUpdate) { + QTouchEvent::TouchPoint p = ev->touchPoints().at(0); + const QPoint pos = p.pos().toPoint(); + const QPoint lastPos = p.lastPos().toPoint(); + const QPoint startPos = p.startPos().toPoint(); + d->lastOffset = QSize(pos.x() - lastPos.x(), pos.y() - lastPos.y()); + d->totalOffset = QSize(pos.x() - startPos.x(), pos.y() - startPos.y()); + if (d->totalOffset.width() > 10 || d->totalOffset.height() > 10 || + d->totalOffset.width() < -10 || d->totalOffset.height() < -10) { + updateState(Qt::GestureUpdated); + } + } +#ifdef Q_OS_MAC + else if (event->type() == QEvent::Wheel) { + // On Mac, there is really no native panning gesture. Instead, a two + // finger pan is delivered as mouse wheel events. Otoh, on Windows, you + // either get mouse wheel events or pan events. We have decided to make this + // the Qt behaviour as well, meaning that on Mac, wheel + // events will be masked away when listening for pan events. +#ifndef QT_MAC_USE_COCOA + // In Carbon we receive neither touch-, nor pan gesture events. + // So we create pan gestures by converting wheel events. After all, this + // is how things are supposed to work on mac in the first place. + const QWheelEvent *wev = static_cast<const QWheelEvent*>(event); + int offset = wev->delta() / -120; + d->lastOffset = wev->orientation() == Qt::Horizontal ? QSize(offset, 0) : QSize(0, offset); + + if (state() == Qt::NoGesture) { + d->totalOffset = d->lastOffset; + } else { + d->totalOffset += d->lastOffset; + } + + killTimer(d->panFinishedTimer); + d->panFinishedTimer = startTimer(200); + updateState(Qt::GestureUpdated); +#endif + return true; + } +#endif + return false; +} + +/*! \internal */ +void QPanGesture::reset() +{ + Q_D(QPanGesture); + d->lastOffset = d->totalOffset = QSize(); + d->lastPosition = QPoint(); +#if defined(Q_OS_MAC) && !defined(QT_MAC_USE_COCOA) + if (d->panFinishedTimer) { + killTimer(d->panFinishedTimer); + d->panFinishedTimer = 0; + } +#endif + QGesture::reset(); +} + +/*! + \property QPanGesture::totalOffset + + Specifies a total pan offset since the start of the gesture. +*/ +QSize QPanGesture::totalOffset() const +{ + Q_D(const QPanGesture); + return d->totalOffset; +} + +/*! + \property QPanGesture::lastOffset + + Specifies a pan offset since the last time the gesture was + triggered. +*/ +QSize QPanGesture::lastOffset() const +{ + Q_D(const QPanGesture); + return d->lastOffset; +} + + +/*! + \class QPinchGesture + \since 4.6 + + \brief The QPinchGesture class represents a Pinch gesture, + providing additional information related to zooming and/or rotation. +*/ + +/*! + Creates a new Pinch gesture handler object and marks it as a child of \a + parent. + + On some platform like Windows it's necessary to provide a non-null widget + as \a parent to get native gesture support. +*/ +QPinchGesture::QPinchGesture(QWidget *parent) + : QGesture(*new QPinchGesturePrivate, parent) +{ + if (parent) { + QApplicationPrivate *qAppPriv = QApplicationPrivate::instance(); + qAppPriv->widgetGestures[parent].pinch = this; +#ifdef Q_WS_WIN + qt_widget_private(parent)->winSetupGestures(); +#endif + } +} + +/*! \internal */ +bool QPinchGesture::event(QEvent *event) +{ + switch (event->type()) { + case QEvent::ParentAboutToChange: + if (QWidget *w = qobject_cast<QWidget*>(parent())) { + QApplicationPrivate::instance()->widgetGestures[w].pinch = 0; +#ifdef Q_WS_WIN + qt_widget_private(w)->winSetupGestures(); +#endif + } + break; + case QEvent::ParentChange: + if (QWidget *w = qobject_cast<QWidget*>(parent())) { + QApplicationPrivate::instance()->widgetGestures[w].pinch = this; +#ifdef Q_WS_WIN + qt_widget_private(w)->winSetupGestures(); +#endif + } + break; + default: + break; + } + return QObject::event(event); +} + +bool QPinchGesture::eventFilter(QObject *receiver, QEvent *event) +{ +#ifdef Q_WS_WIN + Q_D(QPinchGesture); + if (receiver->isWidgetType() && event->type() == QEvent::NativeGesture) { + QNativeGestureEvent *ev = static_cast<QNativeGestureEvent*>(event); + QApplicationPrivate *qAppPriv = QApplicationPrivate::instance(); + QApplicationPrivate::WidgetStandardGesturesMap::iterator it; + it = qAppPriv->widgetGestures.find(static_cast<QWidget*>(receiver)); + if (it == qAppPriv->widgetGestures.end()) + return false; + if (this != it.value().pinch) + return false; + Qt::GestureState nextState = Qt::NoGesture; + switch(ev->gestureType) { + case QNativeGestureEvent::GestureBegin: + // next we might receive the first gesture update event, so we + // prepare for it. + d->state = Qt::NoGesture; + d->scaleFactor = d->lastScaleFactor = 1; + d->rotationAngle = d->lastRotationAngle = 0; + d->startCenterPoint = d->centerPoint = d->lastCenterPoint = QPoint(); + d->initialDistance = 0; + return false; + case QNativeGestureEvent::Rotate: + d->lastRotationAngle = d->rotationAngle; + d->rotationAngle = -1 * GID_ROTATE_ANGLE_FROM_ARGUMENT(ev->argument); + nextState = Qt::GestureUpdated; + event->accept(); + break; + case QNativeGestureEvent::Zoom: + if (d->initialDistance != 0) { + d->lastScaleFactor = d->scaleFactor; + int distance = int(qint64(ev->argument)); + d->scaleFactor = (qreal) distance / d->initialDistance; + } else { + d->initialDistance = int(qint64(ev->argument)); + } + nextState = Qt::GestureUpdated; + event->accept(); + break; + case QNativeGestureEvent::GestureEnd: + if (state() == Qt::NoGesture) + return false; // some other gesture has ended + nextState = Qt::GestureFinished; + break; + default: + return false; + } + if (d->startCenterPoint.isNull()) + d->startCenterPoint = d->centerPoint; + d->lastCenterPoint = d->centerPoint; + d->centerPoint = static_cast<QWidget*>(receiver)->mapFromGlobal(ev->position); + updateState(nextState); + return true; + } +#endif + return QGesture::eventFilter(receiver, event); +} + +/*! \internal */ +bool QPinchGesture::filterEvent(QEvent *event) +{ + Q_UNUSED(event); + return false; +} + +/*! \internal */ +void QPinchGesture::reset() +{ + Q_D(QPinchGesture); + d->scaleFactor = d->lastScaleFactor = 0; + d->rotationAngle = d->lastRotationAngle = 0; + d->startCenterPoint = d->centerPoint = d->lastCenterPoint = QPoint(); + QGesture::reset(); +} + +/*! + \property QPinchGesture::scaleFactor + + Specifies a scale factor of the pinch gesture. +*/ +qreal QPinchGesture::scaleFactor() const +{ + return d_func()->scaleFactor; +} + +/*! + \property QPinchGesture::lastScaleFactor + + Specifies a previous scale factor of the pinch gesture. +*/ +qreal QPinchGesture::lastScaleFactor() const +{ + return d_func()->lastScaleFactor; +} + +/*! + \property QPinchGesture::rotationAngle + + Specifies a rotation angle of the gesture. +*/ +qreal QPinchGesture::rotationAngle() const +{ + return d_func()->rotationAngle; +} + +/*! + \property QPinchGesture::lastRotationAngle + + Specifies a previous rotation angle of the gesture. +*/ +qreal QPinchGesture::lastRotationAngle() const +{ + return d_func()->lastRotationAngle; +} + +/*! + \property QPinchGesture::centerPoint + + Specifies a center point of the gesture. The point can be used as a center + point that the object is rotated around. +*/ +QPoint QPinchGesture::centerPoint() const +{ + return d_func()->centerPoint; +} + +/*! + \property QPinchGesture::lastCenterPoint + + Specifies a previous center point of the gesture. +*/ +QPoint QPinchGesture::lastCenterPoint() const +{ + return d_func()->lastCenterPoint; +} + +/*! + \property QPinchGesture::startCenterPoint + + Specifies an initial center point of the gesture. Difference between the + startCenterPoint and the centerPoint is the distance at which pinching + fingers has shifted. +*/ +QPoint QPinchGesture::startCenterPoint() const +{ + return d_func()->startCenterPoint; +} + +QT_END_NAMESPACE + +#include "moc_qstandardgestures.cpp" + diff --git a/doc/src/classes/q3sqlrecordinfo.qdoc b/doc/src/snippets/gestures/qstandardgestures.h index ce60f6d..8b5421b 100644 --- a/doc/src/classes/q3sqlrecordinfo.qdoc +++ b/doc/src/snippets/gestures/qstandardgestures.h @@ -3,7 +3,7 @@ ** 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. +** This file is part of the QtGui module of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:LGPL$ ** No Commercial Usage @@ -39,51 +39,88 @@ ** ****************************************************************************/ -/*! - \class Q3SqlRecordInfo - \brief The Q3SqlRecordInfo class encapsulates a set of database field meta data. +#ifndef QSTANDARDGESTURES_H +#define QSTANDARDGESTURES_H - \compat +#include <QtGui/qevent.h> +#include <QtCore/qbasictimer.h> - 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. +#include <QtGui/qgesture.h> - \sa Q3SqlFieldInfo -*/ +QT_BEGIN_HEADER -/*! - \fn Q3SqlRecordInfo::Q3SqlRecordInfo() +QT_BEGIN_NAMESPACE - Constructs an empty record info object. -*/ +QT_MODULE(Gui) -/*! - \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const Q3SqlFieldInfoList& other) - \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const QSqlRecord& other) +class QPanGesturePrivate; +class Q_GUI_EXPORT QPanGesture : public QGesture +{ + Q_OBJECT + Q_DECLARE_PRIVATE(QPanGesture) - Constructs a copy of \a other. -*/ + Q_PROPERTY(QSize totalOffset READ totalOffset) + Q_PROPERTY(QSize lastOffset READ lastOffset) -/*! - \fn size_type Q3SqlRecordInfo::contains(const QString& fieldName) const +public: + QPanGesture(QWidget *parent); - 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. -*/ + bool filterEvent(QEvent *event); -/*! - \fn Q3SqlFieldInfo Q3SqlRecordInfo::find(const QString& fieldName) const + QSize totalOffset() const; + QSize lastOffset() 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. -*/ +protected: + void reset(); -/*! - \fn QSqlRecord Q3SqlRecordInfo::toRecord() const +private: + bool event(QEvent *event); + bool eventFilter(QObject *receiver, QEvent *event); - Returns an empty QSqlRecord based on the field information - in this Q3SqlRecordInfo. -*/ + friend class QWidget; +}; + +class QPinchGesturePrivate; +class Q_GUI_EXPORT QPinchGesture : public QGesture +{ + Q_OBJECT + Q_DECLARE_PRIVATE(QPinchGesture) + + Q_PROPERTY(qreal scaleFactor READ scaleFactor) + Q_PROPERTY(qreal lastScaleFactor READ lastScaleFactor) + + Q_PROPERTY(qreal rotationAngle READ rotationAngle) + Q_PROPERTY(qreal lastRotationAngle READ lastRotationAngle) + + Q_PROPERTY(QPoint startCenterPoint READ startCenterPoint) + Q_PROPERTY(QPoint lastCenterPoint READ lastCenterPoint) + Q_PROPERTY(QPoint centerPoint READ centerPoint) + +public: + QPinchGesture(QWidget *parent); + + bool filterEvent(QEvent *event); + void reset(); + + QPoint startCenterPoint() const; + QPoint lastCenterPoint() const; + QPoint centerPoint() const; + + qreal scaleFactor() const; + qreal lastScaleFactor() const; + + qreal rotationAngle() const; + qreal lastRotationAngle() const; + +private: + bool event(QEvent *event); + bool eventFilter(QObject *receiver, QEvent *event); + + friend class QWidget; +}; + +QT_END_NAMESPACE + +QT_END_HEADER + +#endif // QSTANDARDGESTURES_H diff --git a/doc/src/qsqldatatype-table.qdoc b/doc/src/sql-programming/qsqldatatype-table.qdoc index 1903861..e8c2351 100644 --- a/doc/src/qsqldatatype-table.qdoc +++ b/doc/src/sql-programming/qsqldatatype-table.qdoc @@ -41,7 +41,9 @@ /*! \page sql-types.html - \title QtSql Module - Recommended Use of Data Types + \title Recommended Use of Data Types in Databases + + \ingroup best-practices \section1 Recommended Use of Types in Qt Supported Databases diff --git a/doc/src/sql-driver.qdoc b/doc/src/sql-programming/sql-driver.qdoc index ef5812e..832fd0c 100644 --- a/doc/src/sql-driver.qdoc +++ b/doc/src/sql-programming/sql-driver.qdoc @@ -42,9 +42,10 @@ /*! \page sql-driver.html \title SQL Database Drivers - \ingroup architecture \brief How to configure and install QtSql drivers for supported databases. + \ingroup best-practices + The QtSql module uses driver \l{How to Create Qt Plugins}{plugins} to communicate with the different database APIs. Since Qt's SQL Module API is database-independent, all @@ -707,15 +708,14 @@ debug output when loading plugins. \endlist + Make sure you have followed the guide to \l{Deploying Plugins}. If you experience plugin load problems and see output like this: \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 31 - The problem is usually that the plugin had the wrong \l{How to - Create Qt Plugins#The Build Key}{build key}. This might require - removing an entry from the \l{How to Create Qt Plugins#The Plugin - Cache} {plugin cache}. Here is some more \l{How to Create Qt - Plugins#Debugging Plugins} {plugin debugging info}. + the problem is usually that the plugin had the wrong \l{Deploying + Plugins#The Build Key}{build key}. This might require removing an + entry from the \l{Deploying Plugins#The Plugin Cache} {plugin cache}. \target development \section1 How to Write Your Own Database Driver diff --git a/doc/src/qtsql.qdoc b/doc/src/sql-programming/sql-programming.qdoc index 0540ff5..7700a3d 100644 --- a/doc/src/qtsql.qdoc +++ b/doc/src/sql-programming/sql-programming.qdoc @@ -40,56 +40,17 @@ ****************************************************************************/ /*! - \module QtSql - \title QtSql Module - \contentspage Qt's Modules - \previouspage QtScript - \nextpage QtSvg - \ingroup modules + \group database + \title Database Classes - \brief The QtSql module helps you provide seamless database - integration to your Qt applications. - - The SQL classes are divided into three layers: - - \table - \header \o Layer \o Description - \row \o \bold{Driver Layer} - \o This comprises the classes QSqlDriver, - QSqlDriverCreator<T>, QSqlDriverCreatorBase, - QSqlDriverPlugin, and QSqlResult. This layer provides the - low-level bridge between the specific databases and the - SQL API layer. See \l{SQL Database Drivers} for more - information. - \row \o \bold{SQL API Layer} - \o These classes provide access to databases. Connections - are made using the QSqlDatabase class. Database - interaction is achieved by using the QSqlQuery class. - In addition to QSqlDatabase and QSqlQuery, the SQL API - layer is supported by QSqlError, QSqlField, QSqlIndex, - and QSqlRecord. - - \row \o \bold{User Interface Layer} - \o These classes link the data from a database to - data-aware widgets. They include QSqlQueryModel, - QSqlTableModel, and QSqlRelationalTableModel. These - classes are designed to work with Qt's model/view - framework. - \endtable - - Note that to use any of these classes, a QCoreApplication object - must have been instantiated first. To include the definitions of - the module's classes, use the following directive: - - \snippet doc/src/snippets/code/doc_src_qtsql.qdoc 0 - - To link against the module, add this line to your \l qmake \c - .pro file: + \brief Database related classes, e.g. for SQL databases. +*/ - \snippet doc/src/snippets/code/doc_src_qtsql.qdoc 1 +/*! + \page sql-programming.html + \title SQL Programming - The QtSql module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. + \brief Database integration for Qt applications. This overview assumes that you have at least a basic knowledge of SQL. You should be able to understand simple \c SELECT, \c @@ -100,11 +61,65 @@ covering SQL databases is \e {An Introduction to Database Systems} (7th Ed.) by C. J. Date, ISBN 0201385902. - Topics: + \section1 Topics: + + \list + \o \l{Database Classes} + \o \l{Connecting to Databases} + \list + \o \l{SQL Database Drivers} + \endlist + \o \l{Executing SQL Statements} + \list + \o \l{Recommended Use of Data Types in Databases} + \endlist + \o \l{Using the SQL Model Classes} + \o \l{Presenting Data in a Table View} + \o \l{Creating Data-Aware Forms} + \endlist + + \section1 Database Classes + + These classes provide access to SQL databases. + + \annotatedlist database + + The SQL classes are divided into three layers: + + \section2 Driver Layer + + This comprises the classes QSqlDriver, QSqlDriverCreator<T>, + QSqlDriverCreatorBase, QSqlDriverPlugin, and QSqlResult. - \tableofcontents + This layer provides the low-level bridge between the specific databases + and the SQL API layer. See \l{SQL Database Drivers} for more information. - \section1 Connecting to Databases + \section2 SQL API Layer + + These classes provide access to databases. Connections + are made using the QSqlDatabase class. Database + interaction is achieved by using the QSqlQuery class. + In addition to QSqlDatabase and QSqlQuery, the SQL API + layer is supported by QSqlError, QSqlField, QSqlIndex, + and QSqlRecord. + + \section2 User Interface Layer + + These classes link the data from a database to data-aware widgets. + They include QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel. + These classes are designed to work with Qt's + \l{Model/View Programming}{model/view framework}. + + Note that to use any of these classes, a QCoreApplication object + must have been instantiated first. +*/ + +/*! + \page sql-connecting.html + \title Connecting to Databases + + \contentspage SQL Programming + \nextpage Executing SQL Statements To access a database with QSqlQuery or QSqlQueryModel, create and open one or more database connections. Database connections are @@ -165,8 +180,16 @@ To remove a database connection, first close the database using QSqlDatabase::close(), then remove it using the static method QSqlDatabase::removeDatabase(). +*/ - \section1 Executing SQL Statements +/*! + \page sql-sqlstatements.html + \title Executing SQL Statements + + \previouspage Connecting to Databases + \contentspage SQL Programming + \nextpage Using the SQL Model Classes + The QSqlQuery class provides an interface for executing SQL statements and navigating through the result set of a query. @@ -213,7 +236,7 @@ variants to QString and \c int. For an overview of the recommended types used with Qt supported - Databases, please refer to \l {QtSql Module - Recommended use of data types}{this table}. + Databases, please refer to \l{Recommended Use of Data Types in Databases}{this table}. You can iterate back and forth using QSqlQuery::next(), QSqlQuery::previous(), QSqlQuery::first(), QSqlQuery::last(), and @@ -307,8 +330,15 @@ It would be useful to mention transactions, and the fact that some databases don't support them. \endomit +*/ - \section1 Using the SQL Model Classes +/*! + \page sql-model.html + \title Using the SQL Model Classes + + \previouspage Executing SQL Statements + \contentspage SQL Programming + \nextpage Presenting Data in a Table View In addition to QSqlQuery, Qt offers three higher-level classes for accessing databases. These classes are QSqlQueryModel, @@ -446,8 +476,15 @@ \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 2 See the QSqlRelationalTableModel documentation for details. +*/ - \section1 Presenting Data in a Table View +/*! + \page sql-presenting.html + \title Presenting Data in a Table View + + \previouspage Using the SQL Model Classes + \contentspage SQL Programming + \nextpage Creating Data-Aware Forms The QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel classes can be used as a data source for Qt's view classes such @@ -543,8 +580,14 @@ illustrates how to use QSqlRelationalTableModel in conjunction with QSqlRelationalDelegate to provide tables with foreign key support. +*/ - \section1 Creating Data-Aware Forms +/*! + \page sql-forms.html + \title Creating Data-Aware Forms + + \previouspage Presenting Data in a Table View + \contentspage SQL Programming Using the SQL models described above, the contents of a database can be presented to other model/view components. For some applications, diff --git a/doc/src/topics.qdoc b/doc/src/topics.qdoc deleted file mode 100644 index 3db8881..0000000 --- a/doc/src/topics.qdoc +++ /dev/null @@ -1,305 +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://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\group topics -\title Topics - -This page provides a collection of documents grouped by topic. - -The \l{Grouped Classes} page contains a similar list of groups for -Qt's class documentation. - -\generatelist{related} -*/ - -/*! -\group architecture -\title Architecture -\ingroup topics -\brief Documents about Qt's architecture and design. - -These documents describe aspects of Qt's architecture and design, -including overviews of core Qt features and technologies. - -\generatelist{related} -*/ - -/*! -\group buildsystem -\title Build System -\ingroup topics -\brief Tools to help automate building and installation of Qt applications. - -Qt is provided with a set of build tools to help developers automate -the process of building and installing Qt applications. - -\table 100% -\header \o Development \o Cross-Platform Issues \o Specific Tools -\row -\o - \list - \o \l {Debugging Techniques} - \o \l {Qt's Tools} - \o \l {The Qt Resource System} - \o \l {Using Precompiled Headers} -\endlist -\o -\list - \o \l {Cross Compiling Qt for Embedded Linux Applications} - \o \l {Deploying Qt Applications} - \o \l {Installation}{Installing Qt} - \o \l {Window System Specific Notes} -\endlist -\o -\list - \o \l lupdate and \l lrelease - \o \l {moc}{Meta-Object Compiler (moc)} - \o \l {User Interface Compiler (uic)} - \o \l {Resource Compiler (rcc)} -\endlist -\endtable - - -*/ - -/*! -\group classlists -\title Class and Function Indexes -\ingroup topics -\brief Collections of classes and functions grouped together into lists. - -The following documents contain collections of classes, grouped by -subject area or related to particular functionality, or comprehensive -lists of classes and functions. - -\generatelist{related} -*/ - -/*! -\group codecs -\title Codecs -\ingroup topics -\brief Codec support in Qt. - -These codecs provide facilities for conversion between Unicode and -specific text encodings. - -\generatelist{related} -*/ - -/*! -\group gui-programming -\title GUI Programming -\ingroup topics -\brief Resources for developers of GUI applications. - -The following list contains links to guides and other resources for -developers of graphical user interface (GUI) applications. - -\generatelist{related} -*/ - -/*! -\group howto -\title How To Guides and Learning Resources -\ingroup topics -\brief Guides providing help on aspects of using Qt. - -These guides provide specific help about specific Qt-related topics. - -\generatelist{related} -*/ - -/*! -\group platform-notes -\title Platform-Specific Notes -\ingroup topics -\brief Documents describing platform-specific features of Qt. - -These documents describe platform-specific features provided by Qt, and -discuss issues related to particular platforms and environments. - -\generatelist{related} -*/ - -/*! -\group porting -\title Porting Guides -\ingroup topics -\brief Guides related to porting Qt applications and libraries. - -A number of guides and documents are available that cover porting issues, -from detailed coverage of API differences between Qt 3 and Qt 4 to -platform and tool-specific documentation. - -\generatelist{related} -*/ - -/*! -\group text-processing -\title Text Processing -\ingroup topics -\brief Text processing guides and classes. - -Qt provides an extensive collection of classes for text handling. -The following guides and references describe basic text handling, support -for internationalization and character encodings, and Qt's rich text -system. - -\generatelist{related} -*/ - -/*! - \group tutorials - \title Tutorials - \ingroup topics - \brief Tutorials, guides and overviews to help you learn Qt. - - A collection of tutorials and "walkthrough" guides are provided with Qt to - help new users get started with Qt development. These documents cover a - range of topics, from basic use of widgets to step-by-step tutorials that - show how an application is put together. - - \section1 \l{Widgets Tutorial} - - \inlineimage widget-examples.png - - A beginner's guide to getting started with widgets and layouts to create - GUI applications. - - \section1 \l{Address Book Tutorial} - - \inlineimage addressbook-tutorial.png - - A seven part guide to creating a fully-functioning address book - application. This tutorial is also available with - \l{Tutoriel "Carnet d'adresses"}{French explanation}. - -*/ - -/*! -\group activeqt-tools -\title Tools for ActiveQt -\ingroup topics -\brief Tools to help integrate Qt applications with ActiveX components. - -These tools provide support for integrating Qt with ActiveX components. - -\generatelist{related} - -\sa {ActiveQt Framework} -*/ - -/*! -\group scripting -\title Scripting with ECMAScript -\ingroup topics -\brief Guides and references covering application scripting with ECMAScript. - -Qt 4.3 and later provides support for application scripting with ECMAScript. -The following guides and references cover aspects of programming with -ECMAScript and Qt. - -\generatelist{related} -*/ - -/*! -\group threading -\title Threading and Concurrent Programming -\ingroup topics -\brief Guides and references covering threading and concurrent programming. - -Qt provides a number of classes to handle the primitives used for multithreaded -programming. From Qt 4.4, the QtConcurrent namespace also provides a set of higher -level classes for concurrent programming. - -\generatelist{related} -*/ - -/*! -\group qtce -\title Qt for Windows CE -\ingroup topics -\ingroup qt-embedded -\brief Documents related to Qt on Windows CE - -Qt for Windows CE is a C++ framework for GUI and application development -for embedded devices running Windows CE. It runs on a variety of processors, -including ARM, Intel x86, MIPS and SH-4. - -\table 100% -\header \o Getting Started \o Reference \o Performance and Optimization -\row -\o - \list - \o \l {Qt for Windows CE Requirements} - \o \l {Installing Qt on Windows CE} - \o \l {Windows CE - Introduction to using Qt}{Introduction to using Qt} -\endlist -\o -\list - \o \l {Windows CE - Using shadow builds}{Using shadow builds} - \o \l {Windows CE - Working with Custom SDKs}{Working with Custom SDKs} -\endlist -\o -\list - \o \l {Windows CE OpenGL ES}{OpenGL ES} - \o \l {Qt Performance Tuning} - \o \l {Fine-Tuning Features in Qt} -\endlist -\endtable -*/ - -/*! -\group qts60 -\title Qt for S60 -\ingroup topics -\ingroup qt-embedded -\brief Documents related to Qt for S60 - -Qt for S60 is a C++ framework for GUI and application development -for embedded devices running Symbian. - -\list - \o \l {Exception Safety with Symbian} -\endlist -*/ diff --git a/doc/src/tutorials/addressbook-fr.qdoc b/doc/src/tutorials/addressbook-fr.qdoc index 3ce2987..990e06e 100644 --- a/doc/src/tutorials/addressbook-fr.qdoc +++ b/doc/src/tutorials/addressbook-fr.qdoc @@ -43,11 +43,10 @@ \page tutorials-addressbook-fr.html \startpage {index.html}{Qt Reference Documentation} + \contentspage Tutorials \nextpage {tutorials/addressbook-fr/part1}{Chapitre 1} \title Tutoriel "Carnet d'adresses" - \ingroup howto - \ingroup tutorials \brief Une introduction à la programation d'interface graphique montrant comment construire une application simple avec Qt. Ce tutoriel est une introduction à la programmation de GUI (interface utilisateur) diff --git a/doc/src/tutorials/addressbook.qdoc b/doc/src/tutorials/addressbook.qdoc index d27b95c..4623aaa 100644 --- a/doc/src/tutorials/addressbook.qdoc +++ b/doc/src/tutorials/addressbook.qdoc @@ -43,11 +43,10 @@ \page tutorials-addressbook.html \startpage {index.html}{Qt Reference Documentation} + \contentspage Tutorials \nextpage {tutorials/addressbook/part1}{Chapter 1} \title Address Book Tutorial - \ingroup howto - \ingroup tutorials \brief An introduction to GUI programming, showing how to put together a simple yet fully-functioning application. diff --git a/doc/src/tutorials/widgets-tutorial.qdoc b/doc/src/tutorials/widgets-tutorial.qdoc index 39f6b00..3c0220e 100644 --- a/doc/src/tutorials/widgets-tutorial.qdoc +++ b/doc/src/tutorials/widgets-tutorial.qdoc @@ -41,15 +41,15 @@ /*! \page widgets-tutorial.html - \startpage {index.html}{Qt Reference Documentation} - \nextpage {tutorials/widgets/toplevel}{Creating a Window} - \title Widgets Tutorial - \ingroup tutorials - \brief This tutorial covers basic usage of widgets and layouts, showing how they are used to build GUI applications. + \startpage {index.html}{Qt Reference Documentation} + \contentspage Tutorials + \nextpage {tutorials/widgets/toplevel}{Creating a Window} + + \section1 Introduction Widgets are the basic building blocks of graphical user interface (GUI) @@ -94,7 +94,7 @@ example. For example, the GUI for a main window may be set up in the constructor of a QMainWindow subclass. - The \l{Qt Examples#Widgets}{Widgets examples} are a good place to look for + The \l{Widgets examples} are a good place to look for more complex and complete examples and applications. \section1 Building Examples and Tutorials @@ -279,6 +279,5 @@ \snippet tutorials/widgets/nestedlayouts/main.cpp set up the model The use of models and views is covered in the - \l{Qt Examples#Item Views}{item view examples} and in the - \l{Model/View Programming} overview. + \l{Item Views Examples} and in the \l{Model/View Programming} overview. */ diff --git a/doc/src/focus.qdoc b/doc/src/widgets-and-layouts/focus.qdoc index 459a9d8..1cbc71b 100644 --- a/doc/src/focus.qdoc +++ b/doc/src/widgets-and-layouts/focus.qdoc @@ -39,24 +39,11 @@ ** ****************************************************************************/ -/**************************************************************************** -** -** Documentation of focus handling in Qt. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - /*! \page focus.html \title Keyboard Focus - \ingroup architecture - \ingroup gui-programming - \brief An overview of the keyboard focus management and handling. + \brief Keyboard focus management and handling. + \ingroup frameworks-technologies \keyword keyboard focus diff --git a/doc/src/gallery-cde.qdoc b/doc/src/widgets-and-layouts/gallery-cde.qdoc index 02dabb1..02dabb1 100644 --- a/doc/src/gallery-cde.qdoc +++ b/doc/src/widgets-and-layouts/gallery-cde.qdoc diff --git a/doc/src/gallery-cleanlooks.qdoc b/doc/src/widgets-and-layouts/gallery-cleanlooks.qdoc index 13c0f8f..13c0f8f 100644 --- a/doc/src/gallery-cleanlooks.qdoc +++ b/doc/src/widgets-and-layouts/gallery-cleanlooks.qdoc diff --git a/doc/src/gallery-gtk.qdoc b/doc/src/widgets-and-layouts/gallery-gtk.qdoc index 8251f04..8251f04 100644 --- a/doc/src/gallery-gtk.qdoc +++ b/doc/src/widgets-and-layouts/gallery-gtk.qdoc diff --git a/doc/src/gallery-macintosh.qdoc b/doc/src/widgets-and-layouts/gallery-macintosh.qdoc index c7efabe..c7efabe 100644 --- a/doc/src/gallery-macintosh.qdoc +++ b/doc/src/widgets-and-layouts/gallery-macintosh.qdoc diff --git a/doc/src/gallery-motif.qdoc b/doc/src/widgets-and-layouts/gallery-motif.qdoc index 1539753..1539753 100644 --- a/doc/src/gallery-motif.qdoc +++ b/doc/src/widgets-and-layouts/gallery-motif.qdoc diff --git a/doc/src/gallery-plastique.qdoc b/doc/src/widgets-and-layouts/gallery-plastique.qdoc index 49bd13e..49bd13e 100644 --- a/doc/src/gallery-plastique.qdoc +++ b/doc/src/widgets-and-layouts/gallery-plastique.qdoc diff --git a/doc/src/gallery-windows.qdoc b/doc/src/widgets-and-layouts/gallery-windows.qdoc index 2fa971c..2fa971c 100644 --- a/doc/src/gallery-windows.qdoc +++ b/doc/src/widgets-and-layouts/gallery-windows.qdoc diff --git a/doc/src/gallery-windowsvista.qdoc b/doc/src/widgets-and-layouts/gallery-windowsvista.qdoc index 9ab3a2f..9ab3a2f 100644 --- a/doc/src/gallery-windowsvista.qdoc +++ b/doc/src/widgets-and-layouts/gallery-windowsvista.qdoc diff --git a/doc/src/gallery-windowsxp.qdoc b/doc/src/widgets-and-layouts/gallery-windowsxp.qdoc index aefff65..aefff65 100644 --- a/doc/src/gallery-windowsxp.qdoc +++ b/doc/src/widgets-and-layouts/gallery-windowsxp.qdoc diff --git a/doc/src/gallery.qdoc b/doc/src/widgets-and-layouts/gallery.qdoc index e96a8ef..cb92cb4 100644 --- a/doc/src/gallery.qdoc +++ b/doc/src/widgets-and-layouts/gallery.qdoc @@ -42,7 +42,6 @@ /*! \group gallery \title Qt Widget Gallery - \ingroup topics \brief Qt widgets shown in different styles on various platforms. Qt's support for widget styles and themes enables your application to fit in diff --git a/doc/src/layout.qdoc b/doc/src/widgets-and-layouts/layout.qdoc index dc75bc6..4622301 100644 --- a/doc/src/layout.qdoc +++ b/doc/src/widgets-and-layouts/layout.qdoc @@ -40,12 +40,21 @@ ****************************************************************************/ /*! - \page layout.html + \group geomanagement + \title Layout Classes +*/ +/*! + \page layout.html \title Layout Management - \ingroup architecture \brief A tour of the standard layout managers and an introduction to custom layouts. + + \previouspage Widget Classes + \contentspage Widgets and Layouts + \nextpage {Implementing Styles and Style Aware Widgets}{Styles} + + \ingroup frameworks-technologies The Qt layout system provides a simple and powerful way of automatically arranging child widgets within a widget to ensure that they make good use @@ -78,6 +87,8 @@ \endlist \endlist + \section1 Qt's Layout Classes + Qt's layout classes were designed for hand-written C++ code, allowing measurements to be specified in pixels for simplicity, so they are easy to understand and use. The code generated for forms created using \QD also @@ -85,6 +96,7 @@ design of a form since it avoids the compile, link and run cycle usually involved in user interface development. + \annotatedlist geomanagement \section1 Horizontal, Vertical, Grid, and Form Layouts diff --git a/doc/src/styles.qdoc b/doc/src/widgets-and-layouts/styles.qdoc index e6c6e8c..aa51838 100644 --- a/doc/src/styles.qdoc +++ b/doc/src/widgets-and-layouts/styles.qdoc @@ -40,23 +40,34 @@ ****************************************************************************/ /*! - \page style-reference.html + \group appearance + \title Widget Appearance and Style + \brief Classes used for customizing UI appearance and style. +*/ +/*! + \page style-reference.html \title Implementing Styles and Style Aware Widgets - \ingroup architecture \brief An overview of styles and the styling of widgets. - \tableofcontents + \ingroup frameworks-technologies - \section1 Introduction + \previouspage Widget Classes + \contentspage Widgets and Layouts + \nextpage {Qt Style Sheets}{Style sheets} Styles (classes that inherit QStyle) draw on behalf of widgets - and encapsulate the look and feel of a GUI. Several styles are - built into Qt (e.g., windows style and motif style). Other styles are - only available on specific platforms (such as the windows XP style). - Custom styles are made available as plugins or by creating an - instance of the style class in an application and setting it with - QApplication::setStyle(). + and encapsulate the look and feel of a GUI. The QStyle class is + an abstract base class that encapsulates the look and feel of a + GUI. Qt's built-in widgets use it to perform nearly all of their + drawing, ensuring that they look exactly like the equivalent + native widgets. + + Several styles are built into Qt (e.g., windows style and motif style). + Other styles are only available on specific platforms (such as + the windows XP style). Custom styles are made available as plugins + or by creating an instance of the style class in an application and + setting it with QApplication::setStyle(). To implement a new style, you inherit one of Qt's existing styles - the one most resembling the style you want to create - and @@ -79,6 +90,15 @@ current style. This document shows how widgets draw themselves and which possibilities the style gives them. + \tableofcontents + + \section1 Classes for Widget Styling + + These classes are used to customize an application's appearance and + style. + + \annotatedlist appearance + \section1 The QStyle implementation The API of QStyle contains functions that draw the widgets, static @@ -91,9 +111,26 @@ QStyle draws graphical elements; an element is a widget or a widget part like a push button bevel, a window frame, or a scroll - bar. When a widget asks a style to draw an element, it provides the - style with a style option, which is a class that contains the - information necessary for drawing. + bar. Most draw functions now take four arguments: + + \list + \o an enum value specifying which graphical element to draw + \o a QStyleOption specifying how and where to render that element + \o a QPainter that should be used to draw the element + \o a QWidget on which the drawing is performed (optional) + \endlist + + When a widget asks a style to draw an element, it provides the style + with a QStyleOption, which is a class that contains the information + necessary for drawing. Thanks to QStyleOption, it is possible to make + QStyle draw widgets without linking in any code for the widget. This + makes it possible to use \l{QStyle}'s draw functions on any paint + device. Ie you can draw a combobox on any widget, not just on a + QComboBox. + + The widget is passed as the last argument in case the style needs + it to perform special effects (such as animated default buttons on + Mac OS X), but it isn't mandatory. We will in the course of this section look at the style elements, the style options, and the functions of QStyle. Finally, we describe @@ -236,11 +273,15 @@ \section2 Style Options - A style option (a class that inherit QStyleOption) stores - parameters used by QStyle functions. The sub-classes of - QStyleOption contain all information necessary to style the - individual widgets. The style options keep public variables for - performance reasons. Style options are filled out by the widgets. + The sub-classes of QStyleOption contain all information necessary + to style the individual elements. Style options are instantiated - + usually on the stack - and filled out by the caller of the QStyle + function. Depending on what is drawn the style will expect + different a different style option class. For example, the + QStyle::PE_FrameFocusRect element expects a QStyleOptionFocusRect + argument, and it's possible to create custom subclasses that a + custom style can use. The style options keep public variables + for performance reasons. The widgets can be in a number of different states, which are defined by the \l{QStyle::}{State} enum. Some of the state flags have @@ -256,6 +297,29 @@ the text, icon, and the size of their icon. The exact contents of all options are described when we go through individual widgets. + When reimplementing QStyle functions that take a + QStyleOption parameter, you often need to cast the + QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For + safety, you can use qstyleoption_cast() to ensure that the + pointer type is correct. If the object isn't of the right type, + qstyleoption_cast() returns 0. For example: + + \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 0 + + The following code snippet illustrates how to use QStyle to + draw the focus rectangle from a custom widget's paintEvent(): + + \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 1 + + The next example shows how to derive from an existing style to + customize the look of a graphical element: + + \snippet doc/src/snippets/customstyle/customstyle.h 0 + \codeline + \snippet doc/src/snippets/customstyle/customstyle.cpp 2 + \snippet doc/src/snippets/customstyle/customstyle.cpp 3 + \snippet doc/src/snippets/customstyle/customstyle.cpp 4 + \section2 QStyle Functions The QStyle class defines three functions for drawing the primitive, diff --git a/doc/src/stylesheet.qdoc b/doc/src/widgets-and-layouts/stylesheet.qdoc index 45621cc..6a3fcb2 100644 --- a/doc/src/stylesheet.qdoc +++ b/doc/src/widgets-and-layouts/stylesheet.qdoc @@ -41,12 +41,15 @@ /*! \page stylesheet.html - \startpage index.html QtReference Documentation - \nextpage The Style Sheet Syntax \title Qt Style Sheets - \ingroup architecture \brief How to use style sheets to customize the appearance of widgets. + \ingroup frameworks-technologies + + \previouspage {Implementing Styles and Style Aware Widgets}{Styles} + \contentspage Widgets and Layouts + \nextpage The Style Sheet Syntax + \keyword style sheet \keyword stylesheet @@ -62,15 +65,10 @@ \list \i \l{Overview} \i \l{The Style Sheet Syntax} - \tableofcontents{1 The Style Sheet Syntax} \i \l{Qt Designer Integration} - \tableofcontents{1 Qt Designer Integration} \i \l{Customizing Qt Widgets Using Style Sheets} - \tableofcontents{1 Customizing Qt Widgets Using Style Sheets} \i \l{Qt Style Sheets Reference} - \tableofcontents{1 Qt Style Sheets Reference} \i \l{Qt Style Sheets Examples} - \tableofcontents{1 Qt Style Sheets Examples} \endlist \target overview @@ -150,7 +148,7 @@ subclasses. We plan to address this in some future release. */ - /*! +/*! \page stylesheet-syntax.html \contentspage {Qt Style Sheet}{Contents} \previouspage Qt Style Sheet @@ -160,6 +158,8 @@ Qt Style Sheet terminology and syntactic rules are almost identical to those of HTML CSS. If you already know CSS, you can probably skim quickly through this section. + + \tableofcontents \section1 Style Rules @@ -549,9 +549,9 @@ If the property references an enum declared with Q_ENUMS, you should reference its constants by name, i.e., not their numeric value. - */ +*/ - /*! +/*! \page stylesheet-designer.html \contentspage {Qt Style Sheet}{Contents} \previouspage The Style Sheet Syntax @@ -577,7 +577,7 @@ \image designer-stylesheet-usage.png */ - /*! +/*! \page stylesheet-customizing.html \contentspage {Qt Style Sheet}{Contents} \previouspage Qt Designer Integration @@ -589,6 +589,8 @@ padding rectangle, and the content rectangle. The box model describes this in further detail. + \tableofcontents + \target box model \section1 The Box Model @@ -677,9 +679,9 @@ property or sub-control is customized, \bold{all} the other properties or sub-controls must be customized as well. - */ +*/ - /*! +/*! \page stylesheet-reference.html \contentspage {Qt Style Sheet}{Contents} \previouspage Customizing Qt Widgets Using Style Sheets @@ -1523,7 +1525,7 @@ This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QDialog, QFrame, QGroupBox, QLabel, QLineEdit, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, QToolTip, and plain \l{QWidget}s. @@ -1569,7 +1571,7 @@ This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QDialog, QFrame, QGroupBox, QLabel, QLineEdit, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, QToolTip, and plain \l{QWidget}s. @@ -1614,7 +1616,7 @@ This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, - QComboBox, QDialog, QFrame, QGroupBox, QLabel, QLineEdit, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit and QToolTip. @@ -3356,17 +3358,17 @@ for an example of how to customize a subcontrol. */ - /*! +/*! \page stylesheet-examples.html \contentspage {Qt Style Sheet}{Contents} \previouspage Qt Style Sheets Reference \title Qt Style Sheets Examples + We will now see a few examples to get started with using Qt Style Sheets. + \tableofcontents \section1 Style Sheet Usage - We will now see a few examples to get started with using Qt Style Sheets. - \section2 Customizing the Foreground and Background Colors Let's start by setting yellow as the background color of all diff --git a/doc/src/widgets-and-layouts/widgets.qdoc b/doc/src/widgets-and-layouts/widgets.qdoc new file mode 100644 index 0000000..0697b94 --- /dev/null +++ b/doc/src/widgets-and-layouts/widgets.qdoc @@ -0,0 +1,187 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page widgets-and-layouts.html + \title Widgets and Layouts + + \ingroup frameworks-technologies + + \nextpage Widget Classes + + The primary elements for designing user interfaces in Qt are widgets and layouts. + + \section1 Widgets + + \l{Widget Classes}{Widgets} can display data and status information, receive + user input, and provide a container for other widgets that should be grouped + together. A widget that is not embedded in a parent widget is called a + \l{Application Windows and Dialogs}{window}. + + \image parent-child-widgets.png A parent widget containing various child widgets. + + The QWidget class provides the basic capability to render to the screen, and to + handle user input events. All UI elements that Qt provides are either subclasses + of QWidget, or are used in connection with a QWidget subclass. Creating custom + widgets is done by subclassing QWidget or a suitable subclass and reimplementing + the virtual event handlers. + + \section1 Layouts + + \l{Layout Management}{Layouts} are an elegant and flexible way to automatically + arrange child widgets within their container. Each widget reports its size requirements + to the layout through the \l{QWidget::}{sizeHint} and \l{QWidget::}{sizePolicy} + properties, and the layout distributes the available space accordingly. + + \table + \row + \o \image qgridlayout-with-5-children.png + \o \image qformlayout-with-6-children.png + \endtable + + \l{Qt Designer Manual}{\QD} is a powerful tool for interactively creating and + arranging widgets in layouts. + + \section1 Widget Styles + + \l{Implementing Styles and Style Aware Widgets}{Styles} draw on behalf of widgets + and encapsulate the look and feel of a GUI. Qt's built-in widgets use the QStyle + class to perform nearly all of their drawing, ensuring that they look exactly like + the equivalent native widgets. + + \table + \row + \o \image windowsxp-tabwidget.png + \o \image plastique-tabwidget.png + \o \image macintosh-tabwidget.png + \endtable + + \l{Qt Style Sheets} are a powerful mechanism that allows you to customize the + appearance of widgets, in addition to what is already possible by subclassing QStyle. +*/ + +/*! + \page widget-classes.html + \title Widget Classes + + \contentspage Widgets and Layouts + \nextpage Layout Management + + Below you find a list of all widget classes in Qt. You can also browse the + widget classes Qt provides in the various supported styles in the + \l{Qt Widget Gallery}. + + \tableofcontents + + \section1 Basic Widgets + + These basic widgets (controls), such as buttons, comboboxes and scroll bars, are + designed for direct use. + + \table + \row + \o \image windows-label.png + \o \image windowsvista-pushbutton.png + \o \image gtk-progressbar.png + \row + \o \image plastique-combobox.png + \o \image macintosh-radiobutton.png + \o \image cde-lineedit.png + \endtable + + \annotatedlist basicwidgets + + \section1 Advanced Widgets + + Advanced GUI widgets such as tab widgets and progress bars provide more + complex user interface controls. + + \table + \row + \o \image windowsxp-treeview.png + \o \image gtk-calendarwidget.png + \o \image qundoview.png + \endtable + + \annotatedlist advanced + + \table + \row + \o \image windowsvista-tabwidget.png + \o \image macintosh-groupbox.png + \endtable + + \section1 Organizer Widgets + + Classes like splitters, tab bars, button groups, etc are used to + organize and group GUI primitives into more complex applications or + dialogs. + + \annotatedlist organizers + + \section1 Abstract Widget Classes + + Abstract widget classes usable through subclassing. They are generally + not usable in themselves, but provide functionality that can be used + by inheriting these classes. + + \annotatedlist abstractwidgets +*/ + +/*! + \group advanced + \title Advanced Widgets +*/ + +/*! + \group abstractwidgets + \title Abstract Widget Classes +*/ + +/*! + \group basicwidgets + \title Basic Widgets +*/ + +/*! + \group organizers + \title Organizers +*/ diff --git a/doc/src/classes/qprintdialog.qdoc b/doc/src/windows-and-dialogs/dialogs.qdoc index b52edff..1c039d5 100644 --- a/doc/src/classes/qprintdialog.qdoc +++ b/doc/src/windows-and-dialogs/dialogs.qdoc @@ -39,34 +39,38 @@ ** ****************************************************************************/ -#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. + \group standard-dialogs + \title Standard Dialog Classes +*/ - This function is available for Unix platforms only. +/*! + \group dialog-classes + \title Classes for Building Dialogs */ /*! - \fn void QPrintDialog::setPrinter(QPrinter *printer, bool pickupSettings) + \page dialogs.html + \title Dialog Windows + \brief An overview over dialog windows. + + \previouspage The Application Main Window + \contentspage Application Windows and Dialogs + \nextpage Desktop Integration - 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. + Dialogs can be \e{modal}, in which case the user is required to provide + necessary information before work in the main window + can continue, or \e{modeless}. Modeless dialogs do not prevent the user from + interacting with any of the other windows in the application. - This function is available for Unix platforms only. -*/ + Qt provides a set of ready-made dialogs for file, font, color-selection + and more. -/*! - \fn void QPrintDialog::addButton(QPushButton *button) + \annotatedlist standard-dialogs - 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. + Custom dialogs can be easily created by composing regular widgets into + a QDialog. These classes are specifically designed for building custom + dialogs: - This function is available for Unix platforms only. + \annotatedlist dialog-classes */ -#endif diff --git a/doc/src/windows-and-dialogs/mainwindow.qdoc b/doc/src/windows-and-dialogs/mainwindow.qdoc new file mode 100644 index 0000000..e0134a4 --- /dev/null +++ b/doc/src/windows-and-dialogs/mainwindow.qdoc @@ -0,0 +1,279 @@ +/**************************************************************************** +** +** 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://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group mainwindow-classes + \title Main Window and Related Classes +*/ + +/*! + \page application-windows.html + \title Application Windows and Dialogs + \ingroup frameworks-technologies + + \nextpage The Application Main Window + + A \l{Widgets}{widget} that is not embedded in a parent widget is called a window. + Usually, windows have a frame and a title bar, although it is also possible to create + windows without such decoration using suitable window flags). In Qt, QMainWindow + and the various subclasses of QDialog are the most common window types. + + In applications, windows provide the screen space upon which the user + interface is built. Windows separate applications visually from each other + and usually provide a window decoration that allows the user to resize and + position the applications according to his preferences. Windows are typically + integrated into the desktop environment and to some degree managed by the + window management system that the desktop environment provides. For instance, + selected windows of an application are represented in the task bar. + + \section1 Primary and Secondary Windows + + Any QWidget that has no parent will become a window, and will on most platforms + be listed in the desktop's task bar. This is usually only wanted for one + window in the application, the \e{primary window}. + + In addition, a QWidget that has a parent can become a window by setting the + \l{Qt::WindowType}{Qt::WA_Window} flag. Depending on the window management system + such \e{secondary windows} are usually stacked on top of their respective parent + window, and not have a task bar entry of their own. + + The QMainWindow and the QDialog classes set the Qt::WA_Window flag in their + constructor, as they are designed to be used as windows and provide facilities + that are not wanted for child widgets. + + \section1 Main Windows and Dialogs + + \l{The Application Main Window} provides the framework for building the + application's main user interface, and are created by subclassing QMainWindow. + QMainWindow has its own layout to which you can add a \l{QMenuBar}{menu bar}, + \l{QToolBar}{tool bars}, \l{QDockWidget}{dockable widgets} and a + \l{QStatusBar}{status bar}. The center area can be occupied by any kind of + QWidget. + + \l{Dialog Windows} are used as secondary windows that present the user with + options and choices. Dialogs are created by subclassing QDialog and using + \l{Widgets and Layouts}{widgets and layouts} to implement the user interface. + In addition, Qt provides a number of ready-made standard dialogs that can be + used for standard tasks like file or font selection. + + Both main windows and dialogs can be created with \QD, Qt's visual design tool. + Using \QD is a lot faster than hand-coding, and makes it easy to test different + design ideas. Creating designs visually and reading the code generated by + \l{uic} is a great way to learn Qt! + + \keyword window geometry + \section1 Window Geometry + + QWidget provides several functions that deal with a widget's + geometry. Some of these functions operate on the pure client area + (i.e. the window excluding the window frame), others include the + window frame. The differentiation is done in a way that covers the + most common usage transparently. + + \list + \o \bold{Including the window frame:} + \l{QWidget::x()}{x()}, + \l{QWidget::y()}{y()}, + \l{QWidget::frameGeometry()}{frameGeometry()}, + \l{QWidget::pos()}{pos()}, and + \l{QWidget::move()}{move()}. + \o \bold{Excluding the window frame:} + \l{QWidget::geometry()}{geometry()}, + \l{QWidget::width()}{width()}, + \l{QWidget::height()}{height()}, + \l{QWidget::rect()}{rect()}, and + \l{QWidget::size()}{size()}. + \endlist + + Note that the distinction only matters for decorated top-level + widgets. For all child widgets, the frame geometry is equal to the + widget's client geometry. + + This diagram shows most of the functions in use: + \img geometry.png Geometry diagram + + \section2 X11 Peculiarities + + On X11, a window does not have a frame until the window manager + decorates it. This happens asynchronously at some point in time + after calling QWidget::show() and the first paint event the + window receives, or it does not happen at all. Bear in mind that + X11 is policy-free (others call it flexible). Thus you cannot + make any safe assumption about the decoration frame your window + will get. Basic rule: There's always one user who uses a window + manager that breaks your assumption, and who will complain to + you. + + Furthermore, a toolkit cannot simply place windows on the screen. All + Qt can do is to send certain hints to the window manager. The window + manager, a separate process, may either obey, ignore or misunderstand + them. Due to the partially unclear Inter-Client Communication + Conventions Manual (ICCCM), window placement is handled quite + differently in existing window managers. + + X11 provides no standard or easy way to get the frame geometry + once the window is decorated. Qt solves this problem with nifty + heuristics and clever code that works on a wide range of window + managers that exist today. Don't be surprised if you find one + where QWidget::frameGeometry() returns wrong results though. + + Nor does X11 provide a way to maximize a window. + QWidget::showMaximized() has to emulate the feature. Its result + depends on the result of QWidget::frameGeometry() and the + capability of the window manager to do proper window placement, + neither of which can be guaranteed. +*/ + +/*! + \page mainwindow.html + \title The Application Main Window + \brief Everything you need for a typical modern main application window, + including menus, toolbars, workspace, etc. + + \contentspage Application Windows and Dialogs + \nextpage Dialog Windows + + \tableofcontents + + \section1 Overview of the Main Window Classes + + These classes provide everything you need for a typical modern main + application window, like the main window itself, menu and tool bars, + a status bar, etc. + + \annotatedlist mainwindow-classes + + \section1 The Main Window Classes + + Qt 4 provides the following classes for managing main windows and + associated user interface components: + + \list + \o QMainWindow remains the central class around which applications + can be built. The interface to this class has been simplified, and + much of the functionality previously included in this class is now + present in the companion QDockWidget and QToolBar classes. + + \o QDockWidget provides a widget that can be used to create + detachable tool palettes or helper windows. Dock widgets keep track + of their own properties, and they can be moved, closed, and floated + as external windows. + + \o QToolBar provides a generic toolbar widget that can hold a + number of different action-related widgets, such as buttons, + drop-down menus, comboboxes, and spin boxes. The emphasis on a + unified action model in Qt 4 means that toolbars cooperate well + with menus and keyboard shortcuts. + \endlist + + \section1 Example Code + + Using QMainWindow is straightforward. Generally, we subclass + QMainWindow and set up menus, toolbars, and dock widgets inside + the QMainWindow constructor. + + To add a menu bar to the main window, we simply create the menus, and + add them to the main window's menu bar. Note that the + QMainWindow::menuBar() function will automatically create the menu bar + the first time it is called. You can also call + QMainWindow::setMenuBar() to use a custom menu bar in the main window. + + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 0 + \dots + \snippet examples/mainwindows/menus/mainwindow.cpp 5 + \dots + + Once actions have been created, we can add them to the main window + components. To begin with, we add them to the pop-up menus: + + \snippet examples/mainwindows/menus/mainwindow.cpp 10 + \dots + \snippet examples/mainwindows/menus/mainwindow.cpp 11 + \dots + + The QToolBar and QMenu classes use Qt's action system to provide a + consistent API. In the above code, some existing actions were added to + the file menu with the QMenu::addAction() function. QToolBar also + provides this function, making it easy to reuse actions in different + parts of the main window. This avoids unnecessary duplication of work. + + We create a toolbar as a child of the main window, and add the desired + actions to it: + + \snippet examples/mainwindows/sdi/mainwindow.cpp 0 + \dots + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 1 + + In this example, the toolbar is restricted to the top and bottom + toolbar areas of the main window, and is initially placed in the + top tool bar area. We can see that the actions specified by \c + newAct and \c openAct will be displayed both on the toolbar and in + the file menu. + + QDockWidget is used in a similar way to QToolBar. We create a + dock widget as a child of the main window, and add widgets as children + of the dock widget: + + \snippet doc/src/snippets/dockwidgets/mainwindow.cpp 0 + + In this example, the dock widget can only be placed in the left and + right dock areas, and it is initially placed in the left dock area. + + The QMainWindow API allows the programmer to customize which dock + widget areas occupy the four corners of the dock widget area. If + required, the default can be changed with the + QMainWindow::setCorner() function: + + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 2 + + The following diagram shows the configuration produced by the above code. + Note that the left and right dock widgets will occupy the top and bottom + corners of the main window in this layout. + + \image mainwindow-docks-example.png + + Once all of the main window components have been set up, the central widget + is created and installed by using code similar to the following: + + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.qdoc 3 + + The central widget can be any subclass of QWidget. +*/ diff --git a/doc/src/qtxmlpatterns.qdoc b/doc/src/xml-processing/xml-patterns.qdoc index 38a230e..f951712 100644 --- a/doc/src/qtxmlpatterns.qdoc +++ b/doc/src/xml-processing/xml-patterns.qdoc @@ -40,18 +40,15 @@ ****************************************************************************/ /*! - \module QtXmlPatterns - \title QtXmlPatterns Module - \since 4.4 - \contentspage Qt's Modules - \previouspage QtXml - \nextpage Phonon Module - \ingroup modules - \ingroup scripting + \page xmlprocessing.html + \title Using XML Technologies + + \previouspage Working with the DOM Tree + \contentspage XML Processing \keyword Patternist - \brief An overview of Qt's support for using XQuery and XPath in + \brief An overview of Qt's support for using XML technologies in Qt programs. \tableofcontents @@ -134,18 +131,6 @@ \section2 Running the query engine from your Qt application - To access the QtXmlPatterns C++ API from your Qt application, - include the QtXmlPatterns classes at compile time: - - \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 0 - - Link the compiled application with the QtXmlPatterns module by - adding the following line to the - \l{qmake-project-files.html#declaring-qt-libraries} {QT line} in - your qmake \c{.pro} file: - - \snippet doc/src/snippets/code/doc_src_qtxmlpatterns.qdoc 1 - If we save the example XQuery shown above in a text file (e.g. \c{myquery.xq}), we can run it from a Qt application using a standard QtXmlPatterns code sequence: @@ -910,55 +895,6 @@ URIs are first passed to QAbstractUriResolver. Check QXmlQuery::setUriResolver() for possible rewrites. - - \section1 License Information - - The XML Schema implementation provided by this module contains the \c xml.xsd file - (located in \c{src/xmlpatterns/schema/schemas}) which is licensed under the terms - given below. This module is always built with XML Schema support enabled. - - \legalese - W3C\copyright SOFTWARE NOTICE AND LICENSE - - This license came from: http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 - - This work (and included software, documentation such as READMEs, or other - related items) is being provided by the copyright holders under the following - license. By obtaining, using and/or copying this work, you (the licensee) - agree that you have read, understood, and will comply with the following - terms and conditions. - - Permission to copy, modify, and distribute this software and its - documentation, with or without modification, for any purpose and without - fee or royalty is hereby granted, provided that you include the following on - ALL copies of the software and documentation or portions thereof, including - modifications: - - 1. The full text of this NOTICE in a location viewable to users of the - redistributed or derivative work.\br - 2. Any pre-existing intellectual property disclaimers, notices, or terms - and conditions. If none exist, the W3C Software Short Notice should be - included (hypertext is preferred, text is permitted) - within the body of any redistributed or derivative code.\br - 3. Notice of any changes or modifications to the files, including the date - changes were made. (We recommend you provide URIs to the location from - which the code is derived.) - - THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS - MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT - LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR - PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE - ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. - - COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR - CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR - DOCUMENTATION. - - The name and trademarks of copyright holders may NOT be used in - advertising or publicity pertaining to the software without specific, written - prior permission. Title to copyright in this software and any associated - documentation will at all times remain with copyright holders. - \endlegalese */ /*! diff --git a/doc/src/qtxml.qdoc b/doc/src/xml-processing/xml-processing.qdoc index 4df2589..6e48515 100644 --- a/doc/src/qtxml.qdoc +++ b/doc/src/xml-processing/xml-processing.qdoc @@ -40,75 +40,199 @@ ****************************************************************************/ /*! - \module QtXml - \title QtXml Module - \contentspage Qt's Modules - \previouspage QtSvg - \nextpage QtXmlPatterns - \ingroup modules + \group xml-tools + \title XML Classes - \brief The QtXml module provides a stream reader and writer for - XML documents, and C++ implementations of SAX and DOM. + \brief Classes that support XML, via, for example DOM and SAX. - SAX is an event-based standard interface for XML parsers. - The Qt interface follows the design of the SAX2 Java implementation. - Its naming scheme was adapted to fit the Qt naming conventions. - Details on SAX2 can be found at \l{http://www.saxproject.org}. - - Support for SAX2 filters and the reader factory are under - development. The Qt implementation does not include the SAX1 - compatibility classes present in the Java interface. - For an introduction to Qt's SAX2 classes, see \l{The Qt SAX2 Classes}. - - DOM Level 2 is a W3C Recommendation for XML interfaces that maps the - constituents of an XML document to a tree structure. The specification - of DOM Level 2 can be found at \l{http://www.w3.org/DOM/}. - For more information about the DOM classes in Qt is provided, see - \l{The Qt DOM Classes}. + These classes are relevant to XML users. + + \generatelist{related} +*/ - Since version 4.3, Qt provides two new classes for reading and - writing XML: QXmlStreamReader and QXmlStreamWriter. +/*! + \page xml-processing.html + \title XML Processing + \brief An Overview of the XML processing facilities in Qt. In addition to core XML support, classes for higher level querying - and manipulation of XML data, are provided by the QtXmlPatterns + and manipulation of XML data are provided by the QtXmlPatterns module. In the QtSvg module, the QSvgRenderer and QSvgGenerator classes can read and write a subset of SVG, an XML-based file format. Qt also provides helper functions that may be useful to those working with XML and XHTML: see Qt::escape() and Qt::convertFromPlainText(). - Further XML support is provided by the \l{Qt Solutions} group who - provide, for example, classes that support SOAP and MML with the - Qt XML classes. + \section1 Topics: - This module is part of the \l{Qt Full Framework Edition} and the - \l{Open Source Versions of Qt}. + \list + \o \l {Classes for XML Processing} + \o \l {An Introduction to Namespaces} + \o \l {XML Streaming} + \o \l {The SAX Interface} + \o \l {Working with the DOM Tree} + \o \l {Using XML Technologies}{XQuery/XPath and XML Schema} + \list + \o \l{A Short Path to XQuery} + \endlist + \endlist + + \section1 Classes for XML Processing - Topics: + These classes are relevant to XML users. - \tableofcontents + \annotatedlist xml-tools +*/ - \section1 Configuring the Build Process +/*! + \page xml-namespaces.html + \title An Introduction to Namespaces + \target namespaces - Applications that use Qt's XML classes need to be configured to - be built against the QtXml module. The following declaration in a - \c qmake project file ensures that an application is compiled and - linked appropriately: + \contentspage XML Processing + \nextpage XML Streaming - To include the definitions of the module's classes, use the - following directive: + Parts of the Qt XML module documentation assume that you are familiar + with XML namespaces. Here we present a brief introduction; skip to + \link #namespacesConventions Qt XML documentation conventions \endlink + if you already know this material. - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 0 + Namespaces are a concept introduced into XML to allow a more modular + design. With their help data processing software can easily resolve + naming conflicts in XML documents. - To link against the module, add this line to your \l qmake \c - .pro file: + Consider the following example: - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 1 + \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 6 - This line is necessary because only the QtCore and QtGui modules - are used in the default build process. + Here we find three different uses of the name \e title. If you wish to + process this document you will encounter problems because each of the + \e titles should be displayed in a different manner -- even though + they have the same name. - \section1 The QtXml Stream Classes + The solution would be to have some means of identifying the first + occurrence of \e title as the title of a book, i.e. to use the \e + title element of a book namespace to distinguish it from, for example, + the chapter title, e.g.: + \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 7 + + \e book in this case is a \e prefix denoting the namespace. + + Before we can apply a namespace to element or attribute names we must + declare it. + + Namespaces are URIs like \e http://www.example.com/fnord/book/. This + does not mean that data must be available at this address; the URI is + simply used to provide a unique name. + + We declare namespaces in the same way as attributes; strictly speaking + they \e are attributes. To make for example \e + http://www.example.com/fnord/ the document's default XML namespace \e + xmlns we write + + \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 8 + + To distinguish the \e http://www.example.com/fnord/book/ namespace from + the default, we must supply it with a prefix: + + \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 9 + + A namespace that is declared like this can be applied to element and + attribute names by prepending the appropriate prefix and a ":" + delimiter. We have already seen this with the \e book:title element. + + Element names without a prefix belong to the default namespace. This + rule does not apply to attributes: an attribute without a prefix does + not belong to any of the declared XML namespaces at all. Attributes + always belong to the "traditional" namespace of the element in which + they appear. A "traditional" namespace is not an XML namespace, it + simply means that all attribute names belonging to one element must be + different. Later we will see how to assign an XML namespace to an + attribute. + + Due to the fact that attributes without prefixes are not in any XML + namespace there is no collision between the attribute \e title (that + belongs to the \e author element) and for example the \e title element + within a \e chapter. + + Let's clarify this with an example: + \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 10 + + Within the \e document element we have two namespaces declared. The + default namespace \e http://www.example.com/fnord/ applies to the \e + book element, the \e chapter element, the appropriate \e title element + and of course to \e document itself. + + The \e book:author and \e book:title elements belong to the namespace + with the URI \e http://www.example.com/fnord/book/. + + The two \e book:author attributes \e title and \e name have no XML + namespace assigned. They are only members of the "traditional" + namespace of the element \e book:author, meaning that for example two + \e title attributes in \e book:author are forbidden. + + In the above example we circumvent the last rule by adding a \e title + attribute from the \e http://www.example.com/fnord/ namespace to \e + book:author: the \e fnord:title comes from the namespace with the + prefix \e fnord that is declared in the \e book:author element. + + Clearly the \e fnord namespace has the same namespace URI as the + default namespace. So why didn't we simply use the default namespace + we'd already declared? The answer is quite complex: + \list + \o attributes without a prefix don't belong to any XML namespace at + all, not even to the default namespace; + \o additionally omitting the prefix would lead to a \e title-title clash; + \o writing it as \e xmlns:title would declare a new namespace with the + prefix \e title instead of applying the default \e xmlns namespace. + \endlist + + With the Qt XML classes elements and attributes can be accessed in two + ways: either by refering to their qualified names consisting of the + namespace prefix and the "real" name (or \e local name) or by the + combination of local name and namespace URI. + + More information on XML namespaces can be found at + \l http://www.w3.org/TR/REC-xml-names/. + + \target namespacesConventions + \section1 Conventions Used in the Qt XML Documentation + + The following terms are used to distinguish the parts of names within + the context of namespaces: + \list + \o The \e {qualified name} + is the name as it appears in the document. (In the above example \e + book:title is a qualified name.) + \o A \e {namespace prefix} in a qualified name + is the part to the left of the ":". (\e book is the namespace prefix in + \e book:title.) + \o The \e {local part} of a name (also refered to as the \e {local + name}) appears to the right of the ":". (Thus \e title is the + local part of \e book:title.) + \o The \e {namespace URI} ("Uniform Resource Identifier") is a unique + identifier for a namespace. It looks like a URL + (e.g. \e http://www.example.com/fnord/ ) but does not require + data to be accessible by the given protocol at the named address. + \endlist + + Elements without a ":" (like \e chapter in the example) do not have a + namespace prefix. In this case the local part and the qualified name + are identical (i.e. \e chapter). + + \sa {DOM Bookmarks Example}, {SAX Bookmarks Example} +*/ + +/*! + \page xml-streaming.html + \title XML Streaming + + \previouspage An Introduction to Namespaces + \contentspage XML Processing + \nextpage The SAX Interface + + Since version 4.3, Qt provides two new classes for reading and + writing XML: QXmlStreamReader and QXmlStreamWriter. The QXmlStreamReader and QXmlStreamWriter are two new classes provided in Qt 4.3 and later. A stream reader reports an XML document as a stream @@ -176,10 +300,26 @@ functions of QXmlStreamWriter mentioned above: \snippet examples/xml/streambookmarks/xbelwriter.cpp 1 +*/ - \section1 The Qt SAX2 Classes +/*! + \page xml-sax.html + \title The SAX interface + + \previouspage XML Streaming + \contentspage XML Processing + \nextpage Working with the DOM Tree + + SAX is an event-based standard interface for XML parsers. + The Qt interface follows the design of the SAX2 Java implementation. + Its naming scheme was adapted to fit the Qt naming conventions. + Details on SAX2 can be found at \l{http://www.saxproject.org}. + + Support for SAX2 filters and the reader factory are under + development. The Qt implementation does not include the SAX1 + compatibility classes present in the Java interface. - \section2 Introduction to SAX2 + \section1 Introduction to SAX2 The SAX2 interface is an event-driven mechanism to provide the user with document information. An "event" in this context means something @@ -202,10 +342,10 @@ Whilst this is a fast and simple approach to read XML documents, manipulation is difficult because data is not stored, simply handled - and discarded serially. The \link #dom DOM interface - \endlink reads in and stores the whole document in a tree structure; + and discarded serially. The \l{Working with the DOM Tree}{DOM interface} + reads in and stores the whole document in a tree structure; this takes more memory, but makes it easier to manipulate the - document's structure.. + document's structure. The Qt XML module provides an abstract class, \l QXmlReader, that defines the interface for potential SAX2 readers. Qt includes a reader @@ -257,7 +397,7 @@ QXmlDefaultHandler to read an XML bookmark file (XBEL) and how to generate XML by hand. - \section2 SAX2 Features + \section1 SAX2 Features The behavior of an XML reader depends on its support for certain optional features. For example, a reader may have the feature "report @@ -297,7 +437,7 @@ \l QXmlSimpleReader is not validating, so it does not support \e http://xml.org/sax/features/validation. - \section2 Namespace Support via Features + \section1 Namespace Support via Features As we have seen in the previous section, we can configure the behavior of the reader when it comes to namespace @@ -352,7 +492,7 @@ note that the combination of both features set to false is illegal. - \section3 Summary + \section2 Summary \l QXmlSimpleReader implements the following behavior: @@ -370,7 +510,7 @@ The behavior of the entries marked with an asterisk (*) is not specified by SAX. - \section2 Properties + \section1 Properties Properties are a more general concept. They have a unique name, represented as an URI, but their value is \c void*. Thus nearly @@ -390,13 +530,23 @@ To set or query properties the following functions are provided: \l QXmlReader::setProperty(), \l QXmlReader::property() and \l QXmlReader::hasProperty(). +*/ - +/*! + \page xml-dom.tml + \title Working with the DOM Tree \target dom - \section1 The Qt DOM Classes + + \previouspage The SAX Interface + \contentspage XML Processing + \nextpage {Using XML Technologies}{XQuery/XPath and XML Schema} + + DOM Level 2 is a W3C Recommendation for XML interfaces that maps the + constituents of an XML document to a tree structure. The specification + of DOM Level 2 can be found at \l{http://www.w3.org/DOM/}. \target domIntro - \section2 Introduction to DOM + \section1 Introduction to DOM DOM provides an interface to access and change the content and structure of an XML file. It makes a hierarchical view of the document @@ -478,138 +628,4 @@ You might also want to take a look at the \l{DOM Bookmarks example}, which illustrates how to read and write an XML bookmark file (XBEL) using DOM. - - \target namespaces - \section1 An Introduction to Namespaces - - Parts of the Qt XML module documentation assume that you are familiar - with XML namespaces. Here we present a brief introduction; skip to - \link #namespacesConventions Qt XML documentation conventions \endlink - if you already know this material. - - Namespaces are a concept introduced into XML to allow a more modular - design. With their help data processing software can easily resolve - naming conflicts in XML documents. - - Consider the following example: - - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 6 - - Here we find three different uses of the name \e title. If you wish to - process this document you will encounter problems because each of the - \e titles should be displayed in a different manner -- even though - they have the same name. - - The solution would be to have some means of identifying the first - occurrence of \e title as the title of a book, i.e. to use the \e - title element of a book namespace to distinguish it from, for example, - the chapter title, e.g.: - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 7 - - \e book in this case is a \e prefix denoting the namespace. - - Before we can apply a namespace to element or attribute names we must - declare it. - - Namespaces are URIs like \e http://example.com/fnord/book/. This - does not mean that data must be available at this address; the URI is - simply used to provide a unique name. - - We declare namespaces in the same way as attributes; strictly speaking - they \e are attributes. To make for example \e - http://example.com/fnord/ the document's default XML namespace \e - xmlns we write - - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 8 - - To distinguish the \e http://example.com/fnord/book/ namespace from - the default, we must supply it with a prefix: - - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 9 - - A namespace that is declared like this can be applied to element and - attribute names by prepending the appropriate prefix and a ":" - delimiter. We have already seen this with the \e book:title element. - - Element names without a prefix belong to the default namespace. This - rule does not apply to attributes: an attribute without a prefix does - not belong to any of the declared XML namespaces at all. Attributes - always belong to the "traditional" namespace of the element in which - they appear. A "traditional" namespace is not an XML namespace, it - simply means that all attribute names belonging to one element must be - different. Later we will see how to assign an XML namespace to an - attribute. - - Due to the fact that attributes without prefixes are not in any XML - namespace there is no collision between the attribute \e title (that - belongs to the \e author element) and for example the \e title element - within a \e chapter. - - Let's clarify this with an example: - \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 10 - - Within the \e document element we have two namespaces declared. The - default namespace \e http://example.com/fnord/ applies to the \e - book element, the \e chapter element, the appropriate \e title element - and of course to \e document itself. - - The \e book:author and \e book:title elements belong to the namespace - with the URI \e http://example.com/fnord/book/. - - The two \e book:author attributes \e title and \e name have no XML - namespace assigned. They are only members of the "traditional" - namespace of the element \e book:author, meaning that for example two - \e title attributes in \e book:author are forbidden. - - In the above example we circumvent the last rule by adding a \e title - attribute from the \e http://example.com/fnord/ namespace to \e - book:author: the \e fnord:title comes from the namespace with the - prefix \e fnord that is declared in the \e book:author element. - - Clearly the \e fnord namespace has the same namespace URI as the - default namespace. So why didn't we simply use the default namespace - we'd already declared? The answer is quite complex: - \list - \o attributes without a prefix don't belong to any XML namespace at - all, not even to the default namespace; - \o additionally omitting the prefix would lead to a \e title-title clash; - \o writing it as \e xmlns:title would declare a new namespace with the - prefix \e title instead of applying the default \e xmlns namespace. - \endlist - - With the Qt XML classes elements and attributes can be accessed in two - ways: either by refering to their qualified names consisting of the - namespace prefix and the "real" name (or \e local name) or by the - combination of local name and namespace URI. - - More information on XML namespaces can be found at - \l http://www.w3.org/TR/REC-xml-names/. - - - \target namespacesConventions - \section2 Conventions Used in the Qt XML Documentation - - The following terms are used to distinguish the parts of names within - the context of namespaces: - \list - \o The \e {qualified name} - is the name as it appears in the document. (In the above example \e - book:title is a qualified name.) - \o A \e {namespace prefix} in a qualified name - is the part to the left of the ":". (\e book is the namespace prefix in - \e book:title.) - \o The \e {local part} of a name (also refered to as the \e {local - name}) appears to the right of the ":". (Thus \e title is the - local part of \e book:title.) - \o The \e {namespace URI} ("Uniform Resource Identifier") is a unique - identifier for a namespace. It looks like a URL - (e.g. \e http://example.com/fnord/ ) but does not require - data to be accessible by the given protocol at the named address. - \endlist - - Elements without a ":" (like \e chapter in the example) do not have a - namespace prefix. In this case the local part and the qualified name - are identical (i.e. \e chapter). - - \sa {DOM Bookmarks Example}, {SAX Bookmarks Example} */ diff --git a/doc/src/xquery-introduction.qdoc b/doc/src/xml-processing/xquery-introduction.qdoc index 02e4f47..d944b09 100644 --- a/doc/src/xquery-introduction.qdoc +++ b/doc/src/xml-processing/xquery-introduction.qdoc @@ -42,9 +42,8 @@ /*! \page xquery-introduction.html \title A Short Path to XQuery - \ingroup scripting - \startpage index.html QtReference Documentation + \startpage Using XML Technologies \target XQuery-introduction XQuery is a language for querying XML data or non-XML data that can be |