diff options
Diffstat (limited to 'examples')
-rw-r--r-- | examples/network/doc/images/blockingfortuneclient-example.png | bin | 0 -> 9199 bytes | |||
-rw-r--r-- | examples/network/doc/images/broadcastreceiver-example.png | bin | 0 -> 7447 bytes | |||
-rw-r--r-- | examples/network/doc/images/broadcastsender-example.png | bin | 0 -> 5688 bytes | |||
-rw-r--r-- | examples/network/doc/images/fortuneclient-example.png | bin | 0 -> 8282 bytes | |||
-rw-r--r-- | examples/network/doc/images/fortuneserver-example.png | bin | 0 -> 7883 bytes | |||
-rw-r--r-- | examples/network/doc/images/googlesuggest-example.png | bin | 0 -> 9006 bytes | |||
-rw-r--r-- | examples/network/doc/images/http-example.png | bin | 0 -> 7006 bytes | |||
-rw-r--r-- | examples/network/doc/images/loopback-example.png | bin | 0 -> 6195 bytes | |||
-rw-r--r-- | examples/network/doc/images/multicastreceiver-example.png | bin | 0 -> 13042 bytes | |||
-rw-r--r-- | examples/network/doc/images/multicastsender-example.png | bin | 0 -> 21092 bytes | |||
-rw-r--r-- | examples/network/doc/images/network-chat-example.png | bin | 0 -> 17453 bytes | |||
-rw-r--r-- | examples/network/doc/images/securesocketclient.png | bin | 0 -> 12056 bytes | |||
-rw-r--r-- | examples/network/doc/images/securesocketclient2.png | bin | 0 -> 15532 bytes | |||
-rw-r--r-- | examples/network/doc/images/threadedfortuneserver-example.png | bin | 0 -> 8528 bytes | |||
-rw-r--r-- | examples/network/doc/images/torrent-example.png | bin | 0 -> 18915 bytes | |||
-rw-r--r-- | examples/network/doc/src/blockingfortuneclient.qdoc | 216 | ||||
-rw-r--r-- | examples/network/doc/src/broadcastreceiver.qdoc | 36 | ||||
-rw-r--r-- | examples/network/doc/src/broadcastsender.qdoc | 36 | ||||
-rw-r--r-- | examples/network/doc/src/fortuneclient.qdoc | 160 | ||||
-rw-r--r-- | examples/network/doc/src/fortuneserver.qdoc | 105 | ||||
-rw-r--r-- | examples/network/doc/src/googlesuggest.qdoc | 180 | ||||
-rw-r--r-- | examples/network/doc/src/http.qdoc | 36 | ||||
-rw-r--r-- | examples/network/doc/src/loopback.qdoc | 36 | ||||
-rw-r--r-- | examples/network/doc/src/multicastreceiver.qdoc | 36 | ||||
-rw-r--r-- | examples/network/doc/src/multicastsender.qdoc | 36 | ||||
-rw-r--r-- | examples/network/doc/src/network-chat.qdoc | 37 | ||||
-rw-r--r-- | examples/network/doc/src/securesocketclient.qdoc | 39 | ||||
-rw-r--r-- | examples/network/doc/src/threadedfortuneserver.qdoc | 107 | ||||
-rw-r--r-- | examples/network/doc/src/torrent.qdoc | 69 | ||||
-rw-r--r-- | examples/opengl/doc/images/2dpainting-example.png | bin | 0 -> 32682 bytes | |||
-rw-r--r-- | examples/opengl/doc/images/cube.png | bin | 0 -> 40459 bytes | |||
-rw-r--r-- | examples/opengl/doc/images/cube_faces.png | bin | 0 -> 63082 bytes | |||
-rw-r--r-- | examples/opengl/doc/images/framebufferobject2-example.png | bin | 0 -> 203754 bytes | |||
-rw-r--r-- | examples/opengl/doc/images/grabber-example.png | bin | 0 -> 9893 bytes | |||
-rw-r--r-- | examples/opengl/doc/images/hellogl-es-example.png | bin | 0 -> 61110 bytes | |||
-rw-r--r-- | examples/opengl/doc/images/hellogl-example.png | bin | 0 -> 9520 bytes | |||
-rw-r--r-- | examples/opengl/doc/images/overpainting-example.png | bin | 0 -> 67841 bytes | |||
-rw-r--r-- | examples/opengl/doc/images/pbuffers-example.png | bin | 0 -> 192554 bytes | |||
-rw-r--r-- | examples/opengl/doc/images/pbuffers2-example.png | bin | 0 -> 176171 bytes | |||
-rw-r--r-- | examples/opengl/doc/images/samplebuffers-example.png | bin | 0 -> 16292 bytes | |||
-rw-r--r-- | examples/opengl/doc/images/textures-example.png | bin | 0 -> 46640 bytes | |||
-rw-r--r-- | examples/opengl/doc/src/2dpainting.qdoc | 210 | ||||
-rw-r--r-- | examples/opengl/doc/src/cube.qdoc | 178 | ||||
-rw-r--r-- | examples/opengl/doc/src/framebufferobject2.qdoc | 37 | ||||
-rw-r--r-- | examples/opengl/doc/src/grabber.qdoc | 35 | ||||
-rw-r--r-- | examples/opengl/doc/src/hellogl.qdoc | 305 | ||||
-rw-r--r-- | examples/opengl/doc/src/hellogl_es.qdoc | 128 | ||||
-rw-r--r-- | examples/opengl/doc/src/overpainting.qdoc | 243 | ||||
-rw-r--r-- | examples/opengl/doc/src/pbuffers.qdoc | 37 | ||||
-rw-r--r-- | examples/opengl/doc/src/pbuffers2.qdoc | 37 | ||||
-rw-r--r-- | examples/opengl/doc/src/samplebuffers.qdoc | 36 | ||||
-rw-r--r-- | examples/opengl/doc/src/textures.qdoc | 36 | ||||
-rw-r--r-- | examples/sql/doc/images/cachedtable-example.png | bin | 0 -> 15908 bytes | |||
-rw-r--r-- | examples/sql/doc/images/drilldown-example.png | bin | 0 -> 128081 bytes | |||
-rw-r--r-- | examples/sql/doc/images/masterdetail-example.png | bin | 0 -> 104228 bytes | |||
-rw-r--r-- | examples/sql/doc/images/querymodel-example.png | bin | 0 -> 30882 bytes | |||
-rw-r--r-- | examples/sql/doc/images/relationaltablemodel-example.png | bin | 0 -> 10188 bytes | |||
-rw-r--r-- | examples/sql/doc/images/sql-widget-mapper.png | bin | 0 -> 13040 bytes | |||
-rw-r--r-- | examples/sql/doc/images/sqlbrowser-demo.png | bin | 0 -> 20671 bytes | |||
-rw-r--r-- | examples/sql/doc/images/tablemodel-example.png | bin | 0 -> 20904 bytes | |||
-rw-r--r-- | examples/sql/doc/images/widgetmapper-sql-mapping-table.png | bin | 0 -> 39681 bytes | |||
-rw-r--r-- | examples/sql/doc/images/widgetmapper-sql-mapping.png | bin | 0 -> 60265 bytes | |||
-rw-r--r-- | examples/sql/doc/src/cachedtable.qdoc | 197 | ||||
-rw-r--r-- | examples/sql/doc/src/drilldown.qdoc | 536 | ||||
-rw-r--r-- | examples/sql/doc/src/masterdetail.qdoc | 43 | ||||
-rw-r--r-- | examples/sql/doc/src/querymodel.qdoc | 37 | ||||
-rw-r--r-- | examples/sql/doc/src/relationaltablemodel.qdoc | 36 | ||||
-rw-r--r-- | examples/sql/doc/src/sqlbrowser.qdoc | 36 | ||||
-rw-r--r-- | examples/sql/doc/src/sqlwidgetmapper.qdoc | 185 | ||||
-rw-r--r-- | examples/sql/doc/src/tablemodel.qdoc | 36 | ||||
-rw-r--r-- | examples/tools/doc/src/customcompleter.qdoc | 187 | ||||
-rw-r--r-- | examples/tools/doc/src/customtype.qdoc | 143 | ||||
-rw-r--r-- | examples/widgets/doc/images/itemviewspuzzle-example.png | bin | 0 -> 211091 bytes | |||
-rw-r--r-- | examples/widgets/doc/src/addressbook-fr.qdoc | 1033 | ||||
-rw-r--r-- | examples/widgets/doc/src/addressbook-tutorial.qdoc | 979 | ||||
-rw-r--r-- | examples/widgets/doc/src/addressbook.qdoc (renamed from examples/widgets/doc/addressbook.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/affine.qdoc (renamed from examples/widgets/doc/affine.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/analogclock.qdoc (renamed from examples/widgets/doc/analogclock.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/animatedtiles.qdoc (renamed from examples/widgets/doc/animatedtiles.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/appchooser.qdoc (renamed from examples/widgets/doc/appchooser.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/application.qdoc (renamed from examples/widgets/doc/application.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/applicationicon.qdoc | 67 | ||||
-rw-r--r-- | examples/widgets/doc/src/basicdrawing.qdoc (renamed from examples/widgets/doc/basicdrawing.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/basicgraphicslayouts.qdoc (renamed from examples/widgets/doc/basicgraphicslayouts.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/basiclayouts.qdoc (renamed from examples/widgets/doc/basiclayouts.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/basicsortfiltermodel.qdoc (renamed from examples/widgets/doc/basicsortfiltermodel.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/blurpicker.qdoc (renamed from examples/widgets/doc/blurpicker.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/borderlayout.qdoc (renamed from examples/widgets/doc/borderlayout.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/boxes.qdoc (renamed from examples/widgets/doc/boxes.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/calculator.qdoc (renamed from examples/widgets/doc/calculator.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/calendar.qdoc (renamed from examples/widgets/doc/calendar.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/calendarwidget.qdoc (renamed from examples/widgets/doc/calendarwidget.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/charactermap.qdoc (renamed from examples/widgets/doc/charactermap.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/chart.qdoc (renamed from examples/widgets/doc/chart.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/chip.qdoc (renamed from examples/widgets/doc/chip.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/classwizard.qdoc (renamed from examples/widgets/doc/classwizard.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/codeeditor.qdoc (renamed from examples/widgets/doc/codeeditor.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/coloreditorfactory.qdoc (renamed from examples/widgets/doc/coloreditorfactory.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/combowidgetmapper.qdoc (renamed from examples/widgets/doc/combowidgetmapper.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/composition.qdoc (renamed from examples/widgets/doc/composition.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/concentriccircles.qdoc (renamed from examples/widgets/doc/concentriccircles.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/configdialog.qdoc (renamed from examples/widgets/doc/configdialog.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/customsortfiltermodel.qdoc (renamed from examples/widgets/doc/customsortfiltermodel.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/deform.qdoc (renamed from examples/widgets/doc/deform.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/diagramscene.qdoc (renamed from examples/widgets/doc/diagramscene.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/digitalclock.qdoc (renamed from examples/widgets/doc/digitalclock.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/dirview.qdoc (renamed from examples/widgets/doc/dirview.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/dockwidgets.qdoc (renamed from examples/widgets/doc/dockwidgets.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/draganddroppuzzle.qdoc (renamed from examples/widgets/doc/draganddroppuzzle.qdoc) | 2 | ||||
-rw-r--r-- | examples/widgets/doc/src/dragdroprobot.qdoc (renamed from examples/widgets/doc/dragdroprobot.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/draggableicons.qdoc | 90 | ||||
-rw-r--r-- | examples/widgets/doc/src/draggabletext.qdoc | 36 | ||||
-rw-r--r-- | examples/widgets/doc/src/dynamiclayouts.qdoc (renamed from examples/widgets/doc/dynamiclayouts.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/easing.qdoc (renamed from examples/widgets/doc/easing.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/editabletreemodel.qdoc (renamed from examples/widgets/doc/editabletreemodel.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/elasticnodes.qdoc (renamed from examples/widgets/doc/elasticnodes.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/elidedlabel.qdoc (renamed from examples/widgets/doc/elidedlabel.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/embeddeddialogs.qdoc (renamed from examples/widgets/doc/embeddeddialogs.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/eventtransitions.qdoc (renamed from examples/widgets/doc/eventtransitions.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/extension.qdoc (renamed from examples/widgets/doc/extension.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/factorial.qdoc (renamed from examples/widgets/doc/factorial.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/fademessage.qdoc (renamed from examples/widgets/doc/fademessage.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/fetchmore.qdoc (renamed from examples/widgets/doc/fetchmore.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/findfiles.qdoc (renamed from examples/widgets/doc/findfiles.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/flowlayout.qdoc (renamed from examples/widgets/doc/flowlayout.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/fontsampler.qdoc (renamed from examples/widgets/doc/fontsampler.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/frozencolumn.qdoc (renamed from examples/widgets/doc/frozencolumn.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/gradients.qdoc (renamed from examples/widgets/doc/gradients.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/groupbox.qdoc (renamed from examples/widgets/doc/groupbox.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/icons.qdoc (renamed from examples/widgets/doc/icons.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/imagecomposition.qdoc (renamed from examples/widgets/doc/imagecomposition.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/imageviewer.qdoc (renamed from examples/widgets/doc/imageviewer.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/interview.qdoc (renamed from examples/widgets/doc/interview.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/itemviewspuzzle.qdoc (renamed from examples/widgets/doc/itemviewspuzzle.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/licensewizard.qdoc (renamed from examples/widgets/doc/licensewizard.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/lighting.qdoc (renamed from examples/widgets/doc/lighting.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/lineedits.qdoc (renamed from examples/widgets/doc/lineedits.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/mainwindow.qdoc (renamed from examples/widgets/doc/mainwindow.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/mdi.qdoc (renamed from examples/widgets/doc/mdi.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/menus.qdoc (renamed from examples/widgets/doc/menus.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/moveblocks.qdoc (renamed from examples/widgets/doc/moveblocks.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/movie.qdoc (renamed from examples/widgets/doc/movie.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/orderform.qdoc (renamed from examples/widgets/doc/orderform.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/padnavigator.qdoc (renamed from examples/widgets/doc/padnavigator.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/painterpaths.qdoc (renamed from examples/widgets/doc/painterpaths.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/pathstroke.qdoc (renamed from examples/widgets/doc/pathstroke.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/pingpong.qdoc (renamed from examples/widgets/doc/pingpong.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/pixelator.qdoc (renamed from examples/widgets/doc/pixelator.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/recentfiles.qdoc (renamed from examples/widgets/doc/recentfiles.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/rogue.qdoc (renamed from examples/widgets/doc/rogue.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/screenshot.qdoc (renamed from examples/widgets/doc/screenshot.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/scribble.qdoc (renamed from examples/widgets/doc/scribble.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/sdi.qdoc (renamed from examples/widgets/doc/sdi.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/shapedclock.qdoc (renamed from examples/widgets/doc/shapedclock.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/simpledommodel.qdoc (renamed from examples/widgets/doc/simpledommodel.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/simpletreemodel.qdoc (renamed from examples/widgets/doc/simpletreemodel.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/simplewidgetmapper.qdoc (renamed from examples/widgets/doc/simplewidgetmapper.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/sipdialog.qdoc (renamed from examples/widgets/doc/sipdialog.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/sliders.qdoc (renamed from examples/widgets/doc/sliders.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/spinboxdelegate.qdoc (renamed from examples/widgets/doc/spinboxdelegate.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/spinboxes.qdoc (renamed from examples/widgets/doc/spinboxes.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/spreadsheet.qdoc (renamed from examples/widgets/doc/spreadsheet.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/standarddialogs.qdoc (renamed from examples/widgets/doc/standarddialogs.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/stardelegate.qdoc (renamed from examples/widgets/doc/stardelegate.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/states.qdoc (renamed from examples/widgets/doc/states.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/stickman.qdoc (renamed from examples/widgets/doc/stickman.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/styles.qdoc (renamed from examples/widgets/doc/styles.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/stylesheet.qdoc (renamed from examples/widgets/doc/stylesheet.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/sub-attaq.qdoc (renamed from examples/widgets/doc/sub-attaq.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/syntaxhighlighter.qdoc (renamed from examples/widgets/doc/syntaxhighlighter.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/tabdialog.qdoc (renamed from examples/widgets/doc/tabdialog.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/tablet.qdoc (renamed from examples/widgets/doc/tablet.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/tetrix.qdoc (renamed from examples/widgets/doc/tetrix.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/textedit.qdoc (renamed from examples/widgets/doc/textedit.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/tooltips.qdoc (renamed from examples/widgets/doc/tooltips.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/trafficlight.qdoc (renamed from examples/widgets/doc/trafficlight.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/transformations.qdoc (renamed from examples/widgets/doc/transformations.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/trivialwizard.qdoc (renamed from examples/widgets/doc/trivialwizard.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/twowaybutton.qdoc (renamed from examples/widgets/doc/twowaybutton.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/wiggly.qdoc (renamed from examples/widgets/doc/wiggly.qdoc) | 0 | ||||
-rw-r--r-- | examples/widgets/doc/src/windowflags.qdoc (renamed from examples/widgets/doc/windowflags.qdoc) | 0 | ||||
-rw-r--r-- | examples/xml/doc/images/saxbookmarks-example.png | bin | 0 -> 26219 bytes | |||
-rw-r--r-- | examples/xml/doc/src/saxbookmarks.qdoc | 40 |
183 files changed, 6093 insertions, 1 deletions
diff --git a/examples/network/doc/images/blockingfortuneclient-example.png b/examples/network/doc/images/blockingfortuneclient-example.png Binary files differnew file mode 100644 index 0000000000..cdb7cac0d3 --- /dev/null +++ b/examples/network/doc/images/blockingfortuneclient-example.png diff --git a/examples/network/doc/images/broadcastreceiver-example.png b/examples/network/doc/images/broadcastreceiver-example.png Binary files differnew file mode 100644 index 0000000000..b83789523c --- /dev/null +++ b/examples/network/doc/images/broadcastreceiver-example.png diff --git a/examples/network/doc/images/broadcastsender-example.png b/examples/network/doc/images/broadcastsender-example.png Binary files differnew file mode 100644 index 0000000000..bf7ccbeb9e --- /dev/null +++ b/examples/network/doc/images/broadcastsender-example.png diff --git a/examples/network/doc/images/fortuneclient-example.png b/examples/network/doc/images/fortuneclient-example.png Binary files differnew file mode 100644 index 0000000000..b34a98736d --- /dev/null +++ b/examples/network/doc/images/fortuneclient-example.png diff --git a/examples/network/doc/images/fortuneserver-example.png b/examples/network/doc/images/fortuneserver-example.png Binary files differnew file mode 100644 index 0000000000..73f27d5653 --- /dev/null +++ b/examples/network/doc/images/fortuneserver-example.png diff --git a/examples/network/doc/images/googlesuggest-example.png b/examples/network/doc/images/googlesuggest-example.png Binary files differnew file mode 100644 index 0000000000..477d444cbd --- /dev/null +++ b/examples/network/doc/images/googlesuggest-example.png diff --git a/examples/network/doc/images/http-example.png b/examples/network/doc/images/http-example.png Binary files differnew file mode 100644 index 0000000000..16b0539b1b --- /dev/null +++ b/examples/network/doc/images/http-example.png diff --git a/examples/network/doc/images/loopback-example.png b/examples/network/doc/images/loopback-example.png Binary files differnew file mode 100644 index 0000000000..2b1bd4a0f2 --- /dev/null +++ b/examples/network/doc/images/loopback-example.png diff --git a/examples/network/doc/images/multicastreceiver-example.png b/examples/network/doc/images/multicastreceiver-example.png Binary files differnew file mode 100644 index 0000000000..8de11cda63 --- /dev/null +++ b/examples/network/doc/images/multicastreceiver-example.png diff --git a/examples/network/doc/images/multicastsender-example.png b/examples/network/doc/images/multicastsender-example.png Binary files differnew file mode 100644 index 0000000000..a619b047e3 --- /dev/null +++ b/examples/network/doc/images/multicastsender-example.png diff --git a/examples/network/doc/images/network-chat-example.png b/examples/network/doc/images/network-chat-example.png Binary files differnew file mode 100644 index 0000000000..949bb07d87 --- /dev/null +++ b/examples/network/doc/images/network-chat-example.png diff --git a/examples/network/doc/images/securesocketclient.png b/examples/network/doc/images/securesocketclient.png Binary files differnew file mode 100644 index 0000000000..8736cbc264 --- /dev/null +++ b/examples/network/doc/images/securesocketclient.png diff --git a/examples/network/doc/images/securesocketclient2.png b/examples/network/doc/images/securesocketclient2.png Binary files differnew file mode 100644 index 0000000000..23db851e61 --- /dev/null +++ b/examples/network/doc/images/securesocketclient2.png diff --git a/examples/network/doc/images/threadedfortuneserver-example.png b/examples/network/doc/images/threadedfortuneserver-example.png Binary files differnew file mode 100644 index 0000000000..57c66a5605 --- /dev/null +++ b/examples/network/doc/images/threadedfortuneserver-example.png diff --git a/examples/network/doc/images/torrent-example.png b/examples/network/doc/images/torrent-example.png Binary files differnew file mode 100644 index 0000000000..1032716e04 --- /dev/null +++ b/examples/network/doc/images/torrent-example.png diff --git a/examples/network/doc/src/blockingfortuneclient.qdoc b/examples/network/doc/src/blockingfortuneclient.qdoc new file mode 100644 index 0000000000..90bf439354 --- /dev/null +++ b/examples/network/doc/src/blockingfortuneclient.qdoc @@ -0,0 +1,216 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example blockingfortuneclient + \title Blocking Fortune Client Example + + The Blocking Fortune Client example shows how to create a client for a + network service using QTcpSocket's synchronous API in a non-GUI thread. + + \image blockingfortuneclient-example.png + + QTcpSocket supports two general approaches to network programming: + + \list + + \li \e{The asynchronous (non-blocking) approach.} Operations are scheduled + and performed when control returns to Qt's event loop. When the operation + is finished, QTcpSocket emits a signal. For example, + QTcpSocket::connectToHost() returns immediately, and when the connection + has been established, QTcpSocket emits + \l{QTcpSocket::connected()}{connected()}. + + \li \e{The synchronous (blocking) approach.} In non-GUI and multithreaded + applications, you can call the \c waitFor...() functions (e.g., + QTcpSocket::waitForConnected()) to suspend the calling thread until the + operation has completed, instead of connecting to signals. + + \endlist + + The implementation is very similar to the + \l{fortuneclient}{Fortune Client} example, but instead of having + QTcpSocket as a member of the main class, doing asynchronous networking in + the main thread, we will do all network operations in a separate thread + and use QTcpSocket's blocking API. + + The purpose of this example is to demonstrate a pattern that you can use + to simplify your networking code, without losing responsiveness in your + user interface. Use of Qt's blocking network API often leads to + simpler code, but because of its blocking behavior, it should only be used + in non-GUI threads to prevent the user interface from freezing. But + contrary to what many think, using threads with QThread does not + necessarily add unmanagable complexity to your application. + + We will start with the FortuneThread class, which handles the network + code. + + \snippet blockingfortuneclient/fortunethread.h 0 + + FortuneThread is a QThread subclass that provides an API for scheduling + requests for fortunes, and it has signals for delivering fortunes and + reporting errors. You can call requestNewFortune() to request a new + fortune, and the result is delivered by the newFortune() signal. If any + error occurs, the error() signal is emitted. + + It's important to notice that requestNewFortune() is called from the main, + GUI thread, but the host name and port values it stores will be accessed + from FortuneThread's thread. Because we will be reading and writing + FortuneThread's data members from different threads concurrently, we use + QMutex to synchronize access. + + \snippet blockingfortuneclient/fortunethread.cpp 2 + + The requestNewFortune() function stores the host name and port of the + fortune server as member data, and we lock the mutex with QMutexLocker to + protect this data. We then start the thread, unless it is already + running. We will come back to the QWaitCondition::wakeOne() call later. + + \snippet blockingfortuneclient/fortunethread.cpp 4 + \snippet blockingfortuneclient/fortunethread.cpp 5 + + In the run() function, we start by acquiring the mutex lock, fetching the + host name and port from the member data, and then releasing the lock + again. The case that we are protecting ourselves against is that \c + requestNewFortune() could be called at the same time as we are fetching + this data. QString is \l reentrant but \e not \l{thread-safe}, and we must + also avoid the unlikely risk of reading the host name from one request, + and port of another. And as you might have guessed, FortuneThread can only + handle one request at a time. + + The run() function now enters a loop: + + \snippet blockingfortuneclient/fortunethread.cpp 6 + + The loop will continue requesting fortunes for as long as \e quit is + false. We start our first request by creating a QTcpSocket on the stack, + and then we call \l{QTcpSocket::connectToHost()}{connectToHost()}. This + starts an asynchronous operation which, after control returns to Qt's + event loop, will cause QTcpSocket to emit + \l{QTcpSocket::connected()}{connected()} or + \l{QTcpSocket::error()}{error()}. + + \snippet blockingfortuneclient/fortunethread.cpp 8 + + But since we are running in a non-GUI thread, we do not have to worry + about blocking the user interface. So instead of entering an event loop, + we simply call QTcpSocket::waitForConnected(). This function will wait, + blocking the calling thread, until QTcpSocket emits connected() or an + error occurs. If connected() is emitted, the function returns true; if the + connection failed or timed out (which in this example happens after 5 + seconds), false is returned. QTcpSocket::waitForConnected(), like the + other \c waitFor...() functions, is part of QTcpSocket's \e{blocking + API}. + + After this statement, we have a connected socket to work with. Now it's + time to see what the fortune server has sent us. + + \snippet blockingfortuneclient/fortunethread.cpp 9 + \snippet blockingfortuneclient/fortunethread.cpp 10 + + This step is to read the size of the packet. Although we are only reading + two bytes here, and the \c while loop may seem to overdo it, we present this + code to demonstrate a good pattern for waiting for data using + QTcpSocket::waitForReadyRead(). It goes like this: For as long as we still + need more data, we call waitForReadyRead(). If it returns false, + we abort the operation. After this statement, we know that we have received + enough data. + + \snippet blockingfortuneclient/fortunethread.cpp 11 + + Now we can create a QDataStream object, passing the socket to + QDataStream's constructor, and as in the other client examples we set + the stream protocol version to QDataStream::Qt_4_0, and read the size + of the packet. + + \snippet blockingfortuneclient/fortunethread.cpp 12 + \snippet blockingfortuneclient/fortunethread.cpp 13 + + Again, we'll use a loop that waits for more data by calling + QTcpSocket::waitForReadyRead(). In this loop, we're waiting until + QTcpSocket::bytesAvailable() returns the full packet size. + + \snippet blockingfortuneclient/fortunethread.cpp 14 + + Now that we have all the data that we need, we can use QDataStream to + read the fortune string from the packet. The resulting fortune is + delivered by emitting newFortune(). + + \snippet blockingfortuneclient/fortunethread.cpp 15 + + The final part of our loop is that we acquire the mutex so that we can + safely read from our member data. We then let the thread go to sleep by + calling QWaitCondition::wait(). At this point, we can go back to + requestNewFortune() and look closed at the call to wakeOne(): + + \snippet blockingfortuneclient/fortunethread.cpp 1 + \dots + \snippet blockingfortuneclient/fortunethread.cpp 3 + + What happened here was that because the thread falls asleep waiting for a + new request, we needed to wake it up again when a new request + arrives. QWaitCondition is often used in threads to signal a wakeup call + like this. + + \snippet blockingfortuneclient/fortunethread.cpp 0 + + Finishing off the FortuneThread walkthrough, this is the destructor that + sets \e quit to true, wakes up the thread and waits for the thread to exit + before returning. This lets the \c while loop in run() will finish its current + iteration. When run() returns, the thread will terminate and be destroyed. + + Now for the BlockingClient class: + + \snippet blockingfortuneclient/blockingclient.h 0 + + BlockingClient is very similar to the Client class in the + \l{fortuneclient}{Fortune Client} example, but in this class + we store a FortuneThread member instead of a pointer to a QTcpSocket. + When the user clicks the "Get Fortune" button, the same slot is called, + but its implementation is slightly different: + + \snippet blockingfortuneclient/blockingclient.cpp 0 + \snippet blockingfortuneclient/blockingclient.cpp 1 + + We connect our FortuneThread's two signals newFortune() and error() (which + are somewhat similar to QTcpSocket::readyRead() and QTcpSocket::error() in + the previous example) to requestNewFortune() and displayError(). + + \snippet blockingfortuneclient/blockingclient.cpp 2 + + The requestNewFortune() slot calls FortuneThread::requestNewFortune(), + which \e shedules the request. When the thread has received a new fortune + and emits newFortune(), our showFortune() slot is called: + + \snippet blockingfortuneclient/blockingclient.cpp 3 + \codeline + \snippet blockingfortuneclient/blockingclient.cpp 4 + + Here, we simply display the fortune we received as the argument. + + \sa {Fortune Client Example}, {Fortune Server Example} +*/ diff --git a/examples/network/doc/src/broadcastreceiver.qdoc b/examples/network/doc/src/broadcastreceiver.qdoc new file mode 100644 index 0000000000..61abcca15f --- /dev/null +++ b/examples/network/doc/src/broadcastreceiver.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example broadcastreceiver + \title Broadcast Receiver Example + + The Broadcast Receiver example shows how to receive information that is broadcasted + over a local network. + + \image broadcastreceiver-example.png +*/ diff --git a/examples/network/doc/src/broadcastsender.qdoc b/examples/network/doc/src/broadcastsender.qdoc new file mode 100644 index 0000000000..79127efbfb --- /dev/null +++ b/examples/network/doc/src/broadcastsender.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example broadcastsender + \title Broadcast Sender Example + + The Broadcast Sender example shows how to broadcast information to multiple clients + on a local network. + + \image broadcastsender-example.png +*/ diff --git a/examples/network/doc/src/fortuneclient.qdoc b/examples/network/doc/src/fortuneclient.qdoc new file mode 100644 index 0000000000..ccf5d8f150 --- /dev/null +++ b/examples/network/doc/src/fortuneclient.qdoc @@ -0,0 +1,160 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example fortuneclient + \title Fortune Client Example + + The Fortune Client example shows how to create a client for a simple + network service using QTcpSocket. It is intended to be run alongside the + \l{fortuneserver}{Fortune Server} example or + the \l{threadedfortuneserver}{Threaded Fortune Server} example. + + \image fortuneclient-example.png Screenshot of the Fortune Client example + + This example uses a simple QDataStream-based data transfer protocol to + request a line of text from a fortune server (from the + \l{fortuneserver}{Fortune Server} example). The client requests a + fortune by simply connecting to the server. The server then responds with + a 16-bit (quint16) integer containing the length of the fortune text, + followed by a QString. + + QTcpSocket supports two general approaches to network programming: + + \list + + \li \e{The asynchronous (non-blocking) approach.} Operations are scheduled + and performed when control returns to Qt's event loop. When the operation + is finished, QTcpSocket emits a signal. For example, + QTcpSocket::connectToHost() returns immediately, and when the connection + has been established, QTcpSocket emits + \l{QTcpSocket::connected()}{connected()}. + + \li \e{The synchronous (blocking) approach.} In non-GUI and multithreaded + applications, you can call the \c waitFor...() functions (e.g., + QTcpSocket::waitForConnected()) to suspend the calling thread until the + operation has completed, instead of connecting to signals. + + \endlist + + In this example, we will demonstrate the asynchronous approach. The + \l{blockingfortuneclient}{Blocking Fortune Client} example + illustrates the synchronous approach. + + Our class contains some data and a few private slots: + + \snippet fortuneclient/client.h 0 + + Other than the widgets that make up the GUI, the data members include a + QTcpSocket pointer, a copy of the fortune text currently displayed, and + the size of the packet we are currently reading (more on this later). + + The socket is initialized in the Client constructor. We'll pass the main + widget as parent, so that we won't have to worry about deleting the + socket: + + \snippet fortuneclient/client.cpp 0 + \dots + \snippet fortuneclient/client.cpp 1 + + The only QTcpSocket signals we need in this example are + QTcpSocket::readyRead(), signifying that data has been received, and + QTcpSocket::error(), which we will use to catch any connection errors: + + \dots + \snippet fortuneclient/client.cpp 3 + \dots + \snippet fortuneclient/client.cpp 5 + + Clicking the \uicontrol{Get Fortune} button will invoke the \c + requestNewFortune() slot: + + \snippet fortuneclient/client.cpp 6 + + In this slot, we initialize \c blockSize to 0, preparing to read a new block + of data. Because we allow the user to click \uicontrol{Get Fortune} before the + previous connection finished closing, we start off by aborting the + previous connection by calling QTcpSocket::abort(). (On an unconnected + socket, this function does nothing.) We then proceed to connecting to the + fortune server by calling QTcpSocket::connectToHost(), passing the + hostname and port from the user interface as arguments. + + As a result of calling \l{QTcpSocket::connectToHost()}{connectToHost()}, + one of two things can happen: + + \list + \li \e{The connection is established.} In this case, the server will send us a + fortune. QTcpSocket will emit \l{QTcpSocket::readyRead()}{readyRead()} + every time it receives a block of data. + + \li \e{An error occurs.} We need to inform the user if the connection + failed or was broken. In this case, QTcpSocket will emit + \l{QTcpSocket::error()}{error()}, and \c Client::displayError() will be + called. + \endlist + + Let's go through the \l{QTcpSocket::error()}{error()} case first: + + \snippet fortuneclient/client.cpp 13 + + We pop up all errors in a dialog using + QMessageBox::information(). QTcpSocket::RemoteHostClosedError is silently + ignored, because the fortune server protocol ends with the server closing + the connection. + + Now for the \l{QTcpSocket::readyRead()}{readyRead()} alternative. This + signal is connected to \c Client::readFortune(): + + \snippet fortuneclient/client.cpp 8 + \codeline + \snippet fortuneclient/client.cpp 10 + + The protocol is based on QDataStream, so we start by creating a stream + object, passing the socket to QDataStream's constructor. We then + explicitly set the protocol version of the stream to QDataStream::Qt_4_0 + to ensure that we're using the same version as the fortune server, no + matter which version of Qt the client and server use. + + Now, TCP is based on sending a stream of data, so we cannot expect to get + the entire fortune in one go. Especially on a slow network, the data can + be received in several small fragments. QTcpSocket buffers up all incoming + data and emits \l{QTcpSocket::readyRead()}{readyRead()} for every new + block that arrives, and it is our job to ensure that we have received all + the data we need before we start parsing. The server's response starts + with the size of the packet, so first we need to ensure that we can read + the size, then we will wait until QTcpSocket has received the full packet. + + \snippet fortuneclient/client.cpp 11 + \codeline + \snippet fortuneclient/client.cpp 12 + + We proceed by using QDataStream's streaming operator to read the fortune + from the socket into a QString. Once read, we can call QLabel::setText() + to display the fortune. + + \sa {Fortune Server Example}, {Blocking Fortune Client Example} +*/ diff --git a/examples/network/doc/src/fortuneserver.qdoc b/examples/network/doc/src/fortuneserver.qdoc new file mode 100644 index 0000000000..0bc50283c3 --- /dev/null +++ b/examples/network/doc/src/fortuneserver.qdoc @@ -0,0 +1,105 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example fortuneserver + \title Fortune Server Example + + The Fortune Server example shows how to create a server for a simple + network service. It is intended to be run alongside the + \l{fortuneclient}{Fortune Client} example or the + \l{blockingfortuneclient}{Blocking Fortune Client} example. + + \image fortuneserver-example.png Screenshot of the Fortune Server example + + This example uses QTcpServer to accept incoming TCP connections, and a + simple QDataStream based data transfer protocol to write a fortune to the + connecting client (from the \l{fortuneclient}{Fortune Client} + example), before closing the connection. + + \snippet fortuneserver/server.h 0 + + The server is implemented using a simple class with only one slot, for + handling incoming connections. + + \snippet fortuneserver/server.cpp 1 + + In its constructor, our Server object calls QTcpServer::listen() to set up + a QTcpServer to listen on all addresses, on an arbitrary port. In then + displays the port QTcpServer picked in a label, so that user knows which + port the fortune client should connect to. + + \snippet fortuneserver/server.cpp 2 + + Our server generates a list of random fortunes that is can send to + connecting clients. + + \snippet fortuneserver/server.cpp 3 + + When a client connects to our server, QTcpServer will emit + QTcpServer::newConnection(). In turn, this will invoke our + sendFortune() slot: + + \snippet fortuneserver/server.cpp 4 + + The purpose of this slot is to select a random line from our list of + fortunes, encode it into a QByteArray using QDataStream, and then write it + to the connecting socket. This is a common way to transfer binary data + using QTcpSocket. First we create a QByteArray and a QDataStream object, + passing the bytearray to QDataStream's constructor. We then explicitly set + the protocol version of QDataStream to QDataStream::Qt_4_0 to ensure that + we can communicate with clients from future versions of Qt. (See + QDataStream::setVersion().) + + \snippet fortuneserver/server.cpp 6 + + At the start of our QByteArray, we reserve space for a 16 bit integer that + will contain the total size of the data block we are sending. We continue + by streaming in a random fortune. Then we seek back to the beginning of + the QByteArray, and overwrite the reserved 16 bit integer value with the + total size of the array. By doing this, we provide a way for clients to + verify how much data they can expect before reading the whole packet. + + \snippet fortuneserver/server.cpp 7 + + We then call QTcpServer::newPendingConnection(), which returns the + QTcpSocket representing the server side of the connection. By connecting + QTcpSocket::disconnected() to QObject::deleteLater(), we ensure that the + socket will be deleted after disconnecting. + + \snippet fortuneserver/server.cpp 8 + + The encoded fortune is written using QTcpSocket::write(), and we finally + call QTcpSocket::disconnectFromHost(), which will close the connection + after QTcpSocket has finished writing the fortune to the network. Because + QTcpSocket works asynchronously, the data will be written after this + function returns, and control goes back to Qt's event loop. The socket + will then close, which in turn will cause QObject::deleteLater() to delete + it. + + \sa {Fortune Client Example}, {Threaded Fortune Server Example} + */ diff --git a/examples/network/doc/src/googlesuggest.qdoc b/examples/network/doc/src/googlesuggest.qdoc new file mode 100644 index 0000000000..b083f0cd58 --- /dev/null +++ b/examples/network/doc/src/googlesuggest.qdoc @@ -0,0 +1,180 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example googlesuggest + \title Google Suggest Example + + The Google Suggest example demonstrates how to use the QNetworkAccessManager + class to obtain a list of suggestions from the Google search engine as the + user types into a QLineEdit. + + \image googlesuggest-example.png + + The application makes use of the \c get function in + QNetworkAccessManager to post a request and obtain the result of the search + query sent to the Google search engine. The results returned are listed as + clickable links appearing below the search box as a drop-down menu. + + The widget is built up by a QLineEdit as the search box, and a QTreeView + used as a popup menu below the search box. + + \section1 GSuggestCompletion Class Declaration + + This class implements an event filter and a number of functions to display + the search results and to determent when and how to perform the search. + + \snippet googlesuggest/googlesuggest.h 1 + + The class connects to a QLineEdit and uses a QTreeWidget to display the + results. A QTimer controls the start of the network requests that are + executed using a QNetworkAccessManager. + + \section1 GSuggestCompletion Class Implementation + + We start by defining a constant containing the URL to be used in the Google + queries. This is the basis for the query. The letters typed into the search + box will be added to the query to perform the search itself. + + \snippet googlesuggest/googlesuggest.cpp 1 + + In the constructor, we set the parent of this GSuggestCompletion instance + to be the QLineEdit passed in. For simplicity, the QLineEdit is also stored + in the explicit \c editor member variable. + + We then create a QTreeWidget as a toplevel widget and configure the various + properties to give it the look of a popup widget. + + The popup will be populated by the results returned from Google. We set + the number of columns to be two, since we want to display both the + suggested search term and the number of hits it will trigger in the search + engine. + + Furthermore, we install the GSuggestCompletion instance as an event filter + on the QTreeWidget, and connect the \c itemClicked() signal with the \c + doneCompletion() slot. + + A single-shot QTimer is used to start the request when the user has stopped + typing for 500 ms. + + Finally, we connect the networkManagers \c finished() signal with the \c + handleNetworkData() slot to handle the incoming data. + + \snippet googlesuggest/googlesuggest.cpp 2 + + Since the QTreeWidget popup has been instantiated as a toplevel widget, the + destructor has to delete it explicitly from memory to avoid a memory leak. + + \snippet googlesuggest/googlesuggest.cpp 3 + + The event filter handles mouse press and key press events that are + delivered to the popup. For mouse press events we just hide the popup and + return focus to the editor widget, and then return true to prevent further + event processing. + + Key event handling is implemented so that Enter and Return execute the + selected link, while the Escape key hides the popup. Since we want to be + able to navigate the list of suggestions using the different navigation + keys on the keyboard we let Qt continue regular event processing for those + by returning false from the eventFilter reimplementation. + + For all other keys, the event will be passed on to the editor widget and the + popup is hidden. This way the user's typing will not be interrupted by the + popping up of the completion list. + + \snippet googlesuggest/googlesuggest.cpp 4 + + The \c showCompletion() function populates the QTreeWidget with the results + returned from the query. It takes two QStringLists, one with the suggested + search terms and the other with the corresponding number of hits. + + \snippet googlesuggest/googlesuggest.cpp 5 + + A QTreeWidgetItem is created for each index in the list and inserted into + the QTreeWidget. Finally, we adjust position and size of the popup to make + sure that it pops up in the correct position below the editor, and show it. + + The \c doneCompletion() function, which is called by the event filter when + either Enter or Return keys are pressed, stops the timer to prevent further + requests and passes the text of the selected item to the editor. We then + make the \c editor QLineEdit emit the returnPressed() signal, to which the + application can connect to open the respective web page. + + \snippet googlesuggest/googlesuggest.cpp 6 + + The \c autoSuggest() slot is called when the timer times out, and uses the + text in the editor to build the complete search query. The query is then + passed to the QNetworkAccessManager's \c get() function to start the + request. + + \snippet googlesuggest/googlesuggest.cpp 7 + + The function \c preventSuggest() stops the timer to prevent further + requests from being started. + + \snippet googlesuggest/googlesuggest.cpp 8 + + When the network request is finished, the QNetworkAccessManager delivers the + data received from the server through the networkReply object. + + \snippet googlesuggest/googlesuggest.cpp 9 + + To extract the data from the reply we use the \c readAll() function, which + is inherited from QIODevice and returns a QByteArray. Since this data is + encoded in XML we can use a QXmlStreamReader to traverse the data and + extract the search result as QStrings, which we can stream into two + QStringLists used to populate the popup. + + Finally, we schedule the QNetworkReply object for deletion using the \c + deleteLater function. + + \section1 SearchBox Class Declaration + + The SearchBox class inherits QLineEdit and adds the protected slot \c + doSearch(). + + A \c GSuggestCompletion member provides the SearchBox with the request + functionality and the suggestions returned from the Google search engine. + + \snippet googlesuggest/searchbox.h 1 + + \section1 SearchBox Class Implementation + + The search box constructor instantiates the GSuggestCompletion object and + connects the returnPressed() signal to the doSearch() slot. + + \snippet googlesuggest/searchbox.cpp 1 + + The function \c doSearch() stops the completer from sending any further + queries to the search engine. + + Further, the function extracts the selected search phrase and opens it + in the default web browser using QDesktopServices. + + \snippet googlesuggest/searchbox.cpp 2 + +*/ diff --git a/examples/network/doc/src/http.qdoc b/examples/network/doc/src/http.qdoc new file mode 100644 index 0000000000..6b30a83c96 --- /dev/null +++ b/examples/network/doc/src/http.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example http + \title HTTP Example + + The HTTP example demonstrates a simple HTTP client that shows how to fetch files + specified by URLs from remote hosts. + + \image http-example.png +*/ diff --git a/examples/network/doc/src/loopback.qdoc b/examples/network/doc/src/loopback.qdoc new file mode 100644 index 0000000000..ecae81307b --- /dev/null +++ b/examples/network/doc/src/loopback.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example loopback + \title Loopback Example + + The Loopback example shows how to communicate between simple clients and servers on a local + host. + + \image loopback-example.png +*/ diff --git a/examples/network/doc/src/multicastreceiver.qdoc b/examples/network/doc/src/multicastreceiver.qdoc new file mode 100644 index 0000000000..e36e01a38c --- /dev/null +++ b/examples/network/doc/src/multicastreceiver.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example multicastreceiver + \title Multicast Receiver Example + + The Multicast Receiever example shows how to receive information that is + sent to a multicast group. + + \image multicastreceiver-example.png +*/ diff --git a/examples/network/doc/src/multicastsender.qdoc b/examples/network/doc/src/multicastsender.qdoc new file mode 100644 index 0000000000..a1d70caf86 --- /dev/null +++ b/examples/network/doc/src/multicastsender.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example multicastsender + \title Multicast Sender Example + + The Multicast Sender example shows how to send information to multiple + clients in a multicast group. + + \image multicastsender-example.png +*/ diff --git a/examples/network/doc/src/network-chat.qdoc b/examples/network/doc/src/network-chat.qdoc new file mode 100644 index 0000000000..3e0d7540b9 --- /dev/null +++ b/examples/network/doc/src/network-chat.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network-chat + \title Network Chat Example + + The Network Chat example demonstrates a stateful peer-to-peer Chat client + that uses broadcasting with QUdpSocket and QNetworkInterface to discover + its peers. + + \image network-chat-example.png +*/ diff --git a/examples/network/doc/src/securesocketclient.qdoc b/examples/network/doc/src/securesocketclient.qdoc new file mode 100644 index 0000000000..b740af3531 --- /dev/null +++ b/examples/network/doc/src/securesocketclient.qdoc @@ -0,0 +1,39 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example securesocketclient + \title Secure Socket Client Example + + The Secure Socket Client example shows how to use QSslSocket to + communicate over an encrypted (SSL) connection. It also demonstrates how + to deal with authenticity problems, and how to display security and + certificate information. + + \image securesocketclient.png + \image securesocketclient2.png +*/ diff --git a/examples/network/doc/src/threadedfortuneserver.qdoc b/examples/network/doc/src/threadedfortuneserver.qdoc new file mode 100644 index 0000000000..33b6892363 --- /dev/null +++ b/examples/network/doc/src/threadedfortuneserver.qdoc @@ -0,0 +1,107 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example threadedfortuneserver + \title Threaded Fortune Server Example + + The Threaded Fortune Server example shows how to create a server for a + simple network service that uses threads to handle requests from different + clients. It is intended to be run alongside the Fortune Client example. + + \image threadedfortuneserver-example.png + + The implementation of this example is similar to that of the + \l{fortuneserver}{Fortune Server} example, but here we will + implement a subclass of QTcpServer that starts each connection in a + different thread. + + For this we need two classes: FortuneServer, a QTcpServer subclass, and + FortuneThread, which inherits QThread. + + \snippet threadedfortuneserver/fortuneserver.h 0 + + FortuneServer inherits QTcpServer and reimplements + QTcpServer::incomingConnection(). We also use it for storing the list of + random fortunes. + + \snippet threadedfortuneserver/fortuneserver.cpp 0 + + We use FortuneServer's constructor to simply generate the list of + fortunes. + + \snippet threadedfortuneserver/fortuneserver.cpp 1 + + Our implementation of QTcpServer::incomingConnection() creates a + FortuneThread object, passing the incoming socket descriptor and a random + fortune to FortuneThread's constructor. By connecting FortuneThread's + finished() signal to QObject::deleteLater(), we ensure that the thread + gets deleted once it has finished. We can then call QThread::start(), + which starts the thread. + + \snippet threadedfortuneserver/fortunethread.h 0 + + Moving on to the FortuneThread class, this is a QThread subclass whose job + is to write the fortune to the connected socket. The class reimplements + QThread::run(), and it has a signal for reporting errors. + + \snippet threadedfortuneserver/fortunethread.cpp 0 + + FortuneThread's constructor simply stores the socket descriptor and + fortune text, so that they are available for run() later on. + + \snippet threadedfortuneserver/fortunethread.cpp 1 + + The first thing our run() function does is to create a QTcpSocket object + on the stack. What's worth noticing is that we are creating this object + inside the thread, which automatically associates the socket to the + thread's event loop. This ensures that Qt will not try to deliver events + to our socket from the main thread while we are accessing it from + FortuneThread::run(). + + \snippet threadedfortuneserver/fortunethread.cpp 2 + + The socket is initialized by calling QTcpSocket::setSocketDescriptor(), + passing our socket descriptor as an argument. We expect this to succeed, + but just to be sure, (although unlikely, the system may run out of + resources,) we catch the return value and report any error. + + \snippet threadedfortuneserver/fortunethread.cpp 3 + + As with the \l{fortuneserver}{Fortune Server} example, we encode + the fortune into a QByteArray using QDataStream. + + \snippet threadedfortuneserver/fortunethread.cpp 4 + + But unlike the previous example, we finish off by calling + QTcpSocket::waitForDisconnected(), which blocks the calling thread until + the socket has disconnected. Because we are running in a separate thread, + the GUI will remain responsive. + + \sa {Fortune Server Example}, {Fortune Client Example}, {Blocking Fortune + Client Example} +*/ diff --git a/examples/network/doc/src/torrent.qdoc b/examples/network/doc/src/torrent.qdoc new file mode 100644 index 0000000000..a13d447277 --- /dev/null +++ b/examples/network/doc/src/torrent.qdoc @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example torrent + \title Torrent Example + + The Torrent example is a functional BitTorrent client that + illustrates how to write a complex TCP/IP application using Qt. + + \image torrent-example.png + + \section1 License Information + + The implementation of the US Secure Hash Algorithm 1 (SHA1) in this example is + derived from the original description in \l{RFC 3174}. + + \legalese + Copyright (C) The Internet Society (2001). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + \endlegalese +*/ diff --git a/examples/opengl/doc/images/2dpainting-example.png b/examples/opengl/doc/images/2dpainting-example.png Binary files differnew file mode 100644 index 0000000000..2a77e7d7d5 --- /dev/null +++ b/examples/opengl/doc/images/2dpainting-example.png diff --git a/examples/opengl/doc/images/cube.png b/examples/opengl/doc/images/cube.png Binary files differnew file mode 100644 index 0000000000..95dfc984dd --- /dev/null +++ b/examples/opengl/doc/images/cube.png diff --git a/examples/opengl/doc/images/cube_faces.png b/examples/opengl/doc/images/cube_faces.png Binary files differnew file mode 100644 index 0000000000..2c7102a94c --- /dev/null +++ b/examples/opengl/doc/images/cube_faces.png diff --git a/examples/opengl/doc/images/framebufferobject2-example.png b/examples/opengl/doc/images/framebufferobject2-example.png Binary files differnew file mode 100644 index 0000000000..bafb05a08b --- /dev/null +++ b/examples/opengl/doc/images/framebufferobject2-example.png diff --git a/examples/opengl/doc/images/grabber-example.png b/examples/opengl/doc/images/grabber-example.png Binary files differnew file mode 100644 index 0000000000..6a05b94bec --- /dev/null +++ b/examples/opengl/doc/images/grabber-example.png diff --git a/examples/opengl/doc/images/hellogl-es-example.png b/examples/opengl/doc/images/hellogl-es-example.png Binary files differnew file mode 100644 index 0000000000..7e55f09a7a --- /dev/null +++ b/examples/opengl/doc/images/hellogl-es-example.png diff --git a/examples/opengl/doc/images/hellogl-example.png b/examples/opengl/doc/images/hellogl-example.png Binary files differnew file mode 100644 index 0000000000..ecb3a3a7b0 --- /dev/null +++ b/examples/opengl/doc/images/hellogl-example.png diff --git a/examples/opengl/doc/images/overpainting-example.png b/examples/opengl/doc/images/overpainting-example.png Binary files differnew file mode 100644 index 0000000000..0368dcabc8 --- /dev/null +++ b/examples/opengl/doc/images/overpainting-example.png diff --git a/examples/opengl/doc/images/pbuffers-example.png b/examples/opengl/doc/images/pbuffers-example.png Binary files differnew file mode 100644 index 0000000000..c34a6fd02b --- /dev/null +++ b/examples/opengl/doc/images/pbuffers-example.png diff --git a/examples/opengl/doc/images/pbuffers2-example.png b/examples/opengl/doc/images/pbuffers2-example.png Binary files differnew file mode 100644 index 0000000000..4a9c7175a3 --- /dev/null +++ b/examples/opengl/doc/images/pbuffers2-example.png diff --git a/examples/opengl/doc/images/samplebuffers-example.png b/examples/opengl/doc/images/samplebuffers-example.png Binary files differnew file mode 100644 index 0000000000..b751c143b3 --- /dev/null +++ b/examples/opengl/doc/images/samplebuffers-example.png diff --git a/examples/opengl/doc/images/textures-example.png b/examples/opengl/doc/images/textures-example.png Binary files differnew file mode 100644 index 0000000000..b583ede063 --- /dev/null +++ b/examples/opengl/doc/images/textures-example.png diff --git a/examples/opengl/doc/src/2dpainting.qdoc b/examples/opengl/doc/src/2dpainting.qdoc new file mode 100644 index 0000000000..7239ddbf3d --- /dev/null +++ b/examples/opengl/doc/src/2dpainting.qdoc @@ -0,0 +1,210 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example 2dpainting + \title 2D Painting Example + + The 2D Painting example shows how QPainter and QGLWidget can be used + together to display accelerated 2D graphics on supported hardware. + + \image 2dpainting-example.png + + The QPainter class is used to draw 2D graphics primitives onto + paint devices provided by QPaintDevice subclasses, such as QWidget + and QImage. + + Since QGLWidget is a subclass of QWidget, it is possible + to reimplement its \l{QWidget::paintEvent()}{paintEvent()} and use + QPainter to draw on the device, just as you would with a QWidget. + The only difference is that the painting operations will be accelerated + in hardware if it is supported by your system's OpenGL drivers. + + In this example, we perform the same painting operations on a + QWidget and a QGLWidget. The QWidget is shown with anti-aliasing + enabled, and the QGLWidget will also use anti-aliasing if the + required extensions are supported by your system's OpenGL driver. + + \section1 Overview + + To be able to compare the results of painting onto a QGLWidget subclass + with native drawing in a QWidget subclass, we want to show both kinds + of widget side by side. To do this, we derive subclasses of QWidget and + QGLWidget, using a separate \c Helper class to perform the same painting + operations for each, and lay them out in a top-level widget, itself + provided a the \c Window class. + + \section1 Helper Class Definition + + In this example, the painting operations are performed by a helper class. + We do this because we want the same painting operations to be performed + for both our QWidget subclass and the QGLWidget subclass. + + The \c Helper class is minimal: + + \snippet 2dpainting/helper.h 0 + + Apart from the constructor, it only provides a \c paint() function to paint + using a painter supplied by one of our widget subclasses. + + \section1 Helper Class Implementation + + The constructor of the class sets up the resources it needs to paint + content onto a widget: + + \snippet 2dpainting/helper.cpp 0 + + The actual painting is performed in the \c paint() function. This takes + a QPainter that has already been set up to paint onto a paint device + (either a QWidget or a QGLWidget), a QPaintEvent that provides information + about the region to be painted, and a measure of the elapsed time (in + milliseconds) since the paint device was last updated. + + \snippet 2dpainting/helper.cpp 1 + + We begin painting by filling in the region contained in the paint event + before translating the origin of the coordinate system so that the rest + of the painting operations will be displaced towards the center of the + paint device. + + We draw a spiral pattern of circles, using the elapsed time specified to + animate them so that they appear to move outward and around the coordinate + system's origin: + + \snippet 2dpainting/helper.cpp 2 + + Since the coordinate system is rotated many times during + this process, we \l{QPainter::save()}{save()} the QPainter's state + beforehand and \l{QPainter::restore()}{restore()} it afterwards. + + \snippet 2dpainting/helper.cpp 3 + + We draw some text at the origin to complete the effect. + + \section1 Widget Class Definition + + The \c Widget class provides a basic custom widget that we use to + display the simple animation painted by the \c Helper class. + + \snippet 2dpainting/widget.h 0 + + Apart from the constructor, it only contains a + \l{QWidget::paintEvent()}{paintEvent()} function, that lets us draw + customized content, and a slot that is used to animate its contents. + One member variable keeps track of the \c Helper that the widget uses + to paint its contents, and the other records the elapsed time since + it was last updated. + + \section1 Widget Class Implementation + + The constructor only initializes the member variables, storing the + \c Helper object supplied and calling the base class's constructor, + and enforces a fixed size for the widget: + + \snippet 2dpainting/widget.cpp 0 + + The \c animate() slot is called whenever a timer, which we define later, times + out: + + \snippet 2dpainting/widget.cpp 1 + + Here, we determine the interval that has elapsed since the timer last + timed out, and we add it to any existing value before repainting the + widget. Since the animation used in the \c Helper class loops every second, + we can use the modulo operator to ensure that the \c elapsed variable is + always less than 1000. + + Since the \c Helper class does all of the actual painting, we only have + to implement a paint event that sets up a QPainter for the widget and calls + the helper's \c paint() function: + + \snippet 2dpainting/widget.cpp 2 + + \section1 GLWidget Class Definition + + The \c GLWidget class definition is basically the same as the \c Widget + class except that it is derived from QGLWidget. + + \snippet 2dpainting/glwidget.h 0 + + Again, the member variables record the \c Helper used to paint the + widget and the elapsed time since the previous update. + + \section1 GLWidget Class Implementation + + The constructor differs a little from the \c Widget class's constructor: + + \snippet 2dpainting/glwidget.cpp 0 + + As well as initializing the \c elapsed member variable and storing the + \c Helper object used to paint the widget, the base class's constructor + is called with the format that specifies the \l QGL::SampleBuffers flag. + This enables anti-aliasing if it is supported by your system's OpenGL + driver. + + The \c animate() slot is exactly the same as that provided by the \c Widget + class: + + \snippet 2dpainting/glwidget.cpp 1 + + The \c paintEvent() is almost the same as that found in the \c Widget class: + + \snippet 2dpainting/glwidget.cpp 2 + + Since anti-aliasing will be enabled if available, we only need to set up + a QPainter on the widget and call the helper's \c paint() function to display + the widget's contents. + + \section1 Window Class Definition + + The \c Window class has a basic, minimal definition: + + \snippet 2dpainting/window.h 0 + + It contains a single \c Helper object that will be shared between all + widgets. + + \section1 Window Class Implementation + + The constructor does all the work, creating a widget of each type and + inserting them with labels into a layout: + + \snippet 2dpainting/window.cpp 0 + + A timer with a 50 millisecond time out is constructed for animation purposes, + and connected to the \c animate() slots of the \c Widget and \c GLWidget objects. + Once started, the widgets should be updated at around 20 frames per second. + + \section1 Running the Example + + The example shows the same painting operations performed at the same time + in a \c Widget and a \c GLWidget. The quality and speed of rendering in the + \c GLWidget depends on the level of support for multisampling and hardware + acceleration that your system's OpenGL driver provides. If support for either + of these is lacking, the driver may fall back on a software renderer that + may trade quality for speed. +*/ diff --git a/examples/opengl/doc/src/cube.qdoc b/examples/opengl/doc/src/cube.qdoc new file mode 100644 index 0000000000..578c0c9ef9 --- /dev/null +++ b/examples/opengl/doc/src/cube.qdoc @@ -0,0 +1,178 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** GNU Lesser General Public License Usage +** This file may be used under the terms of the GNU Lesser General Public +** License version 2.1 as published by the Free Software Foundation and +** appearing in the file LICENSE.LGPL included in the packaging of this +** file. Please review the following information to ensure the GNU Lesser +** General Public License version 2.1 requirements will be met: +** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU General +** Public License version 3.0 as published by the Free Software Foundation +** and appearing in the file LICENSE.GPL included in the packaging of this +** file. Please review the following information to ensure the GNU General +** Public License version 3.0 requirements will be met: +** http://www.gnu.org/copyleft/gpl.html. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms and +** conditions contained in a signed written agreement between you and Nokia. +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example cube + \group all-examples + \title Cube OpenGL ES 2.0 example + + The Cube OpenGL ES 2.0 example shows how to write mouse rotateable + textured 3D cube using OpenGL ES 2.0 with Qt. It shows how to handle + polygon geometries efficiently and how to write simple vertex and + fragment shader for programmable graphics pipeline. In addition it + shows how to use quaternions for representing 3D object orientation. + + This example has been written for OpenGL ES 2.0 but it works also on + desktop OpenGL because this example is simple enough and for the + most parts desktop OpenGL API is same. It compiles also without OpenGL + support but then it just shows a label stating that OpenGL support is + required. + + \image cube.png Screenshot of the Cube example running on N900 + + The example consist of two classes: + + \list + \li \c MainWidget extends QGLWidget and contains OpenGL ES 2.0 + initialization and drawing and mouse and timer event handling + \li \c GeometryEngine handles polygon geometries. Transfers polygon geometry + to vertex buffer objects and draws geometries from vertex buffer objects. + \endlist + + We'll start by initializing OpenGL ES 2.0 in \c MainWidget. + + \tableofcontents + + \section1 Initializing OpenGL ES 2.0 + + Since OpenGL ES 2.0 doesn't support fixed graphics pipeline anymore it has to + be implemented by ourselves. This makes graphics pipeline very flexible but + in the same time it becomes more difficult because user has to implement graphics + pipeline to get even the simplest example running. It also makes graphics pipeline + more efficient because user can decide what kind of pipeline is needed for the + application. + + First we have to implement vertex shader. It gets vertex data and + model-view-projection matrix (MVP) as parameters. It transforms vertex position + using MVP matrix to screen space and passes texture coordinate to + fragment shader. Texture coordinate will be automatically interpolated on polygon + faces. + + \snippet cube/vshader.glsl 0 + + After that we need to implement second part of the graphics pipeline - fragment + shader. For this exercise we need to implement fragment shader that handles + texturing. It gets interpolated texture coordinate as a parameter and looks up + fragment color from the given texture. + + \snippet cube/fshader.glsl 0 + + Using \c QGLShaderProgram we can compile, link and bind shader code to + graphics pipeline. This code uses Qt Resource files to access shader source code. + + \snippet cube/mainwidget.cpp 3 + + The following code enables depth buffering and back face culling. + + \snippet cube/mainwidget.cpp 2 + + \section1 Loading textures from Qt Resource files + + \c QGLWidget interface implements methods for loading textures from QImage to GL + texture memory. We still need to use OpenGL provided functions for specifying + the GL texture unit and configuring texture filtering options. + + \snippet cube/mainwidget.cpp 4 + + \section1 Cube Geometry + + There are many ways to render polygons in OpenGL but the most efficient way is + to use only triangle strip primitives and render vertices from graphics hardware + memory. OpenGL has a mechanism to create buffer objects to this memory area and + transfer vertex data to these buffers. In OpenGL terminology these are referred + as Vertex Buffer Objects (VBO). + + \image cube_faces.png Cube faces and vertices + + This is how cube faces break down to triangles. Vertices are ordered this way + to get vertex ordering correct using triangle strips. OpenGL determines triangle + front and back face based on vertex ordering. By default OpenGL uses + counter-clockwise order for front faces. This information is used by back face + culling which improves rendering performance by not rendering back faces of the + triangles. This way graphics pipeline can omit rendering sides of the triangle that + aren't facing towards screen. + + Creating vertex buffer objects and transferring data to them is quite simple using + OpenGL provided functions. + + \snippet cube/geometryengine.cpp 0 + + \snippet cube/geometryengine.cpp 1 + + Drawing primitives from VBOs and telling programmable graphics pipeline how to + locate vertex data requires few steps. First we need to bind VBOs to be used. + After that we bind shader program attribute names and configure what + kind of data it has in the bound VBO. Finally we'll draw triangle + strip primitives using indices from the other VBO. + + \snippet cube/geometryengine.cpp 2 + + \section1 Perspective projection + + Using \c QMatrix4x4 helper methods it's really easy to calculate perpective + projection matrix. This matrix is used to project vertices to screen space. + + \snippet cube/mainwidget.cpp 5 + + \section1 Orientation of the 3D object + + Quaternions are handy way to represent orientation of the 3D object. Quaternions + involve quite complex mathematics but fortunately all the necessary mathematics + behind quaternions is implemented in \c QQuaternion. That allows us to store + cube orientation in quaternion and rotating cube around given axis is quite + simple. + + The following code calculates rotation axis and angular speed based on mouse events. + + \snippet cube/mainwidget.cpp 0 + + \c QBasicTimer is used to animate scene and update cube orientation. Rotations + can be concatenated simply by multiplying quaternions. + + \snippet cube/mainwidget.cpp 1 + + Model-view matrix is calculated using the quaternion and by moving world by Z axis. + This matrix is multiplied with the projection matrix to get MVP matrix for shader + program. + + \snippet cube/mainwidget.cpp 6 + +*/ diff --git a/examples/opengl/doc/src/framebufferobject2.qdoc b/examples/opengl/doc/src/framebufferobject2.qdoc new file mode 100644 index 0000000000..44b6fc6018 --- /dev/null +++ b/examples/opengl/doc/src/framebufferobject2.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example framebufferobject2 + \title Framebuffer Object 2 Example + + The Framebuffer Object 2 example demonstrates how to use the + QGLFramebufferObject class to render into an off-screen buffer and + use the contents as a texture in a QGLWidget. + + \image framebufferobject2-example.png +*/ diff --git a/examples/opengl/doc/src/grabber.qdoc b/examples/opengl/doc/src/grabber.qdoc new file mode 100644 index 0000000000..12e1483c9a --- /dev/null +++ b/examples/opengl/doc/src/grabber.qdoc @@ -0,0 +1,35 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example grabber + \title Grabber Example + + The Grabber examples shows how to retrieve the contents of an OpenGL framebuffer. + + \image grabber-example.png +*/ diff --git a/examples/opengl/doc/src/hellogl.qdoc b/examples/opengl/doc/src/hellogl.qdoc new file mode 100644 index 0000000000..2f866a3642 --- /dev/null +++ b/examples/opengl/doc/src/hellogl.qdoc @@ -0,0 +1,305 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example hellogl + \title Hello GL Example + + The Hello GL example demonstrates the basic use of the OpenGL-related classes + provided with Qt. + + \image hellogl-example.png + + Qt provides the QGLWidget class to enable OpenGL graphics to be rendered within + a standard application user interface. By subclassing this class, and providing + reimplementations of event handler functions, 3D scenes can be displayed on + widgets that can be placed in layouts, connected to other objects using signals + and slots, and manipulated like any other widget. + + \tableofcontents + + \section1 GLWidget Class Definition + + The \c GLWidget class contains some standard public definitions for the + constructor, destructor, \l{QWidget::sizeHint()}{sizeHint()}, and + \l{QWidget::minimumSizeHint()}{minimumSizeHint()} functions: + + \snippet hellogl/glwidget.h 0 + + We use a destructor to ensure that any OpenGL-specific data structures + are deleted when the widget is no longer needed (although in this case nothing + needs cleaning up). + + \snippet hellogl/glwidget.h 1 + + The signals and slots are used to allow other objects to interact with the + 3D scene. + + \snippet hellogl/glwidget.h 2 + + OpenGL initialization, viewport resizing, and painting are handled by + reimplementing the QGLWidget::initializeGL(), QGLWidget::resizeGL(), and + QGLWidget::paintGL() handler functions. To enable the user to interact + directly with the scene using the mouse, we reimplement + QWidget::mousePressEvent() and QWidget::mouseMoveEvent(). + + \snippet hellogl/glwidget.h 3 + + The rest of the class contains utility functions and variables that are + used to construct and hold orientation information for the scene. The + \c logo variable will be used to hold a pointer to the QtLogo object which + contains all the geometry. + + \section1 GLWidget Class Implementation + + In this example, we split the class into groups of functions and describe + them separately. This helps to illustrate the differences between subclasses + of native widgets (such as QWidget and QFrame) and QGLWidget subclasses. + + \section2 Widget Construction and Sizing + + The constructor provides default rotation angles for the scene, sets + the pointer to the QtLogo object to null, and sets up some colors for + later use. + + \snippet hellogl/glwidget.cpp 0 + + We also implement a destructor to release OpenGL-related resources when the + widget is deleted: + + \snippet hellogl/glwidget.cpp 1 + + In this case nothing requires cleaning up. + + We provide size hint functions to ensure that the widget is shown at a + reasonable size: + + \snippet hellogl/glwidget.cpp 2 + \codeline + \snippet hellogl/glwidget.cpp 3 + \snippet hellogl/glwidget.cpp 4 + + The widget provides three slots that enable other components in the + example to change the orientation of the scene: + + \snippet hellogl/glwidget.cpp 5 + + In the above slot, the \c xRot variable is updated only if the new angle + is different to the old one, the \c xRotationChanged() signal is emitted to + allow other components to be updated, and the widget's + \l{QGLWidget::updateGL()}{updateGL()} handler function is called. + + The \c setYRotation() and \c setZRotation() slots perform the same task for + rotations measured by the \c yRot and \c zRot variables. + + \section2 OpenGL Initialization + + The \l{QGLWidget::initializeGL()}{initializeGL()} function is used to + perform useful initialization tasks that are needed to render the 3D scene. + These often involve defining colors and materials, enabling and disabling + certain rendering flags, and setting other properties used to customize the + rendering process. + + \snippet hellogl/glwidget.cpp 6 + + In this example, we reimplement the function to set the background color, + create a QtLogo object instance which will contain all the geometry to + display, and set up the rendering process to use a particular shading model + and rendering flags. + + \section2 Resizing the Viewport + + The \l{QGLWidget::resizeGL()}{resizeGL()} function is used to ensure that + the OpenGL implementation renders the scene onto a viewport that matches the + size of the widget, using the correct transformation from 3D coordinates to + 2D viewport coordinates. + + The function is called whenever the widget's dimensions change, and is + supplied with the new width and height. Here, we define a square viewport + based on the length of the smallest side of the widget to ensure that + the scene is not distorted if the widget has sides of unequal length: + + \snippet hellogl/glwidget.cpp 8 + + A discussion of the projection transformation used is outside the scope of + this example. Please consult the OpenGL reference documentation for an + explanation of projection matrices. + + \section2 Painting the Scene + + The \l{QGLWidget::paintGL()}{paintGL()} function is used to paint the + contents of the scene onto the widget. For widgets that only need to be + decorated with pure OpenGL content, we reimplement QGLWidget::paintGL() + \e instead of reimplementing QWidget::paintEvent(): + + \snippet hellogl/glwidget.cpp 7 + + In this example, we clear the widget using the background color that + we defined in the \l{QGLWidget::initializeGL()}{initializeGL()} function, + set up the frame of reference for the geometry we want to display, and + call the draw method of the QtLogo object to render the scene. + + \section2 Mouse Handling + + Just as in subclasses of native widgets, mouse events are handled by + reimplementing functions such as QWidget::mousePressEvent() and + QWidget::mouseMoveEvent(). + + The \l{QWidget::mousePressEvent()}{mousePressEvent()} function simply + records the position of the mouse when a button is initially pressed: + + \snippet hellogl/glwidget.cpp 9 + + The \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} function uses the + previous location of the mouse cursor to determine how much the object + in the scene should be rotated, and in which direction: + + \snippet hellogl/glwidget.cpp 10 + + Since the user is expected to hold down the mouse button and drag the + cursor to rotate the object, the cursor's position is updated every time + a move event is received. + + \section1 QtLogo Class + + This class encapsulates the OpenGL geometry data which will be rendered + in the basic 3D scene. + + \snippet shared/qtlogo.h 0 + + The geometry is divided into a list of parts which may be rendered in + different ways. The data itself is contained in a Geometry structure that + includes the vertices, their lighting normals and index values which + point into the vertices, grouping them into faces. + + \snippet shared/qtlogo.cpp 0 + + The data in the Geometry class is stored in QVector<QVector3D> members + which are convenient for use with OpenGL because they expose raw + contiguous floating point values via the constData() method. Methods + are included for adding new vertex data, either with smooth normals, or + facetted normals; and for enabling the geometry ready for rendering. + + \snippet shared/qtlogo.cpp 1 + + The higher level Patch class has methods for accumulating the geometry + one face at a time, and treating collections of faces or "patches" with + transformations, applying different colors or smoothing. Although faces + may be added as triangles or quads, at the OpenGL level all data is + treated as triangles for compatibility with OpenGL/ES. + + \snippet shared/qtlogo.cpp 2 + + Drawing a Patch is simply acheived by applying any transformation, + and material effect, then drawing the data using the index range for + the patch. The model-view matrix is saved and then restored so that + any transformation does not affect other parts of the scene. + + \snippet shared/qtlogo.cpp 3 + + The geometry is built once on construction of the QtLogo, and it is + paramaterized on a number of divisions - which controls how "chunky" the + curved section of the logo looks - and on a scale, so larger and smaller + QtLogo objects can be created without having to use OpenGL scaling + (which would force normal recalculation). + + The building process is done by helper classes (read the source for full + details) which only exist during the build phase, to assemble the parts + of the scene. + + \snippet shared/qtlogo.cpp 4 + + Finally the complete QtLogo scene is simply drawn by enabling the data arrays + and then iterating over the parts, calling draw() on each one. + + \section1 Window Class Definition + + The \c Window class is used as a container for the \c GLWidget used to + display the scene: + + \snippet hellogl/window.h 0 + + In addition, it contains sliders that are used to change the orientation + of the object in the scene. + + \section1 Window Class Implementation + + The constructor constructs an instance of the \c GLWidget class and some + sliders to manipulate its contents. + + \snippet hellogl/window.cpp 0 + + We connect the \l{QAbstractSlider::valueChanged()}{valueChanged()} signal + from each of the sliders to the appropriate slots in \c{glWidget}. + This allows the user to change the orientation of the object by dragging + the sliders. + + We also connect the \c xRotationChanged(), \c yRotationChanged(), and + \c zRotationChanged() signals from \c glWidget to the + \l{QAbstractSlider::setValue()}{setValue()} slots in the + corresponding sliders. + + \snippet hellogl/window.cpp 1 + + The sliders are placed horizontally in a layout alongside the \c GLWidget, + and initialized with suitable default values. + + The \c createSlider() utility function constructs a QSlider, and ensures + that it is set up with a suitable range, step value, tick interval, and + page step value before returning it to the calling function: + + \snippet hellogl/window.cpp 2 + + \section1 Summary + + The \c GLWidget class implementation shows how to subclass QGLWidget for + the purposes of rendering a 3D scene using OpenGL calls. Since QGLWidget + is a subclass of QWidget, subclasses of QGLWidget can be placed in layouts + and provided with interactive features just like normal custom widgets. + + We ensure that the widget is able to correctly render the scene using OpenGL + by reimplementing the following functions: + + \list + \li QGLWidget::initializeGL() sets up resources needed by the OpenGL implementation + to render the scene. + \li QGLWidget::resizeGL() resizes the viewport so that the rendered scene fits onto + the widget, and sets up a projection matrix to map 3D coordinates to 2D viewport + coordinates. + \li QGLWidget::paintGL() performs painting operations using OpenGL calls. + \endlist + + Since QGLWidget is a subclass of QWidget, it can also be used + as a normal paint device, allowing 2D graphics to be drawn with QPainter. + This use of QGLWidget is discussed in the \l{2D Painting Example}{2D Painting} + example. + + More advanced users may want to paint over parts of a scene rendered using + OpenGL. QGLWidget allows pure OpenGL rendering to be mixed with QPainter + calls, but care must be taken to maintain the state of the OpenGL implementation. + See the \l{Overpainting Example}{Overpainting} example for more information. +*/ diff --git a/examples/opengl/doc/src/hellogl_es.qdoc b/examples/opengl/doc/src/hellogl_es.qdoc new file mode 100644 index 0000000000..8764eda4d6 --- /dev/null +++ b/examples/opengl/doc/src/hellogl_es.qdoc @@ -0,0 +1,128 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example hellogl_es + \title Hello GL ES Example + + The Hello GL ES example is the \l{Hello GL Example} ported to OpenGL ES. + It also included some effects from the OpenGL \l{Overpainting Example}. + + \image hellogl-es-example.png + + A complete introduction to OpenGL ES and a description of all differences + between OpenGL and OpenGL ES is out of the scope of this document; but + we will describe some of the major issues and differences. + + Since Hello GL ES is a direct port of standard OpenGL code, it is a fairly + good example for porting OpenGL code to OpenGL ES. + + \tableofcontents + + \section1 Using QGLWidget + + QGLWidget can be used for OpenGL ES similar to the way it is used with + standard OpenGL; but there are some differences. We use EGL 1.0 to embedd + the OpenGL ES window within the native window manager. In + QGLWidget::initializeGL() we initialize OpenGL ES. + + \section1 Porting OpenGL to OpenGL ES + + Since OpenGL ES is missing the immediate mode and does not support quads, + we have to create triangle arrays. + + We create a quad by adding vertices to a QList of vertices. We create both + sides of the quad and hardcode a distance of 0.05f. We also compute the + correct normal for each face and store them in another QList. + + \snippet hellogl_es/glwidget.cpp 0 + + And then we convert the complete list of vertexes and the list of normals + into the native OpenGL ES format that we can use with the OpenGL ES API. + + \snippet hellogl_es/glwidget.cpp 1 + + In \c paintQtLogo() we draw the triangle array using OpenGL ES. We use + q_vertexTypeEnum to abstract the fact that our vertex and normal arrays + are either in float or in fixed point format. + + \snippet hellogl_es/glwidget.cpp 2 + + \section1 Using QGLPainter + + Since the \c QGLPainter is slower for OpenGL ES we paint the bubbles with + the rasterizer and cache them in a QImage. This happends only once during + the initialiazation. + + \snippet hellogl_es/bubble.cpp 0 + + For each bubble this QImage is then drawn to the QGLWidget by using the + according QPainter with transparency enabled. + + \snippet hellogl_es/bubble.cpp 1 + + Another difference beetwen OpenGL and OpenGL ES is that OpenGL ES does not + support glPushAttrib(GL_ALL_ATTRIB_BITS). So we have to restore all the + OpenGL states ourselves, after we created the QPainter in + GLWidget::paintGL(). + + \snippet hellogl_es/glwidget.cpp 3 + + Setting up up the model view matrix and setting the right OpenGL states is + done in the same way as for standard OpenGL. + + \snippet hellogl_es/glwidget.cpp 4 + + Now we have to restore the OpenGL state for the QPainter. This is not done + automatically for OpenGL ES. + + \snippet hellogl_es/glwidget.cpp 5 + + Now we use the QPainter to draw the transparent bubbles. + + \snippet hellogl_es/glwidget.cpp 6 + + In the end, we calculate the framerate and display it using the QPainter + again. + + \snippet hellogl_es/glwidget.cpp 7 + + After we finished all the drawing operations we swap the screen buffer. + + \snippet hellogl_es/glwidget.cpp 8 + + \section1 Summary + + Similar to the \l{Hello GL Example}, we subclass QGLWidget to render + a 3D scene using OpenGL ES calls. QGLWidget is a subclass of QWidget. + Hence, its \l{QGLWidget}'s subclasses can be placed in layouts and + provided with interactive features just like normal custom widgets. + + QGLWidget allows pure OpenGL ES rendering to be mixed with QPainter calls, + but care must be taken to maintain the state of the OpenGL ES + implementation. +*/ diff --git a/examples/opengl/doc/src/overpainting.qdoc b/examples/opengl/doc/src/overpainting.qdoc new file mode 100644 index 0000000000..e24af4c3ca --- /dev/null +++ b/examples/opengl/doc/src/overpainting.qdoc @@ -0,0 +1,243 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example overpainting + \title Overpainting Example + + The Overpainting example shows how QPainter can be used + to overpaint a scene rendered using OpenGL in a QGLWidget. + + \image overpainting-example.png + + QGLWidget provides a widget with integrated OpenGL graphics support + that enables 3D graphics to be displayed using normal OpenGL calls, + yet also behaves like any other standard Qt widget with support for + signals and slots, properties, and Qt's action system. + + Usually, QGLWidget is subclassed to display a pure 3D scene. The + developer reimplements \l{QGLWidget::initializeGL()}{initializeGL()} + to initialize any required resources, \l{QGLWidget::resizeGL()}{resizeGL()} + to set up the projection and viewport, and + \l{QGLWidget::paintGL()}{paintGL()} to perform the OpenGL calls needed + to render the scene. However, it is possible to subclass QGLWidget + differently to allow 2D graphics, drawn using QPainter, to be + painted over a scene rendered using OpenGL. + + In this example, we demonstrate how this is done by reusing the code + from the \l{Hello GL Example}{Hello GL} example to provide a 3D scene, + and painting over it with some translucent 2D graphics. Instead of + examining each class in detail, we only cover the parts of the + \c GLWidget class that enable overpainting, and provide more detailed + discussion in the final section of this document. + + \section1 GLWidget Class Definition + + The \c GLWidget class is a subclass of QGLWidget, based on the one used + in the \l{Hello GL Example}{Hello GL} example. Rather than describe the + class as a whole, we show the first few lines of the class and only + discuss the changes we have made to the rest of it: + + \snippet overpainting/glwidget.h 0 + \dots + \snippet overpainting/glwidget.h 1 + \dots + \snippet overpainting/glwidget.h 4 + + As usual, the widget uses \l{QGLWidget::initializeGL()}{initializeGL()} + to set up geometry for our scene and perform OpenGL initialization tasks. + The \l{QGLWidget::resizeGL()}{resizeGL()} function is used to ensure that + the 3D graphics in the scene are transformed correctly to the 2D viewport + displayed in the widget. + + Instead of implementing \l{QGLWidget::paintGL()}{paintGL()} to handle updates + to the widget, we implement a normal QWidget::paintEvent(). This + allows us to mix OpenGL calls and QPainter operations in a controlled way. + + In this example, we also implement QWidget::showEvent() to help with the + initialization of the 2D graphics used. + + The new private member functions and variables relate exclusively to the + 2D graphics and animation. The \c animate() slot is called periodically by the + \c animationTimer to update the widget; the \c createBubbles() function + initializes the \c bubbles list with instances of a helper class used to + draw the animation; the \c drawInstructions() function is responsible for + a semi-transparent message that is also overpainted onto the OpenGL scene. + + \section1 GLWidget Class Implementation + + Again, we only show the parts of the \c GLWidget implementation that are + relevant to this example. In the constructor, we initialize a QTimer to + control the animation: + + \snippet overpainting/glwidget.cpp 0 + + We turn off the widget's \l{QWidget::autoFillBackground}{autoFillBackground} property to + instruct OpenGL not to paint a background for the widget when + \l{QPainter::begin()}{QPainter::begin()} is called. + + As in the \l{Hello GL Example}{Hello GL} example, the destructor is responsible + for freeing any OpenGL-related resources: + + \snippet overpainting/glwidget.cpp 1 + + The \c initializeGL() function is fairly minimal, only setting up the QtLogo + object used in the scene. See the \l{Hello GL Example}{Hello GL} example + for details of the QtLogo class. + + \snippet overpainting/glwidget.cpp 2 + + To cooperate fully with QPainter, we defer matrix stack operations and attribute + initialization until the widget needs to be updated. + + In this example, we implement \l{QWidget::paintEvent()}{paintEvent()} rather + than \l{QGLWidget::paintGL()}{paintGL()} to render + our scene. When drawing on a QGLWidget, the paint engine used by QPainter + performs certain operations that change the states of the OpenGL + implementation's matrix and property stacks. Therefore, it is necessary to + make all the OpenGL calls to display the 3D graphics before we construct + a QPainter to draw the 2D overlay. + + We render a 3D scene by setting up model and projection transformations + and other attributes. We use an OpenGL stack operation to preserve the + original matrix state, allowing us to recover it later: + + \snippet overpainting/glwidget.cpp 4 + + We define a color to use for the widget's background, and set up various + attributes that define how the scene will be rendered. + + \snippet overpainting/glwidget.cpp 6 + + We call the \c setupViewport() private function to set up the + projection used for the scene. This is unnecessary in OpenGL + examples that implement the \l{QGLWidget::paintGL()}{paintGL()} + function because the matrix stacks are usually unmodified between + calls to \l{QGLWidget::resizeGL()}{resizeGL()} and + \l{QGLWidget::paintGL()}{paintGL()}. + + Since the widget's background is not drawn by the system or by Qt, we use + an OpenGL call to paint it before positioning the object defined earlier + in the scene: + + \snippet overpainting/glwidget.cpp 7 + + Once the QtLogo object's draw method has been executed, the GL + states we changed and the matrix stack needs to be restored to its + original state at the start of this function before we can begin + overpainting: + + \snippet overpainting/glwidget.cpp 8 + + With the 3D graphics done, we construct a QPainter for use on the widget + and simply overpaint the widget with 2D graphics; in this case, using a + helper class to draw a number of translucent bubbles onto the widget, + and calling \c drawInstructions() to overlay some instructions: + + \snippet overpainting/glwidget.cpp 10 + + When QPainter::end() is called, suitable OpenGL-specific calls are made to + write the scene, and its additional contents, onto the widget. + + With \l{QGLWidget::paintGL()}{paintGL()} the + \l{QGLWidget::swapBuffers()}{swapBuffers()} call is done for us. But an explicit + call to swapBuffers() is still not required because in the + \l{QWidget::paintEvent()}{paintEvent()} method the QPainter on the OpenGL + widget takes care of this for us. + + The implementation of the \l{QGLWidget::resizeGL()}{resizeGL()} function + sets up the dimensions of the viewport and defines a projection + transformation: + + \snippet overpainting/glwidget.cpp 11 + + Ideally, we want to arrange the 2D graphics to suit the widget's dimensions. + To achieve this, we implement the \l{QWidget::showEvent()}{showEvent()} handler, + creating new graphic elements (bubbles) if necessary at appropriate positions + in the widget. + + \snippet overpainting/glwidget.cpp 12 + + This function only has an effect if less than 20 bubbles have already been + created. + + The \c animate() slot is called every time the widget's \c animationTimer emits + the \l{QTimer::timeout()}{timeout()} signal. This keeps the bubbles moving + around. + + \snippet overpainting/glwidget.cpp 13 + + We simply iterate over the bubbles in the \c bubbles list, updating the + widget before and after each of them is moved. + + The \c setupViewport() function is called from \c paintEvent() + and \c resizeGL(). + + \snippet overpainting/glwidget.cpp 14 + + The \c drawInstructions() function is used to prepare some basic + instructions that will be painted with the other 2D graphics over + the 3D scene. + + \snippet overpainting/glwidget.cpp 15 + + \section1 Summary + + When overpainting 2D content onto 3D content, we need to use a QPainter + \e and make OpenGL calls to achieve the desired effect. Since QPainter + itself uses OpenGL calls when used on a QGLWidget subclass, we need to + preserve the state of various OpenGL stacks when we perform our own + calls, using the following approach: + + \list + \li Reimplement QGLWidget::initializeGL(), but only perform minimal + initialization. QPainter will perform its own initialization + routines, modifying the matrix and property stacks, so it is better + to defer certain initialization tasks until just before you render + the 3D scene. + \li Reimplement QGLWidget::resizeGL() as in the pure 3D case. + \li Reimplement QWidget::paintEvent() to draw both 2D and 3D graphics. + \endlist + + The \l{QWidget::paintEvent()}{paintEvent()} implementation performs the + following tasks: + + \list + \li Push the current OpenGL modelview matrix onto a stack. + \li Perform initialization tasks usually done in the + \l{QGLWidget::initializeGL()}{initializeGL()} function. + \li Perform code that would normally be located in the widget's + \l{QGLWidget::resizeGL()}{resizeGL()} function to set the correct + perspective transformation and set up the viewport. + \li Render the scene using OpenGL calls. + \li Pop the OpenGL modelview matrix off the stack. + \li Construct a QPainter object. + \li Initialize it for use on the widget with the QPainter::begin() function. + \li Draw primitives using QPainter's member functions. + \li Call QPainter::end() to finish painting. + \endlist +*/ diff --git a/examples/opengl/doc/src/pbuffers.qdoc b/examples/opengl/doc/src/pbuffers.qdoc new file mode 100644 index 0000000000..baa657e14e --- /dev/null +++ b/examples/opengl/doc/src/pbuffers.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example pbuffers + \title Pixel Buffers Example + + The Pixel Buffers example demonstrates how to use the + QGLPixelBuffer class to render into an off-screen buffer and use + the contents as a dynamic texture in a QGLWidget. + + \image pbuffers-example.png +*/ diff --git a/examples/opengl/doc/src/pbuffers2.qdoc b/examples/opengl/doc/src/pbuffers2.qdoc new file mode 100644 index 0000000000..efa53b06cc --- /dev/null +++ b/examples/opengl/doc/src/pbuffers2.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example pbuffers2 + \title Pixel Buffers 2 Example + + The Pixel Buffers 2 example demonstrates how to use the + QGLPixelBuffer class to render into an off-screen buffer and use + the contents as a dynamic texture in a QGLWidget. + + \image pbuffers2-example.png +*/ diff --git a/examples/opengl/doc/src/samplebuffers.qdoc b/examples/opengl/doc/src/samplebuffers.qdoc new file mode 100644 index 0000000000..93d8b54b4a --- /dev/null +++ b/examples/opengl/doc/src/samplebuffers.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example samplebuffers + \title Sample Buffers Example + + The Sample Buffers example demonstrates how to use and enable + sample buffers in a QGLWidget. + + \image samplebuffers-example.png +*/ diff --git a/examples/opengl/doc/src/textures.qdoc b/examples/opengl/doc/src/textures.qdoc new file mode 100644 index 0000000000..b7e694239d --- /dev/null +++ b/examples/opengl/doc/src/textures.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example textures + \title Textures Example + + The Textures example demonstrates the use of Qt's image classes as textures in + applications that use both OpenGL and Qt to display graphics. + + \image textures-example.png +*/ diff --git a/examples/sql/doc/images/cachedtable-example.png b/examples/sql/doc/images/cachedtable-example.png Binary files differnew file mode 100644 index 0000000000..db770dfdf2 --- /dev/null +++ b/examples/sql/doc/images/cachedtable-example.png diff --git a/examples/sql/doc/images/drilldown-example.png b/examples/sql/doc/images/drilldown-example.png Binary files differnew file mode 100644 index 0000000000..68353f704a --- /dev/null +++ b/examples/sql/doc/images/drilldown-example.png diff --git a/examples/sql/doc/images/masterdetail-example.png b/examples/sql/doc/images/masterdetail-example.png Binary files differnew file mode 100644 index 0000000000..bc282b7a78 --- /dev/null +++ b/examples/sql/doc/images/masterdetail-example.png diff --git a/examples/sql/doc/images/querymodel-example.png b/examples/sql/doc/images/querymodel-example.png Binary files differnew file mode 100644 index 0000000000..908d500e1f --- /dev/null +++ b/examples/sql/doc/images/querymodel-example.png diff --git a/examples/sql/doc/images/relationaltablemodel-example.png b/examples/sql/doc/images/relationaltablemodel-example.png Binary files differnew file mode 100644 index 0000000000..44fc858562 --- /dev/null +++ b/examples/sql/doc/images/relationaltablemodel-example.png diff --git a/examples/sql/doc/images/sql-widget-mapper.png b/examples/sql/doc/images/sql-widget-mapper.png Binary files differnew file mode 100644 index 0000000000..dfa64aba9e --- /dev/null +++ b/examples/sql/doc/images/sql-widget-mapper.png diff --git a/examples/sql/doc/images/sqlbrowser-demo.png b/examples/sql/doc/images/sqlbrowser-demo.png Binary files differnew file mode 100644 index 0000000000..101ec5a0a3 --- /dev/null +++ b/examples/sql/doc/images/sqlbrowser-demo.png diff --git a/examples/sql/doc/images/tablemodel-example.png b/examples/sql/doc/images/tablemodel-example.png Binary files differnew file mode 100644 index 0000000000..3ae2a8c05c --- /dev/null +++ b/examples/sql/doc/images/tablemodel-example.png diff --git a/examples/sql/doc/images/widgetmapper-sql-mapping-table.png b/examples/sql/doc/images/widgetmapper-sql-mapping-table.png Binary files differnew file mode 100644 index 0000000000..98734b34b6 --- /dev/null +++ b/examples/sql/doc/images/widgetmapper-sql-mapping-table.png diff --git a/examples/sql/doc/images/widgetmapper-sql-mapping.png b/examples/sql/doc/images/widgetmapper-sql-mapping.png Binary files differnew file mode 100644 index 0000000000..88718c6a8b --- /dev/null +++ b/examples/sql/doc/images/widgetmapper-sql-mapping.png diff --git a/examples/sql/doc/src/cachedtable.qdoc b/examples/sql/doc/src/cachedtable.qdoc new file mode 100644 index 0000000000..863cbce61e --- /dev/null +++ b/examples/sql/doc/src/cachedtable.qdoc @@ -0,0 +1,197 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example cachedtable + \title Cached Table Example + + The Cached Table example shows how a table view can be used to access a database, + caching any changes to the data until the user explicitly submits them using a + push button. + + \image cachedtable-example.png + + The example consists of a single class, \c TableEditor, which is a + custom dialog widget that allows the user to modify data stored in + a database. We will first review the class definiton and how to + use the class, then we will take a look at the implementation. + + \section1 TableEditor Class Definition + + The \c TableEditor class inherits QDialog making the table editor + widget a top-level dialog window. + + \snippet cachedtable/tableeditor.h 0 + + The \c TableEditor constructor takes two arguments: The first is a + pointer to the parent widget and is passed on to the base class + constructor. The other is a reference to the database table the \c + TableEditor object will operate on. + + Note the QSqlTableModel variable declaration: As we will see in + this example, the QSqlTableModel class can be used to provide data + to view classes such as QTableView. The QSqlTableModel class + provides an editable data model making it possible to read and + write database records from a single table. It is build on top of + the lower-level QSqlQuery class which provides means of executing + and manipulating SQL statements. + + We are also going to show how a table view can be used to cache + any changes to the data until the user explicitly requests to + submit them. For that reason we need to declare a \c submit() slot + in additon to the model and the editor's buttons. + + \table 100% + \header \li Connecting to a Database + \row + \li + + Before we can use the \c TableEditor class, we must create a + connection to the database containing the table we want to edit: + + \snippet cachedtable/main.cpp 0 + + The \c createConnection() function is a helper function provided + for convenience. It is defined in the \c connection.h file which + is located in the \c sql example directory (all the examples in + the \c sql directory use this function to connect to a database). + + \snippet connection.h 0 + + The \c createConnection function opens a connection to an + in-memory SQLITE database and creates a test table. If you want + to use another database, simply modify this function's code. + \endtable + + \section1 TableEditor Class Implementation + + The class implementation consists of only two functions, the + constructor and the \c submit() slot. In the constructor we create + and customize the data model and the various window elements: + + \snippet cachedtable/tableeditor.cpp 0 + + First we create the data model and set the SQL database table we + want the model to operate on. Note that the + QSqlTableModel::setTable() function does not select data from the + table; it only fetches its field information. For that reason we + call the QSqlTableModel::select() function later on, populating + the model with data from the table. The selection can be + customized by specifying filters and sort conditions (see the + QSqlTableModel class documentation for more details). + + We also set the model's edit strategy. The edit strategy dictates + when the changes done by the user in the view, are actually + applied to the database. Since we want to cache the changes in the + table view (i.e. in the model) until the user explicitly submits + them, we choose the QSqlTableModel::OnManualSubmit strategy. The + alternatives are QSqlTableModel::OnFieldChange and + QSqlTableModel::OnRowChange. + + Finally, we set up the labels displayed in the view header using + the \l {QSqlQueryModel::setHeaderData()}{setHeaderData()} function + that the model inherits from the QSqlQueryModel class. + + \snippet cachedtable/tableeditor.cpp 1 + + Then we create a table view. The QTableView class provides a + default model/view implementation of a table view, i.e. it + implements a table view that displays items from a model. It also + allows the user to edit the items, storing the changes in the + model. To create a read only view, set the proper flag using the + \l {QAbstractItemView::editTriggers}{editTriggers} property the + view inherits from the QAbstractItemView class. + + To make the view present our data, we pass our model to the view + using the \l {QAbstractItemView::setModel()}{setModel()} function. + + \snippet cachedtable/tableeditor.cpp 2 + + The \c {TableEditor}'s buttons are regular QPushButton objects. We + add them to a button box to ensure that the buttons are presented + in a layout that is appropriate to the current widget style. The + rationale for this is that dialogs and message boxes typically + present buttons in a layout that conforms to the interface + guidelines for that platform. Invariably, different platforms have + different layouts for their dialogs. QDialogButtonBox allows a + developer to add buttons to it and will automatically use the + appropriate layout for the user's desktop environment. + + Most buttons for a dialog follow certain roles. When adding a + button to a button box using the \l + {QDialogButtonBox}{addButton()} function, the button's role must + be specified using the QDialogButtonBox::ButtonRole + enum. Alternatively, QDialogButtonBox provides several standard + buttons (e.g. \uicontrol OK, \uicontrol Cancel, \uicontrol Save) that you can + use. They exist as flags so you can OR them together in the + constructor. + + \snippet cachedtable/tableeditor.cpp 3 + + We connect the \uicontrol Quit button to the table editor's \l + {QWidget::close()}{close()} slot, and the \uicontrol Submit button to + our private \c submit() slot. The latter slot will take care of + the data transactions. Finally, we connect the \uicontrol Revert button + to our model's \l {QSqlTableModel::revertAll()}{revertAll()} slot, + reverting all pending changes (i.e., restoring the original data). + + \snippet cachedtable/tableeditor.cpp 4 + + In the end we add the button box and the table view to a layout, + install the layout on the table editor widget, and set the + editor's window title. + + \snippet cachedtable/tableeditor.cpp 5 + + The \c submit() slot is called whenever the users hit the \uicontrol + Submit button to save their changes. + + First, we begin a transaction on the database using the + QSqlDatabase::transaction() function. A database transaction is a + unit of interaction with a database management system or similar + system that is treated in a coherent and reliable way independent + of other transactions. A pointer to the used database can be + obtained using the QSqlTableModel::database() function. + + Then, we try to submit all the pending changes, i.e. the model's + modified items. If no error occurs, we commit the transaction to + the database using the QSqlDatabase::commit() function (note that + on some databases, this function will not work if there is an + active QSqlQuery on the database). Otherwise we perform a rollback + of the transaction using the QSqlDatabase::rollback() function and + post a warning to the user. + + \table 100% + \row + \li + \b {See also:} + + A complete list of Qt's SQL \l {Database Classes}, and the \l + {Model/View Programming} documentation. + + \endtable +*/ diff --git a/examples/sql/doc/src/drilldown.qdoc b/examples/sql/doc/src/drilldown.qdoc new file mode 100644 index 0000000000..9a7d0d003b --- /dev/null +++ b/examples/sql/doc/src/drilldown.qdoc @@ -0,0 +1,536 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example drilldown + \title Drill Down Example + + The Drill Down example shows how to read data from a database as + well as submit changes, using the QSqlRelationalTableModel and + QDataWidgetMapper classes. + + \image drilldown-example.png Screenshot of the Drill Down Example + + When running the example application, a user can retrieve + information about each of Nokia's Qt offices by clicking the + corresponding image. The application pops up an information window + displaying the data, and allows the users to alter the location + description as well as the image. The main view will be updated + when the users submit their changes. + + The example consists of three classes: + + \list + \li \c ImageItem is a custom graphics item class used to + display the office images. + + \li \c View is the main application widget allowing the user to + browse through the various locations. + + \li \c InformationWindow displays the requested information, + allowing the users to alter it and submit their changes to the + database. + \endlist + + We will first take a look at the \c InformationWindow class to see + how you can read and modify data from a database. Then we will + review the main application widget, i.e., the \c View class, and + the associated \c ImageItem class. + + \section1 InformationWindow Class Definition + + The \c InformationWindow class is a custom widget inheriting + QWidget: + + \snippet drilldown/informationwindow.h 0 + + When we create an information window, we pass the associated + location ID, a parent, and a pointer to the database, to the + constructor. We will use the database pointer to populate our + window with data, while passing the parent parameter on to the + base class. The ID is stored for future reference. + + Once a window is created, we will use the public \c id() function + to locate it whenever information for the given location is + requested. We will also use the ID to update the main application + widget when the users submit their changes to the database, i.e., + we will emit a signal carrying the ID and file name as parameters + whenever the users changes the associated image. + + \snippet drilldown/informationwindow.h 1 + + Since we allow the users to alter some of the location data, we + must provide functionality for reverting and submitting their + changes. The \c enableButtons() slot is provided for convenience + to enable and disable the various buttons when required. + + \snippet drilldown/informationwindow.h 2 + + The \c createButtons() function is also a convenience function, + provided to simplify the constructor. As mentioned above we store + the location ID for future reference. We also store the name of + the currently displayed image file to be able to determine when to + emit the \c imageChanged() signal. + + The information window uses the QLabel class to display the office + location and the country. The associated image file is displayed + using a QComboBox instance while the description is displayed using + QTextEdit. In addition, the window has three buttons to control + the data flow and whether the window is shown or not. + + Finally, we declare a \e mapper. The QDataWidgetMapper class + provides mapping between a section of a data model to widgets. We + will use the mapper to extract data from the given database, + updating the database whenever the user modifies the data. + + \section1 InformationWindow Class Implementation + + The constructor takes three arguments: a location ID, a database + pointer and a parent widget. The database pointer is actually a + pointer to a QSqlRelationalTableModel object providing an editable + data model (with foreign key support) for our database table. + + \snippet drilldown/informationwindow.cpp 0 + \snippet drilldown/informationwindow.cpp 1 + + First we create the various widgets required to display the data + contained in the database. Most of the widgets are created in a + straight forward manner. But note the combobox displaying the + name of the image file: + + \snippet drilldown/informationwindow.cpp 2 + + In this example, the information about the offices are stored in a + database table called "offices". When creating the model, + we will use a foreign key to establish a relation between this + table and a second data base table, "images", containing the names + of the available image files. We will get back to how this is done + when reviewing the \c View class. The rationale for creating such + a relation though, is that we want to ensure that the user only + can choose between predefined image files. + + The model corresponding to the "images" database table, is + available through the QSqlRelationalTableModel's \l + {QSqlRelationalTableModel::}{relationModel()} function, requiring + the foreign key (in this case the "imagefile" column number) as + argument. We use QComboBox's \l {QComboBox::}{setModel()} function + to make the combobox use the "images" model. And, since this model + has two columns ("locationid" and "file"), we also specify which + column we want to be visible using the QComboBox::setModelColumn() + function. + + \snippet drilldown/informationwindow.cpp 3 + + Then we create the mapper. The QDataWidgetMapper class allows us + to create data-aware widgets by mapping them to sections of an + item model. + + The \l {QDataWidgetMapper::}{addMapping()} function adds a mapping + between the given widget and the specified section of the + model. If the mapper's orientation is horizontal (the default) the + section is a column in the model, otherwise it is a row. We call + the \l {QDataWidgetMapper::}{setCurrentIndex()} function to + initialize the widgets with the data associated with the given + location ID. Every time the current index changes, all the widgets + are updated with the contents from the model. + + We also set the mapper's submit policy to + QDataWidgetMapper::ManualSubmit. This means that no data is + submitted to the database until the user expliclity requests a + submit (the alternative is QDataWidgetMapper::AutoSubmit, + automatically submitting changes when the corresponding widget + looses focus). Finally, we specify the item delegate the mapper + view should use for its items. The QSqlRelationalDelegate class + represents a delegate that unlike the default delegate, enables + combobox functionality for fields that are foreign keys into other + tables (like "imagefile" in our "trolltechoffices" table). + + \snippet drilldown/informationwindow.cpp 4 + + Finally, we connect the "something's changed" signals in the + editors to our custom \c enableButtons() slot, enabling the users + to either submit or revert their changes. We add all the widgets + into a layout, store the location ID and the name of the displayed + image file for future reference, and set the window title and + initial size. + + Note that we also set the Qt::Window window flag to indicate that + our widget is in fact a window, with a window system frame and a + title bar. + + \snippet drilldown/informationwindow.cpp 5 + + When a window is created, it is not deleted until the main + application exits (i.e., if the user closes the information + window, it is only hidden). For this reason we do not want to + create more than one \c InformationWindow object for each + location, and we provide the public \c id() function to be able to + determine whether a window already exists for a given location + when the user requests information about it. + + \snippet drilldown/informationwindow.cpp 6 + + The \c revert() slot is triggered whenever the user hits the \uicontrol + Revert button. + + Since we set the QDataWidgetMapper::ManualSubmit submit policy, + none of the user's changes are written back to the model unless + the user expliclity choose to submit all of them. Nevertheless, we + can use the QDataWidgetMapper's \l {QDataWidgetMapper::}{revert()} + slot to reset the editor widgets, repopulating all widgets with + the current data of the model. + + \snippet drilldown/informationwindow.cpp 7 + + Likewise, the \c submit() slot is triggered whenever the users + decide to submit their changes by pressing the \uicontrol Submit button. + + We use QDataWidgetMapper's \l {QDataWidgetMapper::}{submit()} slot + to submit all changes from the mapped widgets to the model, + i.e. to the database. For every mapped section, the item delegate + will then read the current value from the widget and set it in the + model. Finally, the \e model's \l {QAbstractItemModel::}{submit()} + function is invoked to let the model know that it should submit + whatever it has cached to the permanent storage. + + Note that before any data is submitted, we check if the user has + chosen another image file using the previously stored \c + displayedImage variable as reference. If the current and stored + file names differ, we store the new file name and emit the \c + imageChanged() signal. + + \snippet drilldown/informationwindow.cpp 8 + + The \c createButtons() function is provided for convenience, i.e., + to simplify the constructor. + + We make the \uicontrol Close button the default button, i.e., the button + that is pressed when the user presses \uicontrol Enter, and connect its + \l {QPushButton::}{clicked()} signal to the widget's \l + {QWidget::}{close()} slot. As mentioned above closing the window + only hides the widget; it is not deleted. We also connect the \uicontrol + Submit and \uicontrol Revert buttons to the corresponding \c submit() + and \c revert() slots. + + \snippet drilldown/informationwindow.cpp 9 + + The QDialogButtonBox class is a widget that presents buttons in a + layout that is appropriate to the current widget style. Dialogs + like our information window, typically present buttons in a layout + that conforms to the interface guidelines for that + platform. Invariably, different platforms have different layouts + for their dialogs. QDialogButtonBox allows us to add buttons, + automatically using the appropriate layout for the user's desktop + environment. + + Most buttons for a dialog follow certain roles. We give the \uicontrol + Submit and \uicontrol Revert buttons the \l + {QDialogButtonBox::ButtonRole}{reset} role, i.e., indicating that + pressing the button resets the fields to the default values (in + our case the information contained in the database). The \l + {QDialogButtonBox::ButtonRole}{reject} role indicates that + clicking the button causes the dialog to be rejected. On the other + hand, since we only hide the information window, any changes that + the user has made wil be preserved until the user expliclity + revert or submit them. + + \snippet drilldown/informationwindow.cpp 10 + + The \c enableButtons() slot is called to enable the buttons + whenever the user changes the presented data. Likewise, when the + data the user choose to submit the changes, the buttons are + disabled to indicate that the current data is stored in the + database. + + This completes the \c InformationWindow class. Let's take a look + at how we have used it in our example application. + + \section1 View Class Definition + + The \c View class represents the main application window and + inherits QGraphicsView: + + \snippet drilldown/view.h 0 + \codeline + \snippet drilldown/view.h 1 + + The QGraphicsView class is part of the \l {Graphics View + Framework} which we will use to display the images of Nokia's + Qt offices. To be able to respond to user interaction; + i.e., showing the + appropriate information window whenever the user clicks one of the + office images, we reimplement QGraphicsView's \l + {QGraphicsView::}{mouseReleaseEvent()} function. + + Note that the constructor expects the names of two database + tables: One containing the detailed information about the offices, + and another containing the names of the available image files. We + also provide a private \c updateImage() slot to catch \c + {InformationWindow}'s \c imageChanged() signal that is emitted + whenever the user changes a location's image. + + \snippet drilldown/view.h 2 + + The \c addItems() function is a convenience function provided to + simplify the constructor. It is called only once, creating the + various items and adding them to the view. + + The \c findWindow() function, on the other hand, is frequently + used. It is called from the \c showInformation() function to + detemine whether a window is already created for the given + location (whenever we create an \c InformationWindow object, we + store a reference to it in the \c informationWindows list). The + latter function is in turn called from our custom \c + mouseReleaseEvent() implementation. + + \snippet drilldown/view.h 3 + + Finally we declare a QSqlRelationalTableModel pointer. As + previously mentioned, the QSqlRelationalTableModel class provides + an editable data model with foreign key support. There are a + couple of things you should keep in mind when using the + QSqlRelationalTableModel class: The table must have a primary key + declared and this key cannot contain a relation to another table, + i.e., it cannot be a foreign key. Note also that if a relational + table contains keys that refer to non-existent rows in the + referenced table, the rows containing the invalid keys will not be + exposed through the model. It is the user's or the database's + responsibility to maintain referential integrity. + + \section1 View Class Implementation + + Although the constructor requests the names of both the table + containing office details as well as the table containing the + names of the available image files, we only have to create a + QSqlRelationalTableModel object for the office table: + + \snippet drilldown/view.cpp 0 + + The reason is that once we have a model with the office details, + we can create a relation to the available image files using + QSqlRelationalTableModel's \l + {QSqlRelationalTableModel::}{setRelation()} function. This + function creates a foreign key for the given model column. The key + is specified by the provided QSqlRelation object constructed by + the name of the table the key refers to, the field the key is + mapping to and the field that should be presented to the user. + + Note that setting the table only specifies which table the model + operates on, i.e., we must explicitly call the model's \l + {QSqlRelationalTableModel::}{select()} function to populate our + model. + + \snippet drilldown/view.cpp 1 + + Then we create the contents of our view, i.e., the scene and its + items. The location labels are regular QGraphicsTextItem objects, + and the "Qt" logo is represented by a QGraphicsPixmapItem + object. The images, on the other hand, are instances of the \c + ImageItem class (derived from QGraphicsPixmapItem). We will get + back to this shortly when reviewing the \c addItems() function. + + Finally, we set the main application widget's size constraints and + window title. + + \snippet drilldown/view.cpp 3 + + The \c addItems() function is called only once, i.e., when + creating the main application window. For each row in the database + table, we first extract the corresponding record using the model's + \l {QSqlRelationalTableModel::}{record()} function. The QSqlRecord + class encapsulates both the functionality and characteristics of a + database record, and supports adding and removing fields as well + as setting and retrieving field values. The QSqlRecord::value() + function returns the value of the field with the given name or + index as a QVariant object. + + For each record, we create a label item as well as an image item, + calculate their position and add them to the scene. The image + items are represented by instances of the \c ImageItem class. The + reason we must create a custom item class is that we want to catch + 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{Graphics View Framework} documentation + and the \l{Graphics View Examples} for more details. + + \snippet drilldown/view.cpp 5 + + We reimplement QGraphicsView's \l + {QGraphicsView::}{mouseReleaseEvent()} event handler to respond to + user interaction. If the user clicks any of the image items, this + function calls the private \c showInformation() function to pop up + the associated information window. + + The \l {Graphics View Framework} provides the qgraphicsitem_cast() + function to determine whether the given QGraphicsItem instance is + of a given type. Note that if the event is not related to any of + our image items, we pass it on to the base class implementation. + + \snippet drilldown/view.cpp 6 + + The \c showInformation() function is given an \c ImageItem object + as argument, and starts off by extracting the item's location + ID. Then it determines if there already is created an information + window for this location. If it is, and the window is visible, it + ensures that the window is raised to the top of the widget stack + and activated. If the window exists but is hidden, calling its \l + {QWidget::}{show()} slot gives the same result. + + If no window for the given location exists, we create one by + passing the location ID, a pointer to the model, and our view as a + parent, to the \c InformationWindow constructor. Note that we + connect the information window's \c imageChanged() signal to \e + this widget's \c updateImage() slot, before we give it a suitable + position and add it to the list of existing windows. + + \snippet drilldown/view.cpp 7 + + The \c updateImage() slot takes a location ID and the name of an + image files as arguments. It filters out the image items, and + updates the one that correspond to the given location ID, with the + provided image file. + + \snippet drilldown/view.cpp 8 + + The \c findWindow() function simply searches through the list of + existing windows, returning a pointer to the window that matches + the given location ID, or 0 if the window doesn't exists. + + Finally, let's take a quick look at our custom \c ImageItem class: + + \section1 ImageItem Class Definition + + The \c ImageItem class is provided to facilitate animation of the + image items. It inherits QGraphicsPixmapItem and reimplements its + hover event handlers: + + \snippet drilldown/imageitem.h 0 + + In addition, we implement a public \c id() function to be able to + identify the associated location and a public \c adjust() function + that can be called to ensure that the image item is given the + preferred size regardless of the original image file. + + The animation is implemented using the QTimeLine class together + with the event handlers and the private \c setFrame() slot: The + image item will expand when the mouse cursor hovers over it, + returning back to its original size when the cursor leaves its + borders. + + Finally, we store the location ID that this particular record is + associated with as well as a z-value. In the \l {Graphics View + Framework}, an item's z-value determines its position in the item + stack. An item of high z-value will be drawn on top of an item + with a lower z-value if they share the same parent item. We also + provide an \c updateItemPosition() function to refresh the view + when required. + + \section1 ImageItem Class Implementation + + The \c ImageItem class is really only a QGraphicsPixmapItem with + some additional features, i.e., we can pass most of the + constructor's arguments (the pixmap, parent and scene) on to the + base class constructor: + + \snippet drilldown/imageitem.cpp 0 + + Then we store the ID for future reference, and ensure that our + item will accept hover events. Hover events are delivered when + there is no current mouse grabber item. They are sent when the + mouse cursor enters an item, when it moves around inside the item, + and when the cursor leaves an item. As we mentioned earlier, none + of the \l {Graphics View Framework}'s items accept hover + event's by default. + + The QTimeLine class provides a timeline for controlling + animations. Its \l {QTimeLine::}{duration} property holds the + total duration of the timeline in milliseconds. By default, the + time line runs once from the beginning and towards the end. The + QTimeLine::setFrameRange() function sets the timeline's frame + counter; when the timeline is running, the \l + {QTimeLine::}{frameChanged()} signal is emitted each time the + frame changes. We set the duration and frame range for our + animation, and connect the time line's \l + {QTimeLine::}{frameChanged()} and \l {QTimeLine::}{finished()} + signals to our private \c setFrame() and \c updateItemPosition() + slots. + + Finally, we call \c adjust() to ensure that the item is given the + preferred size. + + \snippet drilldown/imageitem.cpp 1 + \codeline + \snippet drilldown/imageitem.cpp 2 + + Whenever the mouse cursor enters or leave the image item, the + corresponding event handlers are triggered: We first set the time + line's direction, making the item expand or shrink, + respectively. Then we alter the item's z-value if it is not already + set to the expected value. + + In the case of hover \e enter events, we immediately update the + item's position since we want the item to appear on top of all + other items as soon as it starts expanding. In the case of hover + \e leave events, on the other hand, we postpone the actual update + to achieve the same result. But remember that when we constructed + our item, we connected the time line's \l + {QTimeLine::}{finished()} signal to the \c updateItemPosition() + slot. In this way the item is given the correct position in the + item stack once the animation is completed. Finally, if the time + line is not already running, we start it. + + \snippet drilldown/imageitem.cpp 3 + + When the time line is running, it triggers the \c setFrame() slot + whenever the current frame changes due to the connection we + created in the item constructor. It is this slot that controls the + animation, expanding or shrinking the image item step by step. + + We first call the \c adjust() function to ensure that we start off + with the item's original size. Then we scale the item with a + factor depending on the animation's progress (using the \c frame + parameter). Note that by default, the transformation will be + relative to the item's top-left corner. Since we want the item to + be transformed relative to its center, we must translate the + coordinate system before we scale the item. + + In the end, only the following convenience functions remain: + + \snippet drilldown/imageitem.cpp 4 + \codeline + \snippet drilldown/imageitem.cpp 5 + \codeline + \snippet drilldown/imageitem.cpp 6 + + The \c adjust() function defines and applies a transformation + matrix, ensuring that our image item appears with the preferred + size regardless of the size of the source image. The \c id() + function is trivial, and is simply provided to be able to identify + the item. In the \c updateItemPosition() slot we call the + QGraphicsItem::setZValue() function, setting the elevation (i.e., + the position) of the item. +*/ diff --git a/examples/sql/doc/src/masterdetail.qdoc b/examples/sql/doc/src/masterdetail.qdoc new file mode 100644 index 0000000000..c8ec68f639 --- /dev/null +++ b/examples/sql/doc/src/masterdetail.qdoc @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example masterdetail + \title Master Detail Example + + The Master Detail Example shows how to present data from different + data sources in the same application. The album titles, and the + corresponding artists and release dates, are kept in a + database, while each album's tracks are stored in an XML + file. + + The example also shows how to add as well as remove data from both + the database and the associated XML file using the API provided by + the QtSql and QtXml modules, respectively. + + \image masterdetail-example.png +*/ diff --git a/examples/sql/doc/src/querymodel.qdoc b/examples/sql/doc/src/querymodel.qdoc new file mode 100644 index 0000000000..2d1f3c90b1 --- /dev/null +++ b/examples/sql/doc/src/querymodel.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example querymodel + \title Query Model Example + + The Query Model example shows how to make customized versions of + data obtained from a SQL query, using a model that encapsulates + the query and table views to display the results. + + \image querymodel-example.png +*/ diff --git a/examples/sql/doc/src/relationaltablemodel.qdoc b/examples/sql/doc/src/relationaltablemodel.qdoc new file mode 100644 index 0000000000..619554ff91 --- /dev/null +++ b/examples/sql/doc/src/relationaltablemodel.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example relationaltablemodel + \title Relational Table Model Example + + The Relational Table Model example shows how to use table views with a relational + model to visualize the relations between items in a database. + + \image relationaltablemodel-example.png +*/ diff --git a/examples/sql/doc/src/sqlbrowser.qdoc b/examples/sql/doc/src/sqlbrowser.qdoc new file mode 100644 index 0000000000..302964cf75 --- /dev/null +++ b/examples/sql/doc/src/sqlbrowser.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sqlbrowser + \title SQL Browser + + The SQL Browser example shows how a data browser can be used to visualize + the results of SQL statements on a live database. + + \image sqlbrowser-demo.png +*/ diff --git a/examples/sql/doc/src/sqlwidgetmapper.qdoc b/examples/sql/doc/src/sqlwidgetmapper.qdoc new file mode 100644 index 0000000000..cc1c51c97f --- /dev/null +++ b/examples/sql/doc/src/sqlwidgetmapper.qdoc @@ -0,0 +1,185 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sqlwidgetmapper + \title SQL Widget Mapper Example + + The SQL Widget Mapper example shows how to use a map information from a + database to widgets on a form. + + \image sql-widget-mapper.png + + In the \l{Combo Widget Mapper Example}, we showed how to use a named + mapping between a widget mapper and a QComboBox widget with a special + purpose model to relate values in the model to a list of choices. + + Again, we create a \c Window class with an almost identical user interface, + providing a combo box to allow their addresses to be classified as "Home", + "Work" or "Other". However, instead of using a separate model to hold these + address types, we use one database table to hold the example data and + another to hold the address types. In this way, we store all the + information in the same place. + + \section1 Window Class Definition + + The class provides a constructor, a slot to keep the buttons up to date, + and a private function to set up the model: + + \snippet sqlwidgetmapper/window.h Window definition + + In addition to the QDataWidgetMapper object and the controls used to make + up the user interface, we use a QStandardItemModel to hold our data and + a QStringListModel to hold information about the types of address that + can be applied to each person's data. + + \section1 Window Class Implementation + + The first act performed by the \c Window class constructor is to set up + the model used to hold the example data. Since this is a key part of the + example, we will look at this first. + + The model is initialized in the window's \c{setupModel()} function. Here, + we create a SQLite database containing a "person" table with primary key, + name, address and type fields. + + \snippet sqlwidgetmapper/window.cpp Set up the main table + + On each row of the table, we insert default values for these fields, + including values for the address types that correspond to the address + types are stored in a separate table. + + \image widgetmapper-sql-mapping-table.png + + We create an "addresstype" table containing the identifiers used in the + "person" table and the corresponding strings: + + \snippet sqlwidgetmapper/window.cpp Set up the address type table + + The "typeid" field in the "person" table is related to the contents of + the "addresstype" table via a relation in a QSqlRelationalTableModel. + This kind of model performs all the necessary work to store the data in + a database and also allows any relations to be used as models in their + own right. + + In this case, we have defined a relation for the "typeid" field in the + "person" table that relates it to the "id" field in the "addresstype" + table and which causes the contents of the "description" field to be + used wherever the "typeid" is presented to the user. (See the + QSqlRelationalTableModel::setRelation() documentation for details.) + + \image widgetmapper-sql-mapping.png + + The constructor of the \c Window class can be explained in three parts. + In the first part, we set up the model used to hold the data, then we set + up the widgets used for the user interface: + + \snippet sqlwidgetmapper/window.cpp Set up widgets + + We obtain a model for the combo box from the main model, based on the + relation we set up for the "typeid" field. The call to the combo box's + \l{QComboBox::}{setModelColumn()} selects the field in the field in the + model to display. + + Note that this approach is similar to the one used in the + \l{Combo Widget Mapper Example} in that we set up a model for the + combo box. However, in this case, we obtain a model based on a relation + in the QSqlRelationalTableModel rather than create a separate one. + + Next, we set up the widget mapper, relating each input widget to a field + in the model: + + \snippet sqlwidgetmapper/window.cpp Set up the mapper + + For the combo box, we already know the index of the field in the model + from the \c{setupModel()} function. We use a QSqlRelationalDelegate as + a proxy between the mapper and the input widgets to match up the "typeid" + values in the model with those in the combo box's model and populate the + combo box with descriptions rather than integer values. + + As a result, the user is able to select an item from the combo box, + and the associated value is written back to the model. + + The rest of the constructor is very similar to that of the + \l{Simple Widget Mapper Example}: + + \snippet sqlwidgetmapper/window.cpp Set up connections and layouts + + We show the implementation of the \c{updateButtons()} slot for + completeness: + + \snippet sqlwidgetmapper/window.cpp Slot for updating the buttons + + \omit + \section1 Delegate Class Definition and Implementation + + The delegate we use to mediate interaction between the widget mapper and + the input widgets is a small QItemDelegate subclass: + + \snippet sqlwidgetmapper/delegate.h Delegate class definition + + This provides implementations of the two standard functions used to pass + data between editor widgets and the model (see the \l{Delegate Classes} + documentation for a more general description of these functions). + + Since we only provide an empty implementation of the constructor, we + concentrate on the other two functions. + + The \l{QItemDelegate::}{setEditorData()} implementation takes the data + referred to by the model index supplied and processes it according to + the presence of a \c currentIndex property in the editor widget: + + \snippet sqlwidgetmapper/delegate.cpp setEditorData implementation + + If, like QComboBox, the editor widget has this property, it is set using + the value from the model. Since we are passing around QVariant values, + the strings stored in the model are automatically converted to the integer + values needed for the \c currentIndex property. + + As a result, instead of showing "0", "1" or "2" in the combo box, one of + its predefined set of items is shown. We call QItemDelegate::setEditorData() + for widgets without the \c currentIndex property. + + The \l{QItemDelegate::}{setModelData()} implementation performs the reverse + process, taking the value stored in the widget's \c currentIndex property + and storing it back in the model: + + \snippet sqlwidgetmapper/delegate.cpp setModelData implementation + \endomit + + \section1 Summary and Further Reading + + The use of a separate model for the combo box and a special delegate for the + widget mapper allows us to present a menu of choices to the user. Although + the choices are stored in the same database as the user's data, they are held + in a separate table. Using this approach, we can reconstructed complete records + at a later time while using database features appropriately. + + If SQL models are not being used, it is still possible to use more than + one model to present choices to the user. This is covered by the + \l{Combo Widget Mapper Example}. +*/ diff --git a/examples/sql/doc/src/tablemodel.qdoc b/examples/sql/doc/src/tablemodel.qdoc new file mode 100644 index 0000000000..1a08048dd9 --- /dev/null +++ b/examples/sql/doc/src/tablemodel.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tablemodel + \title Table Model Example + + The Table Model example shows how to use a specialized SQL table model with table + views to edit information in a database. + + \image tablemodel-example.png +*/ diff --git a/examples/tools/doc/src/customcompleter.qdoc b/examples/tools/doc/src/customcompleter.qdoc new file mode 100644 index 0000000000..98a95e47a4 --- /dev/null +++ b/examples/tools/doc/src/customcompleter.qdoc @@ -0,0 +1,187 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example customcompleter + \title Custom Completer Example + + The Custom Completer example shows how to provide string-completion + facilities for an input widget based on data provided by a model. The + completer pops up suggestions for possible words based on the first three + characters input by the user and the user's choice of word is inserted + into the \c TextEdit using QTextCursor. + + \image customcompleter-example.png + + \section1 Setting Up The Resource File + + The Custom Completer example requires a resource file, \e wordlist.txt, + that has a list of words to help QCompleter complete words. This file + contains the following: + + \quotefile examples/tools/customcompleter/customcompleter.qrc + + \section1 TextEdit Class Definition + + The \c TextEdit class is a subclass of QTextEdit with a custom + \c insertCompletion() slot and it reimplements the + \l{QAbstractScrollArea::keyPressEvent()}{keyPressEvent()} and the + \l{QWidget::focusInEvent()}{focusInEvent()} functions. \c TextEdit also + contains a private function \c textUnderCursor() and a private instance + of QCompleter, \c c. + + \snippet examples/tools/customcompleter/textedit.h 0 + + \section1 TextEdit Class Implementation + + The constructor for \c TextEdit constructs a \c TextEdit with a parent and + initializes \c c. The instructions to use the completer is displayed on + the \c TextEdit object, using the + \l{QTextEdit::setPlainText()}{setPlainText()} function. + + \snippet examples/tools/customcompleter/textedit.cpp 0 + + In addition, \c TextEdit also includes a default destructor: + + \snippet examples/tools/customcompleter/textedit.cpp 1 + + The \c setCompleter() function accepts a \a completer and sets it up. + We use \c{if (c)} to check if \c c has been initialized. If it has been + initialized, the QObject::disconnect() function is invoked to disconnect + the signal from the slot. This is to ensure that no previous completer + object is still connected to the slot. + + \snippet examples/tools/customcompleter/textedit.cpp 2 + + We then instantiate \c c with \a completer and set it as \c{TextEdit}'s + widget. The completion mode and case sensitivity are also set and then + we connect the \l{QCompleter::activated()}{activated()} signal to the + \c insertCompletion() slot. + + The \c completer() function is a getter function that returns \c c. + + \snippet examples/tools/customcompleter/textedit.cpp 3 + + The completer pops up the options available, based on the contents of + \e wordlist.txt, but the text cursor is responsible for filling in the + missing characters, according to the user's choice of word. + + Suppose the user inputs "ACT" and accepts the completer's suggestion of + "ACTUAL". The \c completion string is then sent to \c insertCompletion() + by the completer's \l{QCompleter::activated()}{activated()} signal. + + The \c insertCompletion() function is responsible for completing the word + using a QTextCursor object, \c tc. It validates to ensure that the + completer's widget is \c TextEdit before using \c tc to insert the extra + characters to complete the word. + + \snippet examples/tools/customcompleter/textedit.cpp 4 + + The figure below illustrates this process: + + \image customcompleter-insertcompletion.png + + \c{completion.length()} = 6 + + \c{c->completionPrefix().length()}=3 + + The difference between these two values is \c extra, which is 3. This + means that the last three characters from the right, "U", "A", and "L", + will be inserted by \c tc. + + The \c textUnderCursor() function uses a QTextCursor, \c tc, to select a + word under the cursor and return it. + + \snippet examples/tools/customcompleter/textedit.cpp 5 + + The \c TextEdit class reimplements \l{QWidget::focusInEvent()} + {focusInEvent()} function, which is an event handler used to receive + keyboard focus events for the widget. + + \snippet examples/tools/customcompleter/textedit.cpp 6 + + The \l{QAbstractScrollArea::keyPressEvent()}{keyPressEvent()} is + reimplemented to ignore key events like Qt::Key_Enter, Qt::Key_Return, + Qt::Key_Escape, Qt::Key_Tab, and Qt::Key_Backtab so the completer can + handle them. + + If there is an active completer, we cannot process the shortcut, Ctrl+E. + + \snippet examples/tools/customcompleter/textedit.cpp 7 + + We also handle other modifiers and shortcuts for which we do not want the + completer to respond to. + + \snippet examples/tools/customcompleter/textedit.cpp 8 + + Finally, we pop up the completer. + + \section1 MainWindow Class Definition + + The \c MainWindow class is a subclass of QMainWindow and implements a + private slot, \c about(). This class also has two private functions, + \c createMenu() and \c modelFromFile() as well as private instances of + QCompleter and \c TextEdit. + + \snippet examples/tools/customcompleter/mainwindow.h 0 + + \section1 MainWindow Class Implementation + + The constructor constructs a \c MainWindow with a parent and initializes + the \c completer. It also instantiates a \c TextEdit and sets its + completer. A QStringListModel, obtained from \c modelFromFile(), is used + to populate the \c completer. The \c{MainWindow}'s central widget is set + to \c TextEdit and its size is set to 500 x 300. + + \snippet examples/tools/customcompleter/mainwindow.cpp 0 + + The \c createMenu() function creates the necessary QAction objects needed + for the "File" and "Help" menu and their \l{QAction::triggered()} + {triggered()} signals are connected to the \c quit(), \c about(), and + \c aboutQt() slots respectively. + + \snippet examples/tools/customcompleter/mainwindow.cpp 1 + + The \c modelFromFile() function accepts a \a fileName and attempts to + extract the contents of this file into a QStringListModel. We display the + Qt::WaitCursor when we are populating the QStringList, \c words, and + restore the mouse cursor when we are done. + + \snippet examples/tools/customcompleter/mainwindow.cpp 2 + + The \c about() function provides a brief description about the Custom + Completer example. + + \snippet examples/tools/customcompleter/mainwindow.cpp 3 + + \section1 \c main() Function + + The \c main() function instantiates \c MainWindow and invokes the + \l{QWidget::show()}{show()} function. + + \snippet examples/tools/customcompleter/main.cpp 0 +*/ diff --git a/examples/tools/doc/src/customtype.qdoc b/examples/tools/doc/src/customtype.qdoc new file mode 100644 index 0000000000..b2f86d6890 --- /dev/null +++ b/examples/tools/doc/src/customtype.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/customtype + \title Custom Type Example + + The Custom Type example shows how to integrate a custom type into Qt's + meta-object system. + + Contents: + + \tableofcontents + + \section1 Overview + + Qt provides a range of standard value types that are used to provide + rich and meaningful APIs. These types are integrated with the meta-object + system, enabling them to be stored in QVariant objects, written out in + debugging information and sent between components in signal-slot + communication. + + Custom types can also be integrated with the meta-object system as long as + they are written to conform to some simple guidelines. In this example, we + introduce a simple \c Message class, we describe how we make it work with + QVariant, and we show how it can be extended to generate a printable + representation of itself for use in debugging output. + + \section1 The Message Class Definition + + The \c Message class is a simple value class that contains two pieces + of information (a QString and a QStringList), each of which can be read + using trivial getter functions: + + \snippet examples/tools/customtype/message.h custom type definition + + The default constructor, copy constructor and destructor are + all required, and must be public, if the type is to be integrated into the + meta-object system. Other than this, we are free to implement whatever we + need to make the type do what we want, so we also include a constructor + that lets us set the type's data members. + + To enable the type to be used with QVariant, we declare it using the + Q_DECLARE_METATYPE() macro: + + \snippet examples/tools/customtype/message.h custom type meta-type declaration + + We do not need to write any additional code to accompany this macro. + + To allow us to see a readable description of each \c Message object when it + is sent to the debug output stream, we define a streaming operator: + + \snippet examples/tools/customtype/message.h custom type streaming operator + + This facility is useful if you need to insert tracing statements in your + code for debugging purposes. + + \section1 The Message Class Implementation + + The implementation of the default constructor, copy constructor and destructor + are straightforward for the \c Message class: + + \snippet examples/tools/customtype/message.cpp Message class implementation + + The streaming operator is implemented in the following way: + + \snippet examples/tools/customtype/message.cpp custom type streaming operator + + Here, we want to represent each value depending on how many lines are stored + in the message body. We stream text to the QDebug object passed to the + operator and return the QDebug object obtained from its maybeSpace() member + function; this is described in more detail in the + \l{Creating Custom Qt Types#Making the Type Printable}{Creating Custom Qt Types} + document. + + We include the code for the getter functions for completeness: + + \snippet examples/tools/customtype/message.cpp getter functions + + With the type fully defined, implemented, and integrated with the + meta-object system, we can now use it. + + \section1 Using the Message + + In the example's \c{main()} function, we show how a \c Message object can + be printed to the console by sending it to the debug stream: + + \snippet examples/tools/customtype/main.cpp printing a custom type + + You can use the type with QVariant in exactly the same way as you would + use standard Qt value types. Here's how to store a value using the + QVariant::setValue() function: + + \snippet examples/tools/customtype/main.cpp storing a custom value + + Alternatively, the QVariant::fromValue() and qVariantSetValue() functions + can be used if you are using a compiler without support for member template + functions. + + The value can be retrieved using the QVariant::value() member template + function: + + \snippet examples/tools/customtype/main.cpp retrieving a custom value + + Alternatively, the qVariantValue() template function can be used if + you are using a compiler without support for member template functions. + + \section1 Further Reading + + The custom \c Message type can also be used with direct signal-slot + connections; see the \l{Custom Type Sending Example} for a demonstration + of this. + To register a custom type for use with queued signals and slots, such as + those used in cross-thread communication, see the + \l{Queued Custom Type Example}. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ diff --git a/examples/widgets/doc/images/itemviewspuzzle-example.png b/examples/widgets/doc/images/itemviewspuzzle-example.png Binary files differnew file mode 100644 index 0000000000..05ae28be81 --- /dev/null +++ b/examples/widgets/doc/images/itemviewspuzzle-example.png diff --git a/examples/widgets/doc/src/addressbook-fr.qdoc b/examples/widgets/doc/src/addressbook-fr.qdoc new file mode 100644 index 0000000000..53bf89f3bd --- /dev/null +++ b/examples/widgets/doc/src/addressbook-fr.qdoc @@ -0,0 +1,1033 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page tutorials-addressbook-fr.html + + \title Tutoriel "Carnet d'adresses" + \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) + à l'aide des outils fournis par la plateforme multiplate-forme Qt. + + \image addressbook-tutorial-screenshot.png + + Ce tutoriel va nous amener à découvrir quelques technologies fondamentales fournies + par Qt, tel que: + + \list + \li Les Widgets et leur mise en page à l'aide des layouts + \li Les signaux et slots + \li Les structures de données de collections + \li Les entrées/sorties + \endlist + + Le code source du tutoriel est distribué avec Qt dans le dossier \c tutorials/addressbook + + Les chapitres du tutoriel: + + \list 1 + \li \l{tutorials/addressbook-fr/part1}{Conception de l'interface utilisateur} + \li \l{tutorials/addressbook-fr/part2}{Ajouter des adresses} + \li \l{tutorials/addressbook-fr/part3}{Navigation entre les éléments} + \li \l{tutorials/addressbook-fr/part4}{éditer et supprimer des adresses} + \li \l{tutorials/addressbook-fr/part5}{Ajout d'une fonction de recherche} + \li \l{tutorials/addressbook-fr/part6}{Sauvegarde et chargement} + \li \l{tutorials/addressbook-fr/part7}{Fonctionnalités avancées} + \endlist + + La petite application que nous développerons ici ne possède pas tous les éléments + des interfaces dernier cri, elle va nous permettre d'utiliser les techniques de base + utilisées dans les applications plus complexes. + + Lorsque vous aurez terminé ce tutoriel, nous vous recommandons de poursuivre avec l'exemple + "\l{mainwindows/application}{Application}", qui présente une interface simple utilisant + les menus et barres d'outils, la barre d'état, etc. + +*/ + +/*! + \page tutorials-addressbook-fr-part1.html + + \example tutorials/addressbook-fr/part1 + \title Carnet d'adresses 1 - Conception de l'interface utilisateur + + La première partie de ce tutoriel traite de la conception d'une interface graphique + (GUI) basique, que l'on utilisera pour l'application Carnet d'adresses. + + La première étape dans la création d'applications graphiques est la conception de + l'interface utilisateur. Dans ce chapitre, nous verrons comment créer les labels + et champs de saisie nécessaires à l'implementation d'un carnet d'adresses de base. + Le résultat attendu est illustré par la capture d'écran ci-dessous. + + \image addressbook-tutorial-part1-screenshot.png + + Nous allons avoir besoin de deux objets QLabel, \c nameLabel et \c addressLabel, + ainsi que deux champs de saisie: un objet QLineEdit, \c nameLine, et un objet + QTextEdit, \c addressText, afin de permettre à l'utilisateur d'entrer le nom d'un + contact et son adresse. Les widgets utilisés ainsi que leur placement sont visibles ci-dessous. + + \image addressbook-tutorial-part1-labeled-screenshot.png + + Trois fichiers sont nécessaires à l'implémentation de ce carnet d'adresses: + + \list + \li \c{addressbook.h} - le fichier de définition (header) pour la classe \c AddressBook, + \li \c{addressbook.cpp} - le fichier source, qui comprend l'implémentation de la classe + \c AddressBook + \li \c{main.cpp} - le fichier qui contient la méthode \c main() , et + une instance de la classe \c AddressBook. + \endlist + + \section1 Programmation en Qt - héritage + + + Lorsque l'on écrit des programmes avec Qt, on a généralement recours à + l'héritage depuis des objets Qt, afin d'y ajouter des fonctionnalités. + C'est l'un des concepts fondamentaux de la création de widgets personnalisés + ou de collections de widgets. Utiliser l'héritage afin de compléter + ou modifier le comportement d'un widget présente les avantages suivants: + + \list + \li La possibilité d'implémenter des méthodes virtuelles et des méthodes + virtuelles pures pour obtenir exactement ce que l'on souhaite, avec la possibilité + d'utiliser l'implémentation de la classe mère si besoin est. + \li Cela permet l'encapsulation partielle de l'interface utilisateur dans une classe, + afin que les autres parties de l'application n'aient pas à se soucier de chacun des + widgets qui forment l'interface utilisateur. + \li La classe fille peut être utilisée pour créer de nombreux widgets personnalisés + dans une même application ou bibliothèque, et le code de la classe fille peut être + réutilisé dans d'autres projets + \endlist + + Comme Qt ne fournit pas de widget standard pour un carnet d'adresses, nous + partirons d'une classe de widget Qt standard et y ajouterons des fonctionnalités. + La classe \c AddressBook crée dans ce tutoriel peut être réutilisée si on a besoin d'un + widget carnet d'adresses basique. + + + \section1 La classe AddressBook + + Le fichier \l{tutorials/addressbook-fr/part1/addressbook.h}{\c addressbook.h} permet de + définir la classe \c AddressBook. + + On commence par définir \c AddressBook comme une classe fille de QWidget et déclarer + un constructeur. On utilise également la macro Q_OBJECT pour indiquer que la classe + exploite les fonctionnalités de signaux et slots offertes par Qt ainsi que + l'internationalisation, bien que nous ne les utilisions pas à ce stade. + + \snippet tutorials/addressbook-fr/part1/addressbook.h class definition + + La classe contient les déclarations de \c nameLine et \c addressText, + les instances privées de QLineEdit et QTextEdit mentionnées précédemment. + Vous verrez, dans les chapitres à venir que les informations contenues + dans \c nameLine et \c addressText sont nécessaires à de nombreuses méthodes + du carnet d'adresses. + + Il n'est pas nécessaire de déclarer les objets QLabel que nous allons utiliser + puisque nous n'aurons pas besoin d'y faire référence après leur création. + La façon dont Qt gère la parenté des objets est traitée dans la section suivante. + + La macro Q_OBJECT implémente des fonctionnalités parmi les plus avancées de Qt. + Pour le moment, il est bon de voir la macro Q_OBJECT comme un raccourci nous + permettant d'utiliser les méthodes \l{QObject::}{tr()} et \l{QObject::}{connect()}. + + Nous en avons maintenant terminé avec le fichier \c addressbook.h et allons + passer à l'implémentation du fichier \c addressbook.cpp. + + \section1 Implémentation de la classe AddressBook + + Le constructeur de la classe \c{AddressBook} prend en paramètre un QWidget, \e parent. + Par convention, on passe ce paramètre au constructeur de la classe mère. + Ce concept de parenté, où un parent peut avoir un ou plusieurs enfants, est utile + pour regrouper les Widgets avec Qt. Par exemple, si vous détruisez le parent, + tous ses enfants seront détruits égalament. + + + \snippet tutorials/addressbook/part1/addressbook.cpp constructor and input fields + + à l'intérieur de ce constructeur, on déclare et instancie deux objets locaux + QLabel, \c nameLabel et \c addressLabel, de même on instancie \c nameLine et + \c addressText. La méthode \l{QObject::tr()}{tr()} renvoie une version traduite + de la chaîne de caractères, si elle existe; dans le cas contraire, elle renvoie + la chaîne elle même. On peut voir cette méthode comme un marqueur \tt{<insérer + la traduction ici>}, permettant de repérer les objets QString à considérer + pour traduire une application. Vous remarquerez, dans les chapitres à venir + comme dans les exemples Qt, qu'elle est utilisée chaque fois + que l'on utilise une chaîne susceptible d'être traduite. + + Lorsque l'on programme avec Qt, il est utile de savoir comment fonctionnent les + agencements ou layouts. Qt fournit trois classes principales de layouts pour + contrôler le placement des widgets: QHBoxLayout, QVBoxLayout et QGridLayout. + + \image addressbook-tutorial-part1-labeled-layout.png + + On utilise un QGridLayout pour positionner nos labels et champs de saisie de manière + structurée. QGridLayout divise l'espace disponible en une grille, et place les + widgets dans les cellules que l'on spécifie par les numéros de ligne et de colonne. + Le diagramme ci-dessus présente les cellules et la position des widgets, et cette + organisation est obtenue à l'aide du code suivant: + + \snippet tutorials/addressbook/part1/addressbook.cpp layout + + On remarque que le label \c AddressLabel est positionné en utilisant Qt::AlignTop + comme argument optionnel. Ceci est destiné à assurer qu'il ne sera pas centré + verticalement dans la cellule (1,0). Pour un aperçu rapide des layouts de Qt, + consultez la section \l{Layout Management}. + + Afin d'installer l'objet layout dans un widget, il faut appeler la méthode + \l{QWidget::setLayout()}{setLayout()} du widget en question: + + \snippet tutorials/addressbook/part1/addressbook.cpp setting the layout + + Enfin, on initialise le titre du widget à "Simple Address Book" + + \section1 Exécution de l'application + + Un fichier séparé, \c main.cpp, est utilisé pour la méthode \c main(). Dans cette + fonction, on crée une instance de QApplication, \c app. QApplication se charge de + des ressources communes à l'ensemble de l'application, tel que les polices de + caractères et le curseur par défaut, ainsi que de l'exécution de la boucle d'évènements. + De ce fait, il y a toujours un objet QApplication dans toute application graphique en Qt. + + \snippet tutorials/addressbook/part1/main.cpp main function + + On construit un nouveau widget \c AddressBook sur la pile et on invoque + sa méthode \l{QWidget::show()}{show()} pour l'afficher. + Cependant, le widget ne sera pas visible tant que la boucle d'évènements + n'aura pas été lancée. On démarre la boucle d'évènements en appelant la + méthode \l{QApplication::}{exec()} de l'application; le résultat renvoyé + par cette méthode est lui même utilisé comme valeur de retour pour la méthode + \c main(). + On comprend maintenant pourquoi \c AddressBook a été créé sur la pile: à la fin + du programme, l'objet sort du scope de la fonction \c main() et tous ses widgets enfants + sont supprimés, assurant ainsi qu'il n'y aura pas de fuites de mémoire. +*/ + +/*! + \page tutorials-addressbook-fr-part2.html + + \example tutorials/addressbook-fr/part2 + \title Carnet d'adresses 2 - Ajouter des adresses + + La prochaine étape pour créer notre carnet d'adresses est d'ajouter un soupçon + d'interactivité. + + \image addressbook-tutorial-part2-add-contact.png + + Nous allons fournir un bouton que l'utilisateur peut + cliquer pour ajouter un nouveau contact. Une structure de données est aussi + nécessaire afin de pouvoir stocker les contacts en mémoire. + + \section1 Définition de la classe AddressBook + + Maintenant que nous avons mis en place les labels et les champs de saisie, + nous ajoutons les boutons pour compléter le processus d'ajout d'un contact. + Cela veut dire que notre fichier \c addressbook.h a maintenant trois + objets QPushButton et trois slots publics correspondant. + + \snippet tutorials/addressbook/part2/addressbook.h slots + + Un slot est une méthode qui répond à un signal. Nous allons + voir ce concept en détail lorsque nous implémenterons la classe \c{AddressBook}. + Pour une explication détaillée du concept de signal et slot, vous pouvez + vous référer au document \l{Signals and Slots}. + + Les trois objets QPushButton \c addButton, \c submitButton et \c cancelButton + sont maintenant inclus dans la déclaration des variables privées, avec + \c nameLine et \c addressText du chapitre précédent. + + \snippet tutorials/addressbook/part2/addressbook.h pushbutton declaration + + Nous avons besoin d'un conteneur pour stocker les contacts du carnet + d'adresses, de façon à pouvoir les énumérer et les afficher. + Un objet QMap, \c contacts, est utilisé pour ça, car il permet de stocker + des paires clé-valeur: le nom du contact est la \e{clé} et l'adresse du contact + est la \e{valeur}. + + \snippet tutorials/addressbook/part2/addressbook.h remaining private variables + + Nous déclarons aussi deux objects QString privés: \c oldName et \c oldAddress. + Ces objets sont nécessaires pour conserver le nom et l'adresse du dernier contact + affiché avant que l'utilisateur ne clique sur le bouton "Add". Grâce à ces variables + si l'utilisateur clique sur "Cancel", il est possible de revenir + à l'affichage du dernier contact. + + \section1 Implémentation de la classe AddressBook + + Dans le constructeur de \c AddressBook, \c nameLine et + \c addressText sont mis en mode lecture seule, de façon à autoriser l'affichage + mais pas la modification du contact courant. + + \dots + \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 1 + \dots + \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 2 + + Ensuite, nous instancions les boutons \c addButton, \c submitButton, et + \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp pushbutton declaration + + Le bouton \c addButton est affiché en invoquant la méthode \l{QPushButton::show()} + {show()}, tandis que \c submitButton et \c cancelButton sont cachés en invoquant + \l{QPushButton::hide()}{hide()}. Ces deux boutons ne seront affichés que lorsque + l'utilisateur cliquera sur "Add", et ceci est géré par la méthode \c addContact() + décrite plus loin. + + \snippet tutorials/addressbook/part2/addressbook.cpp connecting signals and slots + + Nous connectons le signal \l{QPushButton::clicked()}{clicked()} de chaque bouton + au slot qui gèrera l'action. + L'image ci-dessous illustre ceci: + + \image addressbook-tutorial-part2-signals-and-slots.png + + Ensuite, nous arrangeons proprement les boutons sur la droite du widget + AddressBook, et nous utilisons un QVBoxLayout pour les aligner verticalement. + + \snippet tutorials/addressbook/part2/addressbook.cpp vertical layout + + La methode \l{QBoxLayout::addStretch()}{addStretch()} est utilisée pour + assurer que les boutons ne sont pas répartis uniformément, mais regroupés + dans la partie supperieure du widget. La figure ci-dessous montre la différence + si \l{QBoxLayout::addStretch()}{addStretch()} est utilisé ou pas. + + \image addressbook-tutorial-part2-stretch-effects.png + + Ensuite nous ajoutons \c buttonLayout1 à \c mainLayout, en utilisant + \l{QGridLayout::addLayout()}{addLayout()}. Ceci nous permet d'imbriquer les + mises en page puisque \c buttonLayout1 est maintenant un enfant de \c mainLayout. + + \snippet tutorials/addressbook/part2/addressbook.cpp grid layout + + Les coordonnées du layout global ressemblent maintenant à ça: + + \image addressbook-tutorial-part2-labeled-layout.png + + Dans la méthode \c addContact(), nous stockons les détails du dernier + contact affiché dans \c oldName et \c oldAddress. Ensuite, nous + vidons ces champs de saisie et nous désactivons le mode + lecture seule. Le focus est placé sur \c nameLine et on affiche + \c submitButton et \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp addContact + + La méthode \c submitContact() peut être divisée en trois parties: + + \list 1 + \li Nous extrayons les détails du contact depuis \c nameLine et \c addressText + et les stockons dans des objets QString. Nous les validons pour s'assurer + que l'utilisateur n'a pas cliqué sur "Add" avec des champs de saisie + vides; sinon un message est affiché avec QMessageBox pour rappeller à + l'utilisateur que les deux champs doivent être complétés. + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part1 + + \li Ensuite, nous vérifions si le contact existe déjà . Si aucun contacts + existant n'entre en conflit avec le nouveau, nous l'ajoutons à + \c contacts et nous affichons un QMessageBox pour informer l'utilisateur + que le contact a été ajouté. + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part2 + + Si le contact existe déjà , nous affichons un QMessageBox pour informer + l'utilisateur du problème. + Notre objet \c contacts est basé sur des paires clé-valeur formés par + le nom et l'adresse, nous voulons nous assurer que la \e clé est unique. + + \li Une fois que les deux vérifications précédentes ont été traitées, + nous restaurons les boutons à leur état normal à l'aide du code + suivant: + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part3 + + \endlist + + La capture d'écran ci-dessous montre l'affichage fournit par un objet + QMessageBox, utilisé ici pour afficher un message d'information + à l'utilisateur: + + \image addressbook-tutorial-part2-add-successful.png + + La méthode \c cancel() restaure les détails du dernier contact, active + \c addButton, et cache \c submitButton et \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp cancel + + L'idée générale pour augmenter la flexibilité lors de l'ajout d'un + contact est de donner la possiblité de cliquer sur "Add" + ou "Cancel" à n'importe quel moment. + L'organigramme ci-dessous reprend l'ensemble des interactions dévelopées + jusqu'ici: + + \image addressbook-tutorial-part2-add-flowchart.png +*/ + +/*! + \page tutorials-addressbook-fr-part3.html + + \example tutorials/addressbook-fr/part3 + \title Carnet d'adresses 3 - Navigation entre les éléments + + L'application "Carnet d'adresses" est maintenant à moitié terminée. Il + nous faut maintenant ajouter quelques fonctions pour naviguer entre + les contacts. Avant de commencer, il faut se décider sur le type de structure de + données le plus approprié pour stocker les contacts. + + Dans le chapitre 2, nous avons utilisé un QMap utilisant des paires clé-valeur, + avec le nom du contact comme \e clé, et l'adresse du contact comme \e valeur. + Cela fonctionnait bien jusqu'ici, mais pour ajouter la navigation entre les + entrées, quelques améliorations sont nécessaires. + + Nous améliorerons le QMap en le faisant ressembler à une structure de données + similaire à une liste liée, où tous les éléments sont connectés, y compris + le premier et le dernier élément. La figure ci-dessous illustre cette structure + de donnée. + + \image addressbook-tutorial-part3-linkedlist.png + + \section1 Définition de la classe AddressBook + + Pour ajouter les fonctions de navigation au carnet d'adresses, nous avons + besoin de deux slots supplémentaires dans notre classe \c AddressBook: + \c next() et \c previous(). Ceux-ci sont ajoutés au fichier addressbook.h: + + \snippet tutorials/addressbook/part3/addressbook.h navigation functions + + Nous avons aussi besoin de deux nouveaux objets QPushButton, nous ajoutons + donc les variables privées \c nextButton et \c previousButton. + + \snippet tutorials/addressbook/part3/addressbook.h navigation pushbuttons + + \section1 Implémentation de la classe AddressBook + + A l'intérieur du constructeur de \c AddressBook, dans \c addressbook.cpp, nous + instancions \c nextButton et \c previousButton et nous les désactivons + par défaut. Nous faisons ceci car la navigation ne doit être activée + que lorsqu'il y a plus d'un contact dans le carnet d'adresses. + + \snippet tutorials/addressbook/part3/addressbook.cpp navigation pushbuttons + + Nous connectons alors ces boutons à leur slots respectifs: + + \snippet tutorials/addressbook/part3/addressbook.cpp connecting navigation signals + + L'image ci-dessous montre l'interface utilisateur que nous allons créer. + Remarquez que cela ressemble de plus en plus à l'interface du programme + complet. + + \image addressbook-tutorial-part3-screenshot.png + + Nous suivons les conventions pour les fonctions \c next() et \c previous() + en plaçant \c nextButton à droite et \c previousButton à gauche. Pour + faire cette mise en page intuitive, nous utilisons un QHBoxLayout pour + placer les widgets côte à côte: + + \snippet tutorials/addressbook/part3/addressbook.cpp navigation layout + + L'objet QHBoxLayout, \c buttonLayout2, est ensuite ajouté à \c mainLayout. + + \snippet tutorials/addressbook/part3/addressbook.cpp adding navigation layout + + La figure ci-dessous montre les systèmes de coordonnées pour les widgets du + \c mainLayout. + \image addressbook-tutorial-part3-labeled-layout.png + + Dans notre méthode \c addContact(), nous avons desactivé ces boutons + pour être sûr que l'utilisateur n'utilise pas la navigation lors de + l'ajout d'un contact. + + \snippet tutorials/addressbook/part3/addressbook.cpp disabling navigation + + Dans notre méthode \c submitContact(), nous activons les boutons de + navigation, \c nextButton et \c previousButton, en fonction de la + taille de \c contacts. Commen mentionné plus tôt, la navigation n'est + activée que si il y a plus d'un contact dans le carnet d'adresses. + Les lignes suivantes montrent comment faire cela: + + \snippet tutorials/addressbook/part3/addressbook.cpp enabling navigation + + Nous incluons aussi ces lignes de code dans le bouton \c cancel(). + + Souvenez vous que nous voulons émuler une liste-liée ciruculaire à + l'aide de l'objet QMap, \c contacts. Pour faire cela, nous obtenons un itérateur + sur \c contact dans la méthode \c next(), et ensuite: + + \list + \li Si l'itérateur n'est pas à la fin de \c contacts, nous l'incrémentons + \li Si l'itérateur est à la fin de \c contacts, nous changeons sa position + jusqu'au début de \c contacts. Cela donne l'illusion que notre QMap + fonctionne comme une liste circulaire. + \endlist + + \snippet tutorials/addressbook/part3/addressbook.cpp next() function + + Une fois que nous avons itéré jusqu'à l'objet recherché dans \c contacts, + nous affichons son contenu sur \c nameLine et \c addressText. + + De la même façon, pour la méthode \c previous(), nous obtenons un + itérateur sur \c contacts et ensuite: + + \list + \li Si l'itérateur est à la fin de \c contacts, on réinitialise + l'affichage et on retourne. + \li Si l'itérateur est au début de \c contacts, on change sa + position jusqu'à la fin + \li Ensuite, on décrémente l'itérateur + \endlist + + \snippet tutorials/addressbook/part3/addressbook.cpp previous() function + + à nouveau, nous affichons le contenu de l'objet courant dans \c contacts. + +*/ + +/*! + + \page tutorials-addressbook-fr-part4.html + + \example tutorials/addressbook-fr/part4 + \title Carnet d'Adresses 4 - éditer et supprimer des adresses + + + Dans ce chapitre, nous verrons comment modifier les données des contacts + contenus dans l'application carnet d'adresses. + + + \image addressbook-tutorial-screenshot.png + + Nous avons maintenant un carnet d'adresses qui ne se contente pas de + lister des contacts de façon ordonnée, mais permet également la + navigation. Il serait pratique d'inclure des fonctions telles qu'éditer et + supprimer, afin que les détails associés à un contact puissent être + modifiés lorsque c'est nécessaire. Cependant, cela requiert une légère + modification, sous la forme d'énumérations. Au chapitre précédent, nous avions deux + modes: \c {AddingMode} et \c {NavigationMode}, mais ils n'étaient pas + définis en tant qu'énumérations. Au lieu de ça, on activait et désactivait les + boutons correspondants manuellement, au prix de multiples redondances dans + le code. + + Dans ce chapitre, on définit l'énumération \c Mode avec trois valeurs possibles. + + \list + \li \c{NavigationMode}, + \li \c{AddingMode}, et + \li \c{EditingMode}. + \endlist + + \section1 Définition de la classe AddressBook + + Le fichier \c addressbook.h est mis a jour pour contenir l'énumération \c Mode : + + \snippet tutorials/addressbook/part4/addressbook.h Mode enum + + On ajoute également deux nouveaux slots, \c editContact() et + \c removeContact(), à notre liste de slots publics. + + \snippet tutorials/addressbook/part4/addressbook.h edit and remove slots + + Afin de basculer d'un mode à l'autre, on introduit la méthode + \c updateInterface() pour contrôller l'activation et la désactivation de + tous les objets QPushButton. On ajoute également deux nouveaux boutons, + \c editButton et \c removeButton, pour les fonctions d'édition + et de suppression mentionnées plus haut. + + \snippet tutorials/addressbook/part4/addressbook.h updateInterface() declaration + \dots + \snippet tutorials/addressbook/part4/addressbook.h buttons declaration + \dots + \snippet tutorials/addressbook/part4/addressbook.h mode declaration + + Enfin, on déclare \c currentMode pour garder une trace du mode + actuellement utilisé. + + \section1 Implémentation de la classe AddressBook + + Il nous faut maintenant implémenter les fonctionnalités de changement de + mode de l'application carnet d'adresses. Les boutons \c editButton et + \c removeButton sont instanciés et désactivés par défaut, puisque le + carnet d'adresses démarre sans aucun contact en mémoire. + + \snippet tutorials/addressbook/part4/addressbook.cpp edit and remove buttons + + Ces boutons sont ensuite connectés à leurs slots respectifs, + \c editContact() et \c removeContact(), avant d'être ajoutés à + \c buttonLayout1. + + \snippet tutorials/addressbook/part4/addressbook.cpp connecting edit and remove + \dots + \snippet tutorials/addressbook/part4/addressbook.cpp adding edit and remove to the layout + + La methode \c editContact() place les anciens détails du contact dans + \c oldName et \c oldAddress, avant de basculer vers le mode + \c EditingMode. Dans ce mode, les boutons \c submitButton et + \c cancelButton sont tous deux activés, l'utilisateur peut par conséquent + modifier les détails du contact et cliquer sur l'un de ces deux boutons + par la suite. + + \snippet tutorials/addressbook/part4/addressbook.cpp editContact() function + + La méthode \c submitContact() a été divisée en deux avec un bloc + \c{if-else}. On teste \c currentMode pour voir si le mode courant est + \c AddingMode. Si c'est le cas, on procède à l'ajout. + + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function beginning + \dots + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part1 + + Sinon, on s'assure que \c currentMode est en \c EditingMode. Si c'est le + cas, on compare \c oldName et \c name. Si le nom a changé, on supprime + l'ancien contact de \c contacts et on insère le contact mis a jour. + + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part2 + + Si seule l'adresse a changé (i.e. \c oldAddress n'est pas identique à + \c address), on met à jour l'adresse du contact. Enfin on règle + \c currentMode à \c NavigationMode. C'est une étape importante puisque + c'est cela qui réactive tous les boutons désactivés. + + Afin de retirer un contact du carnet d'adresses, on implémente la méthode + \c removeContact(). Cette méthode vérifie que le contact est présent dans + \c contacts. + + \snippet tutorials/addressbook/part4/addressbook.cpp removeContact() function + + Si c'est le cas, on affiche une boîte de dialogue QMessageBox, demandant + confirmation de la suppression à l'utilisateur. Une fois la confirmation + effectuée, on appelle \c previous(), afin de s'assurer que l'interface + utilisateur affiche une autre entrée, et on supprime le contact en + utilisant le méthode \l{QMap::remove()}{remove()} de \l{QMap}. Dans un + souci pratique, on informe l'utilisateur de la suppression par le biais + d'une autre QMessageBox. Les deux boîtes de dialogue utilisées dans cette + méthode sont représentées ci-dessous. + + \image addressbook-tutorial-part4-remove.png + + \section2 Mise à jour de l'Interface utilisateur + + On a évoqué plus haut la méthode \c updateInterface() comme moyen + d'activer et de désactiver les différents boutons de l'interface en + fonction du mode. Cette méthode met à jour le mode courant selon + l'argument \c mode qui lui est passé, en l'assignant à \c currentMode, + avant de tester sa valeur. + + Chacun des boutons est ensuite activé ou désactivé, en fonction du mode. + Le code source pour les cas \c AddingMode et \c EditingMode est visible + ci-dessous: + + \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 1 + + Dans le cas de \c NavigationMode, en revanche, des tests conditionnels + sont passés en paramètre de QPushButton::setEnabled(). Ceci permet de + s'assurer que les boutons \c editButton et \c removeButton ne sont activés + que s'il existe au moins un contact dans le carnet d'adresses; + \c nextButton et \c previousButton ne sont activés que lorsqu'il existe + plus d'un contact dans le carnet d'adresses. + + \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 2 + + En effectuant les opérations de réglage du mode et de mise à jour de + l'interface utilisateur au sein de la même méthode, on est à l'abri de + l'éventualité où l'interface utilisateur se "désynchronise" de l'état + interne de l'application. + +*/ + +/*! + \page tutorials-addressbook-fr-part5.html + + \example tutorials/addressbook-fr/part5 + \title Carnet d'adresse 5 - Ajout d'une fonction de recherche + + Dans ce chapitre, nous allons voir les possibilités pour rechercher + des contacts dans le carnet d'adresse. + + \image addressbook-tutorial-part5-screenshot.png + + Plus nous ajoutons des contacts dans l'application, plus + il devient difficile de naviguer avec les boutons \e Next et \e Previous. + Dans ce cas, une fonction de recherche serait plus efficace pour rechercher + les contacts. + La capture d'écran ci-dessus montre le bouton de recherche \e Find et sa position + dans le paneau de bouton. + + Lorsque l'utilisateur clique sur le bouton \e Find, il est courant d'afficher + une boîte de dialogue qui demande à l'utilisateur d'entrer un nom de contact. + Qt fournit la classe QDialog, que nous sous-classons dans ce chapitre pour + implémenter la class \c FindDialog. + + \section1 Définition de la classe FindDialog + + \image addressbook-tutorial-part5-finddialog.png + + Pour sous-classer QDialog, nous commençons par inclure le header de + QDialog dans le fichier \c finddialog.h. De plus, nous déclarons les + classes QLineEdit et QPushButton car nous utilisons ces widgets dans + notre classe dialogue. + + Tout comme dans la classe \c AddressBook, la classe \c FindDialog utilise + la macro Q_OBJECT et son constructeur est défini de façon à accepter + un QWidget parent, même si cette boîte de dialogue sera affichée dans une + fenêtre séparée. + + \snippet tutorials/addressbook/part5/finddialog.h FindDialog header + + Nous définissons la méthode publique \c getFindText() pour être utilisée + par les classes qui instancient \c FindDialog, ce qui leur permet d'obtenir + le texte entré par l'utilisateur. Un slot public, \c findClicked(), est + défini pour prendre en charge le texte lorsque l'utilisateur clique sur + le bouton \uicontrol Find. + + Finalement, nous définissons les variables privées \c findButton, + \c lineEdit et \c findText, qui correspondent respectivement au bouton + \uicontrol Find, au champ de texte dans lequel l'utilisateur tape le texte + à rechercher, et à une variable interne stockant le texte pour une + utilisation ultérieure. + + \section1 Implémentation de la classe FindDialog + + Dans le constructeur de \c FindDialog, nous instancions les objets des + variables privées \c lineEdit, \c findButton et \c findText. Nous utilisons ensuite + un QHBoxLayout pour positionner les widgets. + + \snippet tutorials/addressbook/part5/finddialog.cpp constructor + + Nous mettons en place la mise en page et le titre de la fenêtre, et + nous connectons les signaux aux slots. Remarquez que le signal + \l{QPushButton::clicked()}{clicked()} de \c{findButton} est connecté + à \c findClicked() et \l{QDialog::accept()}{accept()}. Le slot + \l{QDialog::accept()}{accept()} fourni par le QDialog ferme + la boîte de dialogue et lui donne le code de retour \l{QDialog::}{Accepted}. + Nous utilisons cette fonction pour aider la méthode \c findContact() de la classe + \c{AddressBook} à savoir si l'objet \c FindDialog a été fermé. Ceci sera + expliqué plus loin lorsque nous verrons la méthode \c findContact(). + + \image addressbook-tutorial-part5-signals-and-slots.png + + Dans \c findClicked(), nous validons le champ de texte pour nous + assurer que l'utilisateur n'a pas cliqué sur le bouton \uicontrol Find sans + avoir entré un nom de contact. Ensuite, nous stockons le texte du champ + d'entrée \c lineEdit dans \c findText. Et finalement nous vidons le + contenu de \c lineEdit et cachons la boîte de dialogue. + + \snippet tutorials/addressbook/part5/finddialog.cpp findClicked() function + + La variable \c findText a un accesseur publique associé: \c getFindText(). + Étant donné que nous ne modifions \c findText directement que dans le + constructeur et la méthode \c findClicked(), nous ne créons pas + de manipulateurs associé à \c getFindText(). + Puisque \c getFindText() est publique, les classes instanciant et + utilisant \c FindDialog peuvent toujours accéder à la chaîne de + caractères que l'utilisateur a entré et accepté. + + \snippet tutorials/addressbook/part5/finddialog.cpp getFindText() function + + \section1 Définition de la classe AddressBook + + Pour utiliser \c FindDialog depuis la classe \c AddressBook, nous + incluons \c finddialog.h dans le fichier \c addressbook.h. + + \snippet tutorials/addressbook/part5/addressbook.h include finddialog's header + + Jusqu'ici, toutes les fonctionnalités du carnet d'adresses ont un + QPushButton et un slot correspondant. De la même façon, pour la + fonctionnalité \uicontrol Find, nous avons \c findButton et \c findContact(). + + Le \c findButton est déclaré comme une variable privée et la + méthode \c findContact() est déclarée comme un slot public. + + \snippet tutorials/addressbook/part5/addressbook.h findContact() declaration + \dots + \snippet tutorials/addressbook/part5/addressbook.h findButton declaration + + Finalement, nous déclarons la variable privée \c dialog que nous allons + utiliser pour accéder à une instance de \c FindDialog. + + \snippet tutorials/addressbook/part5/addressbook.h FindDialog declaration + + Une fois que nous avons instancié la boîte de dialogue, nous voulons l'utiliser + plus qu'une fois. Utiliser une variable privée nous permet d'y référer + à plus d'un endroit dans la classe. + + \section1 Implémentation de la classe AddressBook + + Dans le constructeur de \c AddressBook, nous instancions nos objets privés, + \c findbutton et \c findDialog: + + \snippet tutorials/addressbook/part5/addressbook.cpp instantiating findButton + \dots + \snippet tutorials/addressbook/part5/addressbook.cpp instantiating FindDialog + + Ensuite, nous connectons le signal \l{QPushButton::clicked()}{clicked()} de + \c{findButton} à \c findContact(). + + \snippet tutorials/addressbook/part5/addressbook.cpp signals and slots for find + + Maintenant, tout ce qui manque est le code de notre méthode \c findContact(): + + \snippet tutorials/addressbook/part5/addressbook.cpp findContact() function + + Nous commençons par afficher l'instance de \c FindDialog, \c dialog. + L'utilisateur peut alors entrer le nom du contact à rechercher. Lorsque + l'utilisateur clique sur le bouton \c findButton, la boîte de dialogue est + masquée et le code de retour devient QDialog::Accepted. Ce code de retour + vient remplir la condition du premier if. + + Ensuite, nous extrayons le texte que nous utiliserons pour la recherche, + il s'agit ici de \c contactName obtenu à l'aide de la méthode \c getFindText() + de \c FindDialog. Si le contact existe dans le carnet d'adresse, nous + l'affichons directement. Sinon, nous affichons le QMessageBox suivant pour + indiquer que la recherche à échouée. + + \image addressbook-tutorial-part5-notfound.png +*/ + +/*! + \page tutorials-addressbook-part6.html + + \example tutorials/addressbook-fr/part6 + \title Carnet d'Adresses 6 - Sauvegarde et chargement + + Ce chapitre couvre les fonctionnalités de gestion des fichiers de Qt que + l'on utilise pour écrire les procédures de sauvegarde et chargement pour + l'application carnet d'adresses. + + \image addressbook-tutorial-part6-screenshot.png + + Bien que la navigation et la recherche de contacts soient des + fonctionnalités importantes, notre carnet d'adresses ne sera pleinement + utilisable qu'une fois que l'on pourra sauvegarder les contacts existants + et les charger à nouveau par la suite. + Qt fournit de nombreuses classes pour gérer les \l{Input/Output and + Networking}{entrées et sorties}, mais nous avons choisi de nous contenter d'une + combinaison de deux classes simples à utiliser ensemble: QFile et QDataStream. + + Un objet QFile représente un fichier sur le disque qui peut être lu, et + dans lequel on peut écrire. QFile est une classe fille de la classe plus + générique QIODevice, qui peut représenter différents types de + périphériques. + + Un objet QDataStream est utilisé pour sérialiser des données binaires + dans le but de les passer à un QIODevice pour les récupérer dans le + futur. Pour lire ou écrire dans un QIODevice, il suffit d'ouvrir le + flux, avec le périphérique approprié en paramètre, et d'y lire ou + écrire. + + \section1 Définition de la classe AddressBook + + On déclare deux slots publics, \c saveToFile() et \c loadFromFile(), + ainsi que deux objets QPushButton, \c loadButton et \c saveButton. + + \snippet tutorials/addressbook/part6/addressbook.h save and load functions declaration + \dots + \snippet tutorials/addressbook/part6/addressbook.h save and load buttons declaration + + \section1 Implémentation de la classe AddressBook + + Dans notre constructeur, on instancie \c loadButton et \c saveButton. + Idéalement, l'interface serait plus conviviale avec des boutons + affichant "Load contacts from a file" et "Save contacts to a file". Mais + compte tenu de la dimension des autres boutons, on initialise les labels + des boutons à \uicontrol{Load...} et \uicontrol{Save...}. Heureusement, Qt offre une + façon simple d'ajouter des info-bulles avec + \l{QWidget::setToolTip()}{setToolTip()}, et nous l'exploitons de la façon + suivante pour nos boutons: + + \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 1 + \dots + \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 2 + + Bien qu'on ne cite pas le code correspondant ici, nous ajoutons ces deux boutons au + layout de droite, \c button1Layout, comme pour les fonctionnalités précédentes, et + nous connectons leurs signaux + \l{QPushButton::clicked()}{clicked()} à leurs slots respectifs. + + Pour la sauvegarde, on commence par récupérer le nom de fichier + \c fileName, en utilisant QFileDialog::getSaveFileName(). C'est une + méthode pratique fournie par QFileDialog, qui ouvre une boîte de + dialogue modale et permet à l'utilisateur d'entrer un nom de fichier ou + de choisir un fichier \c{.abk} existant. Les fichiers \c{.abk} + correspondent à l'extension choisie pour la sauvegarde des contacts de + notre carnet d'adresses. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part1 + + La boîte de dialogue affichée est visible sur la capture d'écran ci- + dessous. + + \image addressbook-tutorial-part6-save.png + + Si \c fileName n'est pas vide, on crée un objet QFile, \c file, à partir + de \c fileName. QFile fonctionne avec QDataStream puisqu'il dérive de + QIODevice. + + Ensuite, on essaie d'ouvrir le fichier en écriture, ce qui correspond au + mode \l{QIODevice::}{WriteOnly}. Si cela échoue, on en informe + l'utilisateur avec une QMessageBox. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part2 + + Dans le cas contraire, on instancie un objet QDataStream, \c out, afin + d'écrire dans le fichier ouvert. QDataStream nécessite que la même + version de flux soit utilisée pour la lecture et l'écriture. On s'assure + que c'est le cas en spécifiant explicitement d'utiliser la + \l{QDataStream::Qt_4_5}{version introduite avec Qt 4.5} avant de + sérialiser les données vers le fichier \c file. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part3 + + Pour le chargement, on récupère également \c fileName en utilisant + QFileDialog::getOpenFileName(). Cette méthode est l'homologue de + QFileDialog::getSaveFileName() et affiche également une boîte de + dialogue modale permettant à l'utilisateur d'entrer un nom de fichier ou + de selectionner un fichier \c{.abk} existant, afin de le charger dans le + carnet d'adresses. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part1 + + Sous Windows, par exemple, cette méthode affiche une boîte de dialogue + native pour la sélection de fichier, comme illustré sur la capture + d'écran suivante: + + \image addressbook-tutorial-part6-load.png + + Si \c fileName n'est pas vide, on utilise une fois de plus un objet + QFile, \c file, et on tente de l'ouvrir en lecture, avec le mode + \l{QIODevice::}{ReadOnly}. De même que précédemment dans notre + implémentation de \c saveToFile(), si cette tentative s'avère + infructueuse, on en informe l'utilisateur par le biais d'une + QMessageBox. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part2 + + Dans le cas contraire, on instancie un objet QDataStream, \c in, en + spécifiant la version à utiliser comme précédemment, et on lit les + informations sérialisées vers la structure de données \c contacts. Notez + qu'on purge \c contacts avant d'y mettre les informations lues afin de + simplifier le processus de lecture de fichier. Une façon plus avancée de + procéder serait de lire les contacts dans un objet QMap temporaire, et + de copier uniquement les contacts n'existant pas encore dans + \c contacts. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part3 + + Pour afficher les contacts lus depuis le fichier, on doit d'abord + valider les données obtenues afin de s'assurer que le fichier lu + contient effectivement des entrées de carnet d'adresses. Si c'est le + cas, on affiche le premier contact; sinon on informe l'utilisateur du + problème par une QMessageBox. Enfin, on met à jour l'interface afin + d'activer et de désactiver les boutons de façon appropriée. +*/ + +/*! + \page tutorials-addressbook-fr-part7.html + + \example tutorials/addressbook-fr/part7 + \title Carnet d'adresse 7 - Fonctionnalités avancées + + Ce chapitre couvre quelques fonctionnalités additionnelles qui + feront de notre carnet d'adresses une application plus pratique + pour une utilisation quotidienne. + + \image addressbook-tutorial-part7-screenshot.png + + Bien que notre application carnet d'adresses soit utile en tant que telle, + il serait pratique de pouvoir échanger les contacts avec d'autres applications. + Le format vCard est un un format de fichier populaire pour échanger + ce type de données. + Dans ce chapitre, nous étendrons notre carnet d'adresses pour permettre + d'exporter des contacts dans des fichiers vCard \c{.vcf}. + + \section1 Définition de la classe AddressBook + + Nous ajoutons un objet QPushButton, \c exportButton, et un slot + public correspondant, \c exportAsVCard(), à notre classe \c AddressBook + dans le fichier \c addressbook.h. + + \snippet tutorials/addressbook/part7/addressbook.h exportAsVCard() declaration + \dots + \snippet tutorials/addressbook/part7/addressbook.h exportButton declaration + + \section1 Implémentation de la classe AddressBook + + Dans le constructeur de \c AddressBook, nous connectons le signal + \l{QPushButton::clicked()}{clicked()} de \c{exportButton} au slot + \c exportAsVCard(). + Nous ajoutons aussi ce bouton à \c buttonLayout1, le layout responsable + du groupe de boutons sur la droite. + + Dans la méthode \c exportAsVCard(), nous commençons par extraire le + nom du contact dans \c name. Nous déclarons \c firstname, \c lastName et + \c nameList. + Ensuite, nous cherchons la position du premier espace blanc de \c name. + Si il y a un espace, nous séparons le nom du contact en \c firstName et + \c lastName. Finalement, nous remplaçons l'espace par un underscore ("_"). + Si il n'y a pas d'espace, nous supposons que le contact ne comprend que + le prénom. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part1 + + Comme pour la méthode \c saveToFile(), nous ouvrons une boîte de dialogue + pour donner la possibilité à l'utilisateur de choisir un emplacement pour + le fichier. Avec le nom de fichier choisi, nous créons une instance de QFile + pour y écrire. + + Nous essayons d'ouvrir le fichier en mode \l{QIODevice::}{WriteOnly}. Si + cela échoue, nous affichons un QMessageBox pour informer l'utilisateur + à propos de l'origine du problème et nous quittons la méthode. Sinon, nous passons le + fichier comme paramètre pour créer un objet QTextStream, \c out. De la même façon que + QDataStream, la classe QTextStream fournit les fonctionnalités pour + lire et écrire des fichiers de texte. Grâce à celà , le fichier \c{.vcf} + généré pourra être ouvert et édité à l'aide d'un simple éditeur de texte. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part2 + + Nous écrivons ensuite un fichier vCard avec la balise \c{BEGIN:VCARD}, + suivit par \c{VERSION:2.1}. + Le nom d'un contact est écrit à l'aide de la balise \c{N:}. Pour la balise + \c{FN:}, qui remplit le titre du contact, nous devons vérifier si le contact + à un nom de famille défini ou non. Si oui, nous utilions les détails de + \c nameList pour remplir le champ, dans le cas contraire on écrit uniquement le contenu + de \c firstName. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part3 + + Nous continuons en écrivant l'adresse du contact. Les points-virgules + dans l'adresse sont échappés à l'aide de "\\", les retours de ligne sont + remplacés par des points-virgules, et les vigules sont remplacées par des espaces. + Finalement nous écrivons les balises \c{ADR;HOME:;} suivies par l'adresse + et la balise \c{END:VCARD}. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part4 + + À la fin de la méthode, un QMessageBox est affiché pour informer l'utilisateur + que la vCard a été exportée avec succès. + + \e{vCard est une marque déposée de \l{http://www.imc.org} + {Internet Mail Consortium}}. +*/ diff --git a/examples/widgets/doc/src/addressbook-tutorial.qdoc b/examples/widgets/doc/src/addressbook-tutorial.qdoc new file mode 100644 index 0000000000..c1e39643f9 --- /dev/null +++ b/examples/widgets/doc/src/addressbook-tutorial.qdoc @@ -0,0 +1,979 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page tutorials-addressbook.html + + \title Address Book Tutorial + \brief An introduction to GUI programming, showing how to put together a + simple yet fully-functioning application. + + This tutorial is an introduction to GUI programming with the Qt + cross-platform framework. + + \image addressbook-tutorial-screenshot.png + + \omit + It doesn't cover everything; the emphasis is on teaching the programming + philosophy of GUI programming, and Qt's features are introduced as needed. + Some commonly used features are never used in this tutorial. + \endomit + + In this tutorial, you will learn about some of the basic + components of Qt, including: + + \list + \li Widgets and layout managers + \li Container classes + \li Signals and slots + \li Input and output devices + \endlist + + Tutorial contents: + + \list 1 + \li \l{tutorials/addressbook/part1}{Designing the User Interface} + \li \l{tutorials/addressbook/part2}{Adding Addresses} + \li \l{tutorials/addressbook/part3}{Navigating between Entries} + \li \l{tutorials/addressbook/part4}{Editing and Removing Addresses} + \li \l{tutorials/addressbook/part5}{Adding a Find Function} + \li \l{tutorials/addressbook/part6}{Loading and Saving} + \li \l{tutorials/addressbook/part7}{Additional Features} + \endlist + + The tutorial source code is located in \c{tutorials/addressbook}. + + Although this little application does not look much like a + fully-fledged modern GUI application, it uses many of the basic + elements that are used in more complex applications. After you + have worked through this tutorial, we recommend reading the + \l{mainwindows/application}{Application} example, which presents a + small GUI application, with menus, toolbars, a status bar, and so + on. +*/ + +/*! + \page tutorials-addressbook-part1.html + + \example tutorials/addressbook/part1 + \title Part 1 - Designing the User Interface + + This first part covers the design of the basic graphical user + interface (GUI) for our address book application. + + The first step in creating a GUI program is to design the user + interface. Here the our goal is to set up the labels and input + fields to implement a basic address book. The figure below is a + screenshot of the expected output. + + \image addressbook-tutorial-part1-screenshot.png + + We require two QLabel objects, \c nameLabel and \c addressLabel, as well + as two input fields, a QLineEdit object, \c nameLine, and a QTextEdit + object, \c addressText, to enable the user to enter a contact's name and + address. The widgets used and their positions are shown in the figure + below. + + \image addressbook-tutorial-part1-labeled-screenshot.png + + There are three files used to implement this address book: + + \list + \li \c{addressbook.h} - the definition file for the \c AddressBook + class, + \li \c{addressbook.cpp} - the implementation file for the + \c AddressBook class, and + \li \c{main.cpp} - the file containing a \c main() function, with + an instance of \c AddressBook. + \endlist + + \section1 Qt Programming - Subclassing + + When writing Qt programs, we usually subclass Qt objects to add + functionality. This is one of the essential concepts behind creating + custom widgets or collections of standard widgets. Subclassing to + extend or change the behavior of a widget has the following advantages: + + \list + \li We can write implementations of virtual or pure virtual functions to + obtain exactly what we need, falling back on the base class's implementation + when necessary. + \li It allows us to encapsulate parts of the user interface within a class, + so that the other parts of the application don't need to know about the + individual widgets in the user interface. + \li The subclass can be used to create multiple custom widgets in the same + application or library, and the code for the subclass can be reused in other + projects. + \endlist + + Since Qt does not provide a specific address book widget, we subclass a + standard Qt widget class and add features to it. The \c AddressBook class + we create in this tutorial can be reused in situations where a basic address + book widget is needed. + + \section1 Defining the AddressBook Class + + The \l{tutorials/addressbook/part1/addressbook.h}{\c addressbook.h} file is + used to define the \c AddressBook class. + + We start by defining \c AddressBook as a QWidget subclass and declaring + a constructor. We also use the Q_OBJECT macro to indicate that the class + uses internationalization and Qt's signals and slots features, even + if we do not use all of these features at this stage. + + \snippet tutorials/addressbook/part1/addressbook.h class definition + + The class holds declarations of \c nameLine and \c addressText, + the private instances of QLineEdit and QTextEdit mentioned + earlier. The data stored in \c nameLine and \c addressText will + be needed for many of the address book functions. + + We don't include declarations of the QLabel objects we will use + because we will not need to reference them once they have been + created. The way Qt tracks the ownership of objects is explained + in the next section. + + The Q_OBJECT macro itself implements some of the more advanced features of Qt. + For now, it is useful to think of the Q_OBJECT macro as a shortcut which allows + us to use the \l{QObject::}{tr()} and \l{QObject::}{connect()} functions. + + We have now completed the \c addressbook.h file and we move on to + implement the corresponding \c addressbook.cpp file. + + \section1 Implementing the AddressBook Class + + The constructor of \c AddressBook accepts a QWidget parameter, \a parent. + By convention, we pass this parameter to the base class's constructor. + This concept of ownership, where a parent can have one or more children, + is useful for grouping widgets in Qt. For example, if you delete a parent, + all of its children will be deleted as well. + + \snippet tutorials/addressbook/part1/addressbook.cpp constructor and input fields + + In this constructor, the QLabel objects \c nameLabel and \c + addressLabel are instantiated, as well as \c nameLine and \c + addressText. The \l{QObject::tr()}{tr()} function returns a + translated version of the string, if there is one + available. Otherwise it returns the string itself. This function + marks its QString parameter as one that should be translated into + other languages. It should be used wherever a translatable string + appears. + + When programming with Qt, it is useful to know how layouts work. + Qt provides three main layout classes: QHBoxLayout, QVBoxLayout + and QGridLayout to handle the positioning of widgets. + + \image addressbook-tutorial-part1-labeled-layout.png + + We use a QGridLayout to position our labels and input fields in a + structured manner. QGridLayout divides the available space into a grid and + places widgets in the cells we specify with row and column numbers. The + diagram above shows the layout cells and the position of our widgets, and + we specify this arrangement using the following code: + + \snippet tutorials/addressbook/part1/addressbook.cpp layout + + Notice that \c addressLabel is positioned using Qt::AlignTop as an + additional argument. This is to make sure it is not vertically centered in + cell (1,0). For a basic overview on Qt Layouts, refer to the + \l{Layout Management} documentation. + + In order to install the layout object onto the widget, we have to invoke + the widget's \l{QWidget::setLayout()}{setLayout()} function: + + \snippet tutorials/addressbook/part1/addressbook.cpp setting the layout + + Lastly, we set the widget's title to "Simple Address Book". + + \section1 Running the Application + + A separate file, \c main.cpp, is used for the \c main() function. Within + this function, we instantiate a QApplication object, \c app. QApplication + is responsible for various application-wide resources, such as the default + font and cursor, and for running an event loop. Hence, there is always one + QApplication object in every GUI application using Qt. + + \snippet tutorials/addressbook/part1/main.cpp main function + + We construct a new \c AddressBook widget on the stack and invoke + its \l{QWidget::show()}{show()} function to display it. + However, the widget will not be shown until the application's event loop + is started. We start the event loop by calling the application's + \l{QApplication::}{exec()} function; the result returned by this function + is used as the return value from the \c main() function. At this point, + it becomes apparent why we instanciated \c AddressBook on the stack: It + will now go out of scope. Therefore, \c AddressBook and all its child widgets + will be deleted, thus preventing memory leaks. +*/ + +/*! + \page tutorials-addressbook-part2.html + + \example tutorials/addressbook/part2 + \title Part 2 - Adding Addresses + + The next step in creating the address book is to implement some + user interactions. + + \image addressbook-tutorial-part2-add-contact.png + + We will provide a push button that the user can click to add a new contact. + Also, some form of data structure is needed to store these contacts in an + organized way. + + \section1 Defining the AddressBook Class + + Now that we have the labels and input fields set up, we add push buttons to + complete the process of adding a contact. This means that our + \c addressbook.h file now has three QPushButton objects declared and three + corresponding public slots. + + \snippet tutorials/addressbook/part2/addressbook.h slots + + A slot is a function that responds to a particular signal. We will discuss + this concept in further detail when implementing the \c AddressBook class. + However, for an overview of Qt's signals and slots concept, you can refer + to the \l{Signals and Slots} document. + + Three QPushButton objects (\c addButton, \c submitButton, and + \c cancelButton) are now included in our private variable declarations, + along with \c nameLine and \c addressText. + + \snippet tutorials/addressbook/part2/addressbook.h pushbutton declaration + + We need a container to store our address book contacts, so that we can + traverse and display them. A QMap object, \c contacts, is used for this + purpose as it holds a key-value pair: the contact's name as the \e key, + and the contact's address as the \e{value}. + + \snippet tutorials/addressbook/part2/addressbook.h remaining private variables + + We also declare two private QString objects, \c oldName and \c oldAddress. + These objects are needed to hold the name and address of the contact that + was last displayed, before the user clicked \uicontrol Add. So, when the user clicks + \uicontrol Cancel, we can revert to displaying the details of the last contact. + + \section1 Implementing the AddressBook Class + + Within the constructor of \c AddressBook, we set the \c nameLine and + \c addressText to read-only, so that we can only display but not edit + existing contact details. + + \dots + \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 1 + \dots + \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 2 + + Then, we instantiate our push buttons: \c addButton, \c submitButton, and + \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp pushbutton declaration + + The \c addButton is displayed by invoking the \l{QPushButton::show()} + {show()} function, while the \c submitButton and \c cancelButton are + hidden by invoking \l{QPushButton::hide()}{hide()}. These two push + buttons will only be displayed when the user clicks \uicontrol Add and this is + handled by the \c addContact() function discussed below. + + \snippet tutorials/addressbook/part2/addressbook.cpp connecting signals and slots + + We connect the push buttons' \l{QPushButton::clicked()}{clicked()} signal + to their respective slots. The figure below illustrates this. + + \image addressbook-tutorial-part2-signals-and-slots.png + + Next, we arrange our push buttons neatly to the right of our address book + widget, using a QVBoxLayout to line them up vertically. + + \snippet tutorials/addressbook/part2/addressbook.cpp vertical layout + + The \l{QBoxLayout::addStretch()}{addStretch()} function is used to ensure + the push buttons are not evenly spaced, but arranged closer to the top of + the widget. The figure below shows the difference between using + \l{QBoxLayout::addStretch()}{addStretch()} and not using it. + + \image addressbook-tutorial-part2-stretch-effects.png + + We then add \c buttonLayout1 to \c mainLayout, using + \l{QGridLayout::addLayout()}{addLayout()}. This gives us nested layouts + as \c buttonLayout1 is now a child of \c mainLayout. + + \snippet tutorials/addressbook/part2/addressbook.cpp grid layout + + Our layout coordinates now look like this: + + \image addressbook-tutorial-part2-labeled-layout.png + + In the \c addContact() function, we store the last displayed contact + details in \c oldName and \c oldAddress. Then we clear these input + fields and turn off the read-only mode. The focus is set on \c nameLine + and we display \c submitButton and \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp addContact + + The \c submitContact() function can be divided into three parts: + + \list 1 + \li We extract the contact's details from \c nameLine and \c addressText + and store them in QString objects. We also validate to make sure that the + user did not click \uicontrol Submit with empty input fields; otherwise, a + QMessageBox is displayed to remind the user for a name and address. + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part1 + + \li We then proceed to check if the contact already exists. If it does not + exist, we add the contact to \c contacts and we display a QMessageBox to + inform the user that the contact has been added. + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part2 + + If the contact already exists, again, we display a QMessageBox to inform + the user about this, preventing the user from adding duplicate contacts. + Our \c contacts object is based on key-value pairs of name and address, + hence, we want to ensure that \e key is unique. + + \li Once we have handled both cases mentioned above, we restore the push + buttons to their normal state with the following code: + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part3 + + \endlist + + The screenshot below shows the QMessageBox object we use to display + information messages to the user. + + \image addressbook-tutorial-part2-add-successful.png + + The \c cancel() function restores the last displayed contact details and + enables \c addButton, as well as hides \c submitButton and + \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp cancel + + The general idea behind adding a contact is to give the user the + flexibility to click \uicontrol Submit or \uicontrol Cancel at any time. The flowchart below + further explains this concept: + + \image addressbook-tutorial-part2-add-flowchart.png +*/ + +/*! + \page tutorials-addressbook-part3.html + + \example tutorials/addressbook/part3 + \title Part 3 - Navigating between Entries + + The address book is now about half complete. We should add the + capability to navigate among the contacts, but first we must + decide what sort of a data structure we need for containing these + contacts. + + In the previous section, we used a QMap of key-value pairs with + the contact's name as the \e key, and the contact's address as the + \e value. This works well for our case. However, in order to + navigate and display each entry, a little bit of enhancement is + needed. + + We enhance the QMap by making it replicate a data structure similar to a + circularly-linked list, where all elements are connected, including the + first element and the last element. The figure below illustrates this data + structure. + + \image addressbook-tutorial-part3-linkedlist.png + + \section1 Defining the AddressBook Class + + To add navigation functions to the address book, we must add two + more slots to the \c AddressBook class: \c next() and \c + previous() to the \c addressbook.h file: + + \snippet tutorials/addressbook/part3/addressbook.h navigation functions + + We also require another two QPushButton objects, so we declare \c nextButton + and \c previousButton as private variables: + + \snippet tutorials/addressbook/part3/addressbook.h navigation pushbuttons + + \section1 Implementing the AddressBook Class + + In the \c AddressBook constructor in \c addressbook.cpp, we instantiate + \c nextButton and \c previousButton and disable them by default. This is + because navigation is only enabled when there is more than one contact + in the address book. + + \snippet tutorials/addressbook/part3/addressbook.cpp navigation pushbuttons + + We then connect these push buttons to their respective slots: + + \snippet tutorials/addressbook/part3/addressbook.cpp connecting navigation signals + + The image below is the expected graphical user interface. + + \image addressbook-tutorial-part3-screenshot.png + + We follow basic conventions for \c next() and \c previous() functions by + placing the \c nextButton on the right and the \c previousButton on the + left. In order to achieve this intuitive layout, we use QHBoxLayout to + place the widgets side-by-side: + + \snippet tutorials/addressbook/part3/addressbook.cpp navigation layout + + The QHBoxLayout object, \c buttonLayout2, is then added to \c mainLayout. + + \snippet tutorials/addressbook/part3/addressbook.cpp adding navigation layout + + The figure below shows the coordinates of the widgets in \c mainLayout. + \image addressbook-tutorial-part3-labeled-layout.png + + Within our \c addContact() function, we have to disable these buttons so + that the user does not attempt to navigate while adding a contact. + + \snippet tutorials/addressbook/part3/addressbook.cpp disabling navigation + + Also, in our \c submitContact() function, we enable the navigation + buttons, \c nextButton and \c previousButton, depending on the size + of \c contacts. As mentioned earlier, navigation is only enabled when + there is more than one contact in the address book. The following lines + of code demonstrates how to do this: + + \snippet tutorials/addressbook/part3/addressbook.cpp enabling navigation + + We also include these lines of code in the \c cancel() function. + + Recall that we intend to emulate a circularly-linked list with our QMap + object, \c contacts. So, in the \c next() function, we obtain an iterator + for \c contacts and then: + + \list + \li If the iterator is not at the end of \c contacts, we increment it + by one. + \li If the iterator is at the end of \c contacts, we move it to the + beginning of \c contacts. This gives us the illusion that our QMap is + working like a circularly-linked list. + \endlist + + \snippet tutorials/addressbook/part3/addressbook.cpp next() function + + Once we have iterated to the correct object in \c contacts, we display + its contents on \c nameLine and \c addressText. + + Similarly, for the \c previous() function, we obtain an iterator for + \c contacts and then: + + \list + \li If the iterator is at the end of \c contacts, we clear the + display and return. + \li If the iterator is at the beginning of \c contacts, we move it to + the end. + \li We then decrement the iterator by one. + \endlist + + \snippet tutorials/addressbook/part3/addressbook.cpp previous() function + + Again, we display the contents of the current object in \c contacts. + +*/ + +/*! + \page tutorials-addressbook-part4.html + + \example tutorials/addressbook/part4 + \title Part 4 - Editing and Removing Addresses + + Now we look at ways to modify the contents of contacts stored in + the address book. + + \image addressbook-tutorial-screenshot.png + + We now have an address book that not only holds contacts in an + organized manner, but also allows navigation. It would be + convenient to include edit and remove functions so that a + contact's details can be changed when needed. However, this + requires a little improvement, in the form of enums. We defined + two modes: \c{AddingMode} and \c{NavigationMode}, but they were + not defined as enum values. Instead, we enabled and disabled the + corresponding buttons manually, resulting in multiple lines of + repeated code. + + Here we define the \c Mode enum with three different values: + + \list + \li \c{NavigationMode}, + \li \c{AddingMode}, and + \li \c{EditingMode}. + \endlist + + \section1 Defining the AddressBook Class + + The \c addressbook.h file is updated to contain the \c Mode enum: + + \snippet tutorials/addressbook/part4/addressbook.h Mode enum + + We also add two new slots, \c editContact() and \c removeContact(), to + our current list of public slots. + + \snippet tutorials/addressbook/part4/addressbook.h edit and remove slots + + In order to switch between modes, we introduce the \c updateInterface() function + to control the enabling and disabling of all QPushButton objects. We also + add two new push buttons, \c editButton and \c removeButton, for the edit + and remove functions mentioned earlier. + + \snippet tutorials/addressbook/part4/addressbook.h updateInterface() declaration + \dots + \snippet tutorials/addressbook/part4/addressbook.h buttons declaration + \dots + \snippet tutorials/addressbook/part4/addressbook.h mode declaration + + Lastly, we declare \c currentMode to keep track of the enum's current mode. + + \section1 Implementing the AddressBook Class + + We now implement the mode-changing features of the address + book. The \c editButton and \c removeButton are instantiated and + disabled by default. The address book starts with zero contacts + in memory. + + \snippet tutorials/addressbook/part4/addressbook.cpp edit and remove buttons + + These buttons are then connected to their respective slots, \c editContact() + and \c removeContact(), and we add them to \c buttonLayout1. + + \snippet tutorials/addressbook/part4/addressbook.cpp connecting edit and remove + \dots + \snippet tutorials/addressbook/part4/addressbook.cpp adding edit and remove to the layout + + The \c editContact() function stores the contact's old details in + \c oldName and \c oldAddress, before switching the mode to \c EditingMode. + In this mode, the \c submitButton and \c cancelButton are both enabled, + hence, the user can change the contact's details and click either button. + + \snippet tutorials/addressbook/part4/addressbook.cpp editContact() function + + The \c submitContact() function has been divided in two with an \c{if-else} + statement. We check \c currentMode to see if it's in \c AddingMode. If it is, + we proceed with our adding process. + + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function beginning + \dots + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part1 + + Otherwise, we check to see if \c currentMode is in \c EditingMode. If it + is, we compare \c oldName with \c name. If the name has changed, we remove + the old contact from \c contacts and insert the newly updated contact. + + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part2 + + If only the address has changed (i.e., \c oldAddress is not the same as \c address), + we update the contact's address. Lastly, we set \c currentMode to + \c NavigationMode. This is an important step as it re-enables all the + disabled push buttons. + + To remove a contact from the address book, we implement the + \c removeContact() function. This function checks to see if the contact + exists in \c contacts. + + \snippet tutorials/addressbook/part4/addressbook.cpp removeContact() function + + If it does, we display a QMessageBox, to confirm the removal with the + user. Once the user has confirmed, we call \c previous() to ensure that the + user interface shows another contact, and we remove the contact using \l{QMap}'s + \l{QMap::remove()}{remove()} function. As a courtesy, we display a QMessageBox + to inform the user. Both the message boxes used in this function are shown below: + + \image addressbook-tutorial-part4-remove.png + + \section2 Updating the User Interface + + We mentioned the \c updateInterface() function earlier as a means to + enable and disable the push buttons depending on the current mode. + The function updates the current mode according to the \c mode argument + passed to it, assigning it to \c currentMode before checking its value. + + Each of the push buttons is then enabled or disabled, depending on the + current mode. The code for \c AddingMode and \c EditingMode is shown below: + + \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 1 + + For \c NavigationMode, however, we include conditions within the parameters + of the QPushButton::setEnabled() function. This is to ensure that + \c editButton and \c removeButton are enabled when there is at least one + contact in the address book; \c nextButton and \c previousButton are only + enabled when there is more than one contact in the address book. + + \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 2 + + By setting the mode and updating the user interface in the same + function, we avoid the possibility of the user interface getting + out of sync with the internal state of the application. + */ + +/*! + \page tutorials-addressbook-part5.html + + \example tutorials/addressbook/part5 + \title Part 5 - Adding a Find Function + + Here we look at ways to locate contacts and addresses in the + address book. + + \image addressbook-tutorial-part5-screenshot.png + + As we add contacts to our address book, it becomes tedious to + navigate the list with the \e Next and \e Previous buttons. A \e + Find function would be more efficient. The screenshot above shows + the \e Find button and its position on the panel of buttons. + + When the user clicks on the \e Find button, it is useful to + display a dialog that prompts for a contact's name. Qt provides + QDialog, which we subclass here to implement a \c FindDialog + class. + + \section1 Defining the FindDialog Class + + \image addressbook-tutorial-part5-finddialog.png + + In order to subclass QDialog, we first include the header for QDialog in + the \c finddialog.h file. Also, we use forward declaration to declare + QLineEdit and QPushButton since we will be using those widgets in our + dialog class. + + As in our \c AddressBook class, the \c FindDialog class includes + the Q_OBJECT macro and its constructor is defined to accept a parent + QWidget, even though the dialog will be opened as a separate window. + + \snippet tutorials/addressbook/part5/finddialog.h FindDialog header + + We define a public function, \c getFindText(), to be used by classes that + instantiate \c FindDialog. This function allows these classes to obtain the + search string entered by the user. A public slot, \c findClicked(), is also + defined to handle the search string when the user clicks the \uicontrol Find + button. + + Lastly, we define the private variables, \c findButton, \c lineEdit + and \c findText, corresponding to the \uicontrol Find button, the line edit + into which the user types the search string, and an internal string + used to store the search string for later use. + + \section1 Implementing the FindDialog Class + + Within the constructor of \c FindDialog, we set up the private variables, + \c lineEdit, \c findButton and \c findText. We use a QHBoxLayout to + position the widgets. + + \snippet tutorials/addressbook/part5/finddialog.cpp constructor + + We set the layout and window title, as well as connect the signals to their + respective slots. Notice that \c{findButton}'s \l{QPushButton::clicked()} + {clicked()} signal is connected to to \c findClicked() and + \l{QDialog::accept()}{accept()}. The \l{QDialog::accept()}{accept()} slot + provided by QDialog hides the dialog and sets the result code to + \l{QDialog::}{Accepted}. We use this function to help \c{AddressBook}'s + \c findContact() function know when the \c FindDialog object has been + closed. We will explain this logic in further detail when discussing the + \c findContact() function. + + \image addressbook-tutorial-part5-signals-and-slots.png + + In \c findClicked(), we validate \c lineEdit to ensure that the user + did not click the \uicontrol Find button without entering a contact's name. Then, we set + \c findText to the search string, extracted from \c lineEdit. After that, + we clear the contents of \c lineEdit and hide the dialog. + + \snippet tutorials/addressbook/part5/finddialog.cpp findClicked() function + + The \c findText variable has a public getter function, \c getFindText(), + associated with it. Since we only ever set \c findText directly in both the + constructor and in the \c findClicked() function, we do not create a + setter function to accompany \c getFindText(). + Because \c getFindText() is public, classes instantiating and using + \c FindDialog can always access the search string that the user has + entered and accepted. + + \snippet tutorials/addressbook/part5/finddialog.cpp getFindText() function + + \section1 Defining the AddressBook Class + + To ensure we can use \c FindDialog from within our \c AddressBook class, we + include \c finddialog.h in the \c addressbook.h file. + + \snippet tutorials/addressbook/part5/addressbook.h include finddialog's header + + So far, all our address book features have a QPushButton and a + corresponding slot. Similarly, for the \uicontrol Find feature we have + \c findButton and \c findContact(). + + The \c findButton is declared as a private variable and the + \c findContact() function is declared as a public slot. + + \snippet tutorials/addressbook/part5/addressbook.h findContact() declaration + \dots + \snippet tutorials/addressbook/part5/addressbook.h findButton declaration + + Lastly, we declare the private variable, \c dialog, which we will use to + refer to an instance of \c FindDialog. + + \snippet tutorials/addressbook/part5/addressbook.h FindDialog declaration + + Once we have instantiated a dialog, we will want to use it more than once; + using a private variable allows us to refer to it from more than one place + in the class. + + \section1 Implementing the AddressBook Class + + Within the \c AddressBook class's constructor, we instantiate our private + objects, \c findButton and \c findDialog: + + \snippet tutorials/addressbook/part5/addressbook.cpp instantiating findButton + \dots + \snippet tutorials/addressbook/part5/addressbook.cpp instantiating FindDialog + + Next, we connect the \c{findButton}'s + \l{QPushButton::clicked()}{clicked()} signal to \c findContact(). + + \snippet tutorials/addressbook/part5/addressbook.cpp signals and slots for find + + Now all that is left is the code for our \c findContact() function: + + \snippet tutorials/addressbook/part5/addressbook.cpp findContact() function + + We start out by displaying the \c FindDialog instance, \c dialog. This is + when the user enters a contact name to look up. Once the user clicks + the dialog's \c findButton, the dialog is hidden and the result code is + set to QDialog::Accepted. This ensures that + our \c if statement is always true. + + We then proceed to extract the search string, which in this case is + \c contactName, using \c{FindDialog}'s \c getFindText() function. If the + contact exists in our address book, we display it immediately. Otherwise, + we display the QMessageBox shown below to indicate that their search + failed. + + \image addressbook-tutorial-part5-notfound.png +*/ + +/*! + \page tutorials-addressbook-part6.html + + \example tutorials/addressbook/part6 + \title Part 6 - Loading and Saving + + This part covers the Qt file handling features we use to write + loading and saving routines for the address book. + + \image addressbook-tutorial-part6-screenshot.png + + Although browsing and searching the contact list are useful + features, our address book is not complete until we can save + existing contacts and load them again at a later time. + + Qt provides a number of classes for \l{Input/Output and Networking} + {input and output}, but we have chosen to use two which are simple to use + in combination: QFile and QDataStream. + + A QFile object represents a file on disk that can be read from and written + to. QFile is a subclass of the more general QIODevice class which + represents many different kinds of devices. + + A QDataStream object is used to serialize binary data so that it can be + stored in a QIODevice and retrieved again later. Reading from a QIODevice + and writing to it is as simple as opening the stream - with the respective + device as a parameter - and reading from or writing to it. + + + \section1 Defining the AddressBook Class + + We declare two public slots, \c saveToFile() and \c loadFromFile(), as well + as two QPushButton objects, \c loadButton and \c saveButton. + + \snippet tutorials/addressbook/part6/addressbook.h save and load functions declaration + \dots + \snippet tutorials/addressbook/part6/addressbook.h save and load buttons declaration + + \section1 Implementing the AddressBook Class + + In our constructor, we instantiate \c loadButton and \c saveButton. + Ideally, it would be more user-friendly to set the push buttons' labels + to "Load contacts from a file" and "Save contacts to a file". However, due + to the size of our other push buttons, we set the labels to \uicontrol{Load...} + and \uicontrol{Save...}. Fortunately, Qt provides a simple way to set tooltips with + \l{QWidget::setToolTip()}{setToolTip()} and we use it in the following way + for our push buttons: + + \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 1 + \dots + \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 2 + + Although it is not shown here, just like the other features we implemented, + we add the push buttons to the layout panel on the right, \c buttonLayout1, + and we connect the push buttons' \l{QPushButton::clicked()}{clicked()} + signals to their respective slots. + + For the saving feature, we first obtain \c fileName using + QFileDialog::getSaveFileName(). This is a convenience function provided + by QFileDialog, which pops up a modal file dialog and allows the user to + enter a file name or select any existing \c{.abk} file. The \c{.abk} file + is our Address Book extension that we create when we save contacts. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part1 + + The file dialog that pops up is displayed in the screenshot below: + + \image addressbook-tutorial-part6-save.png + + If \c fileName is not empty, we create a QFile object, \c file, with + \c fileName. QFile works with QDataStream as QFile is a QIODevice. + + Next, we attempt to open the file in \l{QIODevice::}{WriteOnly} mode. + If this is unsuccessful, we display a QMessageBox to inform the user. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part2 + + Otherwise, we instantiate a QDataStream object, \c out, to write the open + file. QDataStream requires that the same version of the stream is used + for reading and writing. We ensure that this is the case by setting the + version used to the \l{QDataStream::Qt_4_5}{version introduced with Qt 4.5} + before serializing the data to \c file. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part3 + + For the loading feature, we also obtain \c fileName using + QFileDialog::getOpenFileName(). This function, the counterpart to + QFileDialog::getSaveFileName(), also pops up the modal file dialog and + allows the user to enter a file name or select any existing \c{.abk} file + to load it into the address book. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part1 + + On Windows, for example, this function pops up a native file dialog, as + shown in the following screenshot. + + \image addressbook-tutorial-part6-load.png + + If \c fileName is not empty, again, we use a QFile object, \c file, and + attempt to open it in \l{QIODevice::}{ReadOnly} mode. Similar to our + implementation of \c saveToFile(), if this attempt is unsuccessful, we + display a QMessageBox to inform the user. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part2 + + Otherwise, we instantiate a QDataStream object, \c in, set its version as + above and read the serialized data into the \c contacts data structure. + The \c contacts object is emptied before data is read into it to simplify + the file reading process. A more advanced method would be to read the + contacts into a temporary QMap object, and copy over non-duplicate contacts + into \c contacts. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part3 + + To display the contacts that have been read from the file, we must first + validate the data obtained to ensure that the file we read from actually + contains address book contacts. If it does, we display the first contact; + otherwise, we display a QMessageBox to inform the user about the problem. + Lastly, we update the interface to enable and disable the push buttons + accordingly. +*/ + +/*! + \page tutorials-addressbook-part7.html + + \example tutorials/addressbook/part7 + \title Part 7 - Additional Features + + This part covers some additional features that make the address + book more convenient for the frequent user. + + \image addressbook-tutorial-part7-screenshot.png + + Although our address book is useful in isolation, it would be + better if we could exchange contact data with other applications. + The vCard format is a popular file format that can be used for + this purpose. Here we extend our address book client to allow + contacts to be exported to vCard \c{.vcf} files. + + \section1 Defining the AddressBook Class + + We add a QPushButton object, \c exportButton, and a corresponding public + slot, \c exportAsVCard() to our \c AddressBook class in the + \c addressbook.h file. + + \snippet tutorials/addressbook/part7/addressbook.h exportAsVCard() declaration + \dots + \snippet tutorials/addressbook/part7/addressbook.h exportButton declaration + + \section1 Implementing the AddressBook Class + + Within the \c AddressBook constructor, we connect \c{exportButton}'s + \l{QPushButton::clicked()}{clicked()} signal to \c exportAsVCard(). + We also add this button to our \c buttonLayout1, the layout responsible + for our panel of buttons on the right. + + In our \c exportAsVCard() function, we start by extracting the contact's + name into \c name. We declare \c firstName, \c lastName and \c nameList. + Next, we look for the index of the first white space in \c name. If there + is a white space, we split the contact's name into \c firstName and + \c lastName. Then, we replace the space with an underscore ("_"). + Alternately, if there is no white space, we assume that the contact only + has a first name. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part1 + + As with the \c saveToFile() function, we open a file dialog to let the user + choose a location for the file. Using the file name chosen, we create an + instance of QFile to write to. + + We attempt to open the file in \l{QIODevice::}{WriteOnly} mode. If this + process fails, we display a QMessageBox to inform the user about the + problem and return. Otherwise, we pass the file as a parameter to a + QTextStream object, \c out. Like QDataStream, the QTextStream class + provides functionality to read and write plain text to files. As a result, + the \c{.vcf} file generated can be opened for editing in a text editor. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part2 + + We then write out a vCard file with the \c{BEGIN:VCARD} tag, followed by + the \c{VERSION:2.1} tag. The contact's name is written with the \c{N:} + tag. For the \c{FN:} tag, which fills in the "File as" property of a vCard, + we have to check whether the contact has a last name or not. If the contact + does, we use the details in \c nameList to fill it. Otherwise, we write + \c firstName only. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part3 + + We proceed to write the contact's address. The semicolons in the address + are escaped with "\\", the newlines are replaced with semicolons, and the + commas are replaced with spaces. Lastly, we write the \c{ADR;HOME:;} + tag, followed by \c address and then the \c{END:VCARD} tag. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part4 + + In the end, a QMessageBox is displayed to inform the user that the vCard + has been successfully exported. + + \e{vCard is a trademark of the \l{http://www.imc.org} + {Internet Mail Consortium}}. +*/ diff --git a/examples/widgets/doc/addressbook.qdoc b/examples/widgets/doc/src/addressbook.qdoc index 9b4ede5775..9b4ede5775 100644 --- a/examples/widgets/doc/addressbook.qdoc +++ b/examples/widgets/doc/src/addressbook.qdoc diff --git a/examples/widgets/doc/affine.qdoc b/examples/widgets/doc/src/affine.qdoc index c69794d511..c69794d511 100644 --- a/examples/widgets/doc/affine.qdoc +++ b/examples/widgets/doc/src/affine.qdoc diff --git a/examples/widgets/doc/analogclock.qdoc b/examples/widgets/doc/src/analogclock.qdoc index bb4bdb54ae..bb4bdb54ae 100644 --- a/examples/widgets/doc/analogclock.qdoc +++ b/examples/widgets/doc/src/analogclock.qdoc diff --git a/examples/widgets/doc/animatedtiles.qdoc b/examples/widgets/doc/src/animatedtiles.qdoc index 4fe25388cf..4fe25388cf 100644 --- a/examples/widgets/doc/animatedtiles.qdoc +++ b/examples/widgets/doc/src/animatedtiles.qdoc diff --git a/examples/widgets/doc/appchooser.qdoc b/examples/widgets/doc/src/appchooser.qdoc index 092db7c29e..092db7c29e 100644 --- a/examples/widgets/doc/appchooser.qdoc +++ b/examples/widgets/doc/src/appchooser.qdoc diff --git a/examples/widgets/doc/application.qdoc b/examples/widgets/doc/src/application.qdoc index 5465f99e99..5465f99e99 100644 --- a/examples/widgets/doc/application.qdoc +++ b/examples/widgets/doc/src/application.qdoc diff --git a/examples/widgets/doc/src/applicationicon.qdoc b/examples/widgets/doc/src/applicationicon.qdoc new file mode 100644 index 0000000000..8c8f762894 --- /dev/null +++ b/examples/widgets/doc/src/applicationicon.qdoc @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! \example widgets/applicationicon + \group all-examples + \title Application Icon Example + + The example shows how to add an application icon to a mobile application. + + \image appicon_screenshot.png The icon on a Nokia XPressMusic 5800 + + \section1 Creating an icon for Maemo + + Maemo expects the icon of an application to be a 64x64 PNG image file. The + file name of the icon should be the same as the executable with a \c .png + extension. You also need a \c .desktop file that gives the window manager + hints about the application, such as name, type and icon. + + \quotefile applicationicon/applicationicon.desktop + + The \c Icon field should also contain the name of the executable. On the + device, application icons are stored in the + \c /usr/share/icons/hicolor/64x64/apps directory + and desktop files in the \c /usr/share/applications/hildon directory. + + \section1 Adding the icons to the project + + For Maemo, we need to add that the \c .desktop and icon file should be + installed. + + \quotefile applicationicon/applicationicon.pro + + Currently, Qt Creator doesn't include the icon and desktop files in the + application package for Maemo, merely the executable file is included. As a + workaround for this, the files can be added manually in the Projects tab. + In the "Create Package" build step for the Maemo target, the \c .desktop + file and icon can be added to be a part of the package contents. + Unfortunately, these additions are only stored as a part of the + \c .pro.user file. This issue will be resolved in a future release of + Qt Creator. + + \image appicon_packagecontents.png Manual addition of files to the "Create Package" build step +*/ diff --git a/examples/widgets/doc/basicdrawing.qdoc b/examples/widgets/doc/src/basicdrawing.qdoc index 899aa361f8..899aa361f8 100644 --- a/examples/widgets/doc/basicdrawing.qdoc +++ b/examples/widgets/doc/src/basicdrawing.qdoc diff --git a/examples/widgets/doc/basicgraphicslayouts.qdoc b/examples/widgets/doc/src/basicgraphicslayouts.qdoc index 9f52b3eafa..9f52b3eafa 100644 --- a/examples/widgets/doc/basicgraphicslayouts.qdoc +++ b/examples/widgets/doc/src/basicgraphicslayouts.qdoc diff --git a/examples/widgets/doc/basiclayouts.qdoc b/examples/widgets/doc/src/basiclayouts.qdoc index a0f083ba58..a0f083ba58 100644 --- a/examples/widgets/doc/basiclayouts.qdoc +++ b/examples/widgets/doc/src/basiclayouts.qdoc diff --git a/examples/widgets/doc/basicsortfiltermodel.qdoc b/examples/widgets/doc/src/basicsortfiltermodel.qdoc index 0ecf4a0629..0ecf4a0629 100644 --- a/examples/widgets/doc/basicsortfiltermodel.qdoc +++ b/examples/widgets/doc/src/basicsortfiltermodel.qdoc diff --git a/examples/widgets/doc/blurpicker.qdoc b/examples/widgets/doc/src/blurpicker.qdoc index bd57acb061..bd57acb061 100644 --- a/examples/widgets/doc/blurpicker.qdoc +++ b/examples/widgets/doc/src/blurpicker.qdoc diff --git a/examples/widgets/doc/borderlayout.qdoc b/examples/widgets/doc/src/borderlayout.qdoc index aaff2dda1d..aaff2dda1d 100644 --- a/examples/widgets/doc/borderlayout.qdoc +++ b/examples/widgets/doc/src/borderlayout.qdoc diff --git a/examples/widgets/doc/boxes.qdoc b/examples/widgets/doc/src/boxes.qdoc index aa34a61bc3..aa34a61bc3 100644 --- a/examples/widgets/doc/boxes.qdoc +++ b/examples/widgets/doc/src/boxes.qdoc diff --git a/examples/widgets/doc/calculator.qdoc b/examples/widgets/doc/src/calculator.qdoc index 8480d90477..8480d90477 100644 --- a/examples/widgets/doc/calculator.qdoc +++ b/examples/widgets/doc/src/calculator.qdoc diff --git a/examples/widgets/doc/calendar.qdoc b/examples/widgets/doc/src/calendar.qdoc index b7fa7c8617..b7fa7c8617 100644 --- a/examples/widgets/doc/calendar.qdoc +++ b/examples/widgets/doc/src/calendar.qdoc diff --git a/examples/widgets/doc/calendarwidget.qdoc b/examples/widgets/doc/src/calendarwidget.qdoc index c6e86d1668..c6e86d1668 100644 --- a/examples/widgets/doc/calendarwidget.qdoc +++ b/examples/widgets/doc/src/calendarwidget.qdoc diff --git a/examples/widgets/doc/charactermap.qdoc b/examples/widgets/doc/src/charactermap.qdoc index fee2a42156..fee2a42156 100644 --- a/examples/widgets/doc/charactermap.qdoc +++ b/examples/widgets/doc/src/charactermap.qdoc diff --git a/examples/widgets/doc/chart.qdoc b/examples/widgets/doc/src/chart.qdoc index 44263d1027..44263d1027 100644 --- a/examples/widgets/doc/chart.qdoc +++ b/examples/widgets/doc/src/chart.qdoc diff --git a/examples/widgets/doc/chip.qdoc b/examples/widgets/doc/src/chip.qdoc index 966c16900a..966c16900a 100644 --- a/examples/widgets/doc/chip.qdoc +++ b/examples/widgets/doc/src/chip.qdoc diff --git a/examples/widgets/doc/classwizard.qdoc b/examples/widgets/doc/src/classwizard.qdoc index 0c357b7286..0c357b7286 100644 --- a/examples/widgets/doc/classwizard.qdoc +++ b/examples/widgets/doc/src/classwizard.qdoc diff --git a/examples/widgets/doc/codeeditor.qdoc b/examples/widgets/doc/src/codeeditor.qdoc index 695ac5c4ce..695ac5c4ce 100644 --- a/examples/widgets/doc/codeeditor.qdoc +++ b/examples/widgets/doc/src/codeeditor.qdoc diff --git a/examples/widgets/doc/coloreditorfactory.qdoc b/examples/widgets/doc/src/coloreditorfactory.qdoc index a2c02f8c1d..a2c02f8c1d 100644 --- a/examples/widgets/doc/coloreditorfactory.qdoc +++ b/examples/widgets/doc/src/coloreditorfactory.qdoc diff --git a/examples/widgets/doc/combowidgetmapper.qdoc b/examples/widgets/doc/src/combowidgetmapper.qdoc index 949014930d..949014930d 100644 --- a/examples/widgets/doc/combowidgetmapper.qdoc +++ b/examples/widgets/doc/src/combowidgetmapper.qdoc diff --git a/examples/widgets/doc/composition.qdoc b/examples/widgets/doc/src/composition.qdoc index 6aca01d255..6aca01d255 100644 --- a/examples/widgets/doc/composition.qdoc +++ b/examples/widgets/doc/src/composition.qdoc diff --git a/examples/widgets/doc/concentriccircles.qdoc b/examples/widgets/doc/src/concentriccircles.qdoc index 67bc125dbe..67bc125dbe 100644 --- a/examples/widgets/doc/concentriccircles.qdoc +++ b/examples/widgets/doc/src/concentriccircles.qdoc diff --git a/examples/widgets/doc/configdialog.qdoc b/examples/widgets/doc/src/configdialog.qdoc index 9acea72a3b..9acea72a3b 100644 --- a/examples/widgets/doc/configdialog.qdoc +++ b/examples/widgets/doc/src/configdialog.qdoc diff --git a/examples/widgets/doc/customsortfiltermodel.qdoc b/examples/widgets/doc/src/customsortfiltermodel.qdoc index 4dce820f9c..4dce820f9c 100644 --- a/examples/widgets/doc/customsortfiltermodel.qdoc +++ b/examples/widgets/doc/src/customsortfiltermodel.qdoc diff --git a/examples/widgets/doc/deform.qdoc b/examples/widgets/doc/src/deform.qdoc index 8195f90ffa..8195f90ffa 100644 --- a/examples/widgets/doc/deform.qdoc +++ b/examples/widgets/doc/src/deform.qdoc diff --git a/examples/widgets/doc/diagramscene.qdoc b/examples/widgets/doc/src/diagramscene.qdoc index b61a936d52..b61a936d52 100644 --- a/examples/widgets/doc/diagramscene.qdoc +++ b/examples/widgets/doc/src/diagramscene.qdoc diff --git a/examples/widgets/doc/digitalclock.qdoc b/examples/widgets/doc/src/digitalclock.qdoc index 92e8003205..92e8003205 100644 --- a/examples/widgets/doc/digitalclock.qdoc +++ b/examples/widgets/doc/src/digitalclock.qdoc diff --git a/examples/widgets/doc/dirview.qdoc b/examples/widgets/doc/src/dirview.qdoc index a4b799678a..a4b799678a 100644 --- a/examples/widgets/doc/dirview.qdoc +++ b/examples/widgets/doc/src/dirview.qdoc diff --git a/examples/widgets/doc/dockwidgets.qdoc b/examples/widgets/doc/src/dockwidgets.qdoc index 12f18a538f..12f18a538f 100644 --- a/examples/widgets/doc/dockwidgets.qdoc +++ b/examples/widgets/doc/src/dockwidgets.qdoc diff --git a/examples/widgets/doc/draganddroppuzzle.qdoc b/examples/widgets/doc/src/draganddroppuzzle.qdoc index d0d336f70f..2c90998dc1 100644 --- a/examples/widgets/doc/draganddroppuzzle.qdoc +++ b/examples/widgets/doc/src/draganddroppuzzle.qdoc @@ -26,7 +26,7 @@ ****************************************************************************/ /*! - \example widgets/draganddrop/puzzle + \example draganddrop/puzzle \title Drag and Drop Puzzle Example The Drag and Drop Puzzle example demonstrates a way of using the drag and drop system with diff --git a/examples/widgets/doc/dragdroprobot.qdoc b/examples/widgets/doc/src/dragdroprobot.qdoc index 60bd4eb4d8..60bd4eb4d8 100644 --- a/examples/widgets/doc/dragdroprobot.qdoc +++ b/examples/widgets/doc/src/dragdroprobot.qdoc diff --git a/examples/widgets/doc/src/draggableicons.qdoc b/examples/widgets/doc/src/draggableicons.qdoc new file mode 100644 index 0000000000..627aa673e0 --- /dev/null +++ b/examples/widgets/doc/src/draggableicons.qdoc @@ -0,0 +1,90 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example draganddrop/draggableicons + \title Draggable Icons Example + + The Draggable Icons example shows how to drag and drop image data between widgets + in the same application, and between different applications. + + \image draggableicons-example.png + + In many situations where drag and drop is used, the user starts dragging from + a particular widget and drops the payload onto another widget. In this example, + we subclass QLabel to create labels that we use as drag sources, and place them + inside \l{QWidget}s that serve as both containers and drop sites. + + In addition, when a drag and drop operation occurs, we want to send more than + just an image. We also want to send information about where the user clicked in + the image so that the user can place it precisely on the drop target. This level + of detail means that we must create a custom MIME type for our data. + + \section1 DragWidget Class Definition + + The icon widgets that we use to display icons are subclassed from QLabel: + + \snippet draganddrop/draggableicons/dragwidget.h 0 + + Since the QLabel class provides most of what we require for the icon, we + only need to reimplement the \l QWidget::mousePressEvent() to provide + drag and drop facilities. + + \section1 DragWidget Class Implementation + + The \c DragWidget constructor sets an attribute on the widget that ensures + that it will be deleted when it is closed: + + \snippet draganddrop/draggableicons/dragwidget.cpp 0 + + To enable dragging from the icon, we need to act on a mouse press event. + We do this by reimplementing \l QWidget::mousePressEvent() and setting up + a QDrag object. + + \snippet draganddrop/draggableicons/dragwidget.cpp 1 + + Since we will be sending pixmap data for the icon and information about the + user's click in the icon widget, we construct a QByteArray and package up the + details using a QDataStream. + + For interoperability, drag and drop operations describe the data they contain + using MIME types. In Qt, we describe this data using a QMimeData object: + + \snippet draganddrop/draggableicons/dragwidget.cpp 2 + + We choose an unofficial MIME type for this purpose, and supply the QByteArray + to the MIME data object. + + The drag and drop operation itself is handled by a QDrag object: + + \snippet draganddrop/draggableicons/dragwidget.cpp 3 + + Here, we pass the data to the drag object, set a pixmap that will be shown + alongside the cursor during the operation, and define the position of a hot + spot that places the position of this pixmap under the cursor. + +*/ diff --git a/examples/widgets/doc/src/draggabletext.qdoc b/examples/widgets/doc/src/draggabletext.qdoc new file mode 100644 index 0000000000..d497206f8b --- /dev/null +++ b/examples/widgets/doc/src/draggabletext.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example draganddrop/draggabletext + \title Draggable Text Example + + The Draggable Text example shows how to drag and drop textual data between widgets + in the same application, and between different applications. + + \image draggabletext-example.png +*/ diff --git a/examples/widgets/doc/dynamiclayouts.qdoc b/examples/widgets/doc/src/dynamiclayouts.qdoc index 318f719503..318f719503 100644 --- a/examples/widgets/doc/dynamiclayouts.qdoc +++ b/examples/widgets/doc/src/dynamiclayouts.qdoc diff --git a/examples/widgets/doc/easing.qdoc b/examples/widgets/doc/src/easing.qdoc index 7fb7f59531..7fb7f59531 100644 --- a/examples/widgets/doc/easing.qdoc +++ b/examples/widgets/doc/src/easing.qdoc diff --git a/examples/widgets/doc/editabletreemodel.qdoc b/examples/widgets/doc/src/editabletreemodel.qdoc index 24745b77b8..24745b77b8 100644 --- a/examples/widgets/doc/editabletreemodel.qdoc +++ b/examples/widgets/doc/src/editabletreemodel.qdoc diff --git a/examples/widgets/doc/elasticnodes.qdoc b/examples/widgets/doc/src/elasticnodes.qdoc index 17f14124f8..17f14124f8 100644 --- a/examples/widgets/doc/elasticnodes.qdoc +++ b/examples/widgets/doc/src/elasticnodes.qdoc diff --git a/examples/widgets/doc/elidedlabel.qdoc b/examples/widgets/doc/src/elidedlabel.qdoc index 2ce469d85f..2ce469d85f 100644 --- a/examples/widgets/doc/elidedlabel.qdoc +++ b/examples/widgets/doc/src/elidedlabel.qdoc diff --git a/examples/widgets/doc/embeddeddialogs.qdoc b/examples/widgets/doc/src/embeddeddialogs.qdoc index 24b3abdb37..24b3abdb37 100644 --- a/examples/widgets/doc/embeddeddialogs.qdoc +++ b/examples/widgets/doc/src/embeddeddialogs.qdoc diff --git a/examples/widgets/doc/eventtransitions.qdoc b/examples/widgets/doc/src/eventtransitions.qdoc index ef3f657c3d..ef3f657c3d 100644 --- a/examples/widgets/doc/eventtransitions.qdoc +++ b/examples/widgets/doc/src/eventtransitions.qdoc diff --git a/examples/widgets/doc/extension.qdoc b/examples/widgets/doc/src/extension.qdoc index 040d5d38d9..040d5d38d9 100644 --- a/examples/widgets/doc/extension.qdoc +++ b/examples/widgets/doc/src/extension.qdoc diff --git a/examples/widgets/doc/factorial.qdoc b/examples/widgets/doc/src/factorial.qdoc index 82ab5da536..82ab5da536 100644 --- a/examples/widgets/doc/factorial.qdoc +++ b/examples/widgets/doc/src/factorial.qdoc diff --git a/examples/widgets/doc/fademessage.qdoc b/examples/widgets/doc/src/fademessage.qdoc index 48f98c03ad..48f98c03ad 100644 --- a/examples/widgets/doc/fademessage.qdoc +++ b/examples/widgets/doc/src/fademessage.qdoc diff --git a/examples/widgets/doc/fetchmore.qdoc b/examples/widgets/doc/src/fetchmore.qdoc index 7ea0b30edf..7ea0b30edf 100644 --- a/examples/widgets/doc/fetchmore.qdoc +++ b/examples/widgets/doc/src/fetchmore.qdoc diff --git a/examples/widgets/doc/findfiles.qdoc b/examples/widgets/doc/src/findfiles.qdoc index 594d57472c..594d57472c 100644 --- a/examples/widgets/doc/findfiles.qdoc +++ b/examples/widgets/doc/src/findfiles.qdoc diff --git a/examples/widgets/doc/flowlayout.qdoc b/examples/widgets/doc/src/flowlayout.qdoc index b08b2283aa..b08b2283aa 100644 --- a/examples/widgets/doc/flowlayout.qdoc +++ b/examples/widgets/doc/src/flowlayout.qdoc diff --git a/examples/widgets/doc/fontsampler.qdoc b/examples/widgets/doc/src/fontsampler.qdoc index 8d7f0e0460..8d7f0e0460 100644 --- a/examples/widgets/doc/fontsampler.qdoc +++ b/examples/widgets/doc/src/fontsampler.qdoc diff --git a/examples/widgets/doc/frozencolumn.qdoc b/examples/widgets/doc/src/frozencolumn.qdoc index c65ce1d524..c65ce1d524 100644 --- a/examples/widgets/doc/frozencolumn.qdoc +++ b/examples/widgets/doc/src/frozencolumn.qdoc diff --git a/examples/widgets/doc/gradients.qdoc b/examples/widgets/doc/src/gradients.qdoc index 75f78b56ea..75f78b56ea 100644 --- a/examples/widgets/doc/gradients.qdoc +++ b/examples/widgets/doc/src/gradients.qdoc diff --git a/examples/widgets/doc/groupbox.qdoc b/examples/widgets/doc/src/groupbox.qdoc index d7384d409a..d7384d409a 100644 --- a/examples/widgets/doc/groupbox.qdoc +++ b/examples/widgets/doc/src/groupbox.qdoc diff --git a/examples/widgets/doc/icons.qdoc b/examples/widgets/doc/src/icons.qdoc index b6625db005..b6625db005 100644 --- a/examples/widgets/doc/icons.qdoc +++ b/examples/widgets/doc/src/icons.qdoc diff --git a/examples/widgets/doc/imagecomposition.qdoc b/examples/widgets/doc/src/imagecomposition.qdoc index 3f06f377b4..3f06f377b4 100644 --- a/examples/widgets/doc/imagecomposition.qdoc +++ b/examples/widgets/doc/src/imagecomposition.qdoc diff --git a/examples/widgets/doc/imageviewer.qdoc b/examples/widgets/doc/src/imageviewer.qdoc index 3556d52f7e..3556d52f7e 100644 --- a/examples/widgets/doc/imageviewer.qdoc +++ b/examples/widgets/doc/src/imageviewer.qdoc diff --git a/examples/widgets/doc/interview.qdoc b/examples/widgets/doc/src/interview.qdoc index 35721ccfae..35721ccfae 100644 --- a/examples/widgets/doc/interview.qdoc +++ b/examples/widgets/doc/src/interview.qdoc diff --git a/examples/widgets/doc/itemviewspuzzle.qdoc b/examples/widgets/doc/src/itemviewspuzzle.qdoc index ca8288cf1c..ca8288cf1c 100644 --- a/examples/widgets/doc/itemviewspuzzle.qdoc +++ b/examples/widgets/doc/src/itemviewspuzzle.qdoc diff --git a/examples/widgets/doc/licensewizard.qdoc b/examples/widgets/doc/src/licensewizard.qdoc index 125e0fec8f..125e0fec8f 100644 --- a/examples/widgets/doc/licensewizard.qdoc +++ b/examples/widgets/doc/src/licensewizard.qdoc diff --git a/examples/widgets/doc/lighting.qdoc b/examples/widgets/doc/src/lighting.qdoc index aafa70f38c..aafa70f38c 100644 --- a/examples/widgets/doc/lighting.qdoc +++ b/examples/widgets/doc/src/lighting.qdoc diff --git a/examples/widgets/doc/lineedits.qdoc b/examples/widgets/doc/src/lineedits.qdoc index c9cb7b5f43..c9cb7b5f43 100644 --- a/examples/widgets/doc/lineedits.qdoc +++ b/examples/widgets/doc/src/lineedits.qdoc diff --git a/examples/widgets/doc/mainwindow.qdoc b/examples/widgets/doc/src/mainwindow.qdoc index b4f6aebed1..b4f6aebed1 100644 --- a/examples/widgets/doc/mainwindow.qdoc +++ b/examples/widgets/doc/src/mainwindow.qdoc diff --git a/examples/widgets/doc/mdi.qdoc b/examples/widgets/doc/src/mdi.qdoc index e8b1b5c9ef..e8b1b5c9ef 100644 --- a/examples/widgets/doc/mdi.qdoc +++ b/examples/widgets/doc/src/mdi.qdoc diff --git a/examples/widgets/doc/menus.qdoc b/examples/widgets/doc/src/menus.qdoc index 3531e439c1..3531e439c1 100644 --- a/examples/widgets/doc/menus.qdoc +++ b/examples/widgets/doc/src/menus.qdoc diff --git a/examples/widgets/doc/moveblocks.qdoc b/examples/widgets/doc/src/moveblocks.qdoc index 8c12280989..8c12280989 100644 --- a/examples/widgets/doc/moveblocks.qdoc +++ b/examples/widgets/doc/src/moveblocks.qdoc diff --git a/examples/widgets/doc/movie.qdoc b/examples/widgets/doc/src/movie.qdoc index e636ce5902..e636ce5902 100644 --- a/examples/widgets/doc/movie.qdoc +++ b/examples/widgets/doc/src/movie.qdoc diff --git a/examples/widgets/doc/orderform.qdoc b/examples/widgets/doc/src/orderform.qdoc index ed40c65093..ed40c65093 100644 --- a/examples/widgets/doc/orderform.qdoc +++ b/examples/widgets/doc/src/orderform.qdoc diff --git a/examples/widgets/doc/padnavigator.qdoc b/examples/widgets/doc/src/padnavigator.qdoc index 8b1da516b5..8b1da516b5 100644 --- a/examples/widgets/doc/padnavigator.qdoc +++ b/examples/widgets/doc/src/padnavigator.qdoc diff --git a/examples/widgets/doc/painterpaths.qdoc b/examples/widgets/doc/src/painterpaths.qdoc index 45b0697cee..45b0697cee 100644 --- a/examples/widgets/doc/painterpaths.qdoc +++ b/examples/widgets/doc/src/painterpaths.qdoc diff --git a/examples/widgets/doc/pathstroke.qdoc b/examples/widgets/doc/src/pathstroke.qdoc index 89a0182934..89a0182934 100644 --- a/examples/widgets/doc/pathstroke.qdoc +++ b/examples/widgets/doc/src/pathstroke.qdoc diff --git a/examples/widgets/doc/pingpong.qdoc b/examples/widgets/doc/src/pingpong.qdoc index c56085d8cf..c56085d8cf 100644 --- a/examples/widgets/doc/pingpong.qdoc +++ b/examples/widgets/doc/src/pingpong.qdoc diff --git a/examples/widgets/doc/pixelator.qdoc b/examples/widgets/doc/src/pixelator.qdoc index 099c382c82..099c382c82 100644 --- a/examples/widgets/doc/pixelator.qdoc +++ b/examples/widgets/doc/src/pixelator.qdoc diff --git a/examples/widgets/doc/recentfiles.qdoc b/examples/widgets/doc/src/recentfiles.qdoc index e2e876b088..e2e876b088 100644 --- a/examples/widgets/doc/recentfiles.qdoc +++ b/examples/widgets/doc/src/recentfiles.qdoc diff --git a/examples/widgets/doc/rogue.qdoc b/examples/widgets/doc/src/rogue.qdoc index 4c65dd2d6e..4c65dd2d6e 100644 --- a/examples/widgets/doc/rogue.qdoc +++ b/examples/widgets/doc/src/rogue.qdoc diff --git a/examples/widgets/doc/screenshot.qdoc b/examples/widgets/doc/src/screenshot.qdoc index 2d41cf0d85..2d41cf0d85 100644 --- a/examples/widgets/doc/screenshot.qdoc +++ b/examples/widgets/doc/src/screenshot.qdoc diff --git a/examples/widgets/doc/scribble.qdoc b/examples/widgets/doc/src/scribble.qdoc index 5749b9ed07..5749b9ed07 100644 --- a/examples/widgets/doc/scribble.qdoc +++ b/examples/widgets/doc/src/scribble.qdoc diff --git a/examples/widgets/doc/sdi.qdoc b/examples/widgets/doc/src/sdi.qdoc index b686888797..b686888797 100644 --- a/examples/widgets/doc/sdi.qdoc +++ b/examples/widgets/doc/src/sdi.qdoc diff --git a/examples/widgets/doc/shapedclock.qdoc b/examples/widgets/doc/src/shapedclock.qdoc index 8d7b856fd6..8d7b856fd6 100644 --- a/examples/widgets/doc/shapedclock.qdoc +++ b/examples/widgets/doc/src/shapedclock.qdoc diff --git a/examples/widgets/doc/simpledommodel.qdoc b/examples/widgets/doc/src/simpledommodel.qdoc index 2564c654fa..2564c654fa 100644 --- a/examples/widgets/doc/simpledommodel.qdoc +++ b/examples/widgets/doc/src/simpledommodel.qdoc diff --git a/examples/widgets/doc/simpletreemodel.qdoc b/examples/widgets/doc/src/simpletreemodel.qdoc index c054352cb8..c054352cb8 100644 --- a/examples/widgets/doc/simpletreemodel.qdoc +++ b/examples/widgets/doc/src/simpletreemodel.qdoc diff --git a/examples/widgets/doc/simplewidgetmapper.qdoc b/examples/widgets/doc/src/simplewidgetmapper.qdoc index 2b7cd2d79a..2b7cd2d79a 100644 --- a/examples/widgets/doc/simplewidgetmapper.qdoc +++ b/examples/widgets/doc/src/simplewidgetmapper.qdoc diff --git a/examples/widgets/doc/sipdialog.qdoc b/examples/widgets/doc/src/sipdialog.qdoc index b5f18cb4be..b5f18cb4be 100644 --- a/examples/widgets/doc/sipdialog.qdoc +++ b/examples/widgets/doc/src/sipdialog.qdoc diff --git a/examples/widgets/doc/sliders.qdoc b/examples/widgets/doc/src/sliders.qdoc index 209d81198d..209d81198d 100644 --- a/examples/widgets/doc/sliders.qdoc +++ b/examples/widgets/doc/src/sliders.qdoc diff --git a/examples/widgets/doc/spinboxdelegate.qdoc b/examples/widgets/doc/src/spinboxdelegate.qdoc index 258811cc4c..258811cc4c 100644 --- a/examples/widgets/doc/spinboxdelegate.qdoc +++ b/examples/widgets/doc/src/spinboxdelegate.qdoc diff --git a/examples/widgets/doc/spinboxes.qdoc b/examples/widgets/doc/src/spinboxes.qdoc index ed4eea6a60..ed4eea6a60 100644 --- a/examples/widgets/doc/spinboxes.qdoc +++ b/examples/widgets/doc/src/spinboxes.qdoc diff --git a/examples/widgets/doc/spreadsheet.qdoc b/examples/widgets/doc/src/spreadsheet.qdoc index 7364f022cb..7364f022cb 100644 --- a/examples/widgets/doc/spreadsheet.qdoc +++ b/examples/widgets/doc/src/spreadsheet.qdoc diff --git a/examples/widgets/doc/standarddialogs.qdoc b/examples/widgets/doc/src/standarddialogs.qdoc index b56642b6ec..b56642b6ec 100644 --- a/examples/widgets/doc/standarddialogs.qdoc +++ b/examples/widgets/doc/src/standarddialogs.qdoc diff --git a/examples/widgets/doc/stardelegate.qdoc b/examples/widgets/doc/src/stardelegate.qdoc index aba8864c2b..aba8864c2b 100644 --- a/examples/widgets/doc/stardelegate.qdoc +++ b/examples/widgets/doc/src/stardelegate.qdoc diff --git a/examples/widgets/doc/states.qdoc b/examples/widgets/doc/src/states.qdoc index 52eda087f1..52eda087f1 100644 --- a/examples/widgets/doc/states.qdoc +++ b/examples/widgets/doc/src/states.qdoc diff --git a/examples/widgets/doc/stickman.qdoc b/examples/widgets/doc/src/stickman.qdoc index cffdb64822..cffdb64822 100644 --- a/examples/widgets/doc/stickman.qdoc +++ b/examples/widgets/doc/src/stickman.qdoc diff --git a/examples/widgets/doc/styles.qdoc b/examples/widgets/doc/src/styles.qdoc index f8be98d2da..f8be98d2da 100644 --- a/examples/widgets/doc/styles.qdoc +++ b/examples/widgets/doc/src/styles.qdoc diff --git a/examples/widgets/doc/stylesheet.qdoc b/examples/widgets/doc/src/stylesheet.qdoc index af45411f8c..af45411f8c 100644 --- a/examples/widgets/doc/stylesheet.qdoc +++ b/examples/widgets/doc/src/stylesheet.qdoc diff --git a/examples/widgets/doc/sub-attaq.qdoc b/examples/widgets/doc/src/sub-attaq.qdoc index ae00eb0926..ae00eb0926 100644 --- a/examples/widgets/doc/sub-attaq.qdoc +++ b/examples/widgets/doc/src/sub-attaq.qdoc diff --git a/examples/widgets/doc/syntaxhighlighter.qdoc b/examples/widgets/doc/src/syntaxhighlighter.qdoc index 66727c0030..66727c0030 100644 --- a/examples/widgets/doc/syntaxhighlighter.qdoc +++ b/examples/widgets/doc/src/syntaxhighlighter.qdoc diff --git a/examples/widgets/doc/tabdialog.qdoc b/examples/widgets/doc/src/tabdialog.qdoc index 98983d124b..98983d124b 100644 --- a/examples/widgets/doc/tabdialog.qdoc +++ b/examples/widgets/doc/src/tabdialog.qdoc diff --git a/examples/widgets/doc/tablet.qdoc b/examples/widgets/doc/src/tablet.qdoc index 846a9a357b..846a9a357b 100644 --- a/examples/widgets/doc/tablet.qdoc +++ b/examples/widgets/doc/src/tablet.qdoc diff --git a/examples/widgets/doc/tetrix.qdoc b/examples/widgets/doc/src/tetrix.qdoc index 1a30845024..1a30845024 100644 --- a/examples/widgets/doc/tetrix.qdoc +++ b/examples/widgets/doc/src/tetrix.qdoc diff --git a/examples/widgets/doc/textedit.qdoc b/examples/widgets/doc/src/textedit.qdoc index 1bb596eb6e..1bb596eb6e 100644 --- a/examples/widgets/doc/textedit.qdoc +++ b/examples/widgets/doc/src/textedit.qdoc diff --git a/examples/widgets/doc/tooltips.qdoc b/examples/widgets/doc/src/tooltips.qdoc index e06f080a93..e06f080a93 100644 --- a/examples/widgets/doc/tooltips.qdoc +++ b/examples/widgets/doc/src/tooltips.qdoc diff --git a/examples/widgets/doc/trafficlight.qdoc b/examples/widgets/doc/src/trafficlight.qdoc index ec3578abaa..ec3578abaa 100644 --- a/examples/widgets/doc/trafficlight.qdoc +++ b/examples/widgets/doc/src/trafficlight.qdoc diff --git a/examples/widgets/doc/transformations.qdoc b/examples/widgets/doc/src/transformations.qdoc index 79681a2799..79681a2799 100644 --- a/examples/widgets/doc/transformations.qdoc +++ b/examples/widgets/doc/src/transformations.qdoc diff --git a/examples/widgets/doc/trivialwizard.qdoc b/examples/widgets/doc/src/trivialwizard.qdoc index e27f9cadc2..e27f9cadc2 100644 --- a/examples/widgets/doc/trivialwizard.qdoc +++ b/examples/widgets/doc/src/trivialwizard.qdoc diff --git a/examples/widgets/doc/twowaybutton.qdoc b/examples/widgets/doc/src/twowaybutton.qdoc index 40f8c6f1f3..40f8c6f1f3 100644 --- a/examples/widgets/doc/twowaybutton.qdoc +++ b/examples/widgets/doc/src/twowaybutton.qdoc diff --git a/examples/widgets/doc/wiggly.qdoc b/examples/widgets/doc/src/wiggly.qdoc index e84ab00e61..e84ab00e61 100644 --- a/examples/widgets/doc/wiggly.qdoc +++ b/examples/widgets/doc/src/wiggly.qdoc diff --git a/examples/widgets/doc/windowflags.qdoc b/examples/widgets/doc/src/windowflags.qdoc index e85842b30a..e85842b30a 100644 --- a/examples/widgets/doc/windowflags.qdoc +++ b/examples/widgets/doc/src/windowflags.qdoc diff --git a/examples/xml/doc/images/saxbookmarks-example.png b/examples/xml/doc/images/saxbookmarks-example.png Binary files differnew file mode 100644 index 0000000000..54d793be56 --- /dev/null +++ b/examples/xml/doc/images/saxbookmarks-example.png diff --git a/examples/xml/doc/src/saxbookmarks.qdoc b/examples/xml/doc/src/saxbookmarks.qdoc new file mode 100644 index 0000000000..05757dba4b --- /dev/null +++ b/examples/xml/doc/src/saxbookmarks.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example saxbookmarks + \title SAX Bookmarks Example + + The SAX Bookmarks example provides a reader for XML Bookmark Exchange Language (XBEL) + files that uses Qt's SAX-based API to read and parse the files. The DOM Bookmarks + example provides an alternative way to read this type of file. + + \image saxbookmarks-example.png + + See the \l{XML Bookmark Exchange Language Resource Page} for more + information about XBEL files. +*/ |