From d16c565ca6a55788435c52ad45647eda67854d80 Mon Sep 17 00:00:00 2001 From: Frederik Gladhorn Date: Tue, 18 Sep 2012 20:32:53 +0200 Subject: Move opengl/wid/net example docs to proper folders. Change-Id: I846439a9cf7ad965ed27a00f98dbc4ff97abe73b Reviewed-by: Jerome Pasion Reviewed-by: Martin Smith --- examples/widgets/doc/addressbook.qdoc | 442 --------- examples/widgets/doc/affine.qdoc | 48 - examples/widgets/doc/analogclock.qdoc | 154 --- examples/widgets/doc/animatedtiles.qdoc | 36 - examples/widgets/doc/appchooser.qdoc | 38 - examples/widgets/doc/application.qdoc | 400 -------- examples/widgets/doc/basicdrawing.qdoc | 454 --------- examples/widgets/doc/basicgraphicslayouts.qdoc | 164 ---- examples/widgets/doc/basiclayouts.qdoc | 190 ---- examples/widgets/doc/basicsortfiltermodel.qdoc | 37 - examples/widgets/doc/blurpicker.qdoc | 33 - examples/widgets/doc/borderlayout.qdoc | 36 - examples/widgets/doc/boxes.qdoc | 49 - examples/widgets/doc/calculator.qdoc | 375 ------- examples/widgets/doc/calendar.qdoc | 223 ----- examples/widgets/doc/calendarwidget.qdoc | 291 ------ examples/widgets/doc/charactermap.qdoc | 274 ------ examples/widgets/doc/chart.qdoc | 82 -- examples/widgets/doc/chip.qdoc | 38 - examples/widgets/doc/classwizard.qdoc | 190 ---- examples/widgets/doc/codeeditor.qdoc | 197 ---- examples/widgets/doc/coloreditorfactory.qdoc | 155 --- examples/widgets/doc/combowidgetmapper.qdoc | 167 ---- examples/widgets/doc/composition.qdoc | 44 - examples/widgets/doc/concentriccircles.qdoc | 231 ----- examples/widgets/doc/configdialog.qdoc | 36 - examples/widgets/doc/customsortfiltermodel.qdoc | 289 ------ examples/widgets/doc/deform.qdoc | 51 - examples/widgets/doc/diagramscene.qdoc | 834 ---------------- examples/widgets/doc/digitalclock.qdoc | 74 -- examples/widgets/doc/dirview.qdoc | 36 - examples/widgets/doc/dockwidgets.qdoc | 163 --- examples/widgets/doc/draganddroppuzzle.qdoc | 42 - examples/widgets/doc/dragdroprobot.qdoc | 365 ------- examples/widgets/doc/dynamiclayouts.qdoc | 34 - examples/widgets/doc/easing.qdoc | 37 - examples/widgets/doc/editabletreemodel.qdoc | 450 --------- examples/widgets/doc/elasticnodes.qdoc | 430 -------- examples/widgets/doc/elidedlabel.qdoc | 162 --- examples/widgets/doc/embeddeddialogs.qdoc | 37 - examples/widgets/doc/eventtransitions.qdoc | 72 -- examples/widgets/doc/extension.qdoc | 138 --- examples/widgets/doc/factorial.qdoc | 88 -- examples/widgets/doc/fademessage.qdoc | 37 - examples/widgets/doc/fetchmore.qdoc | 111 --- examples/widgets/doc/findfiles.qdoc | 249 ----- examples/widgets/doc/flowlayout.qdoc | 145 --- examples/widgets/doc/fontsampler.qdoc | 35 - examples/widgets/doc/frozencolumn.qdoc | 133 --- examples/widgets/doc/gradients.qdoc | 55 -- examples/widgets/doc/groupbox.qdoc | 140 --- examples/widgets/doc/icons.qdoc | 787 --------------- examples/widgets/doc/imagecomposition.qdoc | 165 ---- .../widgets/doc/images/itemviewspuzzle-example.png | Bin 0 -> 211091 bytes examples/widgets/doc/imageviewer.qdoc | 337 ------- examples/widgets/doc/interview.qdoc | 37 - examples/widgets/doc/itemviewspuzzle.qdoc | 43 - examples/widgets/doc/licensewizard.qdoc | 218 ----- examples/widgets/doc/lighting.qdoc | 33 - examples/widgets/doc/lineedits.qdoc | 161 --- examples/widgets/doc/mainwindow.qdoc | 36 - examples/widgets/doc/mdi.qdoc | 37 - examples/widgets/doc/menus.qdoc | 218 ----- examples/widgets/doc/moveblocks.qdoc | 214 ---- examples/widgets/doc/movie.qdoc | 38 - examples/widgets/doc/orderform.qdoc | 364 ------- examples/widgets/doc/padnavigator.qdoc | 583 ----------- examples/widgets/doc/painterpaths.qdoc | 418 -------- examples/widgets/doc/pathstroke.qdoc | 47 - examples/widgets/doc/pingpong.qdoc | 93 -- examples/widgets/doc/pixelator.qdoc | 255 ----- examples/widgets/doc/recentfiles.qdoc | 36 - examples/widgets/doc/rogue.qdoc | 208 ---- examples/widgets/doc/screenshot.qdoc | 247 ----- examples/widgets/doc/scribble.qdoc | 417 -------- examples/widgets/doc/sdi.qdoc | 36 - examples/widgets/doc/shapedclock.qdoc | 131 --- examples/widgets/doc/simpledommodel.qdoc | 280 ------ examples/widgets/doc/simpletreemodel.qdoc | 341 ------- examples/widgets/doc/simplewidgetmapper.qdoc | 125 --- examples/widgets/doc/sipdialog.qdoc | 127 --- examples/widgets/doc/sliders.qdoc | 255 ----- examples/widgets/doc/spinboxdelegate.qdoc | 141 --- examples/widgets/doc/spinboxes.qdoc | 191 ---- examples/widgets/doc/spreadsheet.qdoc | 37 - examples/widgets/doc/src/addressbook-fr.qdoc | 1033 ++++++++++++++++++++ examples/widgets/doc/src/addressbook-tutorial.qdoc | 979 +++++++++++++++++++ examples/widgets/doc/src/addressbook.qdoc | 442 +++++++++ examples/widgets/doc/src/affine.qdoc | 48 + examples/widgets/doc/src/analogclock.qdoc | 154 +++ examples/widgets/doc/src/animatedtiles.qdoc | 36 + examples/widgets/doc/src/appchooser.qdoc | 38 + examples/widgets/doc/src/application.qdoc | 400 ++++++++ examples/widgets/doc/src/applicationicon.qdoc | 67 ++ examples/widgets/doc/src/basicdrawing.qdoc | 454 +++++++++ examples/widgets/doc/src/basicgraphicslayouts.qdoc | 164 ++++ examples/widgets/doc/src/basiclayouts.qdoc | 190 ++++ examples/widgets/doc/src/basicsortfiltermodel.qdoc | 37 + examples/widgets/doc/src/blurpicker.qdoc | 33 + examples/widgets/doc/src/borderlayout.qdoc | 36 + examples/widgets/doc/src/boxes.qdoc | 49 + examples/widgets/doc/src/calculator.qdoc | 375 +++++++ examples/widgets/doc/src/calendar.qdoc | 223 +++++ examples/widgets/doc/src/calendarwidget.qdoc | 291 ++++++ examples/widgets/doc/src/charactermap.qdoc | 274 ++++++ examples/widgets/doc/src/chart.qdoc | 82 ++ examples/widgets/doc/src/chip.qdoc | 38 + examples/widgets/doc/src/classwizard.qdoc | 190 ++++ examples/widgets/doc/src/codeeditor.qdoc | 197 ++++ examples/widgets/doc/src/coloreditorfactory.qdoc | 155 +++ examples/widgets/doc/src/combowidgetmapper.qdoc | 167 ++++ examples/widgets/doc/src/composition.qdoc | 44 + examples/widgets/doc/src/concentriccircles.qdoc | 231 +++++ examples/widgets/doc/src/configdialog.qdoc | 36 + .../widgets/doc/src/customsortfiltermodel.qdoc | 289 ++++++ examples/widgets/doc/src/deform.qdoc | 51 + examples/widgets/doc/src/diagramscene.qdoc | 834 ++++++++++++++++ examples/widgets/doc/src/digitalclock.qdoc | 74 ++ examples/widgets/doc/src/dirview.qdoc | 36 + examples/widgets/doc/src/dockwidgets.qdoc | 163 +++ examples/widgets/doc/src/draganddroppuzzle.qdoc | 42 + examples/widgets/doc/src/dragdroprobot.qdoc | 365 +++++++ examples/widgets/doc/src/draggableicons.qdoc | 90 ++ examples/widgets/doc/src/draggabletext.qdoc | 36 + examples/widgets/doc/src/dynamiclayouts.qdoc | 34 + examples/widgets/doc/src/easing.qdoc | 37 + examples/widgets/doc/src/editabletreemodel.qdoc | 450 +++++++++ examples/widgets/doc/src/elasticnodes.qdoc | 430 ++++++++ examples/widgets/doc/src/elidedlabel.qdoc | 162 +++ examples/widgets/doc/src/embeddeddialogs.qdoc | 37 + examples/widgets/doc/src/eventtransitions.qdoc | 72 ++ examples/widgets/doc/src/extension.qdoc | 138 +++ examples/widgets/doc/src/factorial.qdoc | 88 ++ examples/widgets/doc/src/fademessage.qdoc | 37 + examples/widgets/doc/src/fetchmore.qdoc | 111 +++ examples/widgets/doc/src/findfiles.qdoc | 249 +++++ examples/widgets/doc/src/flowlayout.qdoc | 145 +++ examples/widgets/doc/src/fontsampler.qdoc | 35 + examples/widgets/doc/src/frozencolumn.qdoc | 133 +++ examples/widgets/doc/src/gradients.qdoc | 55 ++ examples/widgets/doc/src/groupbox.qdoc | 140 +++ examples/widgets/doc/src/icons.qdoc | 787 +++++++++++++++ examples/widgets/doc/src/imagecomposition.qdoc | 165 ++++ examples/widgets/doc/src/imageviewer.qdoc | 337 +++++++ examples/widgets/doc/src/interview.qdoc | 37 + examples/widgets/doc/src/itemviewspuzzle.qdoc | 43 + examples/widgets/doc/src/licensewizard.qdoc | 218 +++++ examples/widgets/doc/src/lighting.qdoc | 33 + examples/widgets/doc/src/lineedits.qdoc | 161 +++ examples/widgets/doc/src/mainwindow.qdoc | 36 + examples/widgets/doc/src/mdi.qdoc | 37 + examples/widgets/doc/src/menus.qdoc | 218 +++++ examples/widgets/doc/src/moveblocks.qdoc | 214 ++++ examples/widgets/doc/src/movie.qdoc | 38 + examples/widgets/doc/src/orderform.qdoc | 364 +++++++ examples/widgets/doc/src/padnavigator.qdoc | 583 +++++++++++ examples/widgets/doc/src/painterpaths.qdoc | 418 ++++++++ examples/widgets/doc/src/pathstroke.qdoc | 47 + examples/widgets/doc/src/pingpong.qdoc | 93 ++ examples/widgets/doc/src/pixelator.qdoc | 255 +++++ examples/widgets/doc/src/recentfiles.qdoc | 36 + examples/widgets/doc/src/rogue.qdoc | 208 ++++ examples/widgets/doc/src/screenshot.qdoc | 247 +++++ examples/widgets/doc/src/scribble.qdoc | 417 ++++++++ examples/widgets/doc/src/sdi.qdoc | 36 + examples/widgets/doc/src/shapedclock.qdoc | 131 +++ examples/widgets/doc/src/simpledommodel.qdoc | 280 ++++++ examples/widgets/doc/src/simpletreemodel.qdoc | 341 +++++++ examples/widgets/doc/src/simplewidgetmapper.qdoc | 125 +++ examples/widgets/doc/src/sipdialog.qdoc | 127 +++ examples/widgets/doc/src/sliders.qdoc | 255 +++++ examples/widgets/doc/src/spinboxdelegate.qdoc | 141 +++ examples/widgets/doc/src/spinboxes.qdoc | 191 ++++ examples/widgets/doc/src/spreadsheet.qdoc | 37 + examples/widgets/doc/src/standarddialogs.qdoc | 35 + examples/widgets/doc/src/stardelegate.qdoc | 296 ++++++ examples/widgets/doc/src/states.qdoc | 36 + examples/widgets/doc/src/stickman.qdoc | 102 ++ examples/widgets/doc/src/styles.qdoc | 472 +++++++++ examples/widgets/doc/src/stylesheet.qdoc | 36 + examples/widgets/doc/src/sub-attaq.qdoc | 40 + examples/widgets/doc/src/syntaxhighlighter.qdoc | 252 +++++ examples/widgets/doc/src/tabdialog.qdoc | 134 +++ examples/widgets/doc/src/tablet.qdoc | 369 +++++++ examples/widgets/doc/src/tetrix.qdoc | 431 ++++++++ examples/widgets/doc/src/textedit.qdoc | 36 + examples/widgets/doc/src/tooltips.qdoc | 394 ++++++++ examples/widgets/doc/src/trafficlight.qdoc | 85 ++ examples/widgets/doc/src/transformations.qdoc | 371 +++++++ examples/widgets/doc/src/trivialwizard.qdoc | 82 ++ examples/widgets/doc/src/twowaybutton.qdoc | 68 ++ examples/widgets/doc/src/wiggly.qdoc | 167 ++++ examples/widgets/doc/src/windowflags.qdoc | 216 ++++ examples/widgets/doc/standarddialogs.qdoc | 35 - examples/widgets/doc/stardelegate.qdoc | 296 ------ examples/widgets/doc/states.qdoc | 36 - examples/widgets/doc/stickman.qdoc | 102 -- examples/widgets/doc/styles.qdoc | 472 --------- examples/widgets/doc/stylesheet.qdoc | 36 - examples/widgets/doc/sub-attaq.qdoc | 40 - examples/widgets/doc/syntaxhighlighter.qdoc | 252 ----- examples/widgets/doc/tabdialog.qdoc | 134 --- examples/widgets/doc/tablet.qdoc | 369 ------- examples/widgets/doc/tetrix.qdoc | 431 -------- examples/widgets/doc/textedit.qdoc | 36 - examples/widgets/doc/tooltips.qdoc | 394 -------- examples/widgets/doc/trafficlight.qdoc | 85 -- examples/widgets/doc/transformations.qdoc | 371 ------- examples/widgets/doc/trivialwizard.qdoc | 82 -- examples/widgets/doc/twowaybutton.qdoc | 68 -- examples/widgets/doc/wiggly.qdoc | 167 ---- examples/widgets/doc/windowflags.qdoc | 216 ---- 212 files changed, 21074 insertions(+), 18869 deletions(-) delete mode 100644 examples/widgets/doc/addressbook.qdoc delete mode 100644 examples/widgets/doc/affine.qdoc delete mode 100644 examples/widgets/doc/analogclock.qdoc delete mode 100644 examples/widgets/doc/animatedtiles.qdoc delete mode 100644 examples/widgets/doc/appchooser.qdoc delete mode 100644 examples/widgets/doc/application.qdoc delete mode 100644 examples/widgets/doc/basicdrawing.qdoc delete mode 100644 examples/widgets/doc/basicgraphicslayouts.qdoc delete mode 100644 examples/widgets/doc/basiclayouts.qdoc delete mode 100644 examples/widgets/doc/basicsortfiltermodel.qdoc delete mode 100644 examples/widgets/doc/blurpicker.qdoc delete mode 100644 examples/widgets/doc/borderlayout.qdoc delete mode 100644 examples/widgets/doc/boxes.qdoc delete mode 100644 examples/widgets/doc/calculator.qdoc delete mode 100644 examples/widgets/doc/calendar.qdoc delete mode 100644 examples/widgets/doc/calendarwidget.qdoc delete mode 100644 examples/widgets/doc/charactermap.qdoc delete mode 100644 examples/widgets/doc/chart.qdoc delete mode 100644 examples/widgets/doc/chip.qdoc delete mode 100644 examples/widgets/doc/classwizard.qdoc delete mode 100644 examples/widgets/doc/codeeditor.qdoc delete mode 100644 examples/widgets/doc/coloreditorfactory.qdoc delete mode 100644 examples/widgets/doc/combowidgetmapper.qdoc delete mode 100644 examples/widgets/doc/composition.qdoc delete mode 100644 examples/widgets/doc/concentriccircles.qdoc delete mode 100644 examples/widgets/doc/configdialog.qdoc delete mode 100644 examples/widgets/doc/customsortfiltermodel.qdoc delete mode 100644 examples/widgets/doc/deform.qdoc delete mode 100644 examples/widgets/doc/diagramscene.qdoc delete mode 100644 examples/widgets/doc/digitalclock.qdoc delete mode 100644 examples/widgets/doc/dirview.qdoc delete mode 100644 examples/widgets/doc/dockwidgets.qdoc delete mode 100644 examples/widgets/doc/draganddroppuzzle.qdoc delete mode 100644 examples/widgets/doc/dragdroprobot.qdoc delete mode 100644 examples/widgets/doc/dynamiclayouts.qdoc delete mode 100644 examples/widgets/doc/easing.qdoc delete mode 100644 examples/widgets/doc/editabletreemodel.qdoc delete mode 100644 examples/widgets/doc/elasticnodes.qdoc delete mode 100644 examples/widgets/doc/elidedlabel.qdoc delete mode 100644 examples/widgets/doc/embeddeddialogs.qdoc delete mode 100644 examples/widgets/doc/eventtransitions.qdoc delete mode 100644 examples/widgets/doc/extension.qdoc delete mode 100644 examples/widgets/doc/factorial.qdoc delete mode 100644 examples/widgets/doc/fademessage.qdoc delete mode 100644 examples/widgets/doc/fetchmore.qdoc delete mode 100644 examples/widgets/doc/findfiles.qdoc delete mode 100644 examples/widgets/doc/flowlayout.qdoc delete mode 100644 examples/widgets/doc/fontsampler.qdoc delete mode 100644 examples/widgets/doc/frozencolumn.qdoc delete mode 100644 examples/widgets/doc/gradients.qdoc delete mode 100644 examples/widgets/doc/groupbox.qdoc delete mode 100644 examples/widgets/doc/icons.qdoc delete mode 100644 examples/widgets/doc/imagecomposition.qdoc create mode 100644 examples/widgets/doc/images/itemviewspuzzle-example.png delete mode 100644 examples/widgets/doc/imageviewer.qdoc delete mode 100644 examples/widgets/doc/interview.qdoc delete mode 100644 examples/widgets/doc/itemviewspuzzle.qdoc delete mode 100644 examples/widgets/doc/licensewizard.qdoc delete mode 100644 examples/widgets/doc/lighting.qdoc delete mode 100644 examples/widgets/doc/lineedits.qdoc delete mode 100644 examples/widgets/doc/mainwindow.qdoc delete mode 100644 examples/widgets/doc/mdi.qdoc delete mode 100644 examples/widgets/doc/menus.qdoc delete mode 100644 examples/widgets/doc/moveblocks.qdoc delete mode 100644 examples/widgets/doc/movie.qdoc delete mode 100644 examples/widgets/doc/orderform.qdoc delete mode 100644 examples/widgets/doc/padnavigator.qdoc delete mode 100644 examples/widgets/doc/painterpaths.qdoc delete mode 100644 examples/widgets/doc/pathstroke.qdoc delete mode 100644 examples/widgets/doc/pingpong.qdoc delete mode 100644 examples/widgets/doc/pixelator.qdoc delete mode 100644 examples/widgets/doc/recentfiles.qdoc delete mode 100644 examples/widgets/doc/rogue.qdoc delete mode 100644 examples/widgets/doc/screenshot.qdoc delete mode 100644 examples/widgets/doc/scribble.qdoc delete mode 100644 examples/widgets/doc/sdi.qdoc delete mode 100644 examples/widgets/doc/shapedclock.qdoc delete mode 100644 examples/widgets/doc/simpledommodel.qdoc delete mode 100644 examples/widgets/doc/simpletreemodel.qdoc delete mode 100644 examples/widgets/doc/simplewidgetmapper.qdoc delete mode 100644 examples/widgets/doc/sipdialog.qdoc delete mode 100644 examples/widgets/doc/sliders.qdoc delete mode 100644 examples/widgets/doc/spinboxdelegate.qdoc delete mode 100644 examples/widgets/doc/spinboxes.qdoc delete mode 100644 examples/widgets/doc/spreadsheet.qdoc create mode 100644 examples/widgets/doc/src/addressbook-fr.qdoc create mode 100644 examples/widgets/doc/src/addressbook-tutorial.qdoc create mode 100644 examples/widgets/doc/src/addressbook.qdoc create mode 100644 examples/widgets/doc/src/affine.qdoc create mode 100644 examples/widgets/doc/src/analogclock.qdoc create mode 100644 examples/widgets/doc/src/animatedtiles.qdoc create mode 100644 examples/widgets/doc/src/appchooser.qdoc create mode 100644 examples/widgets/doc/src/application.qdoc create mode 100644 examples/widgets/doc/src/applicationicon.qdoc create mode 100644 examples/widgets/doc/src/basicdrawing.qdoc create mode 100644 examples/widgets/doc/src/basicgraphicslayouts.qdoc create mode 100644 examples/widgets/doc/src/basiclayouts.qdoc create mode 100644 examples/widgets/doc/src/basicsortfiltermodel.qdoc create mode 100644 examples/widgets/doc/src/blurpicker.qdoc create mode 100644 examples/widgets/doc/src/borderlayout.qdoc create mode 100644 examples/widgets/doc/src/boxes.qdoc create mode 100644 examples/widgets/doc/src/calculator.qdoc create mode 100644 examples/widgets/doc/src/calendar.qdoc create mode 100644 examples/widgets/doc/src/calendarwidget.qdoc create mode 100644 examples/widgets/doc/src/charactermap.qdoc create mode 100644 examples/widgets/doc/src/chart.qdoc create mode 100644 examples/widgets/doc/src/chip.qdoc create mode 100644 examples/widgets/doc/src/classwizard.qdoc create mode 100644 examples/widgets/doc/src/codeeditor.qdoc create mode 100644 examples/widgets/doc/src/coloreditorfactory.qdoc create mode 100644 examples/widgets/doc/src/combowidgetmapper.qdoc create mode 100644 examples/widgets/doc/src/composition.qdoc create mode 100644 examples/widgets/doc/src/concentriccircles.qdoc create mode 100644 examples/widgets/doc/src/configdialog.qdoc create mode 100644 examples/widgets/doc/src/customsortfiltermodel.qdoc create mode 100644 examples/widgets/doc/src/deform.qdoc create mode 100644 examples/widgets/doc/src/diagramscene.qdoc create mode 100644 examples/widgets/doc/src/digitalclock.qdoc create mode 100644 examples/widgets/doc/src/dirview.qdoc create mode 100644 examples/widgets/doc/src/dockwidgets.qdoc create mode 100644 examples/widgets/doc/src/draganddroppuzzle.qdoc create mode 100644 examples/widgets/doc/src/dragdroprobot.qdoc create mode 100644 examples/widgets/doc/src/draggableicons.qdoc create mode 100644 examples/widgets/doc/src/draggabletext.qdoc create mode 100644 examples/widgets/doc/src/dynamiclayouts.qdoc create mode 100644 examples/widgets/doc/src/easing.qdoc create mode 100644 examples/widgets/doc/src/editabletreemodel.qdoc create mode 100644 examples/widgets/doc/src/elasticnodes.qdoc create mode 100644 examples/widgets/doc/src/elidedlabel.qdoc create mode 100644 examples/widgets/doc/src/embeddeddialogs.qdoc create mode 100644 examples/widgets/doc/src/eventtransitions.qdoc create mode 100644 examples/widgets/doc/src/extension.qdoc create mode 100644 examples/widgets/doc/src/factorial.qdoc create mode 100644 examples/widgets/doc/src/fademessage.qdoc create mode 100644 examples/widgets/doc/src/fetchmore.qdoc create mode 100644 examples/widgets/doc/src/findfiles.qdoc create mode 100644 examples/widgets/doc/src/flowlayout.qdoc create mode 100644 examples/widgets/doc/src/fontsampler.qdoc create mode 100644 examples/widgets/doc/src/frozencolumn.qdoc create mode 100644 examples/widgets/doc/src/gradients.qdoc create mode 100644 examples/widgets/doc/src/groupbox.qdoc create mode 100644 examples/widgets/doc/src/icons.qdoc create mode 100644 examples/widgets/doc/src/imagecomposition.qdoc create mode 100644 examples/widgets/doc/src/imageviewer.qdoc create mode 100644 examples/widgets/doc/src/interview.qdoc create mode 100644 examples/widgets/doc/src/itemviewspuzzle.qdoc create mode 100644 examples/widgets/doc/src/licensewizard.qdoc create mode 100644 examples/widgets/doc/src/lighting.qdoc create mode 100644 examples/widgets/doc/src/lineedits.qdoc create mode 100644 examples/widgets/doc/src/mainwindow.qdoc create mode 100644 examples/widgets/doc/src/mdi.qdoc create mode 100644 examples/widgets/doc/src/menus.qdoc create mode 100644 examples/widgets/doc/src/moveblocks.qdoc create mode 100644 examples/widgets/doc/src/movie.qdoc create mode 100644 examples/widgets/doc/src/orderform.qdoc create mode 100644 examples/widgets/doc/src/padnavigator.qdoc create mode 100644 examples/widgets/doc/src/painterpaths.qdoc create mode 100644 examples/widgets/doc/src/pathstroke.qdoc create mode 100644 examples/widgets/doc/src/pingpong.qdoc create mode 100644 examples/widgets/doc/src/pixelator.qdoc create mode 100644 examples/widgets/doc/src/recentfiles.qdoc create mode 100644 examples/widgets/doc/src/rogue.qdoc create mode 100644 examples/widgets/doc/src/screenshot.qdoc create mode 100644 examples/widgets/doc/src/scribble.qdoc create mode 100644 examples/widgets/doc/src/sdi.qdoc create mode 100644 examples/widgets/doc/src/shapedclock.qdoc create mode 100644 examples/widgets/doc/src/simpledommodel.qdoc create mode 100644 examples/widgets/doc/src/simpletreemodel.qdoc create mode 100644 examples/widgets/doc/src/simplewidgetmapper.qdoc create mode 100644 examples/widgets/doc/src/sipdialog.qdoc create mode 100644 examples/widgets/doc/src/sliders.qdoc create mode 100644 examples/widgets/doc/src/spinboxdelegate.qdoc create mode 100644 examples/widgets/doc/src/spinboxes.qdoc create mode 100644 examples/widgets/doc/src/spreadsheet.qdoc create mode 100644 examples/widgets/doc/src/standarddialogs.qdoc create mode 100644 examples/widgets/doc/src/stardelegate.qdoc create mode 100644 examples/widgets/doc/src/states.qdoc create mode 100644 examples/widgets/doc/src/stickman.qdoc create mode 100644 examples/widgets/doc/src/styles.qdoc create mode 100644 examples/widgets/doc/src/stylesheet.qdoc create mode 100644 examples/widgets/doc/src/sub-attaq.qdoc create mode 100644 examples/widgets/doc/src/syntaxhighlighter.qdoc create mode 100644 examples/widgets/doc/src/tabdialog.qdoc create mode 100644 examples/widgets/doc/src/tablet.qdoc create mode 100644 examples/widgets/doc/src/tetrix.qdoc create mode 100644 examples/widgets/doc/src/textedit.qdoc create mode 100644 examples/widgets/doc/src/tooltips.qdoc create mode 100644 examples/widgets/doc/src/trafficlight.qdoc create mode 100644 examples/widgets/doc/src/transformations.qdoc create mode 100644 examples/widgets/doc/src/trivialwizard.qdoc create mode 100644 examples/widgets/doc/src/twowaybutton.qdoc create mode 100644 examples/widgets/doc/src/wiggly.qdoc create mode 100644 examples/widgets/doc/src/windowflags.qdoc delete mode 100644 examples/widgets/doc/standarddialogs.qdoc delete mode 100644 examples/widgets/doc/stardelegate.qdoc delete mode 100644 examples/widgets/doc/states.qdoc delete mode 100644 examples/widgets/doc/stickman.qdoc delete mode 100644 examples/widgets/doc/styles.qdoc delete mode 100644 examples/widgets/doc/stylesheet.qdoc delete mode 100644 examples/widgets/doc/sub-attaq.qdoc delete mode 100644 examples/widgets/doc/syntaxhighlighter.qdoc delete mode 100644 examples/widgets/doc/tabdialog.qdoc delete mode 100644 examples/widgets/doc/tablet.qdoc delete mode 100644 examples/widgets/doc/tetrix.qdoc delete mode 100644 examples/widgets/doc/textedit.qdoc delete mode 100644 examples/widgets/doc/tooltips.qdoc delete mode 100644 examples/widgets/doc/trafficlight.qdoc delete mode 100644 examples/widgets/doc/transformations.qdoc delete mode 100644 examples/widgets/doc/trivialwizard.qdoc delete mode 100644 examples/widgets/doc/twowaybutton.qdoc delete mode 100644 examples/widgets/doc/wiggly.qdoc delete mode 100644 examples/widgets/doc/windowflags.qdoc (limited to 'examples/widgets/doc') diff --git a/examples/widgets/doc/addressbook.qdoc b/examples/widgets/doc/addressbook.qdoc deleted file mode 100644 index 9b4ede5775..0000000000 --- a/examples/widgets/doc/addressbook.qdoc +++ /dev/null @@ -1,442 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/addressbook - \title Address Book Example - - The address book example shows how to use proxy models to display - different views onto data from a single model. - - \image addressbook-example.png Screenshot of the Address Book example - - This example provides an address book that allows contacts to be - grouped alphabetically into 9 groups: ABC, DEF, GHI, ... , VW, - ..., XYZ. This is achieved by using multiple views on the same - model, each of which is filtered using an instance of the - QSortFilterProxyModel class. - - - \section1 Overview - - The address book contains 5 classes: \c MainWindow, - \c AddressWidget, \c TableModel, \c NewAddressTab and - \c AddDialog. The \c MainWindow class uses \c AddressWidget as - its central widget and provides \uicontrol File and \uicontrol Tools menus. - - \image addressbook-classes.png Diagram for Address Book Example - - The \c AddressWidget class is a QTabWidget subclass that is used - to manipulate the 10 tabs displayed in the example: the 9 - alphabet group tabs and an instance of \c NewAddressTab. - The \c NewAddressTab class is a subclass of QWidget that - is only used whenever the address book is empty, prompting the - user to add some contacts. \c AddressWidget also interacts with - an instance of \c TableModel to add, edit and remove entries to - the address book. - - \c TableModel is a subclass of QAbstractTableModel that provides - the standard model/view API to access data. It also holds a - QList of \l{QPair}s corresponding to the contacts added. - However, this data is not all visible in a single tab. Instead, - QTableView is used to provide 9 different views of the same - data, according to the alphabet groups. - - QSortFilterProxyModel is the class responsible for filtering - the contacts for each group of contacts. Each proxy model uses - a QRegExp to filter out contacts that do not belong in the - corresponding alphabetical group. The \c AddDialog class is - used to obtain information from the user for the address book. - This QDialog subclass is instantiated by \c NewAddressTab to - add contacts, and by \c AddressWidget to add and edit contacts. - - We begin by looking at the \c TableModel implementation. - - - \section1 TableModel Class Definition - - The \c TableModel class provides standard API to access data in - its QList of \l{QPair}s by subclassing QAbstractTableModel. The - basic functions that must be implemented in order to do so are: - \c rowCount(), \c columnCount(), \c data(), \c headerData(). - For TableModel to be editable, it has to provide implementations - \c insertRows(), \c removeRows(), \c setData() and \c flags() - functions. - - \snippet itemviews/addressbook/tablemodel.h 0 - - Two constructors are used, a default constructor which uses - \c TableModel's own \c {QList>} and one - that takes \c {QList} as an argument, - for convenience. - - - \section1 TableModel Class Implementation - - We implement the two constructors as defined in the header file. - The second constructor initializes the list of pairs in the - model, with the parameter value. - - \snippet itemviews/addressbook/tablemodel.cpp 0 - - The \c rowCount() and \c columnCount() functions return the - dimensions of the model. Whereas, \c rowCount()'s value will vary - depending on the number of contacts added to the address book, - \c columnCount()'s value is always 2 because we only need space - for the \b Name and \b Address columns. - - \note The \c Q_UNUSED() macro prevents the compiler from - generating warnings regarding unused parameters. - - \snippet itemviews/addressbook/tablemodel.cpp 1 - - The \c data() function returns either a \b Name or - \b {Address}, based on the contents of the model index - supplied. The row number stored in the model index is used to - reference an item in the list of pairs. Selection is handled - by the QItemSelectionModel, which will be explained with - \c AddressWidget. - - \snippet itemviews/addressbook/tablemodel.cpp 2 - - The \c headerData() function displays the table's header, - \b Name and \b Address. If you require numbered entries - for your address book, you can use a vertical header which we - have hidden in this example (see the \c AddressWidget - implementation). - - \snippet itemviews/addressbook/tablemodel.cpp 3 - - The \c insertRows() function is called before new data is added, - otherwise the data will not be displayed. The - \c beginInsertRows() and \c endInsertRows() functions are called - to ensure all connected views are aware of the changes. - - \snippet itemviews/addressbook/tablemodel.cpp 4 - - The \c removeRows() function is called to remove data. Again, - \l{QAbstractItemModel::}{beginRemoveRows()} and - \l{QAbstractItemModel::}{endRemoveRows()} are called to ensure - all connected views are aware of the changes. - - \snippet itemviews/addressbook/tablemodel.cpp 5 - - The \c setData() function is the function that inserts data into - the table, item by item and not row by row. This means that to - fill a row in the address book, \c setData() must be called - twice, as each row has 2 columns. It is important to emit the - \l{QAbstractItemModel::}{dataChanged()} signal as it tells all - connected views to update their displays. - - \snippet itemviews/addressbook/tablemodel.cpp 6 - - The \c flags() function returns the item flags for the given - index. - - \snippet itemviews/addressbook/tablemodel.cpp 7 - - We set the Qt::ItemIsEditable flag because we want to allow the - \c TableModel to be edited. Although for this example we don't - use the editing features of the QTableView object, we enable - them here so that we can reuse the model in other programs. - - The last function in \c {TableModel}, \c getList() returns the - QList> object that holds all the - contacts in the address book. We use this function later to - obtain the list of contacts to check for existing entries, write - the contacts to a file and read them back. Further explanation is - given with \c AddressWidget. - - \snippet itemviews/addressbook/tablemodel.cpp 8 - - - \section1 AddressWidget Class Definition - - The \c AddressWidget class is technically the main class - involved in this example as it provides functions to add, edit - and remove contacts, to save the contacts to a file and to load - them from a file. - - \snippet itemviews/addressbook/addresswidget.h 0 - - \c AddressWidget extends QTabWidget in order to hold 10 tabs - (\c NewAddressTab and the 9 alphabet group tabs) and also - manipulates \c table, the \c TableModel object, \c proxyModel, - the QSortFilterProxyModel object that we use to filter the - entries, and \c tableView, the QTableView object. - - - \section1 AddressWidget Class Implementation - - The \c AddressWidget constructor accepts a parent widget and - instantiates \c NewAddressTab, \c TableModel and - QSortFilterProxyModel. The \c NewAddressTab object, which is - used to indicate that the address book is empty, is added - and the rest of the 9 tabs are set up with \c setupTabs(). - - \snippet itemviews/addressbook/addresswidget.cpp 0 - - The \c setupTabs() function is used to set up the 9 alphabet - group tabs, table views and proxy models in - \c AddressWidget. Each proxy model in turn is set to filter - contact names according to the relevant alphabet group using a - \l{Qt::CaseInsensitive}{case-insensitive} QRegExp object. The - table views are also sorted in ascending order using the - corresponding proxy model's \l{QSortFilterProxyModel::}{sort()} - function. - - Each table view's \l{QTableView::}{selectionMode} is set to - QAbstractItemView::SingleSelection and - \l{QTableView::}{selectionBehavior} is set to - QAbstractItemView::SelectRows, allowing the user to select - all the items in one row at the same time. Each QTableView object - is automatically given a QItemSelectionModel that keeps track - of the selected indexes. - - \snippet itemviews/addressbook/addresswidget.cpp 1 - - The QItemSelectionModel class provides a - \l{QItemSelectionModel::selectionChanged()}{selectionChanged} - signal that is connected to \c{AddressWidget}'s - \c selectionChanged() signal. This signal to signal connection - is necessary to enable the \uicontrol{Edit Entry...} and - \uicontrol{Remove Entry} actions in \c MainWindow's Tools menu. This - connection is further explained in \c MainWindow's - implementation. - - Each table view in the address book is added as a tab to the - QTabWidget with the relevant label, obtained from the QStringList - of groups. - - \image addressbook-signals.png Signals and Slots Connections - - We provide 2 \c addEntry() functions: 1 which is intended to be - used to accept user input, and the other which performs the actual - task of adding new entries to the address book. We divide the - responsibility of adding entries into two parts to allow - \c newAddressTab to insert data without having to popup a dialog. - - The first \c addEntry() function is a slot connected to the - \c MainWindow's \uicontrol{Add Entry...} action. This function creates an - \c AddDialog object and then calls the second \c addEntry() - function to actually add the contact to \c table. - - \snippet itemviews/addressbook/addresswidget.cpp 2 - - Basic validation is done in the second \c addEntry() function to - prevent duplicate entries in the address book. As mentioned with - \c TableModel, this is part of the reason why we require the - getter method \c getList(). - - \snippet itemviews/addressbook/addresswidget.cpp 3 - - If the model does not already contain an entry with the same name, - we call \c setData() to insert the name and address into the - first and second columns. Otherwise, we display a QMessageBox - to inform the user. - - \note The \c newAddressTab is removed once a contact is added - as the address book is no longer empty. - - Editing an entry is a way to update the contact's address only, - as the example does not allow the user to change the name of an - existing contact. - - Firstly, we obtain the active tab's QTableView object using - QTabWidget::currentWidget(). Then we extract the - \c selectionModel from the \c tableView to obtain the selected - indexes. - - \snippet itemviews/addressbook/addresswidget.cpp 4a - - Next we extract data from the row the user intends to - edit. This data is displayed in an instance of \c AddDialog - with a different window title. The \c table is only - updated if changes have been made to data in \c aDialog. - - \snippet itemviews/addressbook/addresswidget.cpp 4b - - \image addressbook-editdialog.png Screenshot of Dialog to Edit a Contact - - Entries are removed using the \c removeEntry() function. - The selected row is removed by accessing it through the - QItemSelectionModel object, \c selectionModel. The - \c newAddressTab is re-added to the \c AddressWidget only if - the user removes all the contacts in the address book. - - \snippet itemviews/addressbook/addresswidget.cpp 5 - - The \c writeToFile() function is used to save a file containing - all the contacts in the address book. The file is saved in a - custom \c{.dat} format. The contents of the QList of \l{QPair}s - are written to \c file using QDataStream. If the file cannot be - opened, a QMessageBox is displayed with the related error message. - - \snippet itemviews/addressbook/addresswidget.cpp 6 - - The \c readFromFile() function loads a file containing all the - contacts in the address book, previously saved using - \c writeToFile(). QDataStream is used to read the contents of a - \c{.dat} file into a list of pairs and each of these is added - using \c addEntry(). - - \snippet itemviews/addressbook/addresswidget.cpp 7 - - - \section1 NewAddressTab Class Definition - - The \c NewAddressTab class provides an informative tab telling - the user that the address book is empty. It appears and - disappears according to the contents of the address book, as - mentioned in \c{AddressWidget}'s implementation. - - \image addressbook-newaddresstab.png Screenshot of NewAddressTab - - The \c NewAddressTab class extends QWidget and contains a QLabel - and QPushButton. - - \snippet itemviews/addressbook/newaddresstab.h 0 - - - \section1 NewAddressTab Class Implementation - - The constructor instantiates the \c addButton, - \c descriptionLabel and connects the \c{addButton}'s signal to - the \c{addEntry()} slot. - - \snippet itemviews/addressbook/newaddresstab.cpp 0 - - The \c addEntry() function is similar to \c AddressWidget's - \c addEntry() in the sense that both functions instantiate an - \c AddDialog object. Data from the dialog is extracted and sent - to \c AddressWidget's \c addEntry() slot by emitting the - \c sendDetails() signal. - - \snippet itemviews/addressbook/newaddresstab.cpp 1 - - \image signals-n-slots-aw-nat.png - - - \section1 AddDialog Class Definition - - The \c AddDialog class extends QDialog and provides the user - with a QLineEdit and a QTextEdit to input data into the - address book. - - \snippet itemviews/addressbook/adddialog.h 0 - - \image addressbook-adddialog.png - - - \section1 AddDialog Class Implementation - - The \c AddDialog's constructor sets up the user interface, - creating the necessary widgets and placing them into layouts. - - \snippet itemviews/addressbook/adddialog.cpp 0 - - To give the dialog the desired behavior, we connect the \uicontrol OK - and \uicontrol Cancel buttons to the dialog's \l{QDialog::}{accept()} and - \l{QDialog::}{reject()} slots. Since the dialog only acts as a - container for name and address information, we do not need to - implement any other functions for it. - - - \section1 MainWindow Class Definition - - The \c MainWindow class extends QMainWindow and implements the - menus and actions necessary to manipulate the address book. - - \table - \row \li \inlineimage addressbook-filemenu.png - \li \inlineimage addressbook-toolsmenu.png - \endtable - - \snippet itemviews/addressbook/mainwindow.h 0 - - The \c MainWindow class uses an \c AddressWidget as its central - widget and provides the File menu with \uicontrol Open, \uicontrol Close and - \uicontrol Exit actions, as well as the \uicontrol Tools menu with - \uicontrol{Add Entry...}, \uicontrol{Edit Entry...} and \uicontrol{Remove Entry} - actions. - - - \section1 MainWindow Class Implementation - - The constructor for \c MainWindow instantiates AddressWidget, - sets it as its central widget and calls the \c createMenus() - function. - - \snippet itemviews/addressbook/mainwindow.cpp 0 - - The \c createMenus() function sets up the \uicontrol File and - \uicontrol Tools menus, connecting the actions to their respective slots. - Both the \uicontrol{Edit Entry...} and \uicontrol{Remove Entry} actions are - disabled by default as such actions cannot be carried out on an empty - address book. They are only enabled when one or more contacts - are added. - - \snippet itemviews/addressbook/mainwindow.cpp 1a - \dots - \codeline - \snippet itemviews/addressbook/mainwindow.cpp 1b - - Apart from connecting all the actions' signals to their - respective slots, we also connect \c AddressWidget's - \c selectionChanged() signal to its \c updateActions() slot. - - The \c openFile() function allows the user to choose a file with - the \l{QFileDialog::getOpenFileName()}{open file dialog}. The chosen - file has to be a custom \c{.dat} file that contains address book - contacts. This function is a slot connected to \c openAct in the - \uicontrol File menu. - - \snippet itemviews/addressbook/mainwindow.cpp 2 - - The \c saveFile() function allows the user to save a file with - the \l{QFileDialog::getSaveFileName()}{save file dialog}. This function - is a slot connected to \c saveAct in the \uicontrol File menu. - - \snippet itemviews/addressbook/mainwindow.cpp 3 - - The \c updateActions() function enables and disables - \uicontrol{Edit Entry...} and \uicontrol{Remove Entry} depending on the contents of - the address book. If the address book is empty, these actions - are disabled; otherwise, they are enabled. This function is a slot - is connected to the \c AddressWidget's \c selectionChanged() - signal. - - \snippet itemviews/addressbook/mainwindow.cpp 4 - - - \section1 main() Function - - The main function for the address book instantiates QApplication - and opens a \c MainWindow before running the event loop. - - \snippet itemviews/addressbook/main.cpp 0 -*/ diff --git a/examples/widgets/doc/affine.qdoc b/examples/widgets/doc/affine.qdoc deleted file mode 100644 index c69794d511..0000000000 --- a/examples/widgets/doc/affine.qdoc +++ /dev/null @@ -1,48 +0,0 @@ -/**************************************************************************** -** -** 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 painting/affine - \title Affine Transformations - - In this example we show Qt's ability to perform affine transformations - on painting operations. - - \image affine-demo.png - - Transformations can be performed on any kind of graphics drawn using QPainter. - The transformations used to display the vector graphics, images, and text can be adjusted - in the following ways: - - \list - \li Dragging the red circle in the centre of each drawing moves it to a new position. - \li Dragging the displaced red circle causes the current drawing to be rotated about the - central circle. Rotation can also be controlled with the \uicontrol Rotate slider. - \li Scaling is controlled with the \uicontrol Scale slider. - \li Each drawing can be sheared with the \uicontrol Shear slider. - \endlist -*/ diff --git a/examples/widgets/doc/analogclock.qdoc b/examples/widgets/doc/analogclock.qdoc deleted file mode 100644 index bb4bdb54ae..0000000000 --- a/examples/widgets/doc/analogclock.qdoc +++ /dev/null @@ -1,154 +0,0 @@ -/**************************************************************************** -** -** 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/analogclock - \title Analog Clock Example - - The Analog Clock example shows how to draw the contents of a custom - widget. - - \image analogclock-example.png Screenshot of the Analog Clock example - - This example also demonstrates how the transformation and scaling - features of QPainter can be used to make drawing custom widgets - easier. - - \section1 AnalogClock Class Definition - - The \c AnalogClock class provides a clock widget with hour and minute - hands that is automatically updated every few seconds. - We subclass \l QWidget and reimplement the standard - \l{QWidget::paintEvent()}{paintEvent()} function to draw the clock face: - - \snippet widgets/analogclock/analogclock.h 0 - - \section1 AnalogClock Class Implementation - - \snippet widgets/analogclock/analogclock.cpp 1 - - When the widget is constructed, we set up a one-second timer to - keep track of the current time, and we connect it to the standard - \l{QWidget::update()}{update()} slot so that the clock face is - updated when the timer emits the \l{QTimer::timeout()}{timeout()} - signal. - - Finally, we resize the widget so that it is displayed at a - reasonable size. - - \snippet widgets/analogclock/analogclock.cpp 8 - \snippet widgets/analogclock/analogclock.cpp 10 - - The \c paintEvent() function is called whenever the widget's - contents need to be updated. This happens when the widget is - first shown, and when it is covered then exposed, but it is also - executed when the widget's \l{QWidget::update()}{update()} slot - is called. Since we connected the timer's - \l{QTimer::timeout()}{timeout()} signal to this slot, it will be - called at least once every five seconds. - - Before we set up the painter and draw the clock, we first define - two lists of \l {QPoint}s and two \l{QColor}s that will be used - for the hour and minute hands. The minute hand's color has an - alpha component of 191, meaning that it's 75% opaque. - - We also determine the length of the widget's shortest side so that we - can fit the clock face inside the widget. It is also useful to determine - the current time before we start drawing. - - \snippet widgets/analogclock/analogclock.cpp 11 - \snippet widgets/analogclock/analogclock.cpp 12 - \snippet widgets/analogclock/analogclock.cpp 13 - \snippet widgets/analogclock/analogclock.cpp 14 - - The contents of custom widgets are drawn with a QPainter. - Painters can be used to draw on any QPaintDevice, but they are - usually used with widgets, so we pass the widget instance to the - painter's constructor. - - We call QPainter::setRenderHint() with QPainter::Antialiasing to - turn on antialiasing. This makes drawing of diagonal lines much - smoother. - - The translation moves the origin to the center of the widget, and - the scale operation ensures that the following drawing operations - are scaled to fit within the widget. We use a scale factor that - let's us use x and y coordinates between -100 and 100, and that - ensures that these lie within the length of the widget's shortest - side. - - To make our code simpler, we will draw a fixed size clock face that will - be positioned and scaled so that it lies in the center of the widget. - - The painter takes care of all the transformations made during the - paint event, and ensures that everything is drawn correctly. Letting - the painter handle transformations is often easier than performing - manual calculations just to draw the contents of a custom widget. - - \image analogclock-viewport.png - - We draw the hour hand first, using a formula that rotates the coordinate - system counterclockwise by a number of degrees determined by the current - hour and minute. This means that the hand will be shown rotated clockwise - by the required amount. - - \snippet widgets/analogclock/analogclock.cpp 15 - \snippet widgets/analogclock/analogclock.cpp 16 - - We set the pen to be Qt::NoPen because we don't want any outline, - and we use a solid brush with the color appropriate for - displaying hours. Brushes are used when filling in polygons and - other geometric shapes. - - \snippet widgets/analogclock/analogclock.cpp 17 - \snippet widgets/analogclock/analogclock.cpp 19 - - We save and restore the transformation matrix before and after the - rotation because we want to place the minute hand without having to - take into account any previous rotations. - - \snippet widgets/analogclock/analogclock.cpp 20 - \codeline - \snippet widgets/analogclock/analogclock.cpp 21 - - We draw markers around the edge of the clock for each hour. We - draw each marker then rotate the coordinate system so that the - painter is ready for the next one. - - \snippet widgets/analogclock/analogclock.cpp 22 - \snippet widgets/analogclock/analogclock.cpp 23 - - The minute hand is rotated in a similar way to the hour hand. - - \snippet widgets/analogclock/analogclock.cpp 25 - \codeline - \snippet widgets/analogclock/analogclock.cpp 26 - - Again, we draw markers around the edge of the clock, but this - time to indicate minutes. We skip multiples of 5 to avoid drawing - minute markers on top of hour markers. -*/ diff --git a/examples/widgets/doc/animatedtiles.qdoc b/examples/widgets/doc/animatedtiles.qdoc deleted file mode 100644 index 4fe25388cf..0000000000 --- a/examples/widgets/doc/animatedtiles.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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 animation/animatedtiles - \title Animated Tiles Example - - The Animated Tiles example animates items in a graphics scene. - - \image animatedtiles-example.png -*/ - diff --git a/examples/widgets/doc/appchooser.qdoc b/examples/widgets/doc/appchooser.qdoc deleted file mode 100644 index 092db7c29e..0000000000 --- a/examples/widgets/doc/appchooser.qdoc +++ /dev/null @@ -1,38 +0,0 @@ -/**************************************************************************** -** -** 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 animation/appchooser - \title Application Chooser Example - - The Application Chooser example shows how to use the Qt state - machine and the animation framework to select between - applications. - - \image appchooser-example.png - -*/ diff --git a/examples/widgets/doc/application.qdoc b/examples/widgets/doc/application.qdoc deleted file mode 100644 index 5465f99e99..0000000000 --- a/examples/widgets/doc/application.qdoc +++ /dev/null @@ -1,400 +0,0 @@ -/**************************************************************************** -** -** 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 mainwindows/application - \title Application Example - - The Application example shows how to implement a standard GUI - application with menus, toolbars, and a status bar. The example - itself is a simple text editor program built around QPlainTextEdit. - - \image application.png Screenshot of the Application example - - Nearly all of the code for the Application example is in the \c - MainWindow class, which inherits QMainWindow. QMainWindow - provides the framework for windows that have menus, toolbars, - dock windows, and a status bar. The application provides - \uicontrol{File}, \uicontrol{Edit}, and \uicontrol{Help} entries in the menu - bar, with the following popup menus: - - \image application-menus.png The Application example's menu system - - The status bar at the bottom of the main window shows a - description of the menu item or toolbar button under the cursor. - - To keep the example simple, recently opened files aren't shown in - the \uicontrol{File} menu, even though this feature is desired in 90% - of applications. The \l{mainwindows/recentfiles}{Recent Files} - example shows how to implement this. Furthermore, this example - can only load one file at a time. The \l{mainwindows/sdi}{SDI} - and \l{mainwindows/mdi}{MDI} examples shows how to lift these - restrictions. - - \section1 MainWindow Class Definition - - Here's the class definition: - - \snippet mainwindows/application/mainwindow.h 0 - - The public API is restricted to the constructor. In the \c - protected section, we reimplement QWidget::closeEvent() to detect - when the user attempts to close the window, and warn the user - about unsaved changes. In the \c{private slots} section, we - declare slots that correspond to menu entries, as well as a - mysterious \c documentWasModified() slot. Finally, in the \c - private section of the class, we have various members that will - be explained in due time. - - \section1 MainWindow Class Implementation - - \snippet mainwindows/application/mainwindow.cpp 0 - - We start by including \c , a header file that contains the - definition of all classes in the \l QtCore and \l QtGui - libraries. This saves us from the trouble of having to include - every class individually. We also include \c mainwindow.h. - - You might wonder why we don't include \c in \c - mainwindow.h and be done with it. The reason is that including - such a large header from another header file can rapidly degrade - performances. Here, it wouldn't do any harm, but it's still - generally a good idea to include only the header files that are - strictly necessary from another header file. - - \snippet mainwindows/application/mainwindow.cpp 1 - \snippet mainwindows/application/mainwindow.cpp 2 - - In the constructor, we start by creating a QPlainTextEdit widget as a - child of the main window (the \c this object). Then we call - QMainWindow::setCentralWidget() to tell that this is going to be - the widget that occupies the central area of the main window, - between the toolbars and the status bar. - - Then we call \c createActions(), \c createMenus(), \c - createToolBars(), and \c createStatusBar(), four private - functions that set up the user interface. After that, we call \c - readSettings() to restore the user's preferences. - - We establish a signal-slot connection between the QPlainTextEdit's - document object and our \c documentWasModified() slot. Whenever - the user modifies the text in the QPlainTextEdit, we want to update - the title bar to show that the file was modified. - - At the end, we set the window title using the private - \c setCurrentFile() function. We'll come back to this later. - - \target close event handler - \snippet mainwindows/application/mainwindow.cpp 3 - \snippet mainwindows/application/mainwindow.cpp 4 - - When the user attempts to close the window, we call the private - function \c maybeSave() to give the user the possibility to save - pending changes. The function returns true if the user wants the - application to close; otherwise, it returns false. In the first - case, we save the user's preferences to disk and accept the close - event; in the second case, we ignore the close event, meaning - that the application will stay up and running as if nothing - happened. - - \snippet mainwindows/application/mainwindow.cpp 5 - \snippet mainwindows/application/mainwindow.cpp 6 - - The \c newFile() slot is invoked when the user selects - \uicontrol{File|New} from the menu. We call \c maybeSave() to save any - pending changes and if the user accepts to go on, we clear the - QPlainTextEdit and call the private function \c setCurrentFile() to - update the window title and clear the - \l{QWidget::windowModified}{windowModified} flag. - - \snippet mainwindows/application/mainwindow.cpp 7 - \snippet mainwindows/application/mainwindow.cpp 8 - - The \c open() slot is invoked when the user clicks - \uicontrol{File|Open}. We pop up a QFileDialog asking the user to - choose a file. If the user chooses a file (i.e., \c fileName is - not an empty string), we call the private function \c loadFile() - to actually load the file. - - \snippet mainwindows/application/mainwindow.cpp 9 - \snippet mainwindows/application/mainwindow.cpp 10 - - The \c save() slot is invoked when the user clicks - \uicontrol{File|Save}. If the user hasn't provided a name for the file - yet, we call \c saveAs(); otherwise, we call the private function - \c saveFile() to actually save the file. - - \snippet mainwindows/application/mainwindow.cpp 11 - \snippet mainwindows/application/mainwindow.cpp 12 - - In \c saveAs(), we start by popping up a QFileDialog asking the - user to provide a name. If the user clicks \uicontrol{Cancel}, the - returned file name is empty, and we do nothing. - - \snippet mainwindows/application/mainwindow.cpp 13 - \snippet mainwindows/application/mainwindow.cpp 14 - - The application's About box is done using one statement, using - the QMessageBox::about() static function and relying on its - support for an HTML subset. - - The \l{QObject::tr()}{tr()} call around the literal string marks - the string for translation. It is a good habit to call - \l{QObject::tr()}{tr()} on all user-visible strings, in case you - later decide to translate your application to other languages. - The \l{Internationalization with Qt} overview covers - \l{QObject::tr()}{tr()} in more detail. - - \snippet mainwindows/application/mainwindow.cpp 15 - \snippet mainwindows/application/mainwindow.cpp 16 - - The \c documentWasModified() slot is invoked each time the text - in the QPlainTextEdit changes because of user edits. We call - QWidget::setWindowModified() to make the title bar show that the - file was modified. How this is done varies on each platform. - - \snippet mainwindows/application/mainwindow.cpp 17 - \snippet mainwindows/application/mainwindow.cpp 18 - \dots - \snippet mainwindows/application/mainwindow.cpp 22 - - The \c createActions() private function, which is called from the - \c MainWindow constructor, creates \l{QAction}s. The code is very - repetitive, so we show only the actions corresponding to - \uicontrol{File|New}, \uicontrol{File|Open}, and \uicontrol{Help|About Qt}. - - A QAction is an object that represents one user action, such as - saving a file or invoking a dialog. An action can be put in a - QMenu or a QToolBar, or both, or in any other widget that - reimplements QWidget::actionEvent(). - - An action has a text that is shown in the menu, an icon, a - shortcut key, a tooltip, a status tip (shown in the status bar), - a "What's This?" text, and more. It emits a - \l{QAction::triggered()}{triggered()} signal whenever the user - invokes the action (e.g., by clicking the associated menu item or - toolbar button). We connect this signal to a slot that performs - the actual action. - - The code above contains one more idiom that must be explained. - For some of the actions, we specify an icon as a QIcon to the - QAction constructor. The QIcon constructor takes the file name - of an image that it tries to load. Here, the file name starts - with \c{:}. Such file names aren't ordinary file names, but - rather path in the executable's stored resources. We'll come back - to this when we review the \c application.qrc file that's part of - the project. - - \snippet mainwindows/application/mainwindow.cpp 23 - \snippet mainwindows/application/mainwindow.cpp 24 - - The \uicontrol{Edit|Cut} and \uicontrol{Edit|Copy} actions must be available - only when the QPlainTextEdit contains selected text. We disable them - by default and connect the QPlainTextEdit::copyAvailable() signal to - the QAction::setEnabled() slot, ensuring that the actions are - disabled when the text editor has no selection. - - \snippet mainwindows/application/mainwindow.cpp 25 - \snippet mainwindows/application/mainwindow.cpp 27 - - Creating actions isn't sufficient to make them available to the - user; we must also add them to the menu system. This is what \c - createMenus() does. We create a \uicontrol{File}, an \uicontrol{Edit}, and - a \uicontrol{Help} menu. QMainWindow::menuBar() lets us access the - window's menu bar widget. We don't have to worry about creating - the menu bar ourselves; the first time we call this function, the - QMenuBar is created. - - Just before we create the \uicontrol{Help} menu, we call - QMenuBar::addSeparator(). This has no effect for most widget - styles (e.g., Windows and Mac OS X styles), but for Motif-based - styles this makes sure that \uicontrol{Help} is pushed to the right - side of the menu bar. Try running the application with various - styles and see the results: - - \code - application -style=windows - application -style=motif - application -style=cde - \endcode - - Let's now review the toolbars: - - \snippet mainwindows/application/mainwindow.cpp 30 - - Creating toolbars is very similar to creating menus. The same - actions that we put in the menus can be reused in the toolbars. - - \snippet mainwindows/application/mainwindow.cpp 32 - \snippet mainwindows/application/mainwindow.cpp 33 - - QMainWindow::statusBar() returns a pointer to the main window's - QStatusBar widget. Like with \l{QMainWindow::menuBar()}, the - widget is automatically created the first time the function is - called. - - \snippet mainwindows/application/mainwindow.cpp 34 - \snippet mainwindows/application/mainwindow.cpp 36 - - The \c readSettings() function is called from the constructor to - load the user's preferences and other application settings. The - QSettings class provides a high-level interface for storing - settings permanently on disk. On Windows, it uses the (in)famous - Windows registry; on Mac OS X, it uses the native XML-based - CFPreferences API; on Unix/X11, it uses text files. - - The QSettings constructor takes arguments that identify your - company and the name of the product. This ensures that the - settings for different applications are kept separately. - - We use QSettings::value() to extract the value of the "pos" and - "size" settings. The second argument to QSettings::value() is - optional and specifies a default value for the setting if there - exists none. This value is used the first time the application is - run. - - When restoring the position and size of a window, it's important - to call QWidget::resize() before QWidget::move(). The reason why - is given in the \l{Window Geometry} overview. - - \snippet mainwindows/application/mainwindow.cpp 37 - \snippet mainwindows/application/mainwindow.cpp 39 - - The \c writeSettings() function is called from \c closeEvent(). - Writing settings is similar to reading them, except simpler. The - arguments to the QSettings constructor must be the same as in \c - readSettings(). - - \snippet mainwindows/application/mainwindow.cpp 40 - \snippet mainwindows/application/mainwindow.cpp 41 - - The \c maybeSave() function is called to save pending changes. If - there are pending changes, it pops up a QMessageBox giving the - user to save the document. The options are QMessageBox::Yes, - QMessageBox::No, and QMessageBox::Cancel. The \uicontrol{Yes} button is - made the default button (the button that is invoked when the user - presses \uicontrol{Return}) using the QMessageBox::Default flag; the - \uicontrol{Cancel} button is made the escape button (the button that is - invoked when the user presses \uicontrol{Esc}) using the - QMessageBox::Escape flag. - - The \c maybeSave() function returns \c true in all cases, except - when the user clicks \uicontrol{Cancel}. The caller must check the - return value and stop whatever it was doing if the return value - is \c false. - - \snippet mainwindows/application/mainwindow.cpp 42 - \snippet mainwindows/application/mainwindow.cpp 43 - - In \c loadFile(), we use QFile and QTextStream to read in the - data. The QFile object provides access to the bytes stored in a - file. - - We start by opening the file in read-only mode. The QFile::Text - flag indicates that the file is a text file, not a binary file. - On Unix and Mac OS X, this makes no difference, but on Windows, - it ensures that the "\\r\\n" end-of-line sequence is converted to - "\\n" when reading. - - If we successfully opened the file, we use a QTextStream object - to read in the data. QTextStream automatically converts the 8-bit - data into a Unicode QString and supports various encodings. If no - encoding is specified, QTextStream assumes the file is written - using the system's default 8-bit encoding (for example, Latin-1; - see QTextCodec::codecForLocale() for details). - - Since the call to QTextStream::readAll() might take some time, we - set the cursor to be Qt::WaitCursor for the entire application - while it goes on. - - At the end, we call the private \c setCurrentFile() function, - which we'll cover in a moment, and we display the string "File - loaded" in the status bar for 2 seconds (2000 milliseconds). - - \snippet mainwindows/application/mainwindow.cpp 44 - \snippet mainwindows/application/mainwindow.cpp 45 - - Saving a file is very similar to loading one. Here, the - QFile::Text flag ensures that on Windows, "\\n" is converted into - "\\r\\n" to conform to the Windows convension. - - \snippet mainwindows/application/mainwindow.cpp 46 - \snippet mainwindows/application/mainwindow.cpp 47 - - The \c setCurrentFile() function is called to reset the state of - a few variables when a file is loaded or saved, or when the user - starts editing a new file (in which case \c fileName is empty). - We update the \c curFile variable, clear the - QTextDocument::modified flag and the associated \c - QWidget:windowModified flag, and update the window title to - contain the new file name (or \c untitled.txt). - - The \c strippedName() function call around \c curFile in the - QWidget::setWindowTitle() call shortens the file name to exclude - the path. Here's the function: - - \snippet mainwindows/application/mainwindow.cpp 48 - \snippet mainwindows/application/mainwindow.cpp 49 - - \section1 The main() Function - - The \c main() function for this application is typical of - applications that contain one main window: - - \snippet mainwindows/application/main.cpp 0 - - \section1 The Resource File - - As you will probably recall, for some of the actions, we - specified icons with file names starting with \c{:} and mentioned - that such file names aren't ordinary file names, but path in the - executable's stored resources. These resources are compiled - - The resources associated with an application are specified in a - \c .qrc file, an XML-based file format that lists files on the - disk. Here's the \c application.qrc file that's used by the - Application example: - - \quotefile mainwindows/application/application.qrc - - The \c .png files listed in the \c application.qrc file are files - that are part of the Application example's source tree. Paths are - relative to the directory where the \c application.qrc file is - located (the \c mainwindows/application directory). - - The resource file must be mentioned in the \c application.pro - file so that \c qmake knows about it: - - \snippet mainwindows/application/application.pro 0 - - \c qmake will produce make rules to generate a file called \c - qrc_application.cpp that is linked into the application. This - file contains all the data for the images and other resources as - static C++ arrays of compressed binary data. See - \l{resources.html}{The Qt Resource System} for more information - about resources. -*/ diff --git a/examples/widgets/doc/basicdrawing.qdoc b/examples/widgets/doc/basicdrawing.qdoc deleted file mode 100644 index 899aa361f8..0000000000 --- a/examples/widgets/doc/basicdrawing.qdoc +++ /dev/null @@ -1,454 +0,0 @@ -/**************************************************************************** -** -** 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 painting/basicdrawing - \title Basic Drawing Example - - The Basic Drawing example shows how to display basic graphics - primitives in a variety of styles using the QPainter class. - - QPainter performs low-level painting on widgets and other paint - devices. The class can draw everything from simple lines to - complex shapes like pies and chords. It can also draw aligned text - and pixmaps. Normally, it draws in a "natural" coordinate system, - but it can in addition do view and world transformation. - - \image basicdrawing-example.png - - The example provides a render area, displaying the currently - active shape, and lets the user manipulate the rendered shape and - its appearance using the QPainter parameters: The user can change - the active shape (\uicontrol Shape), and modify the QPainter's pen (\uicontrol - {Pen Width}, \uicontrol {Pen Style}, \uicontrol {Pen Cap}, \uicontrol {Pen Join}), - brush (\uicontrol {Brush Style}) and render hints (\uicontrol - Antialiasing). In addition the user can rotate a shape (\uicontrol - Transformations); behind the scenes we use QPainter's ability to - manipulate the coordinate system to perform the rotation. - - The Basic Drawing example consists of two classes: - - \list - \li \c RenderArea is a custom widget that renders multiple - copies of the currently active shape. - \li \c Window is the application's main window displaying a - \c RenderArea widget in addition to several parameter widgets. - \endlist - - First we will review the \c Window class, then we will take a - look at the \c RenderArea class. - - \section1 Window Class Definition - - The Window class inherits QWidget, and is the application's main - window displaying a \c RenderArea widget in addition to several - parameter widgets. - - \snippet painting/basicdrawing/window.h 0 - - We declare the various widgets, and three private slots updating - the \c RenderArea widget: The \c shapeChanged() slot updates the - \c RenderArea widget when the user changes the currently active - shape. We call the \c penChanged() slot when either of the - QPainter's pen parameters changes. And the \c brushChanged() slot - updates the \c RenderArea widget when the user changes the - painter's brush style. - - \section1 Window Class Implementation - - In the constructor we create and initialize the various widgets - appearing in the main application window. - - \snippet painting/basicdrawing/window.cpp 1 - - First we create the \c RenderArea widget that will render the - currently active shape. Then we create the \uicontrol Shape combobox, - and add the associated items (i.e. the different shapes a QPainter - can draw). - - \snippet painting/basicdrawing/window.cpp 2 - - QPainter's pen is a QPen object; the QPen class defines how a - painter should draw lines and outlines of shapes. A pen has - several properties: Width, style, cap and join. - - A pen's width can be \e zero or greater, but the most common width - is zero. Note that this doesn't mean 0 pixels, but implies that - the shape is drawn as smoothly as possible although perhaps not - mathematically correct. - - We create a QSpinBox for the \uicontrol {Pen Width} parameter. - - \snippet painting/basicdrawing/window.cpp 3 - - The pen style defines the line type. The default style is solid - (Qt::SolidLine). Setting the style to none (Qt::NoPen) tells the - painter to not draw lines or outlines. The pen cap defines how - the end points of lines are drawn. And the pen join defines how - two lines join when multiple connected lines are drawn. The cap - and join only apply to lines with a width of 1 pixel or greater. - - We create \l {QComboBox}es for each of the \uicontrol {Pen Style}, \uicontrol - {Pen Cap} and \uicontrol {Pen Join} parameters, and adds the associated - items (i.e the values of the Qt::PenStyle, Qt::PenCapStyle and - Qt::PenJoinStyle enums respectively). - - \snippet painting/basicdrawing/window.cpp 4 - - The QBrush class defines the fill pattern of shapes drawn by a - QPainter. The default brush style is Qt::NoBrush. This style tells - the painter to not fill shapes. The standard style for filling is - Qt::SolidPattern. - - We create a QComboBox for the \uicontrol {Brush Style} parameter, and add - the associated items (i.e. the values of the Qt::BrushStyle enum). - - \snippet painting/basicdrawing/window.cpp 5 - \snippet painting/basicdrawing/window.cpp 6 - - Antialiasing is a feature that "smoothes" the pixels to create - more even and less jagged lines, and can be applied using - QPainter's render hints. QPainter::RenderHints are used to specify - flags to QPainter that may or may not be respected by any given - engine. - - We simply create a QCheckBox for the \uicontrol Antialiasing option. - - \snippet painting/basicdrawing/window.cpp 7 - - The \uicontrol Transformations option implies a manipulation of the - coordinate system that will appear as if the rendered shape is - rotated in three dimensions. - - We use the QPainter::translate(), QPainter::rotate() and - QPainter::scale() functions to implement this feature represented - in the main application window by a simple QCheckBox. - - \snippet painting/basicdrawing/window.cpp 8 - - Then we connect the parameter widgets with their associated slots - using the static QObject::connect() function, ensuring that the \c - RenderArea widget is updated whenever the user changes the shape, - or any of the other parameters. - - \snippet painting/basicdrawing/window.cpp 9 - \snippet painting/basicdrawing/window.cpp 10 - - Finally, we add the various widgets to a layout, and call the \c - shapeChanged(), \c penChanged(), and \c brushChanged() slots to - initialize the application. We also turn on antialiasing. - - \snippet painting/basicdrawing/window.cpp 11 - - The \c shapeChanged() slot is called whenever the user changes the - currently active shape. - - First we retrieve the shape the user has chosen using the - QComboBox::itemData() function. This function returns the data for - the given role in the given index in the combobox. We use - QComboBox::currentIndex() to retrieve the index of the shape, and - the role is defined by the Qt::ItemDataRole enum; \c IdRole is an - alias for Qt::UserRole. - - Note that Qt::UserRole is only the first role that can be used for - application-specific purposes. If you need to store different data - in the same index, you can use different roles by simply - incrementing the value of Qt::UserRole, for example: 'Qt::UserRole - + 1' and 'Qt::UserRole + 2'. However, it is a good programming - practice to give each role their own name: 'myFirstRole = - Qt::UserRole + 1' and 'mySecondRole = Qt::UserRole + 2'. Even - though we only need a single role in this particular example, we - add the following line of code to the beginning of the \c - window.cpp file. - - \snippet painting/basicdrawing/window.cpp 0 - - The QComboBox::itemData() function returns the data as a QVariant, - so we need to cast the data to \c RenderArea::Shape. If there is - no data for the given role, the function returns - QVariant::Invalid. - - In the end we call the \c RenderArea::setShape() slot to update - the \c RenderArea widget. - - \snippet painting/basicdrawing/window.cpp 12 - - We call the \c penChanged() slot whenever the user changes any of - the pen parameters. Again we use the QComboBox::itemData() - function to retrieve the parameters, and then we call the \c - RenderArea::setPen() slot to update the \c RenderArea widget. - - \snippet painting/basicdrawing/window.cpp 13 - - The brushChanged() slot is called whenever the user changes the - brush parameter which we retrieve using the QComboBox::itemData() - function as before. - - \snippet painting/basicdrawing/window.cpp 14 - - If the brush parameter is a gradient fill, special actions are - required. - - The QGradient class is used in combination with QBrush to specify - gradient fills. Qt currently supports three types of gradient - fills: linear, radial and conical. Each of these is represented by - a subclass of QGradient: QLinearGradient, QRadialGradient and - QConicalGradient. - - So if the brush style is Qt::LinearGradientPattern, we first - create a QLinearGradient object with interpolation area between - the coordinates passed as arguments to the constructor. The - positions are specified using logical coordinates. Then we set the - gradient's colors using the QGradient::setColorAt() function. The - colors is defined using stop points which are composed by a - position (between 0 and 1) and a QColor. The set of stop points - describes how the gradient area should be filled. A gradient can - have an arbitrary number of stop points. - - In the end we call \c RenderArea::setBrush() slot to update the \c - RenderArea widget's brush with the QLinearGradient object. - - \snippet painting/basicdrawing/window.cpp 15 - - A similar pattern of actions, as the one used for QLinearGradient, - is used in the cases of Qt::RadialGradientPattern and - Qt::ConicalGradientPattern. - - The only difference is the arguments passed to the constructor: - Regarding the QRadialGradient constructor the first argument is - the center, and the second the radial gradient's radius. The third - argument is optional, but can be used to define the focal point of - the gradient inside the circle (the default focal point is the - circle center). Regarding the QConicalGradient constructor, the - first argument specifies the center of the conical, and the second - specifies the start angle of the interpolation. - - \snippet painting/basicdrawing/window.cpp 16 - - If the brush style is Qt::TexturePattern we create a QBrush from a - QPixmap. Then we call \c RenderArea::setBrush() slot to update the - \c RenderArea widget with the newly created brush. - - \snippet painting/basicdrawing/window.cpp 17 - - Otherwise we simply create a brush with the given style and a - green color, and then call \c RenderArea::setBrush() slot to - update the \c RenderArea widget with the newly created brush. - - \section1 RenderArea Class Definition - - The \c RenderArea class inherits QWidget, and renders multiple - copies of the currently active shape using a QPainter. - - \snippet painting/basicdrawing/renderarea.h 0 - - First we define a public \c Shape enum to hold the different - shapes that can be rendered by the widget (i.e the shapes that can - be rendered by a QPainter). Then we reimplement the constructor as - well as two of QWidget's public functions: \l - {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l - {QWidget::sizeHint()}{sizeHint()}. - - We also reimplement the QWidget::paintEvent() function to be able - to draw the currently active shape according to the specified - parameters. - - We declare several private slots: The \c setShape() slot changes - the \c RenderArea's shape, the \c setPen() and \c setBrush() slots - modify the widget's pen and brush, and the \c setAntialiased() and - \c setTransformed() slots modify the widget's respective - properties. - - \section1 RenderArea Class Implementation - - In the constructor we initialize some of the widget's variables. - - \snippet painting/basicdrawing/renderarea.cpp 0 - - We set its shape to be a \uicontrol Polygon, its antialiased property to - be false and we load an image into the widget's pixmap - variable. In the end we set the widget's background role, defining - the brush from the widget's \l {QWidget::palette}{palette} that - will be used to render the background. QPalette::Base is typically - white. - - \snippet painting/basicdrawing/renderarea.cpp 2 - - The \c RenderArea inherits QWidget's \l - {QWidget::sizeHint()}{sizeHint} property holding the recommended - size for the widget. If the value of this property is an invalid - size, no size is recommended. - - The default implementation of the QWidget::sizeHint() function - returns an invalid size if there is no layout for the widget, and - returns the layout's preferred size otherwise. - - Our reimplementation of the function returns a QSize with a 400 - pixels width and a 200 pixels height. - - \snippet painting/basicdrawing/renderarea.cpp 1 - - \c RenderArea also inherits QWidget's - \l{QWidget::minimumSizeHint()}{minimumSizeHint} property holding - the recommended minimum size for the widget. Again, if the value - of this property is an invalid size, no size is recommended. - - The default implementation of QWidget::minimumSizeHint() returns - an invalid size if there is no layout for the widget, and returns - the layout's minimum size otherwise. - - Our reimplementation of the function returns a QSize with a 100 - pixels width and a 100 pixels height. - - \snippet painting/basicdrawing/renderarea.cpp 3 - \codeline - \snippet painting/basicdrawing/renderarea.cpp 4 - \codeline - \snippet painting/basicdrawing/renderarea.cpp 5 - - The public \c setShape(), \c setPen() and \c setBrush() slots are - called whenever we want to modify a \c RenderArea widget's shape, - pen or brush. We set the shape, pen or brush according to the - slot parameter, and call QWidget::update() to make the changes - visible in the \c RenderArea widget. - - The QWidget::update() slot does not cause an immediate - repaint; instead it schedules a paint event for processing when Qt - returns to the main event loop. - - \snippet painting/basicdrawing/renderarea.cpp 6 - \codeline - \snippet painting/basicdrawing/renderarea.cpp 7 - - With the \c setAntialiased() and \c setTransformed() slots we - change the state of the properties according to the slot - parameter, and call the QWidget::update() slot to make the changes - visible in the \c RenderArea widget. - - \snippet painting/basicdrawing/renderarea.cpp 8 - - Then we reimplement the QWidget::paintEvent() function. The first - thing we do is to create the graphical objects we will need to - draw the various shapes. - - We create a vector of four \l {QPoint}s. We use this vector to - render the \uicontrol Points, \uicontrol Polyline and \uicontrol Polygon - shapes. Then we create a QRect, defining a rectangle in the plane, - which we use as the bounding rectangle for all the shapes excluding - the \uicontrol Path and the \uicontrol Pixmap. - - We also create a QPainterPath. The QPainterPath class provides a - container for painting operations, enabling graphical shapes to be - constructed and reused. A painter path is an object composed of a - number of graphical building blocks, such as rectangles, ellipses, - lines, and curves. For more information about the QPainterPath - class, see the \l {painting/painterpaths}{Painter Paths} - example. In this example, we create a painter path composed of one - straight line and a Bezier curve. - - In addition we define a start angle and an arc length that we will - use when drawing the \uicontrol Arc, \uicontrol Chord and \uicontrol Pie shapes. - - \snippet painting/basicdrawing/renderarea.cpp 9 - - We create a QPainter for the \c RenderArea widget, and set the - painters pen and brush according to the \c RenderArea's pen and - brush. If the \uicontrol Antialiasing parameter option is checked, we - also set the painter's render hints. QPainter::Antialiasing - indicates that the engine should antialias edges of primitives if - possible. - - \snippet painting/basicdrawing/renderarea.cpp 10 - - Finally, we render the multiple copies of the \c RenderArea's - shape. The number of copies is depending on the size of the \c - RenderArea widget, and we calculate their positions using two \c - for loops and the widgets height and width. - - For each copy we first save the current painter state (pushes the - state onto a stack). Then we translate the coordinate system, - using the QPainter::translate() function, to the position - determined by the variables of the \c for loops. If we omit this - translation of the coordinate system all the copies of the shape - will be rendered on top of each other in the top left cormer of - the \c RenderArea widget. - - \snippet painting/basicdrawing/renderarea.cpp 11 - - If the \uicontrol Transformations parameter option is checked, we do an - additional translation of the coordinate system before we rotate - the coordinate system 60 degrees clockwise using the - QPainter::rotate() function and scale it down in size using the - QPainter::scale() function. In the end we translate the coordinate - system back to where it was before we rotated and scaled it. - - Now, when rendering the shape, it will appear as if it was rotated - in three dimensions. - - \snippet painting/basicdrawing/renderarea.cpp 12 - - Next, we identify the \c RenderArea's shape, and render it using - the associated QPainter drawing function: - - \list - \li QPainter::drawLine(), - \li QPainter::drawPoints(), - \li QPainter::drawPolyline(), - \li QPainter::drawPolygon(), - \li QPainter::drawRect(), - \li QPainter::drawRoundedRect(), - \li QPainter::drawEllipse(), - \li QPainter::drawArc(), - \li QPainter::drawChord(), - \li QPainter::drawPie(), - \li QPainter::drawPath(), - \li QPainter::drawText() or - \li QPainter::drawPixmap() - \endlist - - Before we started rendering, we saved the current painter state - (pushes the state onto a stack). The rationale for this is that we - calculate each shape copy's position relative to the same point in - the coordinate system. When translating the coordinate system, we - lose the knowledge of this point unless we save the current - painter state \e before we start the translating process. - - \snippet painting/basicdrawing/renderarea.cpp 13 - - Then, when we are finished rendering a copy of the shape we can - restore the original painter state, with its associated coordinate - system, using the QPainter::restore() function. In this way we - ensure that the next shape copy will be rendered in the correct - position. - - We could translate the coordinate system back using - QPainter::translate() instead of saving the painter state. But - since we in addition to translating the coordinate system (when - the \uicontrol Transformation parameter option is checked) both rotate - and scale the coordinate system, the easiest solution is to save - the current painter state. -*/ diff --git a/examples/widgets/doc/basicgraphicslayouts.qdoc b/examples/widgets/doc/basicgraphicslayouts.qdoc deleted file mode 100644 index 9f52b3eafa..0000000000 --- a/examples/widgets/doc/basicgraphicslayouts.qdoc +++ /dev/null @@ -1,164 +0,0 @@ -/**************************************************************************** -** -** 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 graphicsview/basicgraphicslayouts - \title Basic Graphics Layouts Example - - The Basic Graphics Layouts example shows how to use the layout classes - in QGraphicsView: QGraphicsLinearLayout and QGraphicsGridLayout. - In addition to that it shows how to write your own custom layout item. - - \image basicgraphicslayouts-example.png Screenshot of the Basic Layouts Example - - \section1 Window Class Definition - - The \c Window class is a subclass of QGraphicsWidget. It has a - constructor with a QGraphicsWidget \a parent as its parameter. - - \snippet graphicsview/basicgraphicslayouts/window.h 0 - - \section1 Window Class Implementation - - The constructor of \c Window instantiates a QGraphicsLinearLayout object, - \c windowLayout, with vertical orientation. We instantiate another - QGraphicsLinearLayout object, \c linear, whose parent is \c windowLayout. - Next, we create a \c LayoutItem object, \c item and add it to \c linear - with the \l{QGraphicsLinearLayout::}{addItem()} function. We also provide - \c item with a \l{QGraphicsLinearLayout::setStretchFactor()} - {stretchFactor}. - - \snippet graphicsview/basicgraphicslayouts/window.cpp 0 - - We repeat the process: - - \list - \li create a new \c LayoutItem, - \li add the item \c linear, and - \li provide a stretch factor. - \endlist - - \snippet graphicsview/basicgraphicslayouts/window.cpp 1 - - We then add \c linear to \c windowLayout, nesting two - QGraphicsLinearLayout objects. Apart from the QGraphicsLinearLayout, we - also use a QGraphicsGridLayout object, \c grid, which is a 4x3 grid with - some cells spanning to other rows. - - We create seven \c LayoutItem objects and place them into \c grid with - the \l{QGraphicsGridLayout::}{addItem()} function as shown in the code - snippet below: - - \snippet graphicsview/basicgraphicslayouts/window.cpp 2 - - The first item we add to \c grid is placed in the top left cell, - spanning four rows. The next two items are placed in the second column, - and they span two rows. Each item's \l{QGraphicsWidget::}{maximumHeight()} - and \l{QGraphicsWidget::}{minimumHeight()} are set to be equal so that - they do not expand vertically. As a result, these items will not - fit vertically in their cells. So, we specify that they should be - vertically aligned in the center of the cell using Qt::AlignVCenter. - - Finally, \c grid itself is added to \c windowLayout. Unlike - QGridLayout::addItem(), QGraphicsGridLayout::addItem() requires a row - and a column for its argument, specifying which cell the item should be - positioned in. Also, if the \c rowSpan and \c columnSpan arguments - are omitted, they will default to 1. - - Note that we do not specify a parent for each \c LayoutItem that we - construct, as all these items will be added to \c windowLayout. When we - add an item to a layout, it will be automatically reparented to the widget - on which the layout is installed. - - \snippet graphicsview/basicgraphicslayouts/window.cpp 3 - - Now that we have set up \c grid and added it to \c windowLayout, we - install \c windowLayout onto the window object using - QGraphicsWidget::setLayout() and we set the window title. - - \section1 LayoutItem Class Definition - - The \c LayoutItem class is a subclass of QGraphicsLayoutItem and - QGraphicsItem. It has a constructor, a destructor, and some required - reimplementations. - Since it inherits QGraphicsLayoutItem it must reimplement - {QGraphicsLayoutItem::setGeometry()}{setGeometry()} and - {QGraphicsLayoutItem::sizeHint()}{sizeHint()}. - In addition to that it inherits QGraphicsItem, so it must reimplement - {QGraphicsItem::boundingRect()}{boundingRect()} and - {QGraphicsItem::paint()}{paint()}. - - \snippet graphicsview/basicgraphicslayouts/layoutitem.h 0 - - The \c LayoutItem class also has a private instance of QPixmap, \c m_pix. - - \section1 LayoutItem Class Implementation - - In \c{LayoutItem}'s constructor, \c m_pix is instantiated and the - \c{block.png} image is loaded into it. - - \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 0 - - We use the Q_UNUSED() macro to prevent the compiler from generating - warnings regarding unused parameters. - - \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 1 - - The idea behind the \c paint() function is to paint the - background rect then paint a rect around the pixmap. - - \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 2 - - The reimplementation of \l{QGraphicsItem::}{boundingRect()} - will set the top left corner at (0,0), and the size of it will be - the size of the layout items - \l{QGraphicsLayoutItem::}{geometry()}. This is the area that - we paint within. - - \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 3 - - - The reimplementation of \l{QGraphicsLayoutItem::setGeometry()}{setGeometry()} - simply calls its baseclass implementation. However, since this will change - the boundingRect we must also call - \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()}. - Finally, we move the item according to \c geom.topLeft(). - - \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 4 - - - Since we don't want the size of the item to be smaller than the pixmap, we - must make sure that we return a size hint that is larger than \c m_pix. - We also add some extra space around for borders that we will paint later. - Alternatively, you could scale the pixmap to prevent the item from - becoming smaller than the pixmap. - The preferred size is the same as the minimum size hint, while we set - maximum to be a large value - - \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 5 - -*/ diff --git a/examples/widgets/doc/basiclayouts.qdoc b/examples/widgets/doc/basiclayouts.qdoc deleted file mode 100644 index a0f083ba58..0000000000 --- a/examples/widgets/doc/basiclayouts.qdoc +++ /dev/null @@ -1,190 +0,0 @@ -/**************************************************************************** -** -** 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 layouts/basiclayouts - \title Basic Layouts Example - - The Basic Layouts example shows how to use the standard layout - managers that are available in Qt: QBoxLayout, QGridLayout and - QFormLayout. - - \image basiclayouts-example.png Screenshot of the Basic Layouts example - - The QBoxLayout class lines up widgets horizontally or vertically. - QHBoxLayout and QVBoxLayout are convenience subclasses of QBoxLayout. - QGridLayout lays out widgets in cells by dividing the available space - into rows and columns. QFormLayout, on the other hand, lays out its - children in a two-column form with labels in the left column and - input fields in the right column. - - \section1 Dialog Class Definition - - \snippet layouts/basiclayouts/dialog.h 0 - - The \c Dialog class inherits QDialog. It is a custom widget that - displays its child widgets using the geometry managers: - QHBoxLayout, QVBoxLayout, QGridLayout and QFormLayout. - - We declare four private functions to simplify the class - constructor: The \c createMenu(), \c createHorizontalGroupBox(), - \c createGridGroupBox() and \c createFormGroupBox() functions create - several widgets that the example uses to demonstrate how the layout - affects their appearances. - - \section1 Dialog Class Implementation - - \snippet layouts/basiclayouts/dialog.cpp 0 - - In the constructor, we first use the \c createMenu() function to - create and populate a menu bar and the \c createHorizontalGroupBox() - function to create a group box containing four buttons with a - horizontal layout. Next we use the \c createGridGroupBox() function - to create a group box containing several line edits and a small text - editor which are displayed in a grid layout. Finally, we use the - \c createFormGroupBox() function to create a group box with - three labels and three input fields: a line edit, a combo box and - a spin box. - - \snippet layouts/basiclayouts/dialog.cpp 1 - - We also create a big text editor and a dialog button box. The - QDialogButtonBox class is a widget that presents buttons in a - layout that is appropriate to the current widget style. The - preferred buttons can be specified as arguments to the - constructor, using the QDialogButtonBox::StandardButtons enum. - - Note that we don't have to specify a parent for the widgets when - we create them. The reason is that all the widgets we create here - will be added to a layout, and when we add a widget to a layout, - it is automatically reparented to the widget the layout is - installed on. - - \snippet layouts/basiclayouts/dialog.cpp 2 - - The main layout is a QVBoxLayout object. QVBoxLayout is a - convenience class for a box layout with vertical orientation. - - In general, the QBoxLayout class takes the space it gets (from its - parent layout or from the parent widget), divides it up into a - series of boxes, and makes each managed widget fill one box. If - the QBoxLayout's orientation is Qt::Horizontal the boxes are - placed in a row. If the orientation is Qt::Vertical, the boxes are - placed in a column. The corresponding convenience classes are - QHBoxLayout and QVBoxLayout, respectively. - - \snippet layouts/basiclayouts/dialog.cpp 3 - - When we call the QLayout::setMenuBar() function, the layout places - the provided menu bar at the top of the parent widget, and outside - the widget's \l {QWidget::contentsRect()}{content margins}. All - child widgets are placed below the bottom edge of the menu bar. - - \snippet layouts/basiclayouts/dialog.cpp 4 - - We use the QBoxLayout::addWidget() function to add the widgets to - the end of layout. Each widget will get at least its minimum size - and at most its maximum size. It is possible to specify a stretch - factor in the \l {QBoxLayout::addWidget()}{addWidget()} function, - and any excess space is shared according to these stretch - factors. If not specified, a widget's stretch factor is 0. - - \snippet layouts/basiclayouts/dialog.cpp 5 - - We install the main layout on the \c Dialog widget using the - QWidget::setLayout() function, and all of the layout's widgets are - automatically reparented to be children of the \c Dialog widget. - - \snippet layouts/basiclayouts/dialog.cpp 6 - - In the private \c createMenu() function we create a menu bar, and - add a pull-down \uicontrol File menu containing an \uicontrol Exit option. - - \snippet layouts/basiclayouts/dialog.cpp 7 - - When we create the horizontal group box, we use a QHBoxLayout as - the internal layout. We create the buttons we want to put in the - group box, add them to the layout and install the layout on the - group box. - - \snippet layouts/basiclayouts/dialog.cpp 8 - - In the \c createGridGroupBox() function we use a QGridLayout which - lays out widgets in a grid. It takes the space made available to - it (by its parent layout or by the parent widget), divides it up - into rows and columns, and puts each widget it manages into the - correct cell. - - \snippet layouts/basiclayouts/dialog.cpp 9 - - For each row in the grid we create a label and an associated line - edit, and add them to the layout. The QGridLayout::addWidget() - function differ from the corresponding function in QBoxLayout: It - needs the row and column specifying the grid cell to put the - widget in. - - \snippet layouts/basiclayouts/dialog.cpp 10 - - QGridLayout::addWidget() can in addition take arguments - specifying the number of rows and columns the cell will be - spanning. In this example, we create a small editor which spans - three rows and one column. - - For both the QBoxLayout::addWidget() and QGridLayout::addWidget() - functions it is also possible to add a last argument specifying - the widget's alignment. By default it fills the whole cell. But we - could, for example, align a widget with the right edge by - specifying the alignment to be Qt::AlignRight. - - \snippet layouts/basiclayouts/dialog.cpp 11 - - Each column in a grid layout has a stretch factor. The stretch - factor is set using QGridLayout::setColumnStretch() and determines - how much of the available space the column will get over and above - its necessary minimum. - - In this example, we set the stretch factors for columns 1 and 2. - The stretch factor is relative to the other columns in this grid; - columns with a higher stretch factor take more of the available - space. So column 2 in our grid layout will get more of the - available space than column 1, and column 0 will not grow at all - since its stretch factor is 0 (the default). - - Columns and rows behave identically; there is an equivalent - stretch factor for rows, as well as a QGridLayout::setRowStretch() - function. - - \snippet layouts/basiclayouts/dialog.cpp 12 - - In the \c createFormGroupBox() function, we use a QFormLayout - to neatly arrange objects into two columns - name and field. - There are three QLabel objects for names with three - corresponding input widgets as fields: a QLineEdit, a QComboBox - and a QSpinBox. Unlike QBoxLayout::addWidget() and - QGridLayout::addWidget(), we use QFormLayout::addRow() to add widgets - to the layout. -*/ diff --git a/examples/widgets/doc/basicsortfiltermodel.qdoc b/examples/widgets/doc/basicsortfiltermodel.qdoc deleted file mode 100644 index 0ecf4a0629..0000000000 --- a/examples/widgets/doc/basicsortfiltermodel.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/basicsortfiltermodel - \title Basic Sort/Filter Model Example - - The Basic Sort/Filter Model example illustrates how to use - QSortFilterProxyModel to perform basic sorting and filtering. - - \image basicsortfiltermodel-example.png Screenshot of the Basic Sort/Filter Model Example - -*/ diff --git a/examples/widgets/doc/blurpicker.qdoc b/examples/widgets/doc/blurpicker.qdoc deleted file mode 100644 index bd57acb061..0000000000 --- a/examples/widgets/doc/blurpicker.qdoc +++ /dev/null @@ -1,33 +0,0 @@ -/**************************************************************************** -** -** 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 effects/blurpicker - \title Blur Picker Effect Example - - \image blurpickereffect-example.png -*/ diff --git a/examples/widgets/doc/borderlayout.qdoc b/examples/widgets/doc/borderlayout.qdoc deleted file mode 100644 index aaff2dda1d..0000000000 --- a/examples/widgets/doc/borderlayout.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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 layouts/borderlayout - \title Border Layout Example - - The Border Layout example shows how to create a custom layout that arranges - child widgets according to a simple set of rules. - - \image borderlayout-example.png -*/ diff --git a/examples/widgets/doc/boxes.qdoc b/examples/widgets/doc/boxes.qdoc deleted file mode 100644 index aa34a61bc3..0000000000 --- a/examples/widgets/doc/boxes.qdoc +++ /dev/null @@ -1,49 +0,0 @@ -/**************************************************************************** -** -** 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 graphicsview/boxes - \title Boxes - - This demo shows Qt's ability to combine advanced OpenGL rendering with the - the \l{Graphics View Framework}. - - \image boxes-demo.png - - Elements in the demo can be controlled using the mouse in the following - ways: - \list - \li Dragging the mouse while pressing the left mouse button rotates the - box in the center. - \li Dragging the mouse while pressing the right mouse button rotates the - satellite boxes. - \li Scrolling the mouse wheel zooms in and out of the scene. - \endlist - - The options pane can be used to fine-tune various parameters in the demo, - including colors and pixel shaders. -*/ diff --git a/examples/widgets/doc/calculator.qdoc b/examples/widgets/doc/calculator.qdoc deleted file mode 100644 index 8480d90477..0000000000 --- a/examples/widgets/doc/calculator.qdoc +++ /dev/null @@ -1,375 +0,0 @@ -/**************************************************************************** -** -** 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/calculator - \title Calculator Example - - The example shows how to use signals and slots to implement the - functionality of a calculator widget, and how to use QGridLayout - to place child widgets in a grid. - - \image calculator-example.png Screenshot of the Calculator example - - The example consists of two classes: - - \list - \li \c Calculator is the calculator widget, with all the - calculator functionality. - \li \c Button is the widget used for each of the calculator - button. It derives from QToolButton. - \endlist - - We will start by reviewing \c Calculator, then we will take a - look at \c Button. - - \section1 Calculator Class Definition - - \snippet widgets/calculator/calculator.h 0 - - The \c Calculator class provides a simple calculator widget. It - inherits from QDialog and has several private slots associated - with the calculator's buttons. QObject::eventFilter() is - reimplemented to handle mouse events on the calculator's display. - - Buttons are grouped in categories according to their behavior. - For example, all the digit buttons (labeled \uicontrol 0 to \uicontrol 9) - append a digit to the current operand. For these, we connect - multiple buttons to the same slot (e.g., \c digitClicked()). The - categories are digits, unary operators (\uicontrol{Sqrt}, \uicontrol{x\unicode{178}}, - \uicontrol{1/x}), additive operators (\uicontrol{+}, \uicontrol{-}), and - multiplicative operators (\uicontrol{\unicode{215}}, \uicontrol{\unicode{247}}). The other buttons - have their own slots. - - \snippet widgets/calculator/calculator.h 1 - \snippet widgets/calculator/calculator.h 2 - - The private \c createButton() function is used as part of the - widget construction. \c abortOperation() is called whenever a - division by zero occurs or when a square root operation is - applied to a negative number. \c calculate() applies a binary - operator (\uicontrol{+}, \uicontrol{-}, \uicontrol{\unicode{215}}, or \uicontrol{\unicode{247}}). - - \snippet widgets/calculator/calculator.h 3 - \snippet widgets/calculator/calculator.h 4 - \snippet widgets/calculator/calculator.h 5 - \snippet widgets/calculator/calculator.h 6 - \snippet widgets/calculator/calculator.h 7 - \snippet widgets/calculator/calculator.h 8 - - These variables, together with the contents of the calculator - display (a QLineEdit), encode the state of the calculator: - - \list - \li \c sumInMemory contains the value stored in the calculator's memory - (using \uicontrol{MS}, \uicontrol{M+}, or \uicontrol{MC}). - \li \c sumSoFar stores the value accumulated so far. When the user - clicks \uicontrol{=}, \c sumSoFar is recomputed and shown on the - display. \uicontrol{Clear All} resets \c sumSoFar to zero. - \li \c factorSoFar stores a temporary value when doing - multiplications and divisions. - \li \c pendingAdditiveOperator stores the last additive operator - clicked by the user. - \li \c pendingMultiplicativeOperator stores the last multiplicative operator - clicked by the user. - \li \c waitingForOperand is \c true when the calculator is - expecting the user to start typing an operand. - \endlist - - Additive and multiplicative operators are treated differently - because they have different precedences. For example, \uicontrol{1 + 2 \unicode{247} - 3} is interpreted as \uicontrol{1 + (2 \unicode{247} 3)} because \uicontrol{\unicode{247}} has higher - precedence than \uicontrol{+}. - - The table below shows the evolution of the calculator state as - the user enters a mathematical expression. - - \table - \header \li User Input \li Display \li Sum so Far \li Add. Op. \li Factor so Far \li Mult. Op. \li Waiting for Operand? - \row \li \li 0 \li 0 \li \li \li \li \c true - \row \li \uicontrol{1} \li 1 \li 0 \li \li \li \li \c false - \row \li \uicontrol{1 +} \li 1 \li 1 \li \uicontrol{+} \li \li \li \c true - \row \li \uicontrol{1 + 2} \li 2 \li 1 \li \uicontrol{+} \li \li \li \c false - \row \li \uicontrol{1 + 2 \unicode{247}} \li 2 \li 1 \li \uicontrol{+} \li 2 \li \uicontrol{\unicode{247}} \li \c true - \row \li \uicontrol{1 + 2 \unicode{247} 3} \li 3 \li 1 \li \uicontrol{+} \li 2 \li \uicontrol{\unicode{247}} \li \c false - \row \li \uicontrol{1 + 2 \unicode{247} 3 -} \li 1.66667 \li 1.66667 \li \uicontrol{-} \li \li \li \c true - \row \li \uicontrol{1 + 2 \unicode{247} 3 - 4} \li 4 \li 1.66667 \li \uicontrol{-} \li \li \li \c false - \row \li \uicontrol{1 + 2 \unicode{247} 3 - 4 =} \li -2.33333 \li 0 \li \li \li \li \c true - \endtable - - Unary operators, such as \uicontrol Sqrt, require no special handling; - they can be applied immediately since the operand is already - known when the operator button is clicked. - - \snippet widgets/calculator/calculator.h 9 - \codeline - \snippet widgets/calculator/calculator.h 10 - - Finally, we declare the variables associated with the display and the - buttons used to display numerals. - - \section1 Calculator Class Implementation - - \snippet widgets/calculator/calculator.cpp 0 - - In the constructor, we initialize the calculator's state. The \c - pendingAdditiveOperator and \c pendingMultiplicativeOperator - variables don't need to be initialized explicitly, because the - QString constructor initializes them to empty strings. - - \snippet widgets/calculator/calculator.cpp 1 - \snippet widgets/calculator/calculator.cpp 2 - - We create the QLineEdit representing the calculator's display and - set up some of its properties. In particular, we set it to be - read-only. - - We also enlarge \c{display}'s font by 8 points. - - \snippet widgets/calculator/calculator.cpp 4 - - For each button, we call the private \c createButton() function with - the proper text label and a slot to connect to the button. - - \snippet widgets/calculator/calculator.cpp 5 - \snippet widgets/calculator/calculator.cpp 6 - - The layout is handled by a single QGridLayout. The - QLayout::setSizeConstraint() call ensures that the \c Calculator - widget is always shown as its optimal size (its - \l{QWidget::sizeHint()}{size hint}), preventing the user from - resizing the calculator. The size hint is determined by the size - and \l{QWidget::sizePolicy()}{size policy} of the child widgets. - - Most child widgets occupy only one cell in the grid layout. For - these, we only need to pass a row and a column to - QGridLayout::addWidget(). The \c display, \c backspaceButton, \c - clearButton, and \c clearAllButton widgets occupy more than one - column; for these we must also pass a row span and a column - span. - - \snippet widgets/calculator/calculator.cpp 7 - - Pressing one of the calculator's digit buttons will emit the - button's \l{QToolButton::clicked()}{clicked()} signal, which will - trigger the \c digitClicked() slot. - - First, we find out which button sent the signal using - QObject::sender(). This function returns the sender as a QObject - pointer. Since we know that the sender is a \c Button object, we - can safely cast the QObject. We could have used a C-style cast or - a C++ \c static_cast<>(), but as a defensive programming - technique we use a \l qobject_cast(). The advantage is that if - the object has the wrong type, a null pointer is returned. - Crashes due to null pointers are much easier to diagnose than - crashes due to unsafe casts. Once we have the button, we extract - the operator using QToolButton::text(). - - The slot needs to consider two situations in particular. If \c - display contains "0" and the user clicks the \uicontrol{0} button, it - would be silly to show "00". And if the calculator is in - a state where it is waiting for a new operand, - the new digit is the first digit of that new operand; in that case, - any result of a previous calculation must be cleared first. - - At the end, we append the new digit to the value in the display. - - \snippet widgets/calculator/calculator.cpp 8 - \snippet widgets/calculator/calculator.cpp 9 - - The \c unaryOperatorClicked() slot is called whenever one of the - unary operator buttons is clicked. Again a pointer to the clicked - button is retrieved using QObject::sender(). The operator is - extracted from the button's text and stored in \c - clickedOperator. The operand is obtained from \c display. - - Then we perform the operation. If \uicontrol Sqrt is applied to a - negative number or \uicontrol{1/x} to zero, we call \c - abortOperation(). If everything goes well, we display the result - of the operation in the line edit and we set \c waitingForOperand - to \c true. This ensures that if the user types a new digit, the - digit will be considered as a new operand, instead of being - appended to the current value. - - \snippet widgets/calculator/calculator.cpp 10 - \snippet widgets/calculator/calculator.cpp 11 - - The \c additiveOperatorClicked() slot is called when the user - clicks the \uicontrol{+} or \uicontrol{-} button. - - Before we can actually do something about the clicked operator, - we must handle any pending operations. We start with the - multiplicative operators, since these have higher precedence than - additive operators: - - \snippet widgets/calculator/calculator.cpp 12 - \snippet widgets/calculator/calculator.cpp 13 - - If \uicontrol{\unicode{215}} or \uicontrol{\unicode{247}} has been clicked earlier, without clicking - \uicontrol{=} afterward, the current value in the display is the right - operand of the \uicontrol{\unicode{215}} or \uicontrol{\unicode{247}} operator and we can finally - perform the operation and update the display. - - \snippet widgets/calculator/calculator.cpp 14 - \snippet widgets/calculator/calculator.cpp 15 - - If \uicontrol{+} or \uicontrol{-} has been clicked earlier, \c sumSoFar is - the left operand and the current value in the display is the - right operand of the operator. If there is no pending additive - operator, \c sumSoFar is simply set to be the text in the - display. - - \snippet widgets/calculator/calculator.cpp 16 - \snippet widgets/calculator/calculator.cpp 17 - - Finally, we can take care of the operator that was just clicked. - Since we don't have the right-hand operand yet, we store the clicked - operator in the \c pendingAdditiveOperator variable. We will - apply the operation later, when we have a right operand, with \c - sumSoFar as the left operand. - - \snippet widgets/calculator/calculator.cpp 18 - - The \c multiplicativeOperatorClicked() slot is similar to \c - additiveOperatorClicked(). We don't need to worry about pending - additive operators here, because multiplicative operators have - precedence over additive operators. - - \snippet widgets/calculator/calculator.cpp 20 - - Like in \c additiveOperatorClicked(), we start by handing any - pending multiplicative and additive operators. Then we display \c - sumSoFar and reset the variable to zero. Resetting the variable - to zero is necessary to avoid counting the value twice. - - \snippet widgets/calculator/calculator.cpp 22 - - The \c pointClicked() slot adds a decimal point to the content in - \c display. - - \snippet widgets/calculator/calculator.cpp 24 - - The \c changeSignClicked() slot changes the sign of the value in - \c display. If the current value is positive, we prepend a minus - sign; if the current value is negative, we remove the first - character from the value (the minus sign). - - \snippet widgets/calculator/calculator.cpp 26 - - The \c backspaceClicked() removes the rightmost character in the - display. If we get an empty string, we show "0" and set \c - waitingForOperand to \c true. - - \snippet widgets/calculator/calculator.cpp 28 - - The \c clear() slot resets the current operand to zero. It is - equivalent to clicking \uicontrol Backspace enough times to erase the - entire operand. - - \snippet widgets/calculator/calculator.cpp 30 - - The \c clearAll() slot resets the calculator to its initial state. - - \snippet widgets/calculator/calculator.cpp 32 - - The \c clearMemory() slot erases the sum kept in memory, \c - readMemory() displays the sum as an operand, \c setMemory() - replace the sum in memory with the current sum, and \c - addToMemory() adds the current value to the value in memory. For - \c setMemory() and \c addToMemory(), we start by calling \c - equalClicked() to update \c sumSoFar and the value in the - display. - - \snippet widgets/calculator/calculator.cpp 34 - - The private \c createButton() function is called from the - constructor to create calculator buttons. - - \snippet widgets/calculator/calculator.cpp 36 - - The private \c abortOperation() function is called whenever a - calculation fails. It resets the calculator state and displays - "####". - - \snippet widgets/calculator/calculator.cpp 38 - - The private \c calculate() function performs a binary operation. - The right operand is given by \c rightOperand. For additive - operators, the left operand is \c sumSoFar; for multiplicative - operators, the left operand is \c factorSoFar. The function - return \c false if a division by zero occurs. - - \section1 Button Class Definition - - Let's now take a look at the \c Button class: - - \snippet widgets/calculator/button.h 0 - - The \c Button class has a convenience constructor that takes a - text label and a parent widget, and it reimplements QWidget::sizeHint() - to provide more space around the text than the amount QToolButton - normally provides. - - \section1 Button Class Implementation - - \snippet widgets/calculator/button.cpp 0 - - The buttons' appearance is determined by the layout of the - calculator widget through the size and - \l{QWidget::sizePolicy}{size policy} of the layout's child - widgets. The call to the - \l{QWidget::setSizePolicy()}{setSizePolicy()} function in the - constructor ensures that the button will expand horizontally to - fill all the available space; by default, \l{QToolButton}s don't - expand to fill available space. Without this call, the different - buttons in a same column would have different widths. - - \snippet widgets/calculator/button.cpp 1 - \snippet widgets/calculator/button.cpp 2 - - In \l{QWidget::sizeHint()}{sizeHint()}, we try to return a size - that looks good for most buttons. We reuse the size hint of the - base class (QToolButton) but modify it in the following ways: - - \list - \li We add 20 to the \l{QSize::height()}{height} component of the size hint. - \li We make the \l{QSize::width()}{width} component of the size - hint at least as much as the \l{QSize::width()}{height}. - \endlist - - This ensures that with most fonts, the digit and operator buttons - will be square, without truncating the text on the - \uicontrol{Backspace}, \uicontrol{Clear}, and \uicontrol{Clear All} buttons. - - The screenshot below shows how the \c Calculator widget would - look like if we \e didn't set the horizontal size policy to - QSizePolicy::Expanding in the constructor and if we didn't - reimplement QWidget::sizeHint(). - - \image calculator-ugly.png The Calculator example with default size policies and size hints - -*/ diff --git a/examples/widgets/doc/calendar.qdoc b/examples/widgets/doc/calendar.qdoc deleted file mode 100644 index b7fa7c8617..0000000000 --- a/examples/widgets/doc/calendar.qdoc +++ /dev/null @@ -1,223 +0,0 @@ -/**************************************************************************** -** -** 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 richtext/calendar - \title Calendar Example - - The Calendar example shows how to create rich text content and display it using - a rich text editor. - - \image calendar-example.png - - Specifically, the example demonstrates the following: - - \list - \li Use of a text editor with a text document - \li Insertion of tables and frames into a document - \li Navigation within a table - \li Insert text in different styles - \endlist - - The rich text editor used to display the document is used within a main window - application. - - \section1 MainWindow Class Definition - - The \c MainWindow class provides a text editor widget and some controls to - allow the user to change the month and year shown. The font size used for the - text can also be adjusted. - - \snippet richtext/calendar/mainwindow.h 0 - - The private \c insertCalendar() function performs most of the work, relying on - the \c fontSize and \c selectedDate variables to write useful information to - the \c editor. - - \section1 MainWindow Class Implementation - - The \c MainWindow constructor sets up the user interface and initializes - variables used to generate a calendar for each month. - - \snippet richtext/calendar/mainwindow.cpp 0 - - We begin by setting default values for the selected date that will be highlighted - in the calendar and the font size to be used. Since we are using a QMainWindow - for the user interface, we construct a widget for use as the central widget. - - The user interface will include a line of controls above the generated calendar; - we construct a label and a combobox to allow the month to be selected, and a - spin box for the year. These widgets are configured to provide a reasonable range - of values for the user to try: - - \snippet richtext/calendar/mainwindow.cpp 1 - - We use the \c selectedDate object to obtain the current month and year, and we - set these in the combobox and spin box: - - The font size is displayed in a spin box which we restrict to a sensible range - of values: - - \snippet richtext/calendar/mainwindow.cpp 2 - - We construct an editor and use the \c insertCalendar() function to create - a calendar for it. Each calendar is displayed in the same text editor; in - this example we use a QTextBrowser since we do not allow the calendar to be - edited. - - The controls used to set the month, year, and font size will not have any - effect on the appearance of the calendar unless we make some signal-slot - connections: - - \snippet richtext/calendar/mainwindow.cpp 3 - - The signals are connected to some simple slots in the \c MainWindow class - which we will describe later. - - We create layouts to manage the widgets we constructed: - - \snippet richtext/calendar/mainwindow.cpp 4 - - Finally, the central widget is set for the window. - - Each calendar is created for the editor by the \c insertCalendar() function - which uses the date and font size, defined by the private \a selectedDate - and \c fontSize variables, to produce a suitable plan for the specified - month and year. - - \snippet richtext/calendar/mainwindow.cpp 5 - - We begin by clearing the editor's rich text document, and obtain a text - cursor from the editor that we will use to add content. We also create a - QDate object based on the currently selected date. - - The calendar is made up of a table with a gray background color that contains - seven columns: one for each day of the week. It is placed in the center of the - page with equal space to the left and right of it. All of these properties are - set in a QTextTableFormat object: - - \snippet richtext/calendar/mainwindow.cpp 6 - - Each cell in the table will be padded and spaced to make the text easier to - read. - - We want the columns to have equal widths, so we provide a vector containing - percentage widths for each of them and set the constraints in the - QTextTableFormat: - - \snippet richtext/calendar/mainwindow.cpp 7 - - The constraints used for the column widths are only useful if the table has - an appropriate number of columns. With the format for the table defined, we - construct a new table with one row and seven columns at the current cursor - position: - - \snippet richtext/calendar/mainwindow.cpp 8 - - We only need one row to start with; more can be added as we need them. Using - this approach means that we do not need to perform any date calculations - until we add cells to the table. - - When inserting objects into a document with the cursor's insertion functions, - the cursor is automatically moved inside the newly inserted object. This means - that we can immediately start modifying the table from within: - - \snippet richtext/calendar/mainwindow.cpp 9 - - Since the table has an outer frame, we obtain the frame and its format so that - we can customize it. After making the changes we want, we set the frame's format - using the modified format object. We have given the table an outer border one - pixel wide. - - \snippet richtext/calendar/mainwindow.cpp 10 - - In a similar way, we obtain the cursor's current character format and - create customized formats based on it. - - We do not set the format on the cursor because this would change the default - character format; instead, we use the customized formats explicitly when we - insert text. The following loop inserts the days of the week into the table - as bold text: - - \snippet richtext/calendar/mainwindow.cpp 11 - - For each day of the week, we obtain an existing table cell in the first row - (row 0) using the table's \l{QTextTable::cellAt()}{cellAt()} function. Since - we start counting the days of the week at day 1 (Monday), we subtract 1 from - \c weekDay to ensure that we obtain the cell for the correct column of the - table. - - Before text can be inserted into a cell, we must obtain a cursor with the - correct position in the document. The cell provides a function for this - purpose, and we use this cursor to insert text using the \c boldFormat - character format that we created earlier: - - \snippet richtext/calendar/mainwindow.cpp 12 - - Inserting text into document objects usually follows the same pattern. - Each object can provide a new cursor that corresponds to the first valid - position within itself, and this can be used to insert new content. We - continue to use this pattern as we insert the days of the month into the - table. - - Since every month has more than seven days, we insert a single row to begin - and add days until we reach the end of the month. If the current date is - encountered, it is inserted with a special format (created earlier) that - makes it stand out: - - \snippet richtext/calendar/mainwindow.cpp 13 - - We add a new row to the table at the end of each week only if the next week - falls within the currently selected month. - - For each calendar that we create, we change the window title to reflect the - currently selected month and year: - - \snippet richtext/calendar/mainwindow.cpp 14 - - The \c insertCalendar() function relies on up-to-date values for the month, - year, and font size. These are set in the following slots: - - \snippet richtext/calendar/mainwindow.cpp 15 - - The \c setFontSize() function simply changes the private \c fontSize variable - before updating the calendar. - - \snippet richtext/calendar/mainwindow.cpp 16 - - The \c setMonth slot is called when the QComboBox used to select the month is - updated. The value supplied is the currently selected row in the combobox. - We add 1 to this value to obtain a valid month number, and create a new QDate - based on the existing one. The calendar is then updated to use this new date. - - \snippet richtext/calendar/mainwindow.cpp 17 - - The \c setYear() slot is called when the QDateTimeEdit used to select the - year is updated. The value supplied is a QDate object; this makes - the construction of a new value for \c selectedDate simple. We update the - calendar afterwards to use this new date. -*/ diff --git a/examples/widgets/doc/calendarwidget.qdoc b/examples/widgets/doc/calendarwidget.qdoc deleted file mode 100644 index c6e86d1668..0000000000 --- a/examples/widgets/doc/calendarwidget.qdoc +++ /dev/null @@ -1,291 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \title Calendar Widget Example - \example widgets/calendarwidget - - The Calendar Widget example shows use of \c QCalendarWidget. - - \image calendarwidgetexample.png - - QCalendarWidget displays one calendar month - at a time and lets the user select a date. - The calendar consists of four components: a navigation - bar that lets the user change the month that is - displayed, a grid where each cell represents one day - in the month, and two headers that display weekday names - and week numbers. - - The Calendar Widget example displays a QCalendarWidget and lets the user - configure its appearance and behavior using - \l{QComboBox}es, \l{QCheckBox}es, and \l{QDateEdit}s. In - addition, the user can influence the formatting of individual dates - and headers. - - The properties of the QCalendarWidget are summarized in the table - below. - - \table - \header \li Property - \li Description - \row \li \l{QCalendarWidget::}{selectedDate} - \li The currently selected date. - \row \li \l{QCalendarWidget::}{minimumDate} - \li The earliest date that can be selected. - \row \li \l{QCalendarWidget::}{maximumDate} - \li The latest date that can be selected. - \row \li \l{QCalendarWidget::}{firstDayOfWeek} - \li The day that is displayed as the first day of the week - (usually Sunday or Monday). - \row \li \l{QCalendarWidget::}{gridVisible} - \li Whether the grid should be shown. - \row \li \l{QCalendarWidget::}{selectionMode} - \li Whether the user can select a date or not. - \row \li \l{QCalendarWidget::}{horizontalHeaderFormat} - \li The format of the day names in the horizontal header - (e.g., "M", "Mon", or "Monday"). - \row \li \l{QCalendarWidget::}{verticalHeaderFormat} - \li The format of the vertical header. - \row \li \l{QCalendarWidget::}{navigationBarVisible} - \li Whether the navigation bar at the top of the calendar - widget is shown. - \endtable - - The example consists of one class, \c Window, which creates and - lays out the QCalendarWidget and the other widgets that let the - user configure the QCalendarWidget. - - \section1 Window Class Definition - - Here is the definition of the \c Window class: - - \snippet widgets/calendarwidget/window.h 0 - \dots - \snippet widgets/calendarwidget/window.h 1 - - As is often the case with classes that represent self-contained - windows, most of the API is private. We will review the private - members as we stumble upon them in the implementation. - - \section1 Window Class Implementation - - Let's now review the class implementation, starting with the constructor: - - \snippet widgets/calendarwidget/window.cpp 0 - - We start by creating the four \l{QGroupBox}es and their child - widgets (including the QCalendarWidget) using four private \c - create...GroupBox() functions, described below. Then we arrange - the group boxes in a QGridLayout. - - We set the grid layout's resize policy to QLayout::SetFixedSize to - prevent the user from resizing the window. In that mode, the - window's size is set automatically by QGridLayout based on the - size hints of its contents widgets. - - To ensure that the window isn't automatically resized every time - we change a property of the QCalendarWidget (e.g., hiding the - navigation bar, trhe vertical header, or the grid), we set the - minimum height of row 0 and the minimum width of column 0 to the - initial size of the QCalendarWidget. - - Let's move on to the \c createPreviewGroupBox() function: - - \snippet widgets/calendarwidget/window.cpp 9 - - The \uicontrol Preview group box contains only one widget: the - QCalendarWidget. We set it up, connect its - \l{QCalendarWidget::}{currentPageChanged()} signal to our \c - reformatCalendarPage() slot to make sure that every new page gets - the formatting specified by the user. - - The \c createGeneralOptionsGroupBox() function is somewhat large - and several widgets are set up the same way; we look at parts of - its implementation here and skip the rest: - - \snippet widgets/calendarwidget/window.cpp 10 - \dots - - We start with the setup of the \uicontrol{Week starts on} combobox. - This combobox controls which day should be displayed as the first - day of the week. - - The QComboBox class lets us attach user data as a QVariant to - each item. The data can later be retrieved with QComboBox's - \l{QComboBox::}{itemData()} function. QVariant doesn't directly - support the Qt::DayOfWeek data type, but it supports \c int, and - C++ will happily convert any enum value to \c int. - - \dots - \snippet widgets/calendarwidget/window.cpp 11 - \dots - - After creating the widgets, we connect the signals and slots. We - connect the comboboxes to private slots of \c Window or to - public slots provided by QComboBox. - - \dots - \snippet widgets/calendarwidget/window.cpp 12 - - At the end of the function, we call the slots that update the calendar to ensure - that the QCalendarWidget is synchronized with the other widgets on startup. - - Let's now take a look at the \c createDatesGroupBox() private function: - - \snippet widgets/calendarwidget/window.cpp 13 - - In this function, we create the \uicontrol {Minimum Date}, \uicontrol {Maximum Date}, - and \uicontrol {Current Date} editor widgets, - which control the calendar's minimum, maximum, and selected dates. - The calendar's minimum and maximum dates have already been - set in \c createPrivewGroupBox(); we can then set the widgets - default values to the calendars values. - - \snippet widgets/calendarwidget/window.cpp 14 - \dots - \snippet widgets/calendarwidget/window.cpp 15 - - We connect the \c currentDateEdit's - \l{QDateEdit::}{dateChanged()} signal directly to the calendar's - \l{QCalendarWidget::}{setSelectedDate()} slot. When the calendar's - selected date changes, either as a result of a user action or - programmatically, our \c selectedDateChanged() slot updates - the \uicontrol {Current Date} editor. We also need to react when the user - changes the \uicontrol{Minimum Date} and \uicontrol{Maximum Date} editors. - - Here is the \c createTextFormatsGroup() function: - - \snippet widgets/calendarwidget/window.cpp 16 - - We set up the \uicontrol {Weekday Color} and \uicontrol {Weekend Color} comboboxes - using \c createColorCombo(), which instantiates a QComboBox and - populates it with colors ("Red", "Blue", etc.). - - \snippet widgets/calendarwidget/window.cpp 17 - - The \uicontrol {Header Text Format} combobox lets the user change the - text format (bold, italic, or plain) used for horizontal and - vertical headers. The \uicontrol {First Friday in blue} and \uicontrol {May 1 - in red} check box affect the rendering of specific dates. - - \snippet widgets/calendarwidget/window.cpp 18 - - We connect the check boxes and comboboxes to various private - slots. The \uicontrol {First Friday in blue} and \uicontrol {May 1 in red} - check boxes are both connected to \c reformatCalendarPage(), - which is also called when the calendar switches month. - - \dots - \snippet widgets/calendarwidget/window.cpp 19 - - At the end of \c createTextFormatsGroupBox(), we call private - slots to synchronize the QCalendarWidget with the other widgets. - - We're now done reviewing the four \c create...GroupBox() - functions. Let's now take a look at the other private functions - and slots. - - \snippet widgets/calendarwidget/window.cpp 20 - - In \c createColorCombo(), we create a combobox and populate it with - standard colors. The second argument to QComboBox::addItem() - is a QVariant storing user data (in this case, QColor objects). - - This function was used to set up the \uicontrol {Weekday Color} - and \uicontrol {Weekend Color} comboboxes. - - \snippet widgets/calendarwidget/window.cpp 1 - - When the user changes the \uicontrol {Week starts on} combobox's - value, \c firstDayChanged() is invoked with the index of the - combobox's new value. We retrieve the custom data item - associated with the new current item using - \l{QComboBox::}{itemData()} and cast it to a Qt::DayOfWeek. - - \c selectionModeChanged(), \c horizontalHeaderChanged(), and \c - verticalHeaderChanged() are very similar to \c firstDayChanged(), - so they are omitted. - - \snippet widgets/calendarwidget/window.cpp 2 - - The \c selectedDateChanged() updates the \uicontrol{Current Date} - editor to reflect the current state of the QCalendarWidget. - - \snippet widgets/calendarwidget/window.cpp 3 - - When the user changes the minimum date, we tell the - QCalenderWidget. We also update the \uicontrol {Maximum Date} editor, - because if the new minimum date is later than the current maximum - date, QCalendarWidget will automatically adapt its maximum date - to avoid a contradicting state. - - \snippet widgets/calendarwidget/window.cpp 4 - - \c maximumDateChanged() is implemented similarly to \c - minimumDateChanged(). - - \snippet widgets/calendarwidget/window.cpp 5 - - Each combobox item has a QColor object as user data corresponding to the - item's text. After fetching the colors from the comboboxes, we - set the text format of each day of the week. - - The text format of a column in the calendar is given as a - QTextCharFormat, which besides the foreground color lets us - specify various character formatting information. In this - example, we only show a subset of the possibilities. - - \snippet widgets/calendarwidget/window.cpp 6 - - \c weekendFormatChanged() is the same as \c - weekdayFormatChanged(), except that it affects Saturday and - Sunday instead of Monday to Friday. - - \snippet widgets/calendarwidget/window.cpp 7 - - The \c reformatHeaders() slot is called when the user - changes the text format of - the headers. We compare the current text of the \uicontrol {Header Text Format} - combobox to determine which format to apply. (An alternative would - have been to store \l{QTextCharFormat} values alongside the combobox - items.) - - \snippet widgets/calendarwidget/window.cpp 8 - - In \c reformatCalendarPage(), we set the text format of the first - Friday in the month and May 1 in the current year. The text - formats that are actually used depend on which check boxes are - checked and what the weekday/weekend formats are. - - QCalendarWidget lets us set the text format of individual dates - with the \l{QCalendarWidget::}{setDateTextFormat()}. We chose to - set the date formats when the calendar page changes - i.e. a new month is - displayed - and when the weekday/weekend format is changed. - We check which of the \c mayFirstCheckBox and \c firstDayCheckBox, if any, - are checked and set the text formats accordingly. -*/ diff --git a/examples/widgets/doc/charactermap.qdoc b/examples/widgets/doc/charactermap.qdoc deleted file mode 100644 index fee2a42156..0000000000 --- a/examples/widgets/doc/charactermap.qdoc +++ /dev/null @@ -1,274 +0,0 @@ -/**************************************************************************** -** -** 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/charactermap -\title Character Map Example - -The Character Map example shows how to create a custom widget that can -both display its own content and respond to user input. - -The example displays an array of characters which the user can click on -to enter text in a line edit. The contents of the line edit can then be -copied into the clipboard, and pasted into other applications. The -purpose behind this sort of tool is to allow users to enter characters -that may be unavailable or difficult to locate on their keyboards. - -\image charactermap-example.png Screenshot of the Character Map example - -The example consists of the following classes: - -\list -\li \c CharacterWidget displays the available characters in the current - font and style. -\li \c MainWindow provides a standard main window that contains font and - style information, a view onto the characters, a line edit, and a push - button for submitting text to the clipboard. -\endlist - -\section1 CharacterWidget Class Definition - -The \c CharacterWidget class is used to display an array of characters in -a user-specified font and style. For flexibility, we subclass QWidget and -reimplement only the functions that we need to provide basic rendering -and interaction features. - -The class definition looks like this: - -\snippet widgets/charactermap/characterwidget.h 0 - -The widget does not contain any other widgets, so it must provide its own -size hint to allow its contents to be displayed correctly. -We reimplement \l{QWidget::paintEvent()} to draw custom content. We also -reimplement \l{QWidget::mousePressEvent()} to allow the user to interact -with the widget. - -The updateFont() and updateStyle() slots are used to update the font and -style of the characters in the widget whenever the user changes the -settings in the application. -The class defines the characterSelected() signal so that other parts -of the application are informed whenever the user selects a character in -the widget. -As a courtesy, the widget provides a tooltip that shows the current -character value. We reimplement the \l{QWidget::mouseMoveEvent()} event -handler and define showToolTip() to enable this feature. - -The \c columns, \c displayFont and \c currentKey private data members -are used to record the number of columns to be shown, the current font, -and the currently highlighted character in the widget. - -\section1 CharacterWidget Class Implementation - -Since the widget is to be used as a simple canvas, the constructor just -calls the base class constructor and defines some default values for -private data members. - -\snippet widgets/charactermap/characterwidget.cpp 0 - -We initialize \c currentKey with a value of -1 to indicate -that no character is initially selected. We enable mouse tracking to -allow us to follow the movement of the cursor across the widget. - -The class provides two functions to allow the font and style to be set up. -Each of these modify the widget's display font and call update(): - -\snippet widgets/charactermap/characterwidget.cpp 1 -\codeline -\snippet widgets/charactermap/characterwidget.cpp 2 - -We use a fixed size font for the display. Similarly, a fixed size hint is -provided by the sizeHint() function: - -\snippet widgets/charactermap/characterwidget.cpp 3 - -Three standard event functions are implemented so that the widget -can respond to clicks, provide tooltips, and render the available -characters. The paintEvent() shows how the contents of the widget are -arranged and displayed: - -\snippet widgets/charactermap/characterwidget.cpp 6 - -A QPainter is created for the widget and, in all cases, we ensure that the -widget's background is painted. The painter's font is set to the -user-specified display font. - -The area of the widget that needs to be redrawn is used to determine which -characters need to be displayed: - -\snippet widgets/charactermap/characterwidget.cpp 7 - -Using integer division, we obtain the row and column numbers of each -characters that should be displayed, and we draw a square on the widget -for each character displayed. - -\snippet widgets/charactermap/characterwidget.cpp 8 -\snippet widgets/charactermap/characterwidget.cpp 9 - -The symbols for each character in the array are drawn within each square, -with the symbol for the most recently selected character displayed in red: - -\snippet widgets/charactermap/characterwidget.cpp 10 - -We do not need to take into account the difference between the area -displayed in the viewport and the area we are drawing on because -everything outside the visible area will be clipped. - -The mousePressEvent() defines how the widget responds to mouse clicks. - -\snippet widgets/charactermap/characterwidget.cpp 5 - -We are only interested when the user clicks with the left mouse button -over the widget. When this happens, we calculate which character was -selected and emit the characterSelected() signal. -The character's number is found by dividing the x and y-coordinates of -the click by the size of each character's grid square. Since the number -of columns in the widget is defined by the \c columns variable, we -simply multiply the row index by that value and add the column number -to obtain the character number. - -If any other mouse button is pressed, the event is passed on to the -QWidget base class. This ensures that the event can be handled properly -by any other interested widgets. - -The mouseMoveEvent() maps the mouse cursor's position in global -coordinates to widget coordinates, and determines the character that -was clicked by performing the calculation - -\snippet widgets/charactermap/characterwidget.cpp 4 - -The tooltip is given a position defined in global coordinates. - -\section1 MainWindow Class Definition - -The \c MainWindow class provides a minimal user interface for the example, -with only a constructor, slots that respond to signals emitted by standard -widgets, and some convenience functions that are used to set up the user -interface. - -The class definition looks like this: - -\snippet widgets/charactermap/mainwindow.h 0 - -The main window contains various widgets that are used to control how -the characters will be displayed, and defines the findFonts() function -for clarity and convenience. The findStyles() slot is used by the widgets -to determine the styles that are available, insertCharacter() inserts -a user-selected character into the window's line edit, and -updateClipboard() synchronizes the clipboard with the contents of the -line edit. - -\section1 MainWindow Class Implementation - -In the constructor, we set up the window's central widget and fill it with -some standard widgets (two comboboxes, a line edit, and a push button). -We also construct a CharacterWidget custom widget, and add a QScrollArea -so that we can view its contents: - -\snippet widgets/charactermap/mainwindow.cpp 0 - -QScrollArea provides a viewport onto the \c CharacterWidget when we set -its widget and handles much of the work needed to provide a scrolling -viewport. - -The font combo box is automatically popuplated with a list of available -fonts. We list the available styles for the current font in the style -combobox using the following function: - -\snippet widgets/charactermap/mainwindow.cpp 1 - -The line edit and push button are used to supply text to the clipboard: - -\snippet widgets/charactermap/mainwindow.cpp 2 - -We also obtain a clipboard object so that we can send text entered by the -user to other applications. - -Most of the signals emitted in the example come from standard widgets. -We connect these signals to slots in this class, and to the slots provided -by other widgets. - -\snippet widgets/charactermap/mainwindow.cpp 4 - -The font combobox's -\l{QFontComboBox::currentFontChanged()}{currentFontChanged()} signal is -connected to the findStyles() function so that the list of available styles -can be shown for each font that is used. Since both the font and the style -can be changed by the user, the font combobox's currentFontChanged() signal -and the style combobox's -\l{QComboBox::currentIndexChanged()}{currentIndexChanged()} are connected -directly to the character widget. - -The final two connections allow characters to be selected in the character -widget, and text to be inserted into the clipboard: - -\snippet widgets/charactermap/mainwindow.cpp 5 - -The character widget emits the characterSelected() custom signal when -the user clicks on a character, and this is handled by the insertCharacter() -function in this class. The clipboard is changed when the push button emits -the clicked() signal, and we handle this with the updateClipboard() function. - -The remaining code in the constructor sets up the layout of the central widget, -and provides a window title: - -\snippet widgets/charactermap/mainwindow.cpp 6 - -The font combobox is automatically populated with a list of available font -families. The styles that can be used with each font are found by the -findStyles() function. This function is called whenever the user selects a -different font in the font combobox. - -\snippet widgets/charactermap/mainwindow.cpp 7 - -We begin by recording the currently selected style, and we clear the -style combobox so that we can insert the styles associated with the -current font family. - -\snippet widgets/charactermap/mainwindow.cpp 8 - -We use the font database to collect the styles that are available for the -current font, and insert them into the style combobox. The current item is -reset if the original style is not available for this font. - -The last two functions are slots that respond to signals from the character -widget and the main window's push button. The insertCharacter() function is -used to insert characters from the character widget when the user clicks a -character: - -\snippet widgets/charactermap/mainwindow.cpp 9 - -The character is inserted into the line edit at the current cursor position. - -The main window's "To clipboard" push button is connected to the -updateClipboard() function so that, when it is clicked, the clipboard is -updated to contain the contents of the line edit: - -\snippet widgets/charactermap/mainwindow.cpp 10 - -We copy all the text from the line edit to the clipboard, but we do not clear -the line edit. -*/ diff --git a/examples/widgets/doc/chart.qdoc b/examples/widgets/doc/chart.qdoc deleted file mode 100644 index 44263d1027..0000000000 --- a/examples/widgets/doc/chart.qdoc +++ /dev/null @@ -1,82 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/chart - \title Chart Example - - The Chart example shows how to create a custom view for the model/view framework. - - \image chart-example.png - - In this example, the items in a table model are represented as slices in a pie chart, - relying on the flexibility of the model/view architecture to handle custom editing - and selection features. - - \b{Note that you only need to create a new view class if your data requires a - specialized representation.} You should first consider using a standard QListView, - QTableView, or QTreeView with a custom QItemDelegate subclass if you need to - represent data in a special way. - - \omit - \section1 PieView Class Definition - - The \c PieView class is a subclass of QAbstractItemView. The base class provides - much of the functionality required by view classes, so we only need to provide - implementations for three public functions: visualRect(), scrollTo(), and - indexAt(). However, the view needs to maintain strict control over its look and - feel, so we also provide implementations for a number of other functions: - - \snippet itemviews/chart/pieview.h 0 - - - - \section1 PieView Class Implementation - - The paint event renders the data from the standard item model as a pie chart. - We interpret the data in the following way: - - \list - \li Column 0 contains data in two different roles: - The \l{Qt::ItemDataRole}{DisplayRole} contains a label, and the - \l{Qt::ItemDataRole}{DecorationRole} contains the color of the pie slice. - \li Column 1 contains a quantity which we will convert to the angular extent of - the slice. - \endlist - - The figure is always drawn with the chart on the left and the key on - the right. This means that we must try and obtain an area that is wider - than it is tall. We do this by imposing a particular aspect ratio on - the chart and applying it to the available vertical space. This ensures - that we always obtain the maximum horizontal space for the aspect ratio - used. - We also apply fixed size margin around the figure. - - We use logical coordinates to draw the chart and key, and position them - on the view using viewports. - \endomit -*/ diff --git a/examples/widgets/doc/chip.qdoc b/examples/widgets/doc/chip.qdoc deleted file mode 100644 index 966c16900a..0000000000 --- a/examples/widgets/doc/chip.qdoc +++ /dev/null @@ -1,38 +0,0 @@ -/**************************************************************************** -** -** 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 graphicsview/chip - \title 40000 Chips - - This demo shows how to visualize a huge scene with 40000 chip items - using Graphics View. It also shows Graphics View's powerful navigation - and interaction features, allowing you to zoom and rotate each of four - views independently, and you can select and move items around the scene. - - \image chip-demo.png -*/ diff --git a/examples/widgets/doc/classwizard.qdoc b/examples/widgets/doc/classwizard.qdoc deleted file mode 100644 index 0c357b7286..0000000000 --- a/examples/widgets/doc/classwizard.qdoc +++ /dev/null @@ -1,190 +0,0 @@ -/**************************************************************************** -** -** 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 dialogs/classwizard - \title Class Wizard Example - - The License Wizard example shows how to implement linear - wizards using QWizard. - - \image classwizard.png Screenshot of the Class Wizard example - - Most wizards have a linear structure, with page 1 followed by - page 2 and so on until the last page. Some wizards are more - complex in that they allow different traversal paths based on the - information provided by the user. The - \l{dialogs/licensewizard}{License Wizard} example shows how to - create such wizards. - - The Class Wizard example consists of the following classes: - - \list - \li \c ClassWizard inherits QWizard and provides a - three-step wizard that generates the skeleton of a C++ class - based on the user's input. - \li \c IntroPage, \c ClassInfoPage, \c CodeStylePage, \c - OutputFilesPage, and \c ConclusionPage are QWizardPage - subclasses that implement the wizard pages. - \endlist - - \section1 ClassWizard Class Definition - - \image classwizard-flow.png The Class Wizard pages - - We will see how to subclass QWizard to implement our own wizard. - The concrete wizard class is called \c ClassWizard and provides - five pages: - - \list - \li The first page is an introduction page, telling the user what - the wizard is going to do. - \li The second page asks for a class name and a base class, and - allows the user to specify whether the class should have a \c - Q_OBJECT macro and what constructors it should provide. - \li The third page allows the user to set some options related to the code - style, such as the macro used to protect the header file from - multiple inclusion (e.g., \c MYDIALOG_H). - \li The fourth page allows the user to specify the names of the - output files. - \li The fifth page is a conclusion page. - \endlist - - Although the program is just an example, if you press \uicontrol Finish - (\uicontrol Done on Mac OS X), actual C++ source files will actually be - generated. - - \section1 The ClassWizard Class - - Here's the \c ClassWizard definition: - - \snippet dialogs/classwizard/classwizard.h 0 - - The class reimplements QDialog's \l{QDialog::}{accept()} slot. - This slot is called when the user clicks \uicontrol{Finish}. - - Here's the constructor: - - \snippet dialogs/classwizard/classwizard.cpp 1 - - We instantiate the five pages and insert them into the wizard - using QWizard::addPage(). The order in which they are inserted - is also the order in which they will be shown later on. - - We call QWizard::setPixmap() to set the banner and the - background pixmaps for all pages. The banner is used as a - background for the page header when the wizard's style is - \l{QWizard::}{ModernStyle}; the background is used as the - dialog's background in \l{QWizard::}{MacStyle}. (See \l{Elements - of a Wizard Page} for more information.) - - \snippet dialogs/classwizard/classwizard.cpp 3 - \snippet dialogs/classwizard/classwizard.cpp 4 - \dots - \snippet dialogs/classwizard/classwizard.cpp 5 - \snippet dialogs/classwizard/classwizard.cpp 6 - - If the user clicks \uicontrol Finish, we extract the information from - the various pages using QWizard::field() and generate the files. - The code is long and tedious (and has barely anything to do with - noble art of designing wizards), so most of it is skipped here. - See the actual example in the Qt distribution for the details if - you're curious. - - \section1 The IntroPage Class - - The pages are defined in \c classwizard.h and implemented in \c - classwizard.cpp, together with \c ClassWizard. We will start with - the easiest page: - - \snippet dialogs/classwizard/classwizard.h 1 - \codeline - \snippet dialogs/classwizard/classwizard.cpp 7 - - A page inherits from QWizardPage. We set a - \l{QWizardPage::}{title} and a - \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting - any \l{QWizardPage::}{subTitle}, we ensure that no header is - displayed for this page. (On Windows, it is customary for wizards - to display a watermark pixmap on the first and last pages, and to - have a header on the other pages.) - - Then we create a QLabel and add it to a layout. - - \section1 The ClassInfoPage Class - - The second page is defined and implemented as follows: - - \snippet dialogs/classwizard/classwizard.h 2 - \codeline - \snippet dialogs/classwizard/classwizard.cpp 9 - \dots - \snippet dialogs/classwizard/classwizard.cpp 12 - \dots - \snippet dialogs/classwizard/classwizard.cpp 13 - - First, we set the page's \l{QWizardPage::}{title}, - \l{QWizardPage::}{subTitle}, and \l{QWizard::LogoPixmap}{logo - pixmap}. The logo pixmap is displayed in the page's header in - \l{QWizard::}{ClassicStyle} and \l{QWizard::}{ModernStyle}. - - Then we create the child widgets, create \l{Registering and Using - Fields}{wizard fields} associated with them, and put them into - layouts. The \c className field is created with an asterisk (\c - *) next to its name. This makes it a \l{mandatory field}, that - is, a field that must be filled before the user can press the - \uicontrol Next button (\uicontrol Continue on Mac OS X). The fields' values - can be accessed from any other page using QWizardPage::field(), - or from the wizard code using QWizard::field(). - - \section1 The CodeStylePage Class - - The third page is defined and implemented as follows: - - \snippet dialogs/classwizard/classwizard.h 3 - \codeline - \snippet dialogs/classwizard/classwizard.cpp 14 - \dots - \snippet dialogs/classwizard/classwizard.cpp 15 - \codeline - \snippet dialogs/classwizard/classwizard.cpp 16 - - The code in the constructor is very similar to what we did for \c - ClassInfoPage, so we skipped most of it. - - The \c initializePage() function is what makes this class - interesting. It is reimplemented from QWizardPage and is used to - initialize some of the page's fields with values from the - previous page (namely, \c className and \c baseClass). For - example, if the class name on page 2 is \c SuperDuperWidget, the - default macro name on page 3 is \c SUPERDUPERWIDGET_H. - - The \c OutputFilesPage and \c ConclusionPage classes are very - similar to \c CodeStylePage, so we won't review them here. - - \sa QWizard, {License Wizard Example}, {Trivial Wizard Example} -*/ diff --git a/examples/widgets/doc/codeeditor.qdoc b/examples/widgets/doc/codeeditor.qdoc deleted file mode 100644 index 695ac5c4ce..0000000000 --- a/examples/widgets/doc/codeeditor.qdoc +++ /dev/null @@ -1,197 +0,0 @@ -/**************************************************************************** -** -** 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/codeeditor - \title Code Editor Example - - The Code Editor example shows how to create a simple editor that - has line numbers and that highlights the current line. - - \image codeeditor-example.png - - As can be seen from the image, the editor displays the line - numbers in an area to the left of the area for editing. The editor - will highlight the line containing the cursor. - - We implement the editor in \c CodeEditor, which is a widget that - inherits QPlainTextEdit. We keep a separate widget in \c - CodeEditor (\c LineNumberArea) onto which we draw the line - numbers. - - QPlainTextEdit inherits from QAbstractScrollArea, and editing - takes place within its \l{QAbstractScrollArea::}{viewport()}'s - margins. We make room for our line number area by setting the left - margin of the viewport to the size we need to draw the line - numbers. - - When it comes to editing code, we prefer QPlainTextEdit over - QTextEdit because it is optimized for handling plain text. See - the QPlainTextEdit class description for details. - - QPlainTextEdit lets us add selections in addition to the - selection the user can make with the mouse or keyboard. We use - this functionality to highlight the current line. More on this - later. - - We will now move on to the definitions and implementations of \c - CodeEditor and \c LineNumberArea. Let's start with the \c - LineNumberArea class. - - \section1 The LineNumberArea Class - - We paint the line numbers on this widget, and place it over the \c - CodeEditor's \l{QAbstractScrollArea::}{viewport()}'s left margin - area. - - We need to use protected functions in QPlainTextEdit while - painting the area. So to keep things simple, we paint the area in - the \c CodeEditor class. The area also asks the editor to - calculate its size hint. - - Note that we could simply paint the line numbers directly on the - code editor, and drop the LineNumberArea class. However, the - QWidget class helps us to \l{QWidget::}{scroll()} its contents. - Also, having a separate widget is the right choice if we wish to - extend the editor with breakpoints or other code editor features. - The widget would then help in the handling of mouse events. - - \snippet widgets/codeeditor/codeeditor.h extraarea - - \section1 CodeEditor Class Definition - - Here is the code editor's class definition: - - \snippet widgets/codeeditor/codeeditor.h codeeditordefinition - - In the editor we resize and draw the line numbers on the \c - LineNumberArea. We need to do this when the number of lines in the - editor changes, and when the editor's viewport() is scrolled. Of - course, it is also done when the editor's size changes. We do - this in \c updateLineNumberWidth() and \c updateLineNumberArea(). - - Whenever, the cursor's position changes, we highlight the current - line in \c highlightCurrentLine(). - - \section1 CodeEditor Class Implementation - - We will now go through the code editors implementation, starting - off with the constructor. - - \snippet widgets/codeeditor/codeeditor.cpp constructor - - In the constructor we connect our slots to signals in - QPlainTextEdit. It is necessary to calculate the line number area - width and highlight the first line when the editor is created. - - \snippet widgets/codeeditor/codeeditor.cpp extraAreaWidth - - The \c lineNumberAreaWidth() function calculates the width of the - \c LineNumberArea widget. We take the number of digits in the last - line of the editor and multiply that with the maximum width of a - digit. - - \snippet widgets/codeeditor/codeeditor.cpp slotUpdateExtraAreaWidth - - When we update the width of the line number area, we simply call - QAbstractScrollArea::setViewportMargins(). - - \snippet widgets/codeeditor/codeeditor.cpp slotUpdateRequest - - This slot is invoked when the editors viewport has been scrolled. - The QRect given as argument is the part of the editing area that - is do be updated (redrawn). \c dy holds the number of pixels the - view has been scrolled vertically. - - \snippet widgets/codeeditor/codeeditor.cpp resizeEvent - - When the size of the editor changes, we also need to resize the - line number area. - - \snippet widgets/codeeditor/codeeditor.cpp cursorPositionChanged - - When the cursor position changes, we highlight the current line, - i.e., the line containing the cursor. - - QPlainTextEdit gives the possibility to have more than one - selection at the same time. we can set the character format - (QTextCharFormat) of these selections. We clear the cursors - selection before setting the new new - QPlainTextEdit::ExtraSelection, else several lines would get - highlighted when the user selects multiple lines with the mouse. - \omit ask someone how this works \endomit - - One sets the selection with a text cursor. When using the - FullWidthSelection property, the current cursor text block (line) - will be selected. If you want to select just a portion of the text - block, the cursor should be moved with QTextCursor::movePosition() - from a position set with \l{QTextCursor::}{setPosition()}. - - \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_0 - - The \c lineNumberAreaPaintEvent() is called from \c LineNumberArea - whenever it receives a paint event. We start off by painting the - widget's background. - - \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_1 - - We will now loop through all visible lines and paint the line - numbers in the extra area for each line. Notice that in a plain - text edit each line will consist of one QTextBlock; though, if - line wrapping is enabled, a line may span several rows in the text - edit's viewport. - - We get the top and bottom y-coordinate of the first text block, - and adjust these values by the height of the current text block in - each iteration in the loop. - - \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_2 - - Notice that we check if the block is visible in addition to check - if it is in the areas viewport - a block can, for example, be - hidden by a window placed over the text edit. - - \section1 Suggestions for Extending the Code Editor - - No self-respecting code editor is without a syntax - highligther; the \l{Syntax Highlighter Example} shows how to - create one. - - In addition to line numbers, you can add more to the extra area, - for instance, break points. - - QSyntaxHighlighter gives the possibility to add user data to each - text block with - \l{QSyntaxHighlighter::}{setCurrentBlockUserData()}. This can be - used to implement parenthesis matching. In the \c - highlightCurrentLine(), the data of the currentBlock() can be - fetched with QTextBlock::userData(). Matching parentheses can be - highlighted with an extra selection. The "Matching Parentheses - with QSyntaxHighlighter" article in Qt Quarterly 31 implements - this. You find it here: \l{http://doc.qt.nokia.com/qq/}. - -*/ diff --git a/examples/widgets/doc/coloreditorfactory.qdoc b/examples/widgets/doc/coloreditorfactory.qdoc deleted file mode 100644 index a2c02f8c1d..0000000000 --- a/examples/widgets/doc/coloreditorfactory.qdoc +++ /dev/null @@ -1,155 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/coloreditorfactory - \title Color Editor Factory Example - - This example shows how to create an editor that can be used by - a QItemDelegate. - - \image coloreditorfactoryimage.png - - When editing data in a QListView, QTableView, or QTreeView, - editors are created and displayed by a \l{Delegate - Classes}{delegate}. QItemDelegate, which is the default delegate - used by Qt's \l{View Classes}{item views}, uses a - QItemEditorFactory to create editors for it. A unique instance - provided by QItemEditorFactory is by default installed on all - item delegates. - - An item editor factory contains a collection of - QItemEditorCreatorBase instances, which are specialized factories - that produce editors for one particular QVariant data type (all - models in Qt store their data in \l{QVariant}s). An editor can be any - Qt or custom widget. - - In this example, we will create an editor (implemented in the \c - ColorListEditor class) that can edit the QColor data type and be - used by \l{QItemDelegate}s. We do this by creating a new - QItemEditorCreatorBase that produces \c ColorListEditors and - register it with a new factory, which we set as the default editor - item factory (the unique factory instance). To test our editor, we - have implemented the \c Window class, which displays a - QTableWidget in which \l{QColor}s can be edited. - - \section1 Window Class Implementation - - In the Window class, we create the item editor creator - base for our color editor and add it to the default factory. - We also create a QTableWidget in which our editor can be - tested. It is filled with some data and displayed in a window. - - We take a closer look at the constructor: - - \snippet itemviews/coloreditorfactory/window.cpp 0 - - The QStandardItemEditorCreator is a convenience class that - inherits QItemEditorCreatorBase. Its constructor takes a template - class, of which instances are returned from - \l{QItemEditorCreatorBase::}{createWidget()}. The creator uses a - constructor that takes a QWidget as its only parameter; the - template class must provide this. This way, there is no need to - subclass QStandardItemEditorCreator. - - After the new factory has been set, all standard item delegates - will use it (i.e, also delegates that were created before the new - default factory was set). - - The \c createGUI() function sets up the table and fills it - with data. - - \section1 ColorListEditor Definition - - The ColorListEditor inherits QComboBox and lets the user - select a QColor from its popup list. - - \snippet itemviews/coloreditorfactory/colorlisteditor.h 0 - - QItemDelegate manages the interaction between the editor and - the model, i.e., it retrieves data to edit from the model and - store data from the editor in the model. The data that is edited - by an editor is stored in the editor's user data property, and the - delegate uses Qt's \l{Qt's Property System}{property system} to - access it by name. We declare our user data property with the - Q_PROPERTY macro. The property is set to be the user type with the - USER keyword. - - \section1 ColorListEditor Implementation - - The constructor of \c ColorListEditor simply calls \c - populateList(), which we will look at later. We move on to the - \c color() function: - - \snippet itemviews/coloreditorfactory/colorlisteditor.cpp 0 - - We return the data that is selected in the combobox. The data - is stored in the Qt::DecorationRole as the color is then also - displayed in the popup list (as shown in the image above). - - \snippet itemviews/coloreditorfactory/colorlisteditor.cpp 1 - - The \c findData() function searches the items in the combobox - and returns the index of the item that has \c color in the - Qt::Decoration role. - - \snippet itemviews/coloreditorfactory/colorlisteditor.cpp 2 - - Qt knows some predefined colors by name. We simply loop - through these to fill our editor with items. - - \section1 Further Customization of Item View Editors - - You can customize Qt's \l{Model/View Programming}{model view - framework} in many ways. The procedure shown in this example is - usually sufficient to provide custom editors. Further - customization is achieved by subclassing QItemEditorFactory - and QItemEditorCreatorBase. It is also possible to subclass - QItemDelegate if you don't wish to use a factory at all. - - Possible suggestions are: - - \list - \li If the editor widget has no user property defined, the delegate - asks the factory for the property name, which it in turn - asks the item editor creator for. In this case, you can use - the QItemEditorCreator class, which takes the property - name to use for editing as a constructor argument. - \li If the editor requires other constructors or other - initialization than provided by QItemEditorCreatorBase, you - must reimplement - QItemEditorCreatorBase::createWidget(). - \li You could also subclass QItemEditorFactory if you only want - to provide editors for certain kinds of data or use another - method of creating the editors than using creator bases. - \endlist - - In this example, we use a standard QVariant data type. You can - also use custom types. In the \l{Star Delegate Example}, we - show how to store a custom data type in a QVariant and paint - and edit it in a class that inherits QItemDelegate. -*/ diff --git a/examples/widgets/doc/combowidgetmapper.qdoc b/examples/widgets/doc/combowidgetmapper.qdoc deleted file mode 100644 index 949014930d..0000000000 --- a/examples/widgets/doc/combowidgetmapper.qdoc +++ /dev/null @@ -1,167 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/combowidgetmapper - \title Combo Widget Mapper Example - - The Combo Widget Mapper example shows how to use a custom delegate to - map information from a model to specific widgets on a form. - - \image combowidgetmapper-example.png - - In the \l{Simple Widget Mapper Example}, we showed the basic use of a - widget mapper to relate data exposed by a model to simple input widgets - in a user interface. However, sometimes we want to use input widgets that - expose data as choices to the user, such as QComboBox, and we need a way - to relate their input to the values stored in the model. - - This example is very similar to the \l{Simple Widget Mapper Example}. - Again, we create a \c Window class with an almost identical user interface, - except that, instead of providing a spin box so that each person's age - can be entered, we provide a combo box to allow their addresses to be - classified as "Home", "Work" or "Other". - - \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 itemviews/combowidgetmapper/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 constructor of the \c Window class can be explained in three parts. - In the first part, we set up the widgets used for the user interface: - - \snippet itemviews/combowidgetmapper/window.cpp Set up widgets - - Note that we set up the mapping the combo box in the same way as for other - widgets, but that we apply its own model to it so that it will display - data from its own model, the \c typeModel, rather than from the model - containing data about each person. - - Next, we set up the widget mapper, relating each input widget to a column - in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}: - - \snippet itemviews/combowidgetmapper/window.cpp Set up the mapper - - For the combo box, we pass an extra argument to tell the widget mapper - which property to relate to values from the model. As a result, the user - is able to select an item from the combo box, and the corresponding - value stored in the widget's \c currentIndex property will be stored in - the model. - - \omit - However, we also set a delegate on the mapper. As with \l{Delegate Classes}, - this changes the way that data is presented to the user. In this case, the - delegate acts as a proxy between the mapper and the input widgets, - translating the data into a suitable form for the combo box but not - interfering with the other input widgets. The implementation is shown later. - \endomit - - The rest of the constructor is very similar to that of the - \l{Simple Widget Mapper Example}: - - \snippet itemviews/combowidgetmapper/window.cpp Set up connections and layouts - - The model is initialized in the window's \c{setupModel()} function. Here, - we create a standard model with 5 rows and 3 columns. In each row, we - insert a name, address, and a value that indicates the type of address. - The address types are stored in a string list model. - - \snippet itemviews/combowidgetmapper/window.cpp Set up the model - - As we insert each row into the model, like a record in a database, we - store values that correspond to items in \c typeModel for each person's - address type. When the widget mapper reads these values from the final - column of each row, it will need to use them as references to values in - \c typeModel, as shown in the following diagram. This is where the - delegate is used. - - \image widgetmapper-combo-mapping.png - - We show the implementation of the \c{updateButtons()} slot for - completeness: - - \snippet itemviews/combowidgetmapper/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 itemviews/combowidgetmapper/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 itemviews/combowidgetmapper/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 itemviews/combowidgetmapper/delegate.cpp setModelData implementation - \endomit - - \section1 Summary and Further Reading - - The use of a separate model for the combo box provides a menu of choices - that are separate from the data stored in the main model. Using a named - mapping that relates the combo box's \c currentIndex property to a column - in the model effectively allows us to store a look-up value in the model. - - However, when reading the model outside the context of the widget mapper, - we need to know about the \c typeModel to make sense of these look-up - values. It would be useful to be able to store both the data and the - choices held by the \c typeModel in one place. - This is covered by the \l{SQL Widget Mapper Example}. -*/ diff --git a/examples/widgets/doc/composition.qdoc b/examples/widgets/doc/composition.qdoc deleted file mode 100644 index 6aca01d255..0000000000 --- a/examples/widgets/doc/composition.qdoc +++ /dev/null @@ -1,44 +0,0 @@ -/**************************************************************************** -** -** 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 painting/composition - \title Composition Modes - - This demo shows some of the more advanced composition modes supported by Qt. - - \image composition-demo.png - - The two most common forms of composition are \b{Source} and \b{SourceOver}. - \b{Source} is used to draw opaque objects onto a paint device. In this mode, - each pixel in the source replaces the corresponding pixel in the destination. - In \b{SourceOver} composition mode, the source object is transparent and is - drawn on top of the destination. - - In addition to these standard modes, Qt defines the complete set of composition modes - as defined by X. Porter and Y. Duff. See the QPainter documentation for details. -*/ diff --git a/examples/widgets/doc/concentriccircles.qdoc b/examples/widgets/doc/concentriccircles.qdoc deleted file mode 100644 index 67bc125dbe..0000000000 --- a/examples/widgets/doc/concentriccircles.qdoc +++ /dev/null @@ -1,231 +0,0 @@ -/**************************************************************************** -** -** 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 painting/concentriccircles - \title Concentric Circles Example - - The Concentric Circles example shows the improved rendering - quality that can be obtained using floating point precision and - anti-aliasing when drawing custom widgets. The example also shows - how to do simple animations. - - The application's main window displays several widgets which are - drawn using the various combinations of precision and - anti-aliasing. - - \image concentriccircles-example.png - - Anti-aliasing is one of QPainter's render hints. The - QPainter::RenderHints are used to specify flags to QPainter that - may, or may not, be respected by any given - engine. QPainter::Antialiasing indicates that the engine should - anti-alias the edges of primitives if possible, i.e. put - additional pixels around the original ones to smooth the edges. - - The difference between floating point precision and integer - precision is a matter of accuracy, and is visible in the - application's main window: Even though the logic that is - calculating the circles' geometry is the same, floating points - ensure that the white spaces between each circle are of the same - size, while integers make two and two circles appear as if they - belong together. The reason is that the integer based precision - rely on rounding off non-integer calculations. - - The example consists of two classes: - - \list - \li \c CircleWidget is a custom widget which renders several animated - concentric circles. - \li \c Window is the application's main window displaying four \c - {CircleWidget}s drawn using different combinations of precision - and aliasing. - \endlist - - First we will review the CircleWidget class, then we will take a - look at the Window class. - - \section1 CircleWidget Class Definition - - The CircleWidget class inherits QWidget, and is a custom widget - which renders several animated concentric circles. - - \snippet painting/concentriccircles/circlewidget.h 0 - - We declare the \c floatBased and \c antialiased variables to hold - whether an instance of the class should be rendered with integer - or float based precision, and whether the rendering should be - anti-aliased or not. We also declare functions setting each of - these variables. - - In addition we reimplement the QWidget::paintEvent() function to - apply the various combinations of precision and anti-aliasing when - rendering, and to support the animation. We reimplement the - QWidget::minimumSizeHint() and QWidget::sizeHint() functions to - give the widget a reasonable size within our application. - - We declare the private \c nextAnimationFrame() slot, and the - associated \c frameNo variable holding the number of "animation - frames" for the widget, to facilitate the animation. - - \section1 CircleWidget Class Implementation - - In the constructor we make the widget's rendering integer based - and aliased by default: - - \snippet painting/concentriccircles/circlewidget.cpp 0 - - We initialize the widget's \c frameNo variable, and set the - widget's background color using the QWidget::setBackgroundColor() - function which takes a \l {QPalette::ColorRole}{color role} as - argument; the QPalette::Base color role is typically white. - - Then we set the widgets size policy using the - QWidget::setSizePolicy() function. QSizePolicy::Expanding means - that the widget's \l {QWidget::sizeHint()}{sizeHint()} is a - sensible size, but that the widget can be shrunk and still be - useful. The widget can also make use of extra space, so it should - get as much space as possible. - - \snippet painting/concentriccircles/circlewidget.cpp 1 - \codeline - \snippet painting/concentriccircles/circlewidget.cpp 2 - - The public \c setFloatBased() and \c setAntialiased() functions - update the widget's rendering preferences, i.e. whether the widget - should be rendered with integer or float based precision, and - whether the rendering should be anti-aliased or not. - - The functions also generate a paint event by calling the - QWidget::update() function, forcing a repaint of the widget with - the new rendering preferences. - - \snippet painting/concentriccircles/circlewidget.cpp 3 - \codeline - \snippet painting/concentriccircles/circlewidget.cpp 4 - - The default implementations of the QWidget::minimumSizeHint() and - QWidget::sizeHint() functions return invalid sizes if there is no - layout for the widget, otherwise they return the layout's minimum and - preferred size, respectively. - - We reimplement the functions to give the widget minimum and - preferred sizes which are reasonable within our application. - - \snippet painting/concentriccircles/circlewidget.cpp 5 - - The nextAnimationFrame() slot simply increments the \c frameNo - variable's value, and calls the QWidget::update() function which - schedules a paint event for processing when Qt returns to the main - event loop. - - \snippet painting/concentriccircles/circlewidget.cpp 6 - - A paint event is a request to repaint all or part of the - widget. The \c paintEvent() function is an event handler that can - be reimplemented to receive the widget's paint events. We - reimplement the event handler to apply the various combinations of - precision and anti-aliasing when rendering the widget, and to - support the animation. - - First, we create a QPainter for the widget, and set its - antialiased flag to the widget's preferred aliasing. We also - translate the painters coordinate system, preparing to draw the - widget's cocentric circles. The translation ensures that the - center of the circles will be equivalent to the widget's center. - - \snippet painting/concentriccircles/circlewidget.cpp 7 - - When painting a circle, we use the number of "animation frames" to - determine the alpha channel of the circle's color. The alpha - channel specifies the color's transparency effect, 0 represents a - fully transparent color, while 255 represents a fully opaque - color. - - \snippet painting/concentriccircles/circlewidget.cpp 8 - - If the calculated alpha channel is fully transparent, we don't - draw anything since that would be equivalent to drawing a white - circle on a white background. Instead we skip to the next circle - still creating a white space. If the calculated alpha channel is - fully opaque, we set the pen (the QColor passed to the QPen - constructor is converted into the required QBrush by default) and - draw the circle. If the widget's preferred precision is float - based, we specify the circle's bounding rectangle using QRectF and - double values, otherwise we use QRect and integers. - - The animation is controlled by the public \c nextAnimationFrame() - slot: Whenever the \c nextAnimationFrame() slot is called the - number of frames is incremented and a paint event is - scheduled. Then, when the widget is repainted, the alpha-blending - of the circles' colors change and the circles appear as animated. - - \section1 Window Class Definition - - The Window class inherits QWidget, and is the application's main - window rendering four \c {CircleWidget}s using different - combinations of precision and aliasing. - - \snippet painting/concentriccircles/window.h 0 - - We declare the various components of the main window, i.e., the text - labels and a double array that will hold reference to the four \c - {CircleWidget}s. In addition we declare the private \c - createLabel() function to simplify the constructor. - - \section1 Window Class Implementation - - \snippet painting/concentriccircles/window.cpp 0 - - In the constructor, we first create the various labels and put - them in a QGridLayout. - - \snippet painting/concentriccircles/window.cpp 1 - - Then we create a QTimer. The QTimer class is a high-level - programming interface for timers, and provides repetitive and - single-shot timers. - - We create a timer to facilitate the animation of our concentric - circles; when we create the four CircleWidget instances (and add - them to the layout), we connect the QTimer::timeout() signal to - each of the widgets' \c nextAnimationFrame() slots. - - \snippet painting/concentriccircles/window.cpp 2 - - Before we set the layout and window title for our main window, we - make the timer start with a timeout interval of 100 milliseconds, - using the QTimer::start() function. That means that the - QTimer::timeout() signal will be emitted, forcing a repaint of the - four \c {CircleWidget}s, every 100 millisecond which is the reason - the circles appear as animated. - - \snippet painting/concentriccircles/window.cpp 3 - - The private \c createLabel() function is implemented to simlify - the constructor. -*/ diff --git a/examples/widgets/doc/configdialog.qdoc b/examples/widgets/doc/configdialog.qdoc deleted file mode 100644 index 9acea72a3b..0000000000 --- a/examples/widgets/doc/configdialog.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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 dialogs/configdialog - \title Config Dialog Example - - The Config Dialog examples shows how a configuration dialog can be created by - using an icon view with a stacked widget. - - \image configdialog-example.png -*/ diff --git a/examples/widgets/doc/customsortfiltermodel.qdoc b/examples/widgets/doc/customsortfiltermodel.qdoc deleted file mode 100644 index 4dce820f9c..0000000000 --- a/examples/widgets/doc/customsortfiltermodel.qdoc +++ /dev/null @@ -1,289 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/customsortfiltermodel - \title Custom Sort/Filter Model Example - - The Custom Sort/Filter Model example illustrates how to subclass - QSortFilterProxyModel to perform advanced sorting and filtering. - - \image customsortfiltermodel-example.png Screenshot of the Custom Sort/Filter Model Example - - The QSortFilterProxyModel class provides support for sorting and - filtering data passed between another model and a view. - - The model transforms the structure of a source model by mapping - the model indexes it supplies to new indexes, corresponding to - different locations, for views to use. This approach allows a - given source model to be restructured as far as views are - concerned, without requiring any transformations on the underlying - data and without duplicating the data in memory. - - The Custom Sort/Filter Model example consists of two classes: - - \list - - \li The \c MySortFilterProxyModel class provides a custom proxy - model. - - \li The \c Window class provides the main application window, - using the custom proxy model to sort and filter a standard - item model. - - \endlist - - We will first take a look at the \c MySortFilterProxyModel class - to see how the custom proxy model is implemented, then we will - take a look at the \c Window class to see how the model is - used. Finally we will take a quick look at the \c main() function. - - \section1 MySortFilterProxyModel Class Definition - - The \c MySortFilterProxyModel class inherits the - QSortFilterProxyModel class. - - Since QAbstractProxyModel and its subclasses are derived from - QAbstractItemModel, much of the same advice about subclassing - normal models also applies to proxy models. - - On the other hand, it is worth noting that many of - QSortFilterProxyModel's default implementations of functions are - written so that they call the equivalent functions in the relevant - source model. This simple proxying mechanism may need to be - overridden for source models with more complex behavior; in this - example we derive from the QSortFilterProxyModel class to ensure - that our filter can recognize a valid range of dates, and to - control the sorting behavior. - - \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.h 0 - - We want to be able to filter our data by specifying a given period - of time. For that reason, we implement the custom \c - setFilterMinimumDate() and \c setFilterMaximumDate() functions as - well as the corresponding \c filterMinimumDate() and \c - filterMaximumDate() functions. We reimplement - QSortFilterProxyModel's \l - {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} - function to only accept rows with valid dates, and - QSortFilterProxyModel::lessThan() to be able to sort the senders - by their email addresses. Finally, we implement a \c dateInRange() - convenience function that we will use to determine if a date is - valid. - - \section1 MySortFilterProxyModel Class Implementation - - The \c MySortFilterProxyModel constructor is trivial, passing the - parent parameter on to the base class constructor: - - \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 0 - - The most interesting parts of the \c MySortFilterProxyModel - implementation are the reimplementations of - QSortFilterProxyModel's \l - {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} - and \l {QSortFilterProxyModel::lessThan()}{lessThan()} - functions. Let's first take a look at our customized \c lessThan() - function. - - \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 4 - - We want to sort the senders by their email addresses. The \l - {QSortFilterProxyModel::}{lessThan()} function is used as the < - operator when sorting. The default implementation handles a - collection of types including QDateTime and String, but in order - to be able to sort the senders by their email addresses we must - first identify the address within the given string: - - \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 6 - - We use QRegExp to define a pattern for the addresses we are looking - for. The QRegExp::indexIn() function attempts to find a match in - the given string and returns the position of the first match, or - -1 if there was no match. If the given string contains the - pattern, we use QRegExp's \l {QRegExp::cap()}{cap()} function to - retrieve the actual address. The \l {QRegExp::cap()}{cap()} - function returns the text captured by the \e nth - subexpression. The entire match has index 0 and the parenthesized - subexpressions have indexes starting from 1 (excluding - non-capturing parentheses). - - \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 3 - - The \l - {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} - function, on the other hand, is expected to return true if the - given row should be included in the model. In our example, a row - is accepted if either the subject or the sender contains the given - regular expression, and the date is valid. - - \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 7 - - We use our custom \c dateInRange() function to determine if a date - is valid. - - To be able to filter our data by specifying a given period of - time, we also implement functions for getting and setting the - minimum and maximum dates: - - \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 1 - \codeline - \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 2 - - The get functions, \c filterMinimumDate() and \c - filterMaximumDate(), are trivial and implemented as inline - function in the header file. - - This completes our custom proxy model. Let's see how we can use it - in an application. - - \section1 Window Class Definition - - The \c CustomFilter class inherits QWidget, and provides this - example's main application window: - - \snippet itemviews/customsortfiltermodel/window.h 0 - - We implement two private slots, \c textFilterChanged() and \c - dateFilterChanged(), to respond to the user changing the filter - pattern, case sensitivity or any of the dates. In addition, we - implement a public \c setSourceModel() convenience function to set - up the model/ view relation. - - \section1 Window Class Implementation - - In this example, we have chosen to create and set the source model - in the \c main () function (which we will come back to later). So - when constructing the main application window, we assume that a - source model already exists and start by creating an instance of - our custom proxy model: - - \snippet itemviews/customsortfiltermodel/window.cpp 0 - - We set the \l - {QSortFilterProxyModel::dynamicSortFilter}{dynamicSortFilter} - property that holds whether the proxy model is dynamically sorted - and filtered. By setting this property to true, we ensure that the - model is sorted and filtered whenever the contents of the source - model change. - - The main application window shows views of both the source model - and the proxy model. The source view is quite simple: - - \snippet itemviews/customsortfiltermodel/window.cpp 1 - - The QTreeView class provides a default model/view implementation - of a tree view; our view implements a tree representation of items - in the application's source model. - - \snippet itemviews/customsortfiltermodel/window.cpp 2 - - The QTreeView class provides a default model/view implementation - of a tree view; our view implements a tree representation of items - in the application's source model. We add our view widget to a - layout that we install on a corresponding group box. - - The proxy model view, on the other hand, contains several widgets - controlling the various aspects of transforming the source model's - data structure: - - \snippet itemviews/customsortfiltermodel/window.cpp 3 - \snippet itemviews/customsortfiltermodel/window.cpp 4 - - Note that whenever the user changes one of the filtering options, - we must explicitly reapply the filter. This is done by connecting - the various editors to functions that update the proxy model. - - \snippet itemviews/customsortfiltermodel/window.cpp 5 - - The sorting will be handled by the view. All we have to do is to - enable sorting for our proxy view by setting the - QTreeView::sortingEnabled property (which is false by - default). Then we add all the filtering widgets and the proxy view - to a layout that we install on a corresponding group box. - - \snippet itemviews/customsortfiltermodel/window.cpp 6 - - Finally, after putting our two group boxes into another layout - that we install on our main application widget, we customize the - application window. - - As mentioned above, we create the source model in the \c main () - function, calling the \c Window::setSourceModel() function to make - the application use it: - - \snippet itemviews/customsortfiltermodel/window.cpp 7 - - The QSortFilterProxyModel::setSourceModel() function makes the - proxy model process the data in the given model, in this case out - mail model. The \l {QAbstractItemView::}{setModel()} that the - view widget inherits from the QAbstractItemModel class, sets the - model for the view to present. Note that the latter function will - also create and set a new selection model. - - \snippet itemviews/customsortfiltermodel/window.cpp 8 - - The \c textFilterChanged() function is called whenever the user - changes the filter pattern or the case sensitivity. - - We first retrieve the preferred syntax (the QRegExp::PatternSyntax - enum is used to interpret the meaning of the given pattern), then - we determine the preferred case sensitivity. Based on these - preferences and the current filter pattern, we set the proxy - model's \l {QSortFilterProxyModel::}{filterRegExp} property. The - \l {QSortFilterProxyModel::}{filterRegExp} property holds the - regular expression used to filter the contents of the source - model. Note that calling QSortFilterProxyModel's \l - {QSortFilterProxyModel::}{setFilterRegExp()} function also updates - the model. - - \snippet itemviews/customsortfiltermodel/window.cpp 9 - - The \c dateFilterChanged() function is called whenever the user - modifies the range of valid dates. We retrieve the new dates from - the user interface, and call the corresponding functions (provided - by our custom proxy model) to set the proxy model's minimum and - maximum dates. As we explained above, calling these functions also - updates the model. - - \section1 The Main() Function - - In this example, we have separated the application from the source - model by creating the model in the \c main () function. First we - create the application, then we create the source model: - - \snippet itemviews/customsortfiltermodel/main.cpp 0 - - The \c createMailModel() function is a convenience function - provided to simplify the constructor. All it does is to create and - return a model describing a collection of emails. The model is an - instance of the QStandardItemModel class, i.e., a generic model - for storing custom data typically used as a repository for - standard Qt data types. Each mail description is added to the - model using \c addMail(), another convenience function. See \l - {itemviews/customsortfiltermodel/main.cpp}{main.cpp} for details. -*/ diff --git a/examples/widgets/doc/deform.qdoc b/examples/widgets/doc/deform.qdoc deleted file mode 100644 index 8195f90ffa..0000000000 --- a/examples/widgets/doc/deform.qdoc +++ /dev/null @@ -1,51 +0,0 @@ -/**************************************************************************** -** -** 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 painting/deform - \title Vector Deformation - - This example shows how to use advanced vector techniques to draw text - using a \c QPainterPath. - - \image deform-demo.png - - We define a vector deformation field in the shape of a lens and apply - this to all points in a path. This means that what is rendered on - screen is not pixel manipulation, but modified vector representations of - the glyphs themselves. This is visible from the high quality of the - antialiased edges for the deformed glyphs. - - To get a fairly complex path we allow the user to type in text and - convert the text to paths. This is done using the - QPainterPath::addText() function. - - The lens is drawn using a single call to QPainter::drawEllipse(), - using a QRadialGradient to fill it with a specialized color - table, giving the effect of the sun's reflection and a drop - shadow. The lens is cached as a pixmap for better performance. -*/ diff --git a/examples/widgets/doc/diagramscene.qdoc b/examples/widgets/doc/diagramscene.qdoc deleted file mode 100644 index b61a936d52..0000000000 --- a/examples/widgets/doc/diagramscene.qdoc +++ /dev/null @@ -1,834 +0,0 @@ -/**************************************************************************** -** -** 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 graphicsview/diagramscene - \title Diagram Scene Example - - This example shows use of Qt's graphics framework. - - \image diagramscene.png - - The Diagram Scene example is an application in which you can - create a flowchart diagram. It is possible to add flowchart shapes - and text and connect the shapes by arrows as shown in the image - above. The shapes, arrows, and text can be given different - colors, and it is possible to change the font, style, and - underline of the text. - - The Qt graphics view framework is designed to manage and display - custom 2D graphics items. The main classes of the framework are - QGraphicsItem, QGraphicsScene and QGraphicsView. The graphics - scene manages the items and provides a surface for them. - QGraphicsView is a widget that is used to render a scene on the - screen. See the \l{Graphics View Framework} for a more detailed - description of the framework. - - In this example we show how to create such custom graphics - scenes and items by implementing classes that inherit - QGraphicsScene and QGraphicsItem. - - In particular we show how to: - - \list - \li Create custom graphics items. - \li Handle mouse events and movement of items. - \li Implement a graphics scene that can manage our custom items. - \li Custom painting of items. - \li Create a movable and editable text item. - \endlist - - The example consists of the following classes: - \list - \li \c MainWindow creates the widgets and display - them in a QMainWindow. It also manages the interaction - between the widgets and the graphics scene, view and - items. - \li \c DiagramItem inherits QGraphicsPolygonItem and - represents a flowchart shape. - \li \c TextDiagramItem inherits QGraphicsTextItem and - represents text items in the diagram. The class adds - support for moving the item with the mouse, which is not - supported by QGraphicsTextItem. - \li \c Arrow inherits QGraphicsLineItem and is an arrow - that connect two DiagramItems. - \li \c DiagramScene inherits QGraphicsDiagramScene and - provides support for \c DiagramItem, \c Arrow and - \c DiagramTextItem (In addition to the support already - handled by QGraphicsScene). - \endlist - - \section1 MainWindow Class Definition - - \snippet graphicsview/diagramscene/mainwindow.h 0 - - The \c MainWindow class creates and lays out the widgets in a - QMainWindow. The class forwards input from the widgets to the - DiagramScene. It also updates its widgets when the diagram - scene's text item changes, or a diagram item or a diagram text item - is inserted into the scene. - - The class also deletes items from the scene and handles the - z-ordering, which decides the order in which items are drawn when - they overlap each other. - - \section1 MainWindow Class Implementation - - - We start with a look at the constructor: - - \snippet graphicsview/diagramscene/mainwindow.cpp 0 - - In the constructor we call methods to create the widgets and - layouts of the example before we create the diagram scene. - The toolbars must be created after the scene as they connect - to its signals. We then lay the widgets out in the window. - - We connect to the \c itemInserted() and \c textInserted() slots of - the diagram scenes as we want to uncheck the buttons in the tool - box when an item is inserted. When an item is selected in - the scene we receive the \c itemSelected() signal. We use this to - update the widgets that display font properties if the item - selected is a \c DiagramTextItem. - - The \c createToolBox() function creates and lays out the widgets - of the \c toolBox QToolBox. We will not examine it with a - high level of detail as it does not deal with graphics framework - specific functionality. Here is its implementation: - - \snippet graphicsview/diagramscene/mainwindow.cpp 21 - - This part of the function sets up the tabbed widget item that - contains the flowchart shapes. An exclusive QButtonGroup always - keeps one button checked; we want the group to allow all buttons - to be unchecked. - We still use a button group since we can associate user - data, which we use to store the diagram type, with each button. - The \c createCellWidget() function sets up the buttons in the - tabbed widget item and is examined later. - - The buttons of the background tabbed widget item is set up in the - same way, so we skip to the creation of the tool box: - - \snippet graphicsview/diagramscene/mainwindow.cpp 22 - - We set the preferred size of the toolbox as its maximum. This - way, more space is given to the graphics view. - - Here is the \c createActions() function: - - \snippet graphicsview/diagramscene/mainwindow.cpp 23 - - We show an example of the creation of an action. The - functionality the actions trigger is discussed in the slots we - connect the actions to. You can see the \l{Application - Example}{application example} if you need a high-level - introduction to actions. - - The is the \c createMenus() function: - - \snippet graphicsview/diagramscene/mainwindow.cpp 24 - - We create the three menus' of the example. - - The \c createToolbars() function sets up the examples tool - bars. The three \l{QToolButton}s in the \c colorToolBar, the \c - fontColorToolButton, \c fillColorToolButton, and \c - lineColorToolButton, are interesting as we create icons for them - by drawing on a QPixmap with a QPainter. We show how the \c - fillColorToolButton is created. This button lets the user select a - color for the diagram items. - - \snippet graphicsview/diagramscene/mainwindow.cpp 25 - \dots - \snippet graphicsview/diagramscene/mainwindow.cpp 26 - - We set the menu of the tool button with - \l{QToolButton::}{setMenu()}. We need the \c fillAction QAction - object to always be pointing to the selected action of the menu. - The menu is created with the \c createColorMenu() function and, as - we shall see later, contains one menu item for each color that the - items can have. When the user presses the button, which trigger - the \l{QToolButton::}{clicked()} signal, we can set the color of - the selected item to the color of \c fillAction. It is with \c - createColorToolButtonIcon() we create the icon for the button. - - \dots - \snippet graphicsview/diagramscene/mainwindow.cpp 27 - - Here is the \c createBackgroundCellWidget() function: - - \snippet graphicsview/diagramscene/mainwindow.cpp 28 - - This function creates \l{QWidget}s containing a tool button - and a label. The widgets created with this function are used for - the background tabbed widget item in the tool box. - - Here is the \c createCellWidget() function: - - \snippet graphicsview/diagramscene/mainwindow.cpp 29 - - This function returns a QWidget containing a QToolButton with - an image of one of the \c DiagramItems, i.e., flowchart shapes. - The image is created by the \c DiagramItem through the \c image() - function. The QButtonGroup class lets us attach an id (int) with - each button; we store the diagram's type, i.e., the - DiagramItem::DiagramType enum. We use the stored diagram type when - we create new diagram items for the scene. The widgets created - with this function is used in the tool box. - - Here is the \c createColorMenu() function: - - \snippet graphicsview/diagramscene/mainwindow.cpp 30 - - This function creates a color menu that is used as the - drop-down menu for the tool buttons in the \c colorToolBar. We - create an action for each color that we add to the menu. We fetch - the actions data when we set the color of items, lines, and text. - - Here is the \c createColorToolButtonIcon() function: - - \snippet graphicsview/diagramscene/mainwindow.cpp 31 - - This function is used to create the QIcon of the \c - fillColorToolButton, \c fontColorToolButton, and \c - lineColorToolButton. The \a imageFile string is either the text, - flood-fill, or line symbol that is used for the buttons. Beneath - the image we draw a filled rectangle using \a color. - - Here is the \c createColorIcon() function: - - \snippet graphicsview/diagramscene/mainwindow.cpp 32 - - This function creates an icon with a filled rectangle in the - color of \a color. It is used for creating icons for the color - menus in the \c fillColorToolButton, \c fontColorToolButton, and - \c lineColorToolButton. - - Here is the \c backgroundButtonGroupClicked() slot: - - \snippet graphicsview/diagramscene/mainwindow.cpp 1 - - In this function we set the QBrush that is used to draw the - background of the diagramscene. The background can be a grid of - squares of blue, gray, or white tiles, or no grid at all. We have - \l{QPixmap}s of the tiles from png files that we create the brush - with. - - When one of the buttons in the background tabbed widget item is - clicked we change the brush; we find out which button it is by - checking its text. - - Here is the implementation of \c buttonGroupClicked(): - - \snippet graphicsview/diagramscene/mainwindow.cpp 2 - - This slot is called when a button in \c buttonGroup is checked. - When a button is checked the user can click on the graphics view - and a \c DiagramItem of the selected type will be inserted into - the \c DiagramScene. We must loop through the buttons in the group - to uncheck other buttons as only one button is allowed to be - checked at a time. - - \c QButtonGroup assigns an id to each button. We have set the id - of each button to the diagram type, as given by DiagramItem::DiagramType - that will be inserted into the scene when it is clicked. We can - then use the button id when we set the diagram type with - \c setItemType(). In the case of text we assigned an id that has a - value that is not in the DiagramType enum. - - Here is the implementation of \c deleteItem(): - - \snippet graphicsview/diagramscene/mainwindow.cpp 3 - - This slot deletes the selected item, if any, from the scene. It - deletes the arrows first in order to avoid to delete them twice. If - the item to be deleted is a \c DiagramItem, we also need to delete - arrows connected to it; we don't want arrows in the scene that - aren't connected to items in both ends. - - This is the implementation of pointerGroupClicked(): - - \snippet graphicsview/diagramscene/mainwindow.cpp 4 - - The \c pointerTypeGroup decides whether the scene is in ItemMove - or InsertLine mode. This button group is exclusive, i.e., only - one button is checked at any time. As with the \c buttonGroup above - we have assigned an id to the buttons that matches values of the - DiagramScene::Mode enum, so that we can use the id to set the - correct mode. - - Here is the \c bringToFront() slot: - - \snippet graphicsview/diagramscene/mainwindow.cpp 5 - - Several items may collide, i.e., overlap, with each other in - the scene. This slot is called when the user requests that an - item should be placed on top of the items it collides with. - \l{QGraphicsItem}{QGrapicsItems} have a z-value that decides the - order in which items are stacked in the scene; you can think of it - as the z-axis in a 3D coordinate system. When items collide the - items with higher z-values will be drawn on top of items with - lower values. When we bring an item to the front we can loop - through the items it collides with and set a z-value that is - higher than all of them. - - Here is the \c sendToBack() slot: - - \snippet graphicsview/diagramscene/mainwindow.cpp 6 - - This slot works in the same way as \c bringToFront() described - above, but sets a z-value that is lower than items the item that - should be send to the back collides with. - - This is the implementation of \c itemInserted(): - - \snippet graphicsview/diagramscene/mainwindow.cpp 7 - - This slot is called from the \c DiagramScene when an item has been - added to the scene. We set the mode of the scene back to the mode - before the item was inserted, which is ItemMove or InsertText - depending on which button is checked in the \c pointerTypeGroup. - We must also uncheck the button in the in the \c buttonGroup. - - Here is the implementation of \c textInserted(): - - \snippet graphicsview/diagramscene/mainwindow.cpp 8 - - We simply set the mode of the scene back to the mode it had before - the text was inserted. - - Here is the \c currentFontChanged() slot: - - \snippet graphicsview/diagramscene/mainwindow.cpp 9 - - When the user requests a font change, by using one of the - widgets in the \c fontToolBar, we create a new QFont object and - set its properties to match the state of the widgets. This is done - in \c handleFontChange(), so we simply call that slot. - - Here is the \c fontSizeChanged() slot: - - \snippet graphicsview/diagramscene/mainwindow.cpp 10 - - When the user requests a font change, by using one of the - widgets in the \c fontToolBar, we create a new QFont object and - set its properties to match the state of the widgets. This is done - in \c handleFontChange(), so we simply call that slot. - - Here is the implementation of \c sceneScaleChanged(): - - \snippet graphicsview/diagramscene/mainwindow.cpp 11 - - The user can increase or decrease the scale, with the \c - sceneScaleCombo, the scene is drawn in. - It is not the scene itself that changes its scale, but only the - view. - - Here is the \c textColorChanged() slot: - - \snippet graphicsview/diagramscene/mainwindow.cpp 12 - - This slot is called when an item in the drop-down menu of the \c - fontColorToolButton is pressed. We need to change the icon on - the button to the color of the selected QAction. We keep a pointer - to the selected action in \c textAction. It is in \c - textButtonTriggered() we change the text color to the color of \c - textAction, so we call that slot. - - Here is the \c itemColorChanged() implementation: - - \snippet graphicsview/diagramscene/mainwindow.cpp 13 - - This slot handles requests for changing the color of \c - DiagramItems in the same manner as \c textColorChanged() does for - \c DiagramTextItems. - - Here is the implementation of \c lineColorChanged(): - - \snippet graphicsview/diagramscene/mainwindow.cpp 14 - - This slot handles requests for changing the color of \c Arrows in - the same manner that \c textColorChanged() does it for \c - DiagramTextItems. - - Here is the \c textButtonTriggered() slot: - - \snippet graphicsview/diagramscene/mainwindow.cpp 15 - - \c textAction points to the QAction of the currently selected menu item - in the \c fontColorToolButton's color drop-down menu. We have set - the data of the action to the QColor the action represents, so we - can simply fetch this when we set the color of text with \c - setTextColor(). - - Here is the \c fillButtonTriggered() slot: - - \snippet graphicsview/diagramscene/mainwindow.cpp 16 - - \c fillAction points to the selected menu item in the drop-down - menu of \c fillColorToolButton(). We can therefore use the data of - this action when we set the item color with \c setItemColor(). - - Here is the \c lineButtonTriggered() slot: - - \snippet graphicsview/diagramscene/mainwindow.cpp 17 - - \c lineAction point to the selected item in the drop-down menu of - \c lineColorToolButton. We use its data when we set the arrow - color with \c setLineColor(). - - Here is the \c handleFontChange() function: - - \snippet graphicsview/diagramscene/mainwindow.cpp 18 - - \c handleFontChange() is called when any of the widgets that show - font properties changes. We create a new QFont object and set its - properties based on the widgets. We then call the \c setFont() - function of \c DiagramScene; it is the scene that set the font of - the \c DiagramTextItems it manages. - - Here is the \c itemSelected() slot: - - \snippet graphicsview/diagramscene/mainwindow.cpp 19 - - This slot is called when an item in the \c DiagramScene is - selected. In the case of this example it is only text items that - emit signals when they are selected, so we do not need to check - what kind of graphics \a item is. - - We set the state of the widgets to match the properties of the - font of the selected text item. - - This is the \c about() slot: - - \snippet graphicsview/diagramscene/mainwindow.cpp 20 - - This slot displays an about box for the example when the user - selects the about menu item from the help menu. - - \section1 DiagramScene Class Definition - - The \c DiagramScene class inherits QGraphicsScene and adds - functionality to handle \c DiagramItems, \c Arrows, and \c - DiagramTextItems in addition to the items handled by its super - class. - - - \snippet graphicsview/diagramscene/diagramscene.h 0 - - In the \c DiagramScene a mouse click can give three different - actions: the item under the mouse can be moved, an item may be - inserted, or an arrow may be connected between to diagram items. - Which action a mouse click has depends on the mode, given by the - Mode enum, the scene is in. The mode is set with the \c setMode() - function. - - The scene also sets the color of its items and the font of its - text items. The colors and font used by the scene can be set with - the \c setLineColor(), \c setTextColor(), \c setItemColor() and \c - setFont() functions. The type of \c DiagramItem, given by the - DiagramItem::DiagramType function, to be created when an item is - inserted is set with the \c setItemType() slot. - - The \c MainWindow and \c DiagramScene share responsibility for - the examples functionality. \c MainWindow handles the following - tasks: the deletion of items, text, and arrows; moving diagram - items to the back and front; and setting the scale of the scene. - - \section1 DiagramScene Class Implementation - - - We start with the constructor: - - \snippet graphicsview/diagramscene/diagramscene.cpp 0 - - The scene uses \c myItemMenu to set the context menu when it - creates \c DiagramItems. We set the default mode to \c - DiagramScene::MoveItem as this gives the default behavior of - QGraphicsScene. - - Here is the \c setLineColor() function: - - \snippet graphicsview/diagramscene/diagramscene.cpp 1 - - The \c isItemChange function returns true if an \c Arrow item is - selected in the scene in which case we want to change its color. - When the \c DiagramScene creates and adds new arrows to the scene - it will also use the new \a color. - - Here is the \c setTextColor() function: - - \snippet graphicsview/diagramscene/diagramscene.cpp 2 - - This function sets the color of \c DiagramTextItems equal to the - way \c setLineColor() sets the color of \c Arrows. - - Here is the \c setItemColor() function: - - \snippet graphicsview/diagramscene/diagramscene.cpp 3 - - This function sets the color the scene will use when creating - \c DiagramItems. It also changes the color of a selected \c - DiagramItem. - - This is the implementation of \c setFont(): - - \snippet graphicsview/diagramscene/diagramscene.cpp 4 - - Set the font to use for new and selected, if a text item is - selected, \c DiagramTextItems. - - This is the implementation of \c editorLostFocus() slot: - - \snippet graphicsview/diagramscene/diagramscene.cpp 5 - - \c DiagramTextItems emit a signal when they loose focus, which is - connected to this slot. We remove the item if it has no text. - If not, we would leak memory and confuse the user as the items - will be edited when pressed on by the mouse. - - The \c mousePressEvent() function handles mouse press event's - different depending on which mode the \c DiagramScene is in. We - examine its implementation for each mode: - - \snippet graphicsview/diagramscene/diagramscene.cpp 6 - - We simply create a new \c DiagramItem and add it to the scene at - the position the mouse was pressed. Note that the origin of its - local coordinate system will be under the mouse pointer position. - - \snippet graphicsview/diagramscene/diagramscene.cpp 7 - - The user adds \c Arrows to the scene by stretching a line between - the items the arrow should connect. The start of the line is fixed - in the place the user clicked the mouse and the end follows the - mouse pointer as long as the button is held down. When the user - releases the mouse button an \c Arrow will be added to the scene - if there is a \c DiagramItem under the start and end of the line. - We will see how this is implemented later; here we simply add the - line. - - \snippet graphicsview/diagramscene/diagramscene.cpp 8 - - The \c DiagramTextItem is editable when the - Qt::TextEditorInteraction flag is set, else it is movable by the - mouse. We always want the text to be drawn on top of the other - items in the scene, so we set the value to a number higher - than other items in the scene. - - \snippet graphicsview/diagramscene/diagramscene.cpp 9 - - We are in MoveItem mode if we get to the default switch; we - can then call the QGraphicsScene implementation, which - handles movement of items with the mouse. We make this call even - if we are in another mode making it possible to add an item and - then keep the mouse button pressed down and start moving - the item. In the case of text items, this is not possible as they - do not propagate mouse events when they are editable. - - This is the \c mouseMoveEvent() function: - - \snippet graphicsview/diagramscene/diagramscene.cpp 10 - - We must draw the line if we are in InsertMode and the mouse button - is pressed down (the line is not 0). As discussed in \c - mousePressEvent() the line is drawn from the position the mouse - was pressed to the current position of the mouse. - - If we are in MoveItem mode, we call the QGraphicsScene - implementation, which handles movement of items. - - In the \c mouseReleaseEvent() function we need to check if an arrow - should be added to the scene: - - \snippet graphicsview/diagramscene/diagramscene.cpp 11 - - First we need to get the items (if any) under the line's start - and end points. The line itself is the first item at these points, - so we remove it from the lists. As a precaution, we check if the - lists are empty, but this should never happen. - - \snippet graphicsview/diagramscene/diagramscene.cpp 12 - - Now we check if there are two different \c DiagramItems under - the lines start and end points. If there are we can create an \c - Arrow with the two items. The arrow is then added to each item and - finally the scene. The arrow must be updated to adjust its start - and end points to the items. We set the z-value of the arrow to - -1000.0 because we always want it to be drawn under the items. - - \snippet graphicsview/diagramscene/diagramscene.cpp 13 - - Here is the \c isItemChange() function: - - \snippet graphicsview/diagramscene/diagramscene.cpp 14 - - The scene has single selection, i.e., only one item can be - selected at any given time. The foreach will then loop one time - with the selected item or none if no item is selected. \c - isItemChange() is used to check whether a selected item exists - and also is of the specified diagram \a type. - - \section1 DiagramItem Class Definition - - - \snippet graphicsview/diagramscene/diagramitem.h 0 - - The \c DiagramItem represents a flowchart shape in the \c - DiagramScene. It inherits QGraphicsPolygonItem and has a polygon - for each shape. The enum DiagramType has a value for each of the - flowchart shapes. - - The class has a list of the arrows that are connected to it. - This is necessary because only the item knows when it is being - moved (with the \c itemChanged() function) at which time the - arrows must be updated. The item can also draw itself onto a - QPixmap with the \c image() function. This is used for the tool - buttons in \c MainWindow, see \c createColorToolButtonIcon() in - \c MainWindow. - - The Type enum is a unique identifier of the class. It is used by - \c qgraphicsitem_cast(), which does dynamic casts of graphics - items. The UserType constant is the minimum value a custom - graphics item type can be. - - \section1 DiagramItem Class Implementation - - - We start with a look at the constructor: - - \snippet graphicsview/diagramscene/diagramitem.cpp 0 - - In the constructor we create the items polygon according to - \a diagramType. \l{QGraphicsItem}s are not movable or selectable - by default, so we must set these properties. - - Here is the \c removeArrow() function: - - \snippet graphicsview/diagramscene/diagramitem.cpp 1 - - \c removeArrow() is used to remove \c Arrow items when they - or \c DiagramItems they are connected to are removed from the - scene. - - Here is the \c removeArrows() function: - - \snippet graphicsview/diagramscene/diagramitem.cpp 2 - - This function is called when the item is removed from the scene - and removes all arrows that are connected to this item. The arrow - must be removed from the \c arrows list of both its start and end - item. - - Here is the \c addArrow() function: - - \snippet graphicsview/diagramscene/diagramitem.cpp 3 - - This function simply adds the \a arrow to the items \c arrows list. - - Here is the \c image() function: - - \snippet graphicsview/diagramscene/diagramitem.cpp 4 - - This function draws the polygon of the item onto a QPixmap. In - this example we use this to create icons for the tool buttons in - the tool box. - - Here is the \c contextMenuEvent() function: - - \snippet graphicsview/diagramscene/diagramitem.cpp 5 - - We show the context menu. As right mouse clicks, which shows the - menu, don't select items by default we set the item selected with - \l{QGraphicsItem::}{setSelected()}. This is necessary since an - item must be selected to change its elevation with the - \c bringToFront and \c sendToBack actions. - - This is the implementation of \c itemChange(): - - \snippet graphicsview/diagramscene/diagramitem.cpp 6 - - If the item has moved, we need to update the positions of the - arrows connected to it. The implementation of QGraphicsItem does - nothing, so we just return \a value. - - \section1 DiagramTextItem Class Definition - - The \c TextDiagramItem class inherits QGraphicsTextItem and - adds the possibility to move editable text items. Editable - QGraphicsTextItems are designed to be fixed in place and editing - starts when the user single clicks on the item. With \c - DiagramTextItem the editing starts with a double click leaving - single click available to interact with and move it. - - \snippet graphicsview/diagramscene/diagramtextitem.h 0 - - We use \c itemChange() and \c focusOutEvent() to notify the - \c DiagramScene when the text item loses focus and gets selected. - - We reimplement the functions that handle mouse events to make it - possible to alter the mouse behavior of QGraphicsTextItem. - - \section1 DiagramTextItem Implementation - - We start with the constructor: - - \snippet graphicsview/diagramscene/diagramtextitem.cpp 0 - - We simply set the item movable and selectable, as these flags are - off by default. - - Here is the \c itemChange() function: - - \snippet graphicsview/diagramscene/diagramtextitem.cpp 1 - - When the item is selected we emit the selectedChanged signal. The - \c MainWindow uses this signal to update the widgets that display - font properties to the font of the selected text item. - - Here is the \c focusOutEvent() function: - - \snippet graphicsview/diagramscene/diagramtextitem.cpp 2 - - \c DiagramScene uses the signal emitted when the text item looses - focus to remove the item if it is empty, i.e., it contains no - text. - - This is the implementation of \c mouseDoubleClickEvent(): - - \snippet graphicsview/diagramscene/diagramtextitem.cpp 5 - - When we receive a double click event, we make the item editable by calling - QGraphicsTextItem::setTextInteractionFlags(). We then forward the - double-click to the item itself. - - \section1 Arrow Class Definition - - The \c Arrow class is a graphics item that connects two \c - DiagramItems. It draws an arrow head to one of the items. To - achieve this the item needs to paint itself and also re implement - methods used by the graphics scene to check for collisions and - selections. The class inherits QGraphicsLine item, and draws the - arrowhead and moves with the items it connects. - - \snippet graphicsview/diagramscene/arrow.h 0 - - The item's color can be set with \c setColor(). - - \c boundingRect() and \c shape() are reimplemented - from QGraphicsLineItem and are used by the scene - to check for collisions and selections. - - Calling \c updatePosition() causes the arrow to recalculate its - position and arrow head angle. \c paint() is reimplemented so that - we can paint an arrow rather than just a line between items. - - \c myStartItem and \c myEndItem are the diagram items that the - arrow connects. The arrow is drawn with its head to the end item. - \c arrowHead is a polygon with three vertices's we use to draw the - arrow head. - - \section1 Arrow Class Implementation - - The constructor of the \c Arrow class looks like this: - - \snippet graphicsview/diagramscene/arrow.cpp 0 - - We set the start and end diagram items of the arrow. The arrow - head will be drawn where the line intersects the end item. - - Here is the \c boundingRect() function: - - \snippet graphicsview/diagramscene/arrow.cpp 1 - - We need to reimplement this function because the arrow is - larger than the bounding rectangle of the QGraphicsLineItem. The - graphics scene uses the bounding rectangle to know which regions - of the scene to update. - - Here is the \c shape() function: - - \snippet graphicsview/diagramscene/arrow.cpp 2 - - The shape function returns a QPainterPath that is the exact - shape of the item. The QGraphicsLineItem::shape() returns a path - with a line drawn with the current pen, so we only need to add - the arrow head. This function is used to check for collisions and - selections with the mouse. - - Here is the \c updatePosition() slot: - - \snippet graphicsview/diagramscene/arrow.cpp 3 - - This slot updates the arrow by setting the start and end - points of its line to the center of the items it connects. - - Here is the \c paint() function: - - \snippet graphicsview/diagramscene/arrow.cpp 4 - - If the start and end items collide we do not draw the arrow; the - algorithm we use to find the point the arrow should be drawn at - may fail if the items collide. - - We first set the pen and brush we will use for drawing the arrow. - - \snippet graphicsview/diagramscene/arrow.cpp 5 - - We then need to find the position at which to draw the - arrowhead. The head should be drawn where the line and the end - item intersects. This is done by taking the line between each - point in the polygon and check if it intersects with the line of - the arrow. Since the line start and end points are set to the - center of the items the arrow line should intersect one and only - one of the lines of the polygon. Note that the points in the - polygon are relative to the local coordinate system of the item. - We must therefore add the position of the end item to make the - coordinates relative to the scene. - - \snippet graphicsview/diagramscene/arrow.cpp 6 - - We calculate the angle between the x-axis and the line of the - arrow. We need to turn the arrow head to this angle so that it - follows the direction of the arrow. If the angle is negative we - must turn the direction of the arrow. - - We can then calculate the three points of the arrow head polygon. - One of the points is the end of the line, which now is the - intersection between the arrow line and the end polygon. Then we - clear the \c arrowHead polygon from the previous calculated arrow - head and set these new points. - - \snippet graphicsview/diagramscene/arrow.cpp 7 - - If the line is selected, we draw two dotted lines that are - parallel with the line of the arrow. We do not use the default - implementation, which uses \l{QGraphicsItem::}{boundingRect()} - because the QRect bounding rectangle is considerably larger than - the line. -*/ diff --git a/examples/widgets/doc/digitalclock.qdoc b/examples/widgets/doc/digitalclock.qdoc deleted file mode 100644 index 92e8003205..0000000000 --- a/examples/widgets/doc/digitalclock.qdoc +++ /dev/null @@ -1,74 +0,0 @@ -/**************************************************************************** -** -** 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/digitalclock - \title Digital Clock Example - - The Digital Clock example shows how to use QLCDNumber to display a - number with LCD-like digits. - - \image digitalclock-example.png Screenshot of the Digital Clock example - - This example also demonstrates how QTimer can be used to update a widget - at regular intervals. - - \section1 DigitalClock Class Definition - - The \c DigitalClock class provides a clock widget showing the time with - hours and minutes separated by a blinking colon. We subclass QLCDNumber - and implement a private slot called \c showTime() to update the clock - display: - - \snippet widgets/digitalclock/digitalclock.h 0 - - \section1 DigitalClock Class Implementation - - \snippet widgets/digitalclock/digitalclock.cpp 0 - - In the constructor, we first change the look of the LCD numbers. The - QLCDNumber::Filled style produces raised segments filled with the - foreground color (typically black). We also set up a one-second timer - to keep track of the current time, and we connect - its \l{QTimer::timeout()}{timeout()} signal to the private \c showTime() slot - so that the display is updated every second. Then, we - call the \c showTime() slot; without this call, there would be a one-second - delay at startup before the time is shown. - - \snippet widgets/digitalclock/digitalclock.cpp 1 - \snippet widgets/digitalclock/digitalclock.cpp 2 - - The \c showTime() slot is called whenever the clock display needs - to be updated. - - The current time is converted into a string with the format "hh:mm". - When QTime::second() is a even number, the colon in the string is - replaced with a space. This makes the colon appear and vanish every - other second. - - Finally, we call QLCDNumber::display() to update the widget. -*/ diff --git a/examples/widgets/doc/dirview.qdoc b/examples/widgets/doc/dirview.qdoc deleted file mode 100644 index a4b799678a..0000000000 --- a/examples/widgets/doc/dirview.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/dirview - \title Dir View Example - - The Dir View example shows a tree view onto the local filing system. It uses the - QDirModel class to provide file and directory information. - - \image dirview-example.png -*/ diff --git a/examples/widgets/doc/dockwidgets.qdoc b/examples/widgets/doc/dockwidgets.qdoc deleted file mode 100644 index 12f18a538f..0000000000 --- a/examples/widgets/doc/dockwidgets.qdoc +++ /dev/null @@ -1,163 +0,0 @@ -/**************************************************************************** -** -** 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 mainwindows/dockwidgets - \title Dock Widgets Example - - The Dock Widgets example shows how to add dock windows to an - application. It also shows how to use Qt's rich text engine. - - \image dockwidgets-example.png Screenshot of the Dock Widgets example - - The application presents a simple business letter template, and has - a list of customer names and addresses and a list of standard - phrases in two dock windows. The user can click a customer to have - their name and address inserted into the template, and click one or - more of the standard phrases. Errors can be corrected by clicking - the Undo button. Once the letter has been prepared it can be printed - or saved as HTML. - - \section1 MainWindow Class Definition - - Here's the class definition: - - \snippet mainwindows/dockwidgets/mainwindow.h 0 - - We will now review each function in turn. - - \section1 MainWindow Class Implementation - - \snippet mainwindows/dockwidgets/mainwindow.cpp 0 - - We start by including \c , a header file that contains the - definition of all classes in the \l QtCore and \l QtGui - libraries. This saves us from having to include - every class individually and is especially convenient if we add new - widgets. We also include \c mainwindow.h. - - \snippet mainwindows/dockwidgets/mainwindow.cpp 1 - - In the constructor, we start by creating a QTextEdit widget. Then we call - QMainWindow::setCentralWidget(). This function passes ownership of - the QTextEdit to the \c MainWindow and tells the \c MainWindow that - the QTextEdit will occupy the \c MainWindow's central area. - - Then we call \c createActions(), \c createMenus(), \c - createToolBars(), \c createStatusBar(), and \c createDockWindows() - to set up the user interface. Finally we call \c setWindowTitle() to - give the application a title, and \c newLetter() to create a new - letter template. - - We won't quote the \c createActions(), \c createMenus(), \c - createToolBars(), and \c createStatusBar() functions since they - follow the same pattern as all the other Qt examples. - - \snippet mainwindows/dockwidgets/mainwindow.cpp 9 - - We create the customers dock window first, and in addition to a - window title, we also pass it a \c this pointer so that it becomes a - child of \c MainWindow. Normally we don't have to pass a parent - because widgets are parented automatically when they are laid out: - but dock windows aren't laid out using layouts. - - We've chosen to restrict the customers dock window to the left and - right dock areas. (So the user cannot drag the dock window to the - top or bottom dock areas.) The user can drag the dock window out of - the dock areas entirely so that it becomes a free floating window. - We can change this (and whether the dock window is moveable or - closable) using QDockWidget::setFeatures(). - - Once we've created the dock window we create a list widget with the - dock window as parent, then we populate the list and make it the - dock window's widget. Finally we add the dock widget to the \c - MainWindow using \c addDockWidget(), choosing to put it in the right - dock area. - - We undertake a similar process for the paragraphs dock window, - except that we don't restrict which dock areas it can be dragged to. - - Finally we set up the signal-slot connections. If the user clicks a - customer or a paragraph their \c currentTextChanged() signal will be - emitted and we connect these to \c insertCustomer() and - addParagraph() passing the text that was clicked. - - We briefly discuss the rest of the implementation, but have now - covered everything relating to dock windows. - - \snippet mainwindows/dockwidgets/mainwindow.cpp 2 - - In this function we clear the QTextEdit so that it is empty. Next we - create a QTextCursor on the QTextEdit. We move the cursor to the - start of the document and create and format a frame. We then create - some character formats and a table format. We insert a table into - the document and insert the company's name and address into a table - using the table and character formats we created earlier. Then we - insert the skeleton of the letter including two markers \c NAME and - \c ADDRESS. We will also use the \c{Yours sincerely,} text as a marker. - - \snippet mainwindows/dockwidgets/mainwindow.cpp 6 - - If the user clicks a customer we split the customer details into - pieces. We then look for the \c NAME marker using the \c find() - function. This function selects the text it finds, so when we call - \c insertText() with the customer's name the name replaces the marker. - We then look for the \c ADDRESS marker and replace it with each line - of the customer's address. Notice that we wrapped all the insertions - between a \c beginEditBlock() and \c endEditBlock() pair. This means - that the entire name and address insertion is treated as a single - operation by the QTextEdit, so a single undo will revert all the - insertions. - - \snippet mainwindows/dockwidgets/mainwindow.cpp 7 - - This function works in a similar way to \c insertCustomer(). First - we look for the marker, in this case, \c {Yours sincerely,}, and then - replace it with the standard paragraph that the user clicked. Again - we use a \c beginEditBlock() ... \c endEditBlock() pair so that the - insertion can be undone as a single operation. - - \snippet mainwindows/dockwidgets/mainwindow.cpp 3 - - Qt's QTextDocument class makes printing documents easy. We simply - take the QTextEdit's QTextDocument, set up the printer and print the - document. - - \snippet mainwindows/dockwidgets/mainwindow.cpp 4 - - QTextEdit can output its contents in HTML format, so we prompt the - user for the name of an HTML file and if they provide one we simply - write the QTextEdit's contents in HTML format to the file. - - \snippet mainwindows/dockwidgets/mainwindow.cpp 5 - - If the focus is in the QTextEdit, pressing \uicontrol Ctrl+Z undoes as - expected. But for the user's convenience we provide an - application-wide undo function that simply calls the QTextEdit's - undo: this means that the user can undo regardless of where the - focus is in the application. -*/ diff --git a/examples/widgets/doc/draganddroppuzzle.qdoc b/examples/widgets/doc/draganddroppuzzle.qdoc deleted file mode 100644 index d0d336f70f..0000000000 --- a/examples/widgets/doc/draganddroppuzzle.qdoc +++ /dev/null @@ -1,42 +0,0 @@ -/**************************************************************************** -** -** 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/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 - item view widgets. - - \image draganddroppuzzle-example.png - - This example is an implementation of a simple jigsaw puzzle game using Qt's - drag and drop API. - The \l{Item Views Puzzle Example}{Item View Puzzle} example shows - many of the same features, but takes an alternative approach that uses Qt's - model/view framework to manage drag and drop operations. -*/ diff --git a/examples/widgets/doc/dragdroprobot.qdoc b/examples/widgets/doc/dragdroprobot.qdoc deleted file mode 100644 index 60bd4eb4d8..0000000000 --- a/examples/widgets/doc/dragdroprobot.qdoc +++ /dev/null @@ -1,365 +0,0 @@ -/**************************************************************************** -** -** 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 graphicsview/dragdroprobot - \title Drag and Drop Robot Example - - The Drag and Drop Robot example shows how to implement Drag and Drop in a - QGraphicsItem subclass, as well as how to animate items using Qt's - \l{Animation Framework}. - - \image dragdroprobot-example.png - - Graphics View provides the QGraphicsScene class for managing and - interacting with a large number of custom-made 2D graphical items derived - from the QGraphicsItem class, and a QGraphicsView widget for visualizing - the items, with support for zooming and rotation. - - This example consists of a \c Robot class, a \c ColorItem class, and a main - function: the \c Robot class describes a simple robot consisting of several - \c RobotPart derived limbs, including \c RobotHead and \c RobotLimb, the \c - ColorItem class provides a draggable colored ellipse, and the \c main() - function provides the main application window. - - We will first review the \c Robot class to see how to assemble the - different parts so that they can be individually rotated and animated using - QPropertyAnimation, and we will then review the \c ColorItem class to - demonstrate how to implement Drag and Drop between items. Finally we will - review the main() function to see how we can put all the pieces together, - to form the final application. - - \section1 Robot Class Definition - - The robot consists of three main classes: the \c RobotHead, the \c - RobotTorso, and the \c RobotLimb, which is used for the upper and lower - arms and legs. All parts derive from the \c RobotPart class, which in turn - inherits \c QGraphicsObject. The \c Robot class itself has no visual - appearance and serves only as a root node for the robot. - - Let's start with the \c RobotPart class declaration. - - \snippet graphicsview/dragdroprobot/robot.h 0 - - This base class inherits QGraphicsObject. QGraphicsObject provides signals - and slots through inheriting QObject, and it also declares QGraphicsItem's - properties using Q_PROPERTY, which makes the properties accessible for - QPropertyAnimation. - - RobotPart also implements the three most important event handlers for - accepting drop events: - \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()}, - \l{QGraphicsItem::dragLeaveEvent()}{dragLeaveEvent()}, and - \l{QGraphicsItem::dropEvent()}{dropEvent()}. - - The color is stored as a member variable, along with the \c dragOver - variable, which we will use later to indicate visually that the limb can - accept colors that are is dragged onto it. - - \snippet graphicsview/dragdroprobot/robot.cpp 0 - - \c RobotPart's constructor initializes the dragOver member and sets the - color to Qt::lightGray. In the constructor body we enable support for - accepting drop events by calling - \l{QGraphicsItem::setAcceptDrops()}{setAcceptDrops(true)}. - - The rest of this class's implementation is to support Drag and Drop. - - \snippet graphicsview/dragdroprobot/robot.cpp 1 - - The \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()} handler is called - when a Drag and Drop element is dragged into the robot part's area. - - The handler implementation determines whether or not this item as a whole - can accept the mime data assiciated with the incoming drag object. \c - RobotPart provides a base behavior for all parts that accepts color drops. - So if the incoming drag object contains a color, the event is accepted, we - set \c dragOver to \c true and call update() to help provide positive - visual feedback to the user; otherwise the event is ignored, which in turn - allows the event to propagate to parent elements. - - \snippet graphicsview/dragdroprobot/robot.cpp 2 - - The \l{QGraphicsItem::dragLeaveEvent()}{dragLeaveEvent()} handler is called - when a Drag and Drop element is dragged away from the robot part's area. - Our implementation simply resets \e dragOver to false and calls - \l{QGraphicsItem::update()}{update()} to help provide visual feedback that - the drag has left this item. - - \snippet graphicsview/dragdroprobot/robot.cpp 3 - - The \l{QGraphicsItem::dropEvent()}{dropEvent()} handler is called when a - Drag and Drop element is dropped onto an item (i.e., when the mouse button - is released over the item while dragging). - - We reset \c dragOver to false, assign the item's new color, and call - \l{QGraphicsItem::update()}{update()}. - - The declaration and implementation of \c RobotHead, \c RobotTorso, and \c - RobotLimb are practically identical. We will review \c RobotHead in detail, - as this class has one minor difference, and leave the other classes as an - exercise for the reader. - - \snippet graphicsview/dragdroprobot/robot.h 1 - - The \c RobotHead class inherits \c RobotPart and provides the necessary - implementations of \l{QGraphicsItem::boundingRect()}{boundingRect()} and - \l{QGraphicsItem::paint()}{paint()}. It also reimplements - \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()} and dropEvent() to - provide special handling of image drops. - - The class contains a private pixmap member that we can use to implement - support for accepting image drops. - - \snippet graphicsview/dragdroprobot/robot.cpp 4 - - \c RobotHead has a rather plain constructor that simply forwards to - \c RobotPart's constructor. - - \snippet graphicsview/dragdroprobot/robot.cpp 5 - - The \l{QGraphicsItem::boundingRect()}{boundingRect()} reimplementation - returns the extents for the head. Because we want the center of rotation to - be the bottom center of the item, we have chosen a bounding rectangle that - starts at (-15, -50) and extends to 30 units wide and 50 units tall. When - rotating the head, the "neck" will stay still while the top of the head - tilts from side to side. - - \snippet graphicsview/dragdroprobot/robot.cpp 6 - - In \l{QGraphicsItem::paint()}{paint()} we draw the actual head. The - implementation is split into two sections; if an image has been dropped - onto the head, we draw the image, otherwise we draw a round rectangular - robot head with simple vector graphics. - - For performance reasons, depending on the complexity of what is painted, it - can often be faster to draw the head as an image rather than using a - sequence of vector operations. - - \snippet graphicsview/dragdroprobot/robot.cpp 7 - - The robot head can accept image drops. In order to support this, its - reimplementation of \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()} - checks if the drag object contains image data, and if it does, then the - event is accepted. Otherwise we fall back to the base \c RobotPart - implementation. - - \snippet graphicsview/dragdroprobot/robot.cpp 8 - - To follow up on image support, we must also implement - \l{QGraphicsItem::dropEvent()}{dropEvent()}. We check if the drag object - contains image data, and if it does, we store this data as a member pixmap - and call \l{QGraphicsItem::update()}{update()}. This pixmap is used inside - the \l{QGraphicsItem::paint()}{paint()} implementation that we reviewed - before. - - \c RobotTorso and \c RobotLimb are similar to \c RobotHead, so let's - skip directly to the \c Robot class. - - \snippet graphicsview/dragdroprobot/robot.h 4 - - The \c Robot class also inherits \c RobotPart, and like the other parts it - also implements \l{QGraphicsItem::boundingRect()}{boundingRect()} and - \l{QGraphicsItem::paint()}{paint()}. It provides a rather special - implementation, though: - - \snippet graphicsview/dragdroprobot/robot.cpp 9 - - Because the \c Robot class is only used as a base node for the rest of the - robot, it has no visual representation. Its - \l{QGraphicsItem::boundingRect()}{boundingRect()} implementation can - therefore return a null QRectF, and its paint() function does nothing. - - \snippet graphicsview/dragdroprobot/robot.cpp 10 - - The constructor starts by setting the flag - \l{QGraphicsItem::ItemHasNoContents}{ItemHasNoContents}, which is a minor - optimization for items that have no visual appearance. - - We then construct all the robot parts (head, torso, and upper/lower arms - and legs). The stacking order is very important, and we use the - parent-child hierarchy to ensure the elements rotate and move properly. We - construct the torso first, as this is the root element. We then construct - the head and pass the torso to \c HeadItem's constructor. This will make - the head a child of the torso; if you rotate the torso, the head will - follow. The same pattern is applied to the rest of the limbs. - - \snippet graphicsview/dragdroprobot/robot.cpp 11 - - Each robot part is carefully positioned. For example, the upper left arm is - moved precisely to the top-left area of the torso, and the upper right arm - is moved to the top-right area. - - \snippet graphicsview/dragdroprobot/robot.cpp 12 - - The next section creates all animation objects. This snippet shows the two - animations that operate on the head's scale and rotation. The two - QPropertyAnimation instances simply set the object, property, and - respective start and end values. - - All animations are controlled by one top-level parallel animation group. - The scale and rotation animations are added to this group. - - The rest of the animations are defined in a similar way. - - \snippet graphicsview/dragdroprobot/robot.cpp 13 - - Finally we set an easing curve and duration on each animation, ensure the - toplevel animation group loops forever, and start the toplevel animation. - - \section1 ColorItem Class Definition - - The \c ColorItem class represents a circular item that can be pressed to - drag colors onto robot parts. - - \snippet graphicsview/dragdroprobot/coloritem.h 0 - - This class is very simple. It does not use animations, and has no need for - properties nor signals and slots, so to save resources, it's most natural - that it inherits QGraphicsItem (as opposed to QGraphicsObject). - - It declares the mandatory \l{QGraphicsItem::boundingRect()}{boundingRect()} - and \l{QGraphicsItem::paint()}{paint()} functions, and adds - reimplementations of - \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()}, - \l{QGraphicsItem::mouseMoveEvent()}{mouseMoveEvent()}, and - \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()}. It contains a - single private color member. - - Let's take a look at its implementation. - - \snippet graphicsview/dragdroprobot/coloritem.cpp 0 - - \c ColorItem's constructor assigns an opaque random color to its color - member by making use of qrand(). For improved usability, it assigns a - tooltip that provides a useful hint to the user, and it also sets a - suitable cursor. This ensures that the cursor will chance to - Qt::OpenHandCursor when the mouse pointer hovers over the item. - - Finally, we call - \l{QGraphicsItem::setAcceptedMouseButtons()}{setAcceptedMouseButtons()} to - ensure that this item can only process Qt::LeftButton. This simplifies the - mouse event handlers greatly, as we can always assume that only the left - mouse button is pressed and released. - - \snippet graphicsview/dragdroprobot/coloritem.cpp 1 - - The item's bounding rect is a fixed 30x30 units centered around the item's - origin (0, 0), and adjusted by 0.5 units in all directions to allow a - scalable pen to draw its outline. For a final visual touch the bounds - also compensate with a few units down and to the right to make room - for a simple dropshadow. - - \snippet graphicsview/dragdroprobot/coloritem.cpp 2 - - The \l{QGraphicsItem::paint()}{paint()} implementation draws an ellipse - with a 1-unit black outline, a plain color fill, and a dark gray - dropshadow. - - \snippet graphicsview/dragdroprobot/coloritem.cpp 3 - - The \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()} handler is - called when you press the mouse button inside the item's area. Our - implementation simply sets the cursor to Qt::ClosedHandCursor. - - \snippet graphicsview/dragdroprobot/coloritem.cpp 4 - - The \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()} handler is - called when you release the mouse button after having pressed it inside an - item's area. Our implementation sets the cursor back to Qt::OpenHandCursor. - The mouse press and release event handlers together provide useful visual - feedback to the user: when you move the mouse pointer over a \c CircleItem, - the cursor changes to an open hand. Pressing the item will show a closed - hand cursor. Releasing will restore to an open hand cursor again. - - \snippet graphicsview/dragdroprobot/coloritem.cpp 5 - - The \l{QGraphicsItem::mouseMoveEvent()}{mouseMoveEvent()} handler is called - when you move the mouse around after pressing the mouse button inside the - \c ColorItem's area. This implementation provides the most important piece - of logic for \c CircleItem: the code that starts and manages drags. - - The implementation starts by checking if the mouse has been dragged far - enough to eliminate mouse jitter noise. We only want to start a drag if the - mouse has been dragged farther than the application start drag distance. - - Continuing, we create a QDrag object, passing the event - \l{QGraphicsSceneEvent::widget()}{widget} (i.e., the QGraphicsView - viewport) to its constructor. Qt will ensure that this object is deleted at - the right time. We also create a QMimeData instance that can contain our - color or image data, and assign this to the drag object. - - \snippet graphicsview/dragdroprobot/coloritem.cpp 6 - - This snippet has a somewhat random outcome: once in a while, a special - image is assigned to the drag object's mime data. The pixmap is also - assiged as the drag object's pixmap. This will ensure that you can see the - image that is being dragged as a pixmap under the mouse cursor. - - \snippet graphicsview/dragdroprobot/coloritem.cpp 7 - - Otherwise, and this is the most common outcome, a simple color is assigned - to the drag object's mime data. We render this \c ColorItem into a new - pixmap to give the user visual feedback that the color is being "dragged". - - \snippet graphicsview/dragdroprobot/coloritem.cpp 8 - - Finally we execute the drag. QDrag::exec() will reenter the event loop, and - only exit if the drag has either been dropped, or canceled. In any case we - reset the cursor to Qt::OpenHandCursor. - - \section1 The main() Function - - Now that the \c Robot and \c ColorItem classes are complete, we can put all - the pieces together inside the main() function. - - \snippet graphicsview/dragdroprobot/main.cpp 0 - - We start off by constructing QApplication, and initializing the random - number generator. This ensures that the color items have different colors - every time the application starts. - - \snippet graphicsview/dragdroprobot/main.cpp 1 - - We construct a fixed size scene, and create 10 \c ColorItem instances - arranged in a circle. Each item is added to the scene. - - In the center of this circle we create one \c Robot instance. The - robot is scaled and moved up a few units. It is then added to the scene. - - \snippet graphicsview/dragdroprobot/main.cpp 2 - - Finally we create a QGraphicsView window, and assign the scene to it. - - For increased visual quality, we enable antialiasing. We also choose to use - bounding rectangle updates to simplify visual update handling. - The view is given a fixed sand-colored background, and a window title. - - We then show the view. The animations start immediately after - control enters the event loop. -*/ - diff --git a/examples/widgets/doc/dynamiclayouts.qdoc b/examples/widgets/doc/dynamiclayouts.qdoc deleted file mode 100644 index 318f719503..0000000000 --- a/examples/widgets/doc/dynamiclayouts.qdoc +++ /dev/null @@ -1,34 +0,0 @@ -/**************************************************************************** -** -** 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 layouts/dynamiclayouts - \title Dynamic Layouts Example - - The Dynamic Layouts example shows how to move widgets around in - existing layouts. -*/ diff --git a/examples/widgets/doc/easing.qdoc b/examples/widgets/doc/easing.qdoc deleted file mode 100644 index 7fb7f59531..0000000000 --- a/examples/widgets/doc/easing.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** 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 animation/easing - \title Easing Curves Example - - The Easing Curves example shows how to use easing curves to - control the speed of an animation. - - \image easing-example.png - -*/ diff --git a/examples/widgets/doc/editabletreemodel.qdoc b/examples/widgets/doc/editabletreemodel.qdoc deleted file mode 100644 index 24745b77b8..0000000000 --- a/examples/widgets/doc/editabletreemodel.qdoc +++ /dev/null @@ -1,450 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/editabletreemodel - \title Editable Tree Model Example - - This example shows how to implement a simple item-based tree model that can - be used with other classes the model/view framework. - - \image itemviews-editabletreemodel.png - - The model supports editable items, custom headers, and the ability to - insert and remove rows and columns. With these features, it is also - possible to insert new child items, and this is shown in the supporting - example code. - - \note The model only shows the basic principles used when creating an - editable, hierarchical model. You may wish to use the \l{ModelTest} - project to test production models. - - \section1 Overview - - As described in the \l{Model Subclassing Reference}, models must - provide implementations for the standard set of model functions: - \l{QAbstractItemModel::}{flags()}, \l{QAbstractItemModel::}{data()}, - \l{QAbstractItemModel::}{headerData()}, - \l{QAbstractItemModel::}{columnCount()}, and - \l{QAbstractItemModel::}{rowCount()}. In addition, hierarchical models, - such as this one, need to provide implementations of - \l{QAbstractItemModel::}{index()} and \l{QAbstractItemModel::}{parent()}. - - An editable model needs to provide implementations of - \l{QAbstractItemModel::}{setData()} and - \l{QAbstractItemModel::}{setHeaderData()}, and must return a suitable - combination of flags from its \l{QAbstractItemModel::}{flags()} function. - - Since this example allows the dimensions of the model to be changed, - we must also implement \l{QAbstractItemModel::}{insertRows()}, - \l{QAbstractItemModel::}{insertColumns()}, - \l{QAbstractItemModel::}{removeRows()}, and - \l{QAbstractItemModel::}{removeColumns()}. - - \section1 Design - - As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example, - the model simply acts as a wrapper around a collection - of instances of a \c TreeItem class. Each \c TreeItem is designed to - hold data for a row of items in a tree view, so it contains a list of - values corresponding to the data shown in each column. - - Since QTreeView provides a row-oriented view onto a model, it is - natural to choose a row-oriented design for data structures that - will supply data via a model to this kind of view. Although this makes - the tree model less flexible, and possibly less useful for use with - more sophisticated views, it makes it less complex to design and easier - to implement. - - \target Relations-between-internal-items - \table - \row \li \inlineimage itemviews-editabletreemodel-items.png - \li \b{Relations between internal items} - - When designing a data structure for use with a custom model, it is useful - to expose each item's parent via a function like - \l{TreeItem::parent}{TreeItem::parent()} because it will make - writing the model's own \l{QAbstractItemModel::}{parent()} function easier. - Similarly, a function like \l{TreeItem::child}{TreeItem::child()} is - helpful when implementing the model's \l{QAbstractItemModel::}{index()} - function. As a result, each \c TreeItem maintains information about - its parent and children, making it possible for us to traverse the tree - structure. - - The diagram shows how \c TreeItem instances are connected via their - \l{TreeItem::parent}{parent()} and \l{TreeItem::child}{child()} - functions. - - In the example shown, two top-level items, \b{A} and - \b{B}, can be obtained from the root item by calling its child() - function, and each of these items return the root node from their - parent() functions, though this is only shown for item \b{A}. - \endtable - - Each \c TreeItem stores data for each column in the row it represents - in its \c itemData private member (a list of QVariant objects). - Since there is a one-to-one mapping between each column in the view - and each entry in the list, we provide a simple - \l{TreeItem::data}{data()} function to read entries in the \c itemData - list and a \l{TreeItem::setData}{setData()} function to allow them to - be modified. - As with other functions in the item, this simplifies the implemention - of the model's \l{QAbstractItemModel::}{data()} and - \l{QAbstractItemModel::}{setData()} functions. - - We place an item at the root of the tree of items. This root item - corresponds to the null model index, \l{QModelIndex::}{QModelIndex()}, - that is used to represent the parent of a top-level item when handling - model indexes. - Although the root item does not have a visible representation in any of - the standard views, we use its internal list of QVariant objects to - store a list of strings that will be passed to views for use as - horizontal header titles. - - \table - \row \li \inlineimage itemviews-editabletreemodel-model.png - \li \b{Accessing data via the model} - - In the case shown in the diagram, the piece of information represented - by \b{a} can be obtained using the standard model/view API: - - \code - QVariant a = model->index(0, 0, QModelIndex()).data(); - \endcode - - Since each items holds pieces of data for each column in a given row, - there can be many model indexes that map to the same \c TreeItem object. - For example, the information represented by \b{b} can be obtained - using the following code: - - \code - QVariant b = model->index(1, 0, QModelIndex()).data(); - \endcode - - The same underlying \c TreeItem would be accessed to obtain information - for the other model indexes in the same row as \b{b}. - \endtable - - In the model class, \c TreeModel, we relate \c TreeItem objects to - model indexes by passing a pointer for each item when we create its - corresponding model index with QAbstractItemModel::createIndex() in - our \l{TreeModel::index}{index()} and \l{TreeModel::parent}{parent()} - implementations. - We can retrieve pointers stored in this way by calling the - \l{QModelIndex::}{internalPointer()} function on the relevant model - index - we create our own \l{TreeModel::getItem}{getItem()} function to - do this work for us, and call it from our \l{TreeModel::data}{data()} - and \l{TreeModel::parent}{parent()} implementations. - - Storing pointers to items is convenient when we control how they are - created and destroyed since we can assume that an address obtained from - \l{QModelIndex::}{internalPointer()} is a valid pointer. - However, some models need to handle items that are obtained from other - components in a system, and in many cases it is not possible to fully - control how items are created or destroyed. In such situations, a pure - pointer-based approach needs to be supplemented by safeguards to ensure - that the model does not attempt to access items that have been deleted. - - \table - \row \li \b{Storing information in the underlying data structure} - - Several pieces of data are stored as QVariant objects in the \c itemData - member of each \c TreeItem instance - - The diagram shows how pieces of information, - represented by the labels \b{a}, \b{b} and \b{c} in the - previous two diagrams, are stored in items \b{A}, \b{B} and - \b{C} in the underlying data structure. Note that pieces of - information from the same row in the model are all obtained from the - same item. Each element in a list corresponds to a piece of information - exposed by each column in a given row in the model. - - \li \inlineimage itemviews-editabletreemodel-values.png - \endtable - - Since the \c TreeModel implementation has been designed for use with - QTreeView, we have added a restriction on the way it uses \c TreeItem - instances: each item must expose the same number of columns of data. - This makes viewing the model consistent, allowing us to use the root - item to determine the number of columns for any given row, and only - adds the requirement that we create items containing enough data for - the total number of columns. As a result, inserting and removing - columns are time-consuming operations because we need to traverse the - entire tree to modify every item. - - An alternative approach would be to design the \c TreeModel class so - that it truncates or expands the list of data in individual \c TreeItem - instances as items of data are modified. However, this "lazy" resizing - approach would only allow us to insert and remove columns at the end of - each row and would not allow columns to be inserted or removed at - arbitrary positions in each row. - - \target Relating-items-using-model-indexes - \table - \row - \li \inlineimage itemviews-editabletreemodel-indexes.png - \li \b{Relating items using model indexes} - - As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example, - the \c TreeModel needs to be able to take a model index, find the - corresponding \c TreeItem, and return model indexes that correspond to - its parents and children. - - In the diagram, we show how the model's \l{TreeModel::parent}{parent()} - implementation obtains the model index corresponding to the parent of - an item supplied by the caller, using the items shown in a - \l{Relations-between-internal-items}{previous diagram}. - - A pointer to item \b{C} is obtained from the corresponding model index - using the \l{QModelIndex::internalPointer()} function. The pointer was - stored internally in the index when it was created. Since the child - contains a pointer to its parent, we use its \l{TreeItem::parent}{parent()} - function to obtain a pointer to item \b{B}. The parent model index is - created using the QAbstractItemModel::createIndex() function, passing - the pointer to item \b{B} as the internal pointer. - \endtable - - \section1 TreeItem Class Definition - - The \c TreeItem class provides simple items that contain several - pieces of data, and which can provide information about their parent - and child items: - - \snippet itemviews/editabletreemodel/treeitem.h 0 - - We have designed the API to be similar to that provided by - QAbstractItemModel by giving each item functions to return the number - of columns of information, read and write data, and insert and remove - columns. However, we make the relationship between items explicit by - providing functions to deal with "children" rather than "rows". - - Each item contains a list of pointers to child items, a pointer to its - parent item, and a list of QVariant objects that correspond to - information held in columns in a given row in the model. - - \section1 TreeItem Class Implementation - - Each \c TreeItem is constructed with a list of data and an optional - parent item: - - \snippet itemviews/editabletreemodel/treeitem.cpp 0 - - Initially, each item has no children. These are added to the item's - internal \c childItems member using the \c insertChildren() function - described later. - - The destructor ensures that each child added to the item is deleted - when the item itself is deleted: - - \snippet itemviews/editabletreemodel/treeitem.cpp 1 - - \target TreeItem::parent - Since each item stores a pointer to its parent, the \c parent() function - is trivial: - - \snippet itemviews/editabletreemodel/treeitem.cpp 9 - - \target TreeItem::child - Three functions provide information about the children of an item. - \c child() returns a specific child from the internal list of children: - - \snippet itemviews/editabletreemodel/treeitem.cpp 2 - - The \c childCount() function returns the total number of children: - - \snippet itemviews/editabletreemodel/treeitem.cpp 3 - - The \c childNumber() function is used to determine the index of the child - in its parent's list of children. It accesses the parent's \c childItems - member directly to obtain this information: - - \snippet itemviews/editabletreemodel/treeitem.cpp 4 - - The root item has no parent item; for this item, we return zero to be - consistent with the other items. - - The \c columnCount() function simply returns the number of elements in - the internal \c itemData list of QVariant objects: - - \snippet itemviews/editabletreemodel/treeitem.cpp 5 - - \target TreeItem::data - Data is retrieved using the \c data() function, which accesses the - appropriate element in the \c itemData list: - - \snippet itemviews/editabletreemodel/treeitem.cpp 6 - - \target TreeItem::setData - Data is set using the \c setData() function, which only stores values - in the \c itemData list for valid list indexes, corresponding to column - values in the model: - - \snippet itemviews/editabletreemodel/treeitem.cpp 11 - - To make implementation of the model easier, we return true to indicate - whether the data was set successfully, or false if an invalid column - - Editable models often need to be resizable, enabling rows and columns to - be inserted and removed. The insertion of rows beneath a given model index - in the model leads to the insertion of new child items in the corresponding - item, handled by the \c insertChildren() function: - - \snippet itemviews/editabletreemodel/treeitem.cpp 7 - - This ensures that new items are created with the required number of columns - and inserted at a valid position in the internal \c childItems list. - Items are removed with the \c removeChildren() function: - - \snippet itemviews/editabletreemodel/treeitem.cpp 10 - - As discussed above, the functions for inserting and removing columns are - used differently to those for inserting and removing child items because - they are expected to be called on every item in the tree. We do this by - recursively calling this function on each child of the item: - - \snippet itemviews/editabletreemodel/treeitem.cpp 8 - - \section1 TreeModel Class Definition - - The \c TreeModel class provides an implementation of the QAbstractItemModel - class, exposing the necessary interface for a model that can be edited and - resized. - - \snippet itemviews/editabletreemodel/treemodel.h 0 - - The constructor and destructor are specific to this model. - - \snippet itemviews/editabletreemodel/treemodel.h 1 - - Read-only tree models only need to provide the above functions. The - following public functions provide support for editing and resizing: - - \snippet itemviews/editabletreemodel/treemodel.h 2 - - To simplify this example, the data exposed by the model is organized into - a data structure by the model's \l{TreeModel::setupModelData}{setupModelData()} - function. Many real world models will not process the raw data at all, but - simply work with an existing data structure or library API. - - \section1 TreeModel Class Implementation - - The constructor creates a root item and initializes it with the header - data supplied: - - \snippet itemviews/editabletreemodel/treemodel.cpp 0 - - We call the internal \l{TreeModel::setupModelData}{setupModelData()} - function to convert the textual data supplied to a data structure we can - use with the model. Other models may be initialized with a ready-made - data structure, or use an API to a library that maintains its own data. - - The destructor only has to delete the root item; all child items will - be recursively deleted by the \c TreeItem destructor. - - \snippet itemviews/editabletreemodel/treemodel.cpp 1 - - \target TreeModel::getItem - Since the model's interface to the other model/view components is based - on model indexes, and the internal data structure is item-based, many of - the functions implemented by the model need to be able to convert any - given model index to its corresponding item. For convenience and - consistency, we have defined a \c getItem() function to perform this - repetitive task: - - \snippet itemviews/editabletreemodel/treemodel.cpp 4 - - This function assumes that each model index it is passed corresponds to - a valid item in memory. If the index is invalid, or its internal pointer - does not refer to a valid item, the root item is returned instead. - - The model's \c rowCount() implementation is simple: it first uses the - \c getItem() function to obtain the relevant item, then returns the - number of children it contains: - - \snippet itemviews/editabletreemodel/treemodel.cpp 8 - - By contrast, the \c columnCount() implementation does not need to look - for a particular item because all items are defined to have the same - number of columns associated with them. - - \snippet itemviews/editabletreemodel/treemodel.cpp 2 - - As a result, the number of columns can be obtained directly from the root - item. - - To enable items to be edited and selected, the \c flags() function needs - to be implemented so that it returns a combination of flags that includes - the Qt::ItemIsEditable and Qt::ItemIsSelectable flags as well as - Qt::ItemIsEnabled: - - \snippet itemviews/editabletreemodel/treemodel.cpp 3 - - \target TreeModel::index - The model needs to be able to generate model indexes to allow other - components to request data and information about its structure. This task - is performed by the \c index() function, which is used to obtain model - indexes corresponding to children of a given parent item: - - \snippet itemviews/editabletreemodel/treemodel.cpp 5 - - In this model, we only return model indexes for child items if the parent - index is invalid (corresponding to the root item) or if it has a zero - column number. - - We use the custom \l{TreeModel::getItem}{getItem()} function to obtain - a \c TreeItem instance that corresponds to the model index supplied, and - request its child item that corresponds to the specified row. - - \snippet itemviews/editabletreemodel/treemodel.cpp 6 - - Since each item contains information for an entire row of data, we create - a model index to uniquely identify it by calling - \l{QAbstractItemModel::}{createIndex()} it with the row and column numbers - and a pointer to the item. In the \l{TreeModel::data}{data()} function, - we will use the item pointer and column number to access the data - associated with the model index; in this model, the row number is not - needed to identify data. - - \target TreeModel::parent - The \c parent() function supplies model indexes for parents of items - by finding the corresponding item for a given model index, using its - \l{TreeItem::parent}{parent()} function to obtain its parent item, - then creating a model index to represent the parent. (See - \l{Relating-items-using-model-indexes}{the above diagram}). - - \snippet itemviews/editabletreemodel/treemodel.cpp 7 - - Items without parents, including the root item, are handled by returning - a null model index. Otherwise, a model index is created and returned as - in the \l{TreeModel::index}{index()} function, with a suitable row number, - but with a zero column number to be consistent with the scheme used in - the \l{TreeModel::index}{index()} implementation. - - \target TreeModel::data - \target TreeModel::setupModelData - -*/ diff --git a/examples/widgets/doc/elasticnodes.qdoc b/examples/widgets/doc/elasticnodes.qdoc deleted file mode 100644 index 17f14124f8..0000000000 --- a/examples/widgets/doc/elasticnodes.qdoc +++ /dev/null @@ -1,430 +0,0 @@ -/**************************************************************************** -** -** 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 graphicsview/elasticnodes - \title Elastic Nodes Example - - The Elastic Nodes example shows how to implement edges between nodes in a - graph, with basic interaction. You can click to drag a node around, and - zoom in and out using the mouse wheel or the keyboard. Hitting the space - bar will randomize the nodes. The example is also resolution independent; - as you zoom in, the graphics remain crisp. - - \image elasticnodes-example.png - - Graphics View provides the QGraphicsScene class for managing and - interacting with a large number of custom-made 2D graphical items derived - from the QGraphicsItem class, and a QGraphicsView widget for visualizing - the items, with support for zooming and rotation. - - This example consists of a \c Node class, an \c Edge class, a \c - GraphWidget test, and a \c main function: the \c Node class represents - draggable yellow nodes in a grid, the \c Edge class represents the lines - between the nodes, the \c GraphWidget class represents the application - window, and the \c main() function creates and shows this window, and runs - the event loop. - - \section1 Node Class Definition - - The \c Node class serves three purposes: - - \list - \li Painting a yellow gradient "ball" in two states: sunken and raised. - \li Managing connections to other nodes. - \li Calculating forces pulling and pushing the nodes in the grid. - \endlist - - Let's start by looking at the \c Node class declaration. - - \snippet graphicsview/elasticnodes/node.h 0 - - The \c Node class inherits QGraphicsItem, and reimplements the two - mandatory functions \l{QGraphicsItem::boundingRect()}{boundingRect()} and - \l{QGraphicsItem::paint()}{paint()} to provide its visual appearance. It - also reimplements \l{QGraphicsItem::shape()}{shape()} to ensure its hit - area has an elliptic shape (as opposed to the default bounding rectangle). - - For edge management purposes, the node provides a simple API for adding - edges to a node, and for listing all connected edges. - - The \l{QGraphicsItem::advance()}{advance()} reimplementation is called - whenever the scene's state advances by one step. The calculateForces() - function is called to calculate the forces that push and pull on this node - and its neighbors. - - The \c Node class also reimplements - \l{QGraphicsItem::itemChange()}{itemChange()} to react to state changes (in - this case, position changes), and - \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()} and - \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()} to update the - item's visual appearance. - - We will start reviewing the \c Node implementation by looking at its - constructor: - - \snippet graphicsview/elasticnodes/node.cpp 0 - - In the constructor, we set the - \l{QGraphicsItem::ItemIsMovable}{ItemIsMovable} flag to allow the item to - move in response to mouse dragging, and - \l{QGraphicsItem::ItemSendsGeometryChanges}{ItemSendsGeometryChanges} to - enable \l{QGraphicsItem::itemChange()}{itemChange()} notifications for - position and transformation changes. We also enable - \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache} to speed up - rendering performance. To ensure that the nodes are always stacked on top - of edges, we finally set the item's Z value to -1. - - \c Node's constructor takes a \c GraphWidget pointer and stores this as a - member variable. We will revisit this pointer later on. - - \snippet graphicsview/elasticnodes/node.cpp 1 - - The addEdge() function adds the input edge to a list of attached edges. The - edge is then adjusted so that the end points for the edge match the - positions of the source and destination nodes. - - The edges() function simply returns the list of attached edges. - - \snippet graphicsview/elasticnodes/node.cpp 2 - - There are two ways to move a node. The \c calculateForces() function - implements the elastic effect that pulls and pushes on nodes in the grid. - In addition, the user can directly move one node around with the mouse. - Because we do not want the two approaches to operate at the same time on - the same node, we start \c calculateForces() by checking if this \c Node is - the current mouse grabber item (i.e., QGraphicsScene::mouseGrabberItem()). - Because we need to find all neighboring (but not necessarily connected) - nodes, we also make sure the item is part of a scene in the first place. - - \snippet graphicsview/elasticnodes/node.cpp 3 - - The "elastic" effect comes from an algorithm that applies pushing and - pulling forces. The effect is impressive, and surprisingly simple to - implement. - - The algorithm has two steps: the first is to calculate the forces that push - the nodes apart, and the second is to subtract the forces that pull the - nodes together. First we need to find all the nodes in the graph. We call - QGraphicsScene::items() to find all items in the scene, and then use - qgraphicsitem_cast() to look for \c Node instances. - - We make use of \l{QGraphicsItem::mapFromItem()}{mapFromItem()} to create a - temporary vector pointing from this node to each other node, in \l{The - Graphics View Coordinate System}{local coordinates}. We use the decomposed - components of this vector to determine the direction and strength of force - that should apply to the node. The forces accumulate for each node, and are - then adjusted so that the closest nodes are given the strongest force, with - rapid degradation when distance increases. The sum of all forces is stored - in \c xvel (X-velocity) and \c yvel (Y-velocity). - - \snippet graphicsview/elasticnodes/node.cpp 4 - - The edges between the nodes represent forces that pull the nodes together. - By visiting each edge that is connected to this node, we can use a similar - approach as above to find the direction and strength of all pulling forces. - These forces are subtracted from \c xvel and \c yvel. - - \snippet graphicsview/elasticnodes/node.cpp 5 - - In theory, the sum of pushing and pulling forces should stabilize to - precisely 0. In practice, however, they never do. To circumvent errors in - numerical precision, we simply force the sum of forces to be 0 when they - are less than 0.1. - - \snippet graphicsview/elasticnodes/node.cpp 6 - - The final step of \c calculateForces() determines the node's new position. - We add the force to the node's current position. We also make sure the new - position stays inside of our defined boundaries. We don't actually move the - item in this function; that's done in a separate step, from \c advance(). - - \snippet graphicsview/elasticnodes/node.cpp 7 - - The \c advance() function updates the item's current position. It is called - from \c GraphWidget::timerEvent(). If the node's position changed, the - function returns true; otherwise false is returned. - - \snippet graphicsview/elasticnodes/node.cpp 8 - - The \c Node's bounding rectangle is a 20x20 sized rectangle centered around - its origin (0, 0), adjusted by 2 units in all directions to compensate for - the node's outline stroke, and by 3 units down and to the right to make - room for a simple drop shadow. - - \snippet graphicsview/elasticnodes/node.cpp 9 - - The shape is a simple ellipse. This ensures that you must click inside the - node's elliptic shape in order to drag it around. You can test this effect - by running the example, and zooming far in so that the nodes are very - large. Without reimplementing \l{QGraphicsItem::shape()}{shape()}, the - item's hit area would be identical to its bounding rectangle (i.e., - rectangular). - - \snippet graphicsview/elasticnodes/node.cpp 10 - - This function implements the node's painting. We start by drawing a simple - dark gray elliptic drop shadow at (-7, -7), that is, (3, 3) units down and - to the right from the top-left corner (-10, -10) of the ellipse. - - We then draw an ellipse with a radial gradient fill. This fill is either - Qt::yellow to Qt::darkYellow when raised, or the opposite when sunken. In - sunken state we also shift the center and focal point by (3, 3) to - emphasize the impression that something has been pushed down. - - Drawing filled ellipses with gradients can be quite slow, especially when - using complex gradients such as QRadialGradient. This is why this example - uses \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache}, a - simple yet effective measure that prevents unnecessary redrawing. - - \snippet graphicsview/elasticnodes/node.cpp 11 - - We reimplement \l{QGraphicsItem::itemChange()}{itemChange()} to adjust the - position of all connected edges, and to notify the scene that an item has - moved (i.e., "something has happened"). This will trigger new force - calculations. - - This notification is the only reason why the nodes need to keep a pointer - back to the \c GraphWidget. Another approach could be to provide such - notification using a signal; in such case, \c Node would need to inherit - from QGraphicsObject. - - \snippet graphicsview/elasticnodes/node.cpp 12 - - Because we have set the \l{QGraphicsItem::ItemIsMovable}{ItemIsMovable} - flag, we don't need to implement the logic that moves the node according to - mouse input; this is already provided for us. We still need to reimplement - the mouse press and release handlers, though, to update the nodes' visual - appearance (i.e., sunken or raised). - - \section1 Edge Class Definition - - The \c Edge class represents the arrow-lines between the nodes in this - example. The class is very simple: it maintains a source- and destination - node pointer, and provides an \c adjust() function that makes sure the line - starts at the position of the source, and ends at the position of the - destination. The edges are the only items that change continuously as - forces pull and push on the nodes. - - Let's take a look at the class declaration: - - \snippet graphicsview/elasticnodes/edge.h 0 - - \c Edge inherits from QGraphicsItem, as it's a simple class that has no use - for signals, slots, and properties (compare to QGraphicsObject). - - The constructor takes two node pointers as input. Both pointers are - mandatory in this example. We also provide get-functions for each node. - - The \c adjust() function repositions the edge, and the item also implements - \l{QGraphicsItem::boundingRect()}{boundingRect()} and - \l{QGraphicsItem::paint()}{paint()}. - - We will now review its implementation. - - \snippet graphicsview/elasticnodes/edge.cpp 0 - - The \c Edge constructor initializes its \c arrowSize data member to 10 units; - this determines the size of the arrow which is drawn in - \l{QGraphicsItem::paint()}{paint()}. - - In the constructor body, we call - \l{QGraphicsItem::setAcceptedMouseButtons()}{setAcceptedMouseButtons(0)}. - This ensures that the edge items are not considered for mouse input at all - (i.e., you cannot click the edges). Then, the source and destination - pointers are updated, this edge is registered with each node, and we call - \c adjust() to update this edge's start end end position. - - \snippet graphicsview/elasticnodes/edge.cpp 1 - - The source and destination get-functions simply return the respective - pointers. - - \snippet graphicsview/elasticnodes/edge.cpp 2 - - In \c adjust(), we define two points: \c sourcePoint, and \c destPoint, - pointing at the source and destination nodes' origins respectively. Each - point is calculated using \l{The Graphics View Coordinate System}{local - coordinates}. - - We want the tip of the edge's arrows to point to the exact outline of the - nodes, as opposed to the center of the nodes. To find this point, we first - decompose the vector pointing from the center of the source to the center - of the destination node into X and Y, and then normalize the components by - dividing by the length of the vector. This gives us an X and Y unit delta - that, when multiplied by the radius of the node (which is 10), gives us the - offset that must be added to one point of the edge, and subtracted from the - other. - - If the length of the vector is less than 20 (i.e., if two nodes overlap), - then we fix the source and destination pointer at the center of the source - node. In practice this case is very hard to reproduce manually, as the - forces between the two nodes is then at its maximum. - - It's important to notice that we call - \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()} in this - function. The reason is that the variables \c sourcePoint and \c destPoint - are used directly when painting, and they are returned from the - \l{QGraphicsItem::boundingRect()}{boundingRect()} reimplementation. We must - always call - \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()} before - changing what \l{QGraphicsItem::boundingRect()}{boundingRect()} returns, - and before these variables can be used by - \l{QGraphicsItem::paint()}{paint()}, to keep Graphics View's internal - bookkeeping clean. It's safest to call this function once, immediately - before any such variable is modified. - - \snippet graphicsview/elasticnodes/edge.cpp 3 - - The edge's bounding rectangle is defined as the smallest rectangle that - includes both the start and the end point of the edge. Because we draw an - arrow on each edge, we also need to compensate by adjusting with half the - arrow size and half the pen width in all directions. The pen is used to - draw the outline of the arrow, and we can assume that half of the outline - can be drawn outside of the arrow's area, and half will be drawn inside. - - \snippet graphicsview/elasticnodes/edge.cpp 4 - - We start the reimplementation of \l{QGraphicsItem::paint()}{paint()} by - checking a few preconditions. Firstly, if either the source or destination - node is not set, then we return immediately; there is nothing to draw. - - At the same time, we check if the length of the edge is approximately 0, - and if it is, then we also return. - - \snippet graphicsview/elasticnodes/edge.cpp 5 - - We draw the line using a pen that has round joins and caps. If you run the - example, zoom in and study the edge in detail, you will see that there are - no sharp/square edges. - - \snippet graphicsview/elasticnodes/edge.cpp 6 - - We proceed to drawing one arrow at each end of the edge. Each arrow is - drawn as a polygon with a black fill. The coordinates for the arrow are - determined using simple trigonometry. - - \section1 GraphWidget Class Definition - - \c GraphWidget is a subclass of QGraphicsView, which provides the main - window with scrollbars. - - \snippet graphicsview/elasticnodes/graphwidget.h 0 - - The class provides a basic constructor that initializes the scene, an \c - itemMoved() function to notify changes in the scene's node graph, a few - event handlers, a reimplementation of - \l{QGraphicsView::drawBackground()}{drawBackground()}, and a helper - function for scaling the view by using the mouse wheel or keyboard. - - \snippet graphicsview/elasticnodes/graphwidget.cpp 0 - - \c GraphicsWidget's constructor creates the scene, and because most items - move around most of the time, it sets QGraphicsScene::NoIndex. The scene - then gets a fixed \l{QGraphicsScene::sceneRect}{scene rectangle}, and is - assigned to the \c GraphWidget view. - - The view enables QGraphicsView::CacheBackground to cache rendering of its - static, and somewhat complex, background. Because the graph renders a close - collection of small items that all move around, it's unnecessary for - Graphics View to waste time finding accurate update regions, so we set the - QGraphicsView::BoundingRectViewportUpdate viewport update mode. The default - would work fine, but this mode is noticably faster for this example. - - To improve rendering quality, we set QPainter::Antialiasing. - - The transformation anchor decides how the view should scroll when you - transform the view, or in our case, when we zoom in or out. We have chosen - QGraphicsView::AnchorUnderMouse, which centers the view on the point under - the mouse cursor. This makes it easy to zoom towards a point in the scene - by moving the mouse over it, and then rolling the mouse wheel. - - Finally we give the window a minimum size that matches the scene's default - size, and set a suitable window title. - - \snippet graphicsview/elasticnodes/graphwidget.cpp 1 - - The last part of the constructor creates the grid of nodes and edges, and - gives each node an initial position. - - \snippet graphicsview/elasticnodes/graphwidget.cpp 2 - - \c GraphWidget is notified of node movement through this \c itemMoved() - function. Its job is simply to restart the main timer in case it's not - running already. The timer is designed to stop when the graph stabilizes, - and start once it's unstable again. - - \snippet graphicsview/elasticnodes/graphwidget.cpp 3 - - This is \c GraphWidget's key event handler. The arrow keys move the center - node around, the '+' and '-' keys zoom in and out by calling \c - scaleView(), and the enter and space keys randomize the positions of the - nodes. All other key events (e.g., page up and page down) are handled by - QGraphicsView's default implementation. - - \snippet graphicsview/elasticnodes/graphwidget.cpp 4 - - The timer event handler's job is to run the whole force calculation - machinery as a smooth animation. Each time the timer is triggered, the - handler will find all nodes in the scene, and call \c - Node::calculateForces() on each node, one at a time. Then, in a final step - it will call \c Node::advance() to move all nodes to their new positions. - By checking the return value of \c advance(), we can decide if the grid - stabilized (i.e., no nodes moved). If so, we can stop the timer. - - \snippet graphicsview/elasticnodes/graphwidget.cpp 5 - - In the wheel event handler, we convert the mouse wheel delta to a scale - factor, and pass this factor to \c scaleView(). This approach takes into - account the speed that the wheel is rolled. The faster you roll the mouse - wheel, the faster the view will zoom. - - \snippet graphicsview/elasticnodes/graphwidget.cpp 6 - - The view's background is rendered in a reimplementation of - QGraphicsView::drawBackground(). We draw a large rectangle filled with a - linear gradient, add a drop shadow, and then render text on top. The text - is rendered twice for a simple drop-shadow effect. - - This background rendering is quite expensive; this is why the view enables - QGraphicsView::CacheBackground. - - \snippet graphicsview/elasticnodes/graphwidget.cpp 7 - - The \c scaleView() helper function checks that the scale factor stays - within certain limits (i.e., you cannot zoom too far in nor too far out), - and then applies this scale to the view. - - \section1 The main() Function - - In contrast to the complexity of the rest of this example, the \c main() - function is very simple: We create a QApplication instance, seed the - randomizer using qsrand(), and then create and show an instance of \c - GraphWidget. Because all nodes in the grid are moved initially, the \c - GraphWidget timer will start immediately after control has returned to the - event loop. -*/ diff --git a/examples/widgets/doc/elidedlabel.qdoc b/examples/widgets/doc/elidedlabel.qdoc deleted file mode 100644 index 2ce469d85f..0000000000 --- a/examples/widgets/doc/elidedlabel.qdoc +++ /dev/null @@ -1,162 +0,0 @@ -/**************************************************************************** -** -** 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/elidedlabel - \group all-examples - \title Elided Label Example - - This example creates a widget similar to QLabel, that elides the last - visible line, if the text is too long to fit the widget's geometry. - - \image elidedlabel-example.png Elided Label example on XPressMusic 5800 - - When text of varying length has to be displayed in a uniformly sized - area, for instance within a list or grid view where all list items have the - same size, it can be useful to give the user a visual clue when not all - text is visible. QLabel can elide text that doesn't fit within it, but only - in one line. The \c ElidedLabel widget shown in this example word wraps its - text by its width, and elides the last visible line if some text is left - out. \c TestWidget gives control to the features of \c ElidedWidget and - forms the example application. - - - \section1 ElidedLabel Class Definition - - Like QLabel, \c ElidedLabel inherits from QFrame. Here's the definition of - the \c ElidedLabel class: - - - \snippet widgets/elidedlabel/elidedlabel.h 0 - - The \c isElided property depends the font, text content and geometry of the - widget. Whenever any of these change, the \c elisionChanged() signal might - trigger. We cache the current elision value in \c elided, so that it - doesn't have to be recomputed every time it's asked for. - - - \section1 ElidedLabel Class Implementation - - Except for initializing the member variables, the constructor sets the size - policy to be horizontally expanding, since it's meant to fill the width of - its container and grow vertically. - - \snippet widgets/elidedlabel/elidedlabel.cpp 0 - - Changing the \c content require a repaint of the widget. - - \snippet widgets/elidedlabel/elidedlabel.cpp 1 - - QTextLayout is used in the \c paintEvent() to divide the \c content into - lines, that wrap on word boundaries. Each line, except the last visible - one, is drawn \c lineSpacing pixels below the previous one. The \c draw() - method of QTextLine will draw the line using the coordinate point as the - top left corner. - - \snippet widgets/elidedlabel/elidedlabel.cpp 2 - - Unfortunately, QTextLayout does not elide text, so the last visible line - has to be treated differently. This last line is elided if it is too wide. - The \c drawText() method of QPainter draws the text starting from the base - line, which is \c ascecnt() pixels below the last drawn line. - - Finally, one more line is created to see if everything fit on this line. - - \snippet widgets/elidedlabel/elidedlabel.cpp 3 - - If the text was elided and wasn't before or vice versa, cache it in - \c elided and emit the change. - - \snippet widgets/elidedlabel/elidedlabel.cpp 4 - - - \section1 TestWidget Class Definition - - \c TestWidget is a QWidget and is the main window of the example. It - contains an \c ElidedLabel which can be resized with two QSlider widgets. - - \snippet widgets/elidedlabel/testwidget.h 0 - - \section1 TestWidget Class Implementation - - The constructor initializes the whole widget. Strings of different length - are stored in \c textSamples. The user is able to switch between these. - - \snippet widgets/elidedlabel/testwidget.cpp 0 - - An \c ElidedLabel is created to contain the first of the sample strings. - The frame is made visible to make it easier to see the actual size of the - widget. - - \snippet widgets/elidedlabel/testwidget.cpp 1 - - The buttons and the elision label are created. By connecting the - \c elisionChanged() signal to the \c setVisible() slot of the \c label, - it will act as an indicator to when the text is elided or not. This signal - could, for instance, be used to make a "More" button visible, or similar. - - \snippet widgets/elidedlabel/testwidget.cpp 2 - - The \c widthSlider and \c heightSlider specify the size of the - \c elidedText. Since the y-axis is inverted, the \c heightSlider has to be - inverted to act appropriately. - - \snippet widgets/elidedlabel/testwidget.cpp 3 - - The components are all stored in a QGridLayout, which is made the layout of - the \c TestWidget. - - \snippet widgets/elidedlabel/testwidget.cpp 4 - - On the Maemo platform, windows are stuck in landscape mode by default. With - this attribute set, the window manager is aware that this window can be - rotated. - - \snippet widgets/elidedlabel/testwidget.cpp 5 - - The \c widthSlider and \c heightSlider have the exact same length as the - dimensions of the \c elidedText. The maximum value for both of them is - thus their lengths, and each tick indicates one pixel. - - \snippet widgets/elidedlabel/testwidget.cpp 6 - - The \c switchText() slot simply cycles through all the available sample - texts. - - \snippet widgets/elidedlabel/testwidget.cpp 7 - - These slots set the width and height of the \c elided text, in response to - changes in the sliders. - - \section1 The \c main() Function - - The \c main() function creates an instance of \c TestWidget fullscreen and - enters the message loop. - - \snippet widgets/elidedlabel/main.cpp 0 -*/ - diff --git a/examples/widgets/doc/embeddeddialogs.qdoc b/examples/widgets/doc/embeddeddialogs.qdoc deleted file mode 100644 index 24b3abdb37..0000000000 --- a/examples/widgets/doc/embeddeddialogs.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** 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 graphicsview/embeddeddialogs - \title Embedded Dialogs - - This example shows how to embed standard dialogs into - Graphics View. It also shows how you can customize the - proxy class and add window shadows. - - \image embeddeddialogs-demo.png -*/ diff --git a/examples/widgets/doc/eventtransitions.qdoc b/examples/widgets/doc/eventtransitions.qdoc deleted file mode 100644 index ef3f657c3d..0000000000 --- a/examples/widgets/doc/eventtransitions.qdoc +++ /dev/null @@ -1,72 +0,0 @@ -/**************************************************************************** -** -** 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 statemachine/eventtransitions - \title Event Transitions Example - - The Event Transitions example shows how to use event transitions, a - feature of \l{The State Machine Framework}. - - \snippet statemachine/eventtransitions/main.cpp 0 - - The \c Window class's constructors begins by creating a button. - - \snippet statemachine/eventtransitions/main.cpp 1 - - Two states, \c s1 and \c s2, are created; upon entry they will assign - "Outside" and "Inside" to the button's text, respectively. - - \snippet statemachine/eventtransitions/main.cpp 2 - - When the button receives an event of type QEvent::Enter and the state - machine is in state \c s1, the machine will transition to state \c s2. - - \snippet statemachine/eventtransitions/main.cpp 3 - - When the button receives an event of type QEvent::Leave and the state - machine is in state \c s2, the machine will transition back to state \c - s1. - - \snippet statemachine/eventtransitions/main.cpp 4 - - Next, the state \c s3 is created. \c s3 will be entered when the button - receives an event of type QEvent::MouseButtonPress and the state machine - is in state \c s2. When the button receives an event of type - QEvent::MouseButtonRelease and the state machine is in state \c s3, the - machine will transition back to state \c s2. - - \snippet statemachine/eventtransitions/main.cpp 5 - - Finally, the states are added to the machine as top-level states, the - initial state is set to be \c s1 ("Outside"), and the machine is started. - - \snippet statemachine/eventtransitions/main.cpp 6 - - The main() function constructs a Window object and shows it. - -*/ diff --git a/examples/widgets/doc/extension.qdoc b/examples/widgets/doc/extension.qdoc deleted file mode 100644 index 040d5d38d9..0000000000 --- a/examples/widgets/doc/extension.qdoc +++ /dev/null @@ -1,138 +0,0 @@ -/**************************************************************************** -** -** 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 dialogs/extension - \title Extension Example - - The Extension example shows how to add an extension to a QDialog - using the QAbstractButton::toggled() signal and the - QWidget::setVisible() slot. - - \image extension-example.png Screenshot of the Extension example - - The Extension application is a dialog that allows the user to - perform a simple search as well as a more advanced search. - - The simple search has two options: \uicontrol {Match case} and \uicontrol - {Search from start}. The advanced search options include the - possibilities to search for \uicontrol {Whole words}, \uicontrol {Search - backward} and \uicontrol {Search selection}. Only the simple search is - visible when the application starts. The advanced search options - are located in the application's extension part, and can be made - visible by pressing the \uicontrol More button: - - \image extension_more.png Screenshot of the Extension example - - \section1 FindDialog Class Definition - - The \c FindDialog class inherits QDialog. The QDialog class is the - base class of dialog windows. A dialog window is a top-level - window mostly used for short-term tasks and brief communications - with the user. - - \snippet dialogs/extension/finddialog.h 0 - - The \c FindDialog widget is the main application widget, and - displays the application's search options and controlling - buttons. - - In addition to a constructor, we declare the several child - widgets: We need a QLineEdit with an associated QLabel to let the - user type a word to search for, we need several \l - {QCheckBox}{QCheckBox}es to facilitate the search options, and we - need three \l {QPushButton}{QPushButton}s: the \uicontrol Find button to - start a search and the \uicontrol More button to enable an advanced search. - Finally, we need a QWidget representing the application's extension - part. - - \section1 FindDialog Class Implementation - - In the constructor we first create the standard child widgets for - the simple search: the QLineEdit with the associated QLabel, two - of the \l {QCheckBox}{QCheckBox}es and all the \l - {QPushButton}{QPushButton}s. - - \snippet dialogs/extension/finddialog.cpp 0 - - We give the options and buttons a shortcut key using the & - character. In the \uicontrol {Find what} option's case, we also need to - use the QLabel::setBuddy() function to make the shortcut key work - as expected; then, when the user presses the shortcut key - indicated by the label, the keyboard focus is transferred to the - label's buddy widget, the QLineEdit. - - We set the \uicontrol Find button's default property to true, using the - QPushButton::setDefault() function. Then the push button will be - pressed if the user presses the Enter (or Return) key. Note that a - QDialog can only have one default button. - - \snippet dialogs/extension/finddialog.cpp 2 - - Then we create the extension widget, and the \l - {QCheckBox}{QCheckBox}es associated with the advanced search - options. - - \snippet dialogs/extension/finddialog.cpp 3 - - Now that the extension widget is created, we can connect the \uicontrol - More button's \l{QAbstractButton::toggled()}{toggled()} signal to - the extension widget's \l{QWidget::setVisible()}{setVisible()} slot. - - The QAbstractButton::toggled() signal is emitted whenever a - checkable button changes its state. The signal's argument is true - if the button is checked, or false if the button is unchecked. The - QWidget::setVisible() slot sets the widget's visible status. If - the status is true the widget is shown, otherwise the widget is - hidden. - - Since we made the \uicontrol More button checkable when we created it, - the connection makes sure that the extension widget is shown - depending on the state of \uicontrol More button. - - We also put the check boxes associated with the advanced - search options into a layout we install on the extension widget. - - \snippet dialogs/extension/finddialog.cpp 4 - - Before we create the main layout, we create several child layouts - for the widgets: First we align the QLabel and its buddy, the - QLineEdit, using a QHBoxLayout. Then we vertically align the - QLabel and QLineEdit with the check boxes associated with the - simple search, using a QVBoxLayout. We also create a QVBoxLayout - for the buttons. In the end we lay out the two latter layouts and - the extension widget using a QGridLayout. - - \snippet dialogs/extension/finddialog.cpp 5 - - Finally, we hide the extension widget using the QWidget::hide() - function, making the application only show the simple search - options when it starts. When the user wants to access the advanced - search options, the dialog only needs to change the visibility of - the extension widget. Qt's layout management takes care of the - dialog's appearance. -*/ diff --git a/examples/widgets/doc/factorial.qdoc b/examples/widgets/doc/factorial.qdoc deleted file mode 100644 index 82ab5da536..0000000000 --- a/examples/widgets/doc/factorial.qdoc +++ /dev/null @@ -1,88 +0,0 @@ -/**************************************************************************** -** -** 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 statemachine/factorial - \title Factorial States Example - - The Factorial States example shows how to use \l{The State Machine - Framework} to calculate the factorial of an integer. - - The statechart for calculating the factorial looks as follows: - - \image factorial-example.png - \omit - \caption This is a caption - \endomit - - In other words, the state machine calculates the factorial of 6 and prints - the result. - - \snippet statemachine/factorial/main.cpp 0 - - The Factorial class is used to hold the data of the computation, \c x and - \c fac. It also provides a signal that's emitted whenever the value of \c - x changes. - - \snippet statemachine/factorial/main.cpp 1 - - The FactorialLoopTransition class implements the guard (\c x > 1) and - calculations (\c fac = \c x * \c fac; \c x = \c x - 1) of the factorial - loop. - - \snippet statemachine/factorial/main.cpp 2 - - The FactorialDoneTransition class implements the guard (\c x <= 1) that - terminates the factorial computation. It also prints the final result to - standard output. - - \snippet statemachine/factorial/main.cpp 3 - - The application's main() function first creates the application object, a - Factorial object and a state machine. - - \snippet statemachine/factorial/main.cpp 4 - - The \c compute state is created, and the initial values of \c x and \c fac - are defined. A FactorialLoopTransition object is created and added to the - state. - - \snippet statemachine/factorial/main.cpp 5 - - A final state, \c done, is created, and a FactorialDoneTransition object - is created with \c done as its target state. The transition is then added - to the \c compute state. - - \snippet statemachine/factorial/main.cpp 6 - - The machine's initial state is set to be the \c compute state. We connect - the QStateMachine::finished() signal to the QCoreApplication::quit() slot, - so the application will quit when the state machine's work is - done. Finally, the state machine is started, and the application's event - loop is entered. - - */ diff --git a/examples/widgets/doc/fademessage.qdoc b/examples/widgets/doc/fademessage.qdoc deleted file mode 100644 index 48f98c03ad..0000000000 --- a/examples/widgets/doc/fademessage.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** 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 effects/fademessage - \title Fade Message Effect Example - - \div { style="text-align: center"} - \inlineimage fademessageeffect-example.png - \inlineimage fademessageeffect-example-faded.png - \enddiv - -*/ diff --git a/examples/widgets/doc/fetchmore.qdoc b/examples/widgets/doc/fetchmore.qdoc deleted file mode 100644 index 7ea0b30edf..0000000000 --- a/examples/widgets/doc/fetchmore.qdoc +++ /dev/null @@ -1,111 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/fetchmore - \title Fetch More Example - - The Fetch More example shows how two add items to an item view - model on demand. - - \image fetchmore-example.png - - The user of the example can enter a directory in the \uicontrol - Directory line edit. The contents of the directory will - be listed in the list view below. - - When you have large - or perhaps even infinite - data sets, you - will need to add items to the model in batches, and preferably only - when the items are needed by the view (i.e., when they are visible - in the view). - - In this example, we implement \c FileListModel - an item view - model containing the entries of a directory. We also have \c - Window, which sets up the GUI and feeds the model with - directories. - - Let's take a tour of \c {FileListModel}'s code. - - \section1 FileListModel Class Definition - - The \c FileListModel inherits QAbstractListModel and contains the - contents of a directory. It will add items to itself only when - requested to do so by the view. - - \snippet itemviews/fetchmore/filelistmodel.h 0 - - The secret lies in the reimplementation of - \l{QAbstractItemModel::}{fetchMore()} and - \l{QAbstractItemModel::}{canFetchMore()} from QAbstractItemModel. - These functions are called by the item view when it needs more - items. - - The \c setDirPath() function sets the directory the model will - work on. We emit \c numberPopulated() each time we add a batch of - items to the model. - - We keep all directory entries in \c fileList. \c fileCount is the - number of items that have been added to the model. - - \section1 FileListModel Class Implementation - - We start by checking out the \c setDirPath(). - - \snippet itemviews/fetchmore/filelistmodel.cpp 0 - - We use a QDir to get the contents of the directory. We need to - inform QAbstractItemModel that we want to remove all items - if - any - from the model. - - \snippet itemviews/fetchmore/filelistmodel.cpp 1 - - The \c canFetchMore() function is called by the view when it needs - more items. We return true if there still are entries that we have - not added to the model; otherwise, we return false. - - And now, the \c fetchMore() function itself: - - \snippet itemviews/fetchmore/filelistmodel.cpp 2 - - We first calculate the number of items to fetch. - \l{QAbstractItemModel::}{beginInsertRows()} and - \l{QAbstractItemModel::}{endInsertRows()} are mandatory for - QAbstractItemModel to keep up with the row insertions. Finally, we - emit \c numberPopulated(), which is picked up by \c Window. - - To complete the tour, we also look at \c rowCount() and \c data(). - - \snippet itemviews/fetchmore/filelistmodel.cpp 4 - - Notice that the row count is only the items we have added so far, - i.e., not the number of entries in the directory. - - In \c data(), we return the appropriate entry from the \c - fileList. We also separate the batches with a different background - color. -*/ - diff --git a/examples/widgets/doc/findfiles.qdoc b/examples/widgets/doc/findfiles.qdoc deleted file mode 100644 index 594d57472c..0000000000 --- a/examples/widgets/doc/findfiles.qdoc +++ /dev/null @@ -1,249 +0,0 @@ -/**************************************************************************** -** -** 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 dialogs/findfiles - \title Find Files Example - - The Find Files example shows how to use QProgressDialog to provide - feedback on the progress of a slow operation. The example also - shows how to use QFileDialog to facilitate browsing, how to use - QTextStream's streaming operators to read a file, and how to use - QTableWidget to provide standard table display facilities for - applications. In addition, files can be opened using the - QDesktopServices class. - - \image findfiles-example.png Screenshot of the Find Files example - - With the Find Files application the user can search for files in a - specified directory, matching a specified file name (using wild - cards if appropriate) and containing a specified text. - - The user is provided with a \uicontrol Browse option, and the result of - the search is displayed in a table with the names of the files - found and their sizes. In addition the application provides a - total count of the files found. - - \section1 Window Class Definition - - The \c Window class inherits QWidget, and is the main application - widget. It shows the search options, and displays the search - results. - - \snippet dialogs/findfiles/window.h 0 - - We need two private slots: The \c browse() slot is called whenever - the user wants to browse for a directory to search in, and the \c - find() slot is called whenever the user requests a search to be - performed by pressing the \uicontrol Find button. - - In addition we declare several private functions: We use the \c - findFiles() function to search for files matching the user's - specifications, we call the \c showFiles() function to display the - results, and we use \c createButton(), \c createComboBox() and \c - createFilesTable() when we are constructing the widget. - - \section1 Window Class Implementation - - In the constructor we first create the application's widgets. - - \snippet dialogs/findfiles/window.cpp 0 - - We create the application's buttons using the private \c - createButton() function. Then we create the comboboxes associated - with the search specifications, using the private \c - createComboBox() function. We also create the application's labels - before we use the private \c createFilesTable() function to create - the table displaying the search results. - - \snippet dialogs/findfiles/window.cpp 1 - - Then we add all the widgets to a main layout using QGridLayout. We - have, however, put the \c Find and \c Quit buttons and a - stretchable space in a separate QHBoxLayout first, to make the - buttons appear in the \c Window widget's bottom right corner. - - \snippet dialogs/findfiles/window.cpp 2 - - The \c browse() slot presents a file dialog to the user, using the - QFileDialog class. QFileDialog enables a user to traverse the file - system in order to select one or many files or a directory. The - easiest way to create a QFileDialog is to use the convenience - static functions. - - Here we use the static QFileDialog::getExistingDirectory() - function which returns an existing directory selected by the - user. Then we display the directory in the directory combobox - using the QComboBox::addItem() function, and updates the current - index. - - QComboBox::addItem() adds an item to the combobox with the given - text (if it is not already present in the list), and containing - the specified userData. The item is appended to the list of - existing items. - - \snippet dialogs/findfiles/window.cpp 3 - - The \c find() slot is called whenever the user requests a new - search by pressing the \uicontrol Find button. - - First we eliminate any previous search results by setting the - table widgets row count to zero. Then we retrieve the - specified file name, text and directory path from the respective - comboboxes. - - \snippet dialogs/findfiles/window.cpp 4 - - We use the directory's path to create a QDir; the QDir class - provides access to directory structures and their contents. We - create a list of the files (contained in the newly created QDir) - that match the specified file name. If the file name is empty - the list will contain all the files in the directory. - - Then we search through all the files in the list, using the private - \c findFiles() function, eliminating the ones that don't contain - the specified text. And finally, we display the results using the - private \c showFiles() function. - - If the user didn't specify any text, there is no reason to search - through the files, and we display the results immediately. - - \image findfiles_progress_dialog.png Screenshot of the Progress Dialog - - \snippet dialogs/findfiles/window.cpp 5 - - In the private \c findFiles() function we search through a list of - files, looking for the ones that contain a specified text. This - can be a very slow operation depending on the number of files as - well as their sizes. In case there are a large number of files, or - there exists some large files on the list, we provide a - QProgressDialog. - - The QProgressDialog class provides feedback on the progress of a - slow operation. It is used to give the user an indication of how - long an operation is going to take, and to demonstrate that the - application has not frozen. It can also give the user an - opportunity to abort the operation. - - \snippet dialogs/findfiles/window.cpp 6 - - We run through the files, one at a time, and for each file we - update the QProgressDialog value. This property holds the current - amount of progress made. We also update the progress dialog's - label. - - Then we call the QCoreApplication::processEvents() function using - the QApplication object. In this way we interleave the display of - the progress made with the process of searching through the files - so the application doesn't appear to be frozen. - - The QApplication class manages the GUI application's control flow - and main settings. It contains the main event loop, where all - events from the window system and other sources are processed and - dispatched. QApplication inherits QCoreApplication. The - QCoreApplication::processEvents() function processes all pending - events according to the specified QEventLoop::ProcessEventFlags - until there are no more events to process. The default flags are - QEventLoop::AllEvents. - - \snippet dialogs/findfiles/window.cpp 7 - - After updating the QProgressDialog, we create a QFile using the - QDir::absoluteFilePath() function which returns the absolute path - name of a file in the directory. We open the file in read-only - mode, and read one line at a time using QTextStream. - - The QTextStream class provides a convenient interface for reading - and writing text. Using QTextStream's streaming operators, you can - conveniently read and write words, lines and numbers. - - For each line we read we check if the QProgressDialog has been - canceled. If it has, we abort the operation, otherwise we check if - the line contains the specified text. When we find the text within - one of the files, we add the file's name to a list of found files - that contain the specified text, and start searching a new file. - - Finally, we return the list of the files found. - - \snippet dialogs/findfiles/window.cpp 8 - - Both the \c findFiles() and \c showFiles() functions are called from - the \c find() slot. In the \c showFiles() function we run through - the provided list of file names, adding each file name to the - first column in the table widget and retrieving the file's size using - QFile and QFileInfo for the second column. - - We also update the total number of files found. - - \snippet dialogs/findfiles/window.cpp 9 - - The private \c createButton() function is called from the - constructor. We create a QPushButton with the provided text, - connect it to the provided slot, and return a pointer to the - button. - - \snippet dialogs/findfiles/window.cpp 10 - - The private \c createComboBox() function is also called from the - contructor. We create a QComboBox with the given text, and make it - editable. - - When the user enters a new string in an editable combobox, the - widget may or may not insert it, and it can insert it in several - locations, depending on the QComboBox::InsertPolicy. The default - policy is is QComboBox::InsertAtBottom. - - Then we add the provided text to the combobox, and specify the - widget's size policies, before we return a pointer to the - combobox. - - \snippet dialogs/findfiles/window.cpp 11 - - The private \c createFilesTable() function is called from the - constructor. In this function we create the QTableWidget that - will display the search results. We set its horizontal headers and - their resize mode. - - QTableWidget inherits QTableView which provides a default - model/view implementation of a table view. The - QTableView::horizontalHeader() function returns the table view's - horizontal header as a QHeaderView. The QHeaderView class provides - a header row or header column for item views, and the - QHeaderView::setResizeMode() function sets the constraints on how - the section in the header can be resized. - - Finally, we hide the QTableWidget's vertical headers using the - QWidget::hide() function, and remove the default grid drawn for - the table using the QTableView::setShowGrid() function. - - \snippet dialogs/findfiles/window.cpp 12 - - The \c openFileOfItem() slot is invoked when the user double - clicks on a cell in the table. The QDesktopServices::openUrl() - knows how to open a file given the file name. -*/ - diff --git a/examples/widgets/doc/flowlayout.qdoc b/examples/widgets/doc/flowlayout.qdoc deleted file mode 100644 index b08b2283aa..0000000000 --- a/examples/widgets/doc/flowlayout.qdoc +++ /dev/null @@ -1,145 +0,0 @@ -/**************************************************************************** -** -** 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 layouts/flowlayout - \title Flow Layout Example - - The Flow Layout example demonstrates a custom layout that arranges child - widgets from left to right and top to bottom in a top-level widget. - - \image flowlayout-example.png Screenshot of the Flow Layout example - - The items are first laid out horizontally and then vertically when each line - in the layout runs out of space. - - The Flowlayout class mainly uses QLayout and QWidgetItem, while the - Window uses QWidget and QLabel. We will only document the definition - and implementation of \c FlowLayout below. - - \section1 FlowLayout Class Definition - - The \c FlowLayout class inherits QLayout. It is a custom layout class - that arranges its child widgets horizontally and vertically. - - \snippet layouts/flowlayout/flowlayout.h 0 - - We reimplement functions inherited from QLayout. These functions add items to - the layout and handle their orientation and geometry. - - We also declare two private methods, \c doLayout() and \c smartSpacing(). - \c doLayout() lays out the layout items, while the \c - smartSpacing() function calculates the spacing between them. - - \section1 FlowLayout Class Implementation - - We start off by looking at the constructor: - - \snippet layouts/flowlayout/flowlayout.cpp 1 - - In the constructor we call \c setContentsMargins() to set the left, top, - right and bottom margin. By default, QLayout uses values provided by - the current style (see QStyle::PixelMetric). - - \snippet layouts/flowlayout/flowlayout.cpp 2 - - In this example we reimplement \c addItem(), which is a pure virtual - function. When using \c addItem() the ownership of the layout items is - transferred to the layout, and it is therefore the layout's - responsibility to delete them. - - \snippet layouts/flowlayout/flowlayout.cpp 3 - - \c addItem() is implemented to add items to the layout. - - \snippet layouts/flowlayout/flowlayout.cpp 4 - - We implement \c horizontalSpacing() and \c verticalSpacing() to get - hold of the spacing between the widgets inside the layout. If the value - is less than or equal to 0, this value will be used. If not, - \c smartSpacing() will be called to calculate the spacing. - - \snippet layouts/flowlayout/flowlayout.cpp 5 - - We then implement \c count() to return the number of items in the - layout. To navigate the list of items we use \c itemAt() and - takeAt() to remove and return items from the list. If an item is - removed, the remaining items will be renumbered. All three - functions are pure virtual functions from QLayout. - - \snippet layouts/flowlayout/flowlayout.cpp 6 - - \c expandingDirections() returns the \l{Qt::Orientation}s in which the - layout can make use of more space than its \c sizeHint(). - - \snippet layouts/flowlayout/flowlayout.cpp 7 - - To adjust to widgets of which height is dependent on width, we implement \c - heightForWidth(). The function \c hasHeightForWidth() is used to test for this - dependency, and \c heightForWidth() passes the width on to \c doLayout() which - in turn uses the width as an argument for the layout rect, i.e., the bounds in - which the items are laid out. This rect does not include the layout margin(). - - \snippet layouts/flowlayout/flowlayout.cpp 8 - - \c setGeometry() is normally used to do the actual layout, i.e., calculate - the geometry of the layout's items. In this example, it calls \c doLayout() - and passes the layout rect. - - \c sizeHint() returns the preferred size of the layout and \c minimumSize() - returns the minimum size of the layout. - - \snippet layouts/flowlayout/flowlayout.cpp 9 - - \c doLayout() handles the layout if \c horizontalSpacing() or \c - verticalSpacing() don't return the default value. It uses - \c getContentsMargins() to calculate the area available to the - layout items. - - \snippet layouts/flowlayout/flowlayout.cpp 10 - - It then sets the proper amount of spacing for each widget in the - layout, based on the current style. - - \snippet layouts/flowlayout/flowlayout.cpp 11 - - The position of each item in the layout is then calculated by - adding the items width and the line height to the initial x and y - coordinates. This in turn lets us find out whether the next item - will fit on the current line or if it must be moved down to the next. - We also find the height of the current line based on the widgets height. - - \snippet layouts/flowlayout/flowlayout.cpp 12 - - \c smartSpacing() is designed to get the default spacing for either - the top-level layouts or the sublayouts. The default spacing for - top-level layouts, when the parent is a QWidget, will be determined - by querying the style. The default spacing for sublayouts, when - the parent is a QLayout, will be determined by querying the spacing - of the parent layout. - -*/ diff --git a/examples/widgets/doc/fontsampler.qdoc b/examples/widgets/doc/fontsampler.qdoc deleted file mode 100644 index 8d7f0e0460..0000000000 --- a/examples/widgets/doc/fontsampler.qdoc +++ /dev/null @@ -1,35 +0,0 @@ -/**************************************************************************** -** -** 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 painting/fontsampler - \title Font Sampler Example - - The Font Sampler example shows how to preview and print multi-page documents. - - \image fontsampler-example.png -*/ diff --git a/examples/widgets/doc/frozencolumn.qdoc b/examples/widgets/doc/frozencolumn.qdoc deleted file mode 100644 index c65ce1d524..0000000000 --- a/examples/widgets/doc/frozencolumn.qdoc +++ /dev/null @@ -1,133 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/frozencolumn - \title Frozen Column Example - - This example demonstrates how to freeze a column within a QTableView. - - \image frozencolumn-example.png "Screenshot of the example" - - We use Qt's model/view framework to implement a table with its first - column frozen. This technique can be aplied to several columns or rows, - as long as they are on the edge of the table. - - The model/view framework allows for one model to be displayed in different - ways using multiple views. For this example, we use two views on the same - model - two \l {QTableView}{table views} sharing one model. The frozen - column is a child of the main tableview, and we provide the desired visual - effect using an overlay technique which will be described step by step in - the coming sections. - - \image frozencolumn-tableview.png - - - \section1 FreezeTableWidget Class Definition - - The \c FreezeTableWidget class has a constructor and a destructor. Also, it - has two private members: the table view that we will use as an overlay, and - the shared model for both table views. Two slots are added to help keep the - section sizes in sync, as well as a function to readjust the frozen - column's geometry. In addition, we reimplement two functions: - \l{QAbstractItemView::}{resizeEvent()} and \l{QTableView::}{moveCursor()}. - - \snippet itemviews/frozencolumn/freezetablewidget.h Widget definition - - \note QAbstractItemView is \l{QTableView}'s ancestor. - - - \section1 FreezeTableWidget Class Implementation - - The constructor takes \a model as an argument and creates a table view that - we will use to display the frozen column. Then, within the constructor, we - invoke the \c init() function to set up the frozen column. Finally, we - connect the \l{QHeaderView::sectionResized()} signals (for horizontal and - vertical headers) to the appropriate slots. This ensures that our frozen - column's sections are in sync with the headers. We also connect the - vertical scrollbars together so that the frozen column scrolls vertically - with the rest of our table. - - \snippet itemviews/frozencolumn/freezetablewidget.cpp constructor - - - In the \c init() function, we ensure that the overlay table view - responsible for displaying the frozen column, is set up properly. This - means that this table view, \c frozenTableView, has to have the same model - as the main table view. However, the difference here is: \c frozenTableView's - only visible column is its first column; we hide the others using - \l{QTableView::}{setColumnHidden()} - - \snippet itemviews/frozencolumn/freezetablewidget.cpp init part1 - - - In terms of the frozen column's z-order, we stack it on top of the - viewport. This is achieved by calling \l{QWidget::}{stackUnder()} on the - viewport. For appearance's sake, we prevent the column from stealing focus - from the main tableview. Also, we make sure that both views share the same - selection model, so only one cell can be selected at a time. A few other - tweaks are done to make our application look good and behave consistently - with the main tableview. Note that we called \c updateFrozenTableGeometry() - to make the column occupy the correct spot. - - \snippet itemviews/frozencolumn/freezetablewidget.cpp init part2 - - When you resize the frozen column, the same column on the main table view - must resize accordingly, to provide seamless integration. This is - accomplished by getting the new size of the column from the \c newSize - value from the \l{QHeaderView::}{sectionResized()} signal, emitted by both - the horizontal and vertical header. - - \snippet itemviews/frozencolumn/freezetablewidget.cpp sections - - Since the width of the frozen column is modified, we adjust the geometry of - the widget accordingly by invoking \c updateFrozenTableGeometry(). This - function is further explained below. - - In our reimplementation of QTableView::resizeEvent(), we call - \c updateFrozenTableGeometry() after invoking the base class - implementation. - - \snippet itemviews/frozencolumn/freezetablewidget.cpp resize - - When navigating around the table with the keyboard, we need to ensure that - the current selection does not disappear behind the frozen column. To - synchronize this, we reimplement QTableView::moveCursor() and adjust the - scrollbar positions if needed, after calling the base class implementation. - - \snippet itemviews/frozencolumn/freezetablewidget.cpp navigate - - The frozen column's geometry calculation is based on the geometry of the - table underneath, so it always appears in the right place. Using the - QFrame::frameWidth() function helps to calculate this geometry correctly, - no matter which style is used. We rely on the geometry of the viewport and - headers to set the boundaries for the frozen column. - - \snippet itemviews/frozencolumn/freezetablewidget.cpp geometry - -*/ - diff --git a/examples/widgets/doc/gradients.qdoc b/examples/widgets/doc/gradients.qdoc deleted file mode 100644 index 75f78b56ea..0000000000 --- a/examples/widgets/doc/gradients.qdoc +++ /dev/null @@ -1,55 +0,0 @@ -/**************************************************************************** -** -** 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 painting/gradients - \title Gradients - - In this example we show the various types of gradients that can - be used in Qt. - - \image gradients-demo.png - - There are three types of gradients: - - \list - \li \b{Linear} gradients interpolate colors between start and end points. - \li \b{Radial} gradients interpolate colors between a focal point and the - points on a circle surrounding it. - \li \b{Conical} gradients interpolate colors around a center point. - \endlist - - The panel on the right contains a color table editor that defines - the colors in the gradient. The three topmost controls determine the red, - green and blue components while the last defines the alpha of the - gradient. You can move points, and add new ones, by clicking with the left - mouse button, and remove points by clicking with the right button. - - There are three default configurations available at the bottom of - the page that are provided as suggestions on how a color table could be - configured. -*/ diff --git a/examples/widgets/doc/groupbox.qdoc b/examples/widgets/doc/groupbox.qdoc deleted file mode 100644 index d7384d409a..0000000000 --- a/examples/widgets/doc/groupbox.qdoc +++ /dev/null @@ -1,140 +0,0 @@ -/**************************************************************************** -** -** 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/groupbox - \title Group Box Example - - The Group Box example shows how to use the different kinds of group - boxes in Qt. - - Group boxes are container widgets that organize buttons into groups, - both logically and on screen. They manage the interactions between - the user and the application so that you do not have to enforce - simple constraints. - - Group boxes are usually used to organize check boxes and radio - buttons into exclusive groups. - - \image groupbox-example.png - - The Group Boxes example consists of a single \c Window class that - is used to show four group boxes: an exclusive radio button group, - a non-exclusive checkbox group, an exclusive radio button group - with an enabling checkbox, and a group box with normal push buttons. - - \section1 Window Class Definition - - The \c Window class is a subclass of \c QWidget that is used to - display a number of group boxes. The class definition contains - functions to construct each group box and populate it with different - selections of button widgets: - - \snippet widgets/groupbox/window.h 0 - - In the example, the widget will be used as a top-level window, so - the constructor is defined so that we do not have to specify a parent - widget. - - \section1 Window Class Implementation - - The constructor creates a grid layout and fills it with each of the - group boxes that are to be displayed: - - \snippet widgets/groupbox/window.cpp 0 - - The functions used to create each group box each return a - QGroupBox to be inserted into the grid layout. - - \snippet widgets/groupbox/window.cpp 1 - - The first group box contains and manages three radio buttons. Since - the group box contains only radio buttons, it is exclusive by - default, so only one radio button can be checked at any given time. - We check the first radio button to ensure that the button group - contains one checked button. - - \snippet widgets/groupbox/window.cpp 3 - - We use a vertical layout within the group box to present the - buttons in the form of a vertical list, and return the group - box to the constructor. - - The second group box is itself checkable, providing a convenient - way to disable all the buttons inside it. Initially, it is - unchecked, so the group box itself must be checked before any of - the radio buttons inside can be checked. - - \snippet widgets/groupbox/window.cpp 4 - - The group box contains three exclusive radio buttons, and an - independent checkbox. For consistency, one radio button must be - checked at all times, so we ensure that the first one is initially - checked. - - \snippet widgets/groupbox/window.cpp 5 - - The buttons are arranged in the same way as those in the first - group box. - - \snippet widgets/groupbox/window.cpp 6 - - The third group box is constructed with a "flat" style that is - better suited to certain types of dialog. - - \snippet widgets/groupbox/window.cpp 7 - - This group box contains only checkboxes, so it is non-exclusive by - default. This means that each checkbox can be checked independently - of the others. - - \snippet widgets/groupbox/window.cpp 8 - - Again, we use a vertical layout within the group box to present - the buttons in the form of a vertical list. - - \snippet widgets/groupbox/window.cpp 9 - - The final group box contains only push buttons and, like the - second group box, it is checkable. - - \snippet widgets/groupbox/window.cpp 10 - - We create a normal button, a toggle button, and a flat push button: - - \snippet widgets/groupbox/window.cpp 11 - - Push buttons can be used to display popup menus. We create one, and - attach a simple menu to it: - - \snippet widgets/groupbox/window.cpp 12 - - Finally, we lay out the widgets vertically, and return the group box - that we created: - - \snippet widgets/groupbox/window.cpp 13 -*/ diff --git a/examples/widgets/doc/icons.qdoc b/examples/widgets/doc/icons.qdoc deleted file mode 100644 index b6625db005..0000000000 --- a/examples/widgets/doc/icons.qdoc +++ /dev/null @@ -1,787 +0,0 @@ -/**************************************************************************** -** -** 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/icons - \title Icons Example - - The Icons example shows how QIcon can generate pixmaps reflecting - an icon's state, mode and size. These pixmaps are generated from - the set of pixmaps made available to the icon, and are used by Qt - widgets to show an icon representing a particular action. - - \image icons-example.png Screenshot of the Icons example - - Contents: - - \tableofcontents - - \section1 QIcon Overview - - The QIcon class provides scalable icons in different modes and - states. An icon's state and mode are depending on the intended use - of the icon. Qt currently defines four modes: - - \table - \header \li Mode \li Description - \row - \li QIcon::Normal - \li Display the pixmap when the user is not interacting with the - icon, but the functionality represented by the icon is - available. - \row - \li QIcon::Active - \li Display the pixmap when the functionality represented by the - icon is available and the user is interacting with the icon, - for example, moving the mouse over it or clicking it. - \row - \li QIcon::Disabled - \li Display the pixmap when the functionality represented by - the icon is not available. - \row - \li QIcon::Selected - \li Display the pixmap when the icon is selected. - \endtable - - QIcon's states are QIcon::On and QIcon::Off, which will display - the pixmap when the widget is in the respective state. The most - common usage of QIcon's states are when displaying checkable tool - buttons or menu entries (see QAbstractButton::setCheckable() and - QAction::setCheckable()). When a tool button or menu entry is - checked, the QIcon's state is \l{QIcon::}{On}, otherwise it's - \l{QIcon::}{Off}. You can, for example, use the QIcon's states to - display differing pixmaps depending on whether the tool button or - menu entry is checked or not. - - A QIcon can generate smaller, larger, active, disabled, and - selected pixmaps from the set of pixmaps it is given. Such - pixmaps are used by Qt widgets to show an icon representing a - particular action. - - \section1 Overview of the Icons Application - - With the Icons application you get a preview of an icon's - generated pixmaps reflecting its different states, modes and size. - - When an image is loaded into the application, it is converted into - a pixmap and becomes a part of the set of pixmaps available to the - icon. An image can be excluded from this set by checking off the - related checkbox. The application provides a sub directory - containing sets of images explicitly designed to illustrate how Qt - renders an icon in different modes and states. - - The application allows you to manipulate the icon size with some - predefined sizes and a spin box. The predefined sizes are style - dependent, but most of the styles have the same values: Only the - Macintosh style differ by using 32 pixels, instead of 16 pixels, - for toolbar buttons. You can navigate between the available styles - using the \uicontrol View menu. - - \image icons-view-menu.png Screenshot of the View menu - - The \uicontrol View menu also provide the option to make the application - guess the icon state and mode from an image's file name. The \uicontrol - File menu provide the options of adding an image and removing all - images. These last options are also available through a context - menu that appears if you press the right mouse button within the - table of image files. In addition, the \uicontrol File menu provide an - \uicontrol Exit option, and the \uicontrol Help menu provide information about - the example and about Qt. - - \image icons_find_normal.png Screenshot of the Find Files - - The screenshot above shows the application with one image file - loaded. The \uicontrol {Guess Image Mode/State} is enabled and the - style is Plastique. - - When QIcon is provided with only one available pixmap, that - pixmap is used for all the states and modes. In this case the - pixmap's icon mode is set to normal, and the generated pixmaps - for the normal and active modes will look the same. But in - disabled and selected mode, Qt will generate a slightly different - pixmap. - - The next screenshot shows the application with an additional file - loaded, providing QIcon with two available pixmaps. Note that the - new image file's mode is set to disabled. When rendering the \uicontrol - Disabled mode pixmaps, Qt will now use the new image. We can see - the difference: The generated disabled pixmap in the first - screenshot is slightly darker than the pixmap with the originally - set disabled mode in the second screenshot. - - \image icons_find_normal_disabled.png Screenshot of the Find Files - - When Qt renders the icon's pixmaps it searches through the set of - available pixmaps following a particular algorithm. The algorithm - is documented in QIcon, but we will describe some particular cases - below. - - \image icons_monkey_active.png Screenshot of the Find Files - - In the screenshot above, we have set \c monkey_on_32x32 to be an - Active/On pixmap and \c monkey_off_64x64 to be Normal/Off. To - render the other six mode/state combinations, QIcon uses the - search algorithm described in the table below: - - \table 100% - \header \li{2,1} Requested Pixmap \li {8,1} Preferred Alternatives (mode/state) - \header \li Mode \li State \li 1 \li 2 \li 3 \li 4 \li 5 \li 6 \li 7 \li 8 - \row \li{1,2} Normal \li Off \li \b N0 \li A0 \li N1 \li A1 \li D0 \li S0 \li D1 \li S1 - \row \li On \li N1 \li \b A1 \li N0 \li A0 \li D1 \li S1 \li D0 \li S0 - \row \li{1,2} Active \li Off \li A0 \li \b N0 \li A1 \li N1 \li D0 \li S0 \li D1 \li S1 - \row \li On \li \b A1 \li N1 \li A0 \li N0 \li D1 \li S1 \li D0 \li S0 - \row \li{1,2} Disabled \li Off \li D0 \li \b {N0'} \li A0' \li D1 \li N1' \li A1' \li S0' \li S1' - \row \li On \li D1 \li N1' \li \b {A1'} \li D0 \li N0' \li A0' \li S1' \li S0' - \row \li{1,2} Selected \li Off \li S0 \li \b {N0''} \li A0'' \li S1 \li N1'' \li A1'' \li D0'' \li D1'' - \row \li On \li S1 \li N1'' \li \b {A1''} \li S0 \li N0'' \li A0'' \li D1'' \li D0'' - \endtable - - In the table, "0" and "1" stand for Off" and "On", respectively. - Single quotes indicates that QIcon generates a disabled ("grayed - out") version of the pixmap; similarly, double quuote indicate - that QIcon generates a selected ("blued out") version of the - pixmap. - - The alternatives used in the screenshot above are shown in bold. - For example, the Disabled/Off pixmap is derived by graying out - the Normal/Off pixmap (\c monkey_off_64x64). - - In the next screenshots, we loaded the whole set of monkey - images. By checking or unchecking file names from the image list, - we get different results: - - \table - \row - \li \inlineimage icons_monkey.png Screenshot of the Monkey Files - \li \inlineimage icons_monkey_mess.png Screenshot of the Monkey Files - \endtable - - For any given mode/state combination, it is possible to specify - several images at different resolutions. When rendering an - icon, QIcon will automatically pick the most suitable image - and scale it down if necessary. (QIcon never scales up images, - because this rarely looks good.) - - The screenshots below shows what happens when we provide QIcon - with three images (\c qt_extended_16x16.png, \c qt_extended_32x32.png, \c - qt_extended_48x48.png) and try to render the QIcon at various - resolutions: - - \table - \row - \li - \li \inlineimage icons_qt_extended_8x8.png Qt Extended icon at 8 x 8 - \li \inlineimage icons_qt_extended_16x16.png Qt Extended icon at 16 x 16 - \li \inlineimage icons_qt_extended_17x17.png Qt Extended icon at 17 x 17 - \row - \li - \li 8 x 8 - \li \b {16 x 16} - \li 17 x 17 - \row - \li \inlineimage icons_qt_extended_32x32.png Qt Extended icon at 32 x 32 - \li \inlineimage icons_qt_extended_33x33.png Qt Extended icon at 33 x 33 - \li \inlineimage icons_qt_extended_48x48.png Qt Extended icon at 48 x 48 - \li \inlineimage icons_qt_extended_64x64.png Qt Extended icon at 64 x 64 - \row - \li \b {32 x 32} - \li 33 x 33 - \li \b {48 x 48} - \li 64 x 64 - \endtable - - For sizes up to 16 x 16, QIcon uses \c qt_extended_16x16.png and - scales it down if necessary. For sizes between 17 x 17 and 32 x - 32, it uses \c qt_extended_32x32.png. For sizes above 32 x 32, it uses - \c qt_extended_48x48.png. - - \section1 Line-by-Line Walkthrough - - The Icons example consists of four classes: - - \list - \li \c MainWindow inherits QMainWindow and is the main application - window. - \li \c IconPreviewArea is a custom widget that displays all - combinations of states and modes for a given icon. - \li \c IconSizeSpinBox is a subclass of QSpinBox that lets the - user enter icon sizes (e.g., "48 x 48"). - \li \c ImageDelegate is a subclass of QItemDelegate that provides - comboboxes for letting the user set the mode and state - associated with an image. - \endlist - - We will start by reviewing the \c IconPreviewArea class before we - take a look at the \c MainWindow class. Finally, we will review the - \c IconSizeSpinBox and \c ImageDelegate classes. - - \section2 IconPreviewArea Class Definition - - An \c IconPreviewArea widget consists of a group box containing a grid of - QLabel widgets displaying headers and pixmaps. - - \image icons_preview_area.png Screenshot of IconPreviewArea. - - \snippet widgets/icons/iconpreviewarea.h 0 - - The \c IconPreviewArea class inherits QWidget. It displays the - generated pixmaps corresponding to an icon's possible states and - modes at a given size. - - We need two public functions to set the current icon and the - icon's size. In addition the class has three private functions: We - use the \c createHeaderLabel() and \c createPixmapLabel() - functions when constructing the preview area, and we need the \c - updatePixmapLabels() function to update the preview area when - the icon or the icon's size has changed. - - The \c NumModes and \c NumStates constants reflect \l{QIcon}'s - number of currently defined modes and states. - - \section2 IconPreviewArea Class Implementation - - \snippet widgets/icons/iconpreviewarea.cpp 0 - - In the constructor we create the labels displaying the headers and - the icon's generated pixmaps, and add them to a grid layout. - - When creating the header labels, we make sure the enums \c - NumModes and \c NumStates defined in the \c .h file, correspond - with the number of labels that we create. Then if the enums at - some point are changed, the \c Q_ASSERT() macro will alert that this - part of the \c .cpp file needs to be updated as well. - - If the application is built in debug mode, the \c Q_ASSERT() - macro will expand to - - \code - if (!condition) - qFatal("ASSERT: "condition" in file ..."); - \endcode - - In release mode, the macro simply disappear. The mode can be set - in the application's \c .pro file. One way to do so is to add an - option to \c qmake when building the application: - - \code - qmake "CONFIG += debug" icons.pro - \endcode - - or - - \code - qmake "CONFIG += release" icons.pro - \endcode - - Another approach is to add this line directly to the \c .pro - file. - - \snippet widgets/icons/iconpreviewarea.cpp 1 - \codeline - \snippet widgets/icons/iconpreviewarea.cpp 2 - - The public \c setIcon() and \c setSize() functions change the icon - or the icon size, and make sure that the generated pixmaps are - updated. - - \snippet widgets/icons/iconpreviewarea.cpp 3 - \codeline - \snippet widgets/icons/iconpreviewarea.cpp 4 - - We use the \c createHeaderLabel() and \c createPixmapLabel() - functions to create the preview area's labels displaying the - headers and the icon's generated pixmaps. Both functions return - the QLabel that is created. - - \snippet widgets/icons/iconpreviewarea.cpp 5 - - We use the private \c updatePixmapLabel() function to update the - generated pixmaps displayed in the preview area. - - For each mode, and for each state, we retrieve a pixmap using the - QIcon::pixmap() function, which generates a pixmap corresponding - to the given state, mode and size. - - \section2 MainWindow Class Definition - - The \c MainWindow widget consists of three main elements: an - images group box, an icon size group box and a preview area. - - \image icons-example.png Screenshot of the Icons example - - \snippet widgets/icons/mainwindow.h 0 - - The MainWindow class inherits from QMainWindow. We reimplement the - constructor, and declare several private slots: - - \list - \li The \c about() slot simply provides information about the example. - \li The \c changeStyle() slot changes the application's GUI style and - adjust the style dependent size options. - \li The \c changeSize() slot changes the size of the preview area's icon. - \li The \c changeIcon() slot updates the set of pixmaps available to the - icon displayed in the preview area. - \li The \c addImage() slot allows the user to load a new image into the - application. - \endlist - - In addition we declare several private functions to simplify the - constructor. - - \section2 MainWindow Class Implementation - - \snippet widgets/icons/mainwindow.cpp 0 - - In the constructor we first create the main window's central - widget and its child widgets, and put them in a grid layout. Then - we create the menus with their associated entries and actions. - - Before we resize the application window to a suitable size, we set - the window title and determine the current style for the - application. We also enable the icon size spin box by clicking the - associated radio button, making the current value of the spin box - the icon's initial size. - - \snippet widgets/icons/mainwindow.cpp 1 - - The \c about() slot displays a message box using the static - QMessageBox::about() function. In this example it displays a - simple box with information about the example. - - The \c about() function looks for a suitable icon in four - locations: It prefers its parent's icon if that exists. If it - doesn't, the function tries the top-level widget containing - parent, and if that fails, it tries the active window. As a last - resort it uses the QMessageBox's Information icon. - - \snippet widgets/icons/mainwindow.cpp 2 - - In the \c changeStyle() slot we first check the slot's - parameter. If it is false we immediately return, otherwise we find - out which style to change to, i.e. which action that triggered the - slot, using the QObject::sender() function. - - This function returns the sender as a QObject pointer. Since we - know that the sender is a QAction object, we can safely cast the - QObject. We could have used a C-style cast or a C++ \c - static_cast(), but as a defensive programming technique we use a - \l qobject_cast(). The advantage is that if the object has the - wrong type, a null pointer is returned. Crashes due to null - pointers are much easier to diagnose than crashes due to unsafe - casts. - - \snippet widgets/icons/mainwindow.cpp 3 - \snippet widgets/icons/mainwindow.cpp 4 - - Once we have the action, we extract the style name using - QAction::data(). Then we create a QStyle object using the static - QStyleFactory::create() function. - - Although we can assume that the style is supported by the - QStyleFactory: To be on the safe side, we use the \c Q_ASSERT() - macro to check if the created style is valid before we use the - QApplication::setStyle() function to set the application's GUI - style to the new style. QApplication will automatically delete - the style object when a new style is set or when the application - exits. - - The predefined icon size options provided in the application are - style dependent, so we need to update the labels in the icon size - group box and in the end call the \c changeSize() slot to update - the icon's size. - - \snippet widgets/icons/mainwindow.cpp 5 - - The \c changeSize() slot sets the size for the preview area's - icon. - - To determine the new size we first check if the spin box is - enabled. If it is, we extract the extent of the new size from the - box. If it's not, we search through the predefined size options, - extract the QStyle::PixelMetric and use the QStyle::pixelMetric() - function to determine the extent. Then we create a QSize object - based on the extent, and use that object to set the size of the - preview area's icon. - - \snippet widgets/icons/mainwindow.cpp 12 - - The first thing we do when the \c addImage() slot is called, is to - show a file dialog to the user. The easiest way to create a file - dialog is to use QFileDialog's static functions. Here we use the - \l {QFileDialog::getOpenFileNames()}{getOpenFileNames()} function - that will return one or more existing files selected by the user. - - For each of the files the file dialog returns, we add a row to the - table widget. The table widget is listing the images the user has - loaded into the application. - - \snippet widgets/icons/mainwindow.cpp 13 - \snippet widgets/icons/mainwindow.cpp 14 - - We retrieve the image name using the QFileInfo::baseName() - function that returns the base name of the file without the path, - and create the first table widget item in the row. Then we add the - file's complete name to the item's data. Since an item can hold - several information pieces, we need to assign the file name a role - that will distinguish it from other data. This role can be Qt::UserRole - or any value above it. - - We also make sure that the item is not editable by removing the - Qt::ItemIsEditable flag. Table items are editable by default. - - \snippet widgets/icons/mainwindow.cpp 15 - \snippet widgets/icons/mainwindow.cpp 16 - \snippet widgets/icons/mainwindow.cpp 17 - - Then we create the second and third items in the row making the - default mode Normal and the default state Off. But if the \uicontrol - {Guess Image Mode/State} option is checked, and the file name - contains "_act", "_dis", or "_sel", the modes are changed to - Active, Disabled, or Selected. And if the file name contains - "_on", the state is changed to On. The sample files in the - example's \c images subdirectory respect this naming convension. - - \snippet widgets/icons/mainwindow.cpp 18 - \snippet widgets/icons/mainwindow.cpp 19 - - In the end we add the items to the associated row, and use the - QTableWidget::openPersistentEditor() function to create - comboboxes for the mode and state columns of the items. - - Due to the connection between the table widget's \l - {QTableWidget::itemChanged()}{itemChanged()} signal and the \c - changeIcon() slot, the new image is automatically converted into a - pixmap and made part of the set of pixmaps available to the icon - in the preview area. So, corresponding to this fact, we need to - make sure that the new image's check box is enabled. - - \snippet widgets/icons/mainwindow.cpp 6 - \snippet widgets/icons/mainwindow.cpp 7 - - The \c changeIcon() slot is called when the user alters the set - of images listed in the QTableWidget, to update the QIcon object - rendered by the \c IconPreviewArea. - - We first create a QIcon object, and then we run through the - QTableWidget, which lists the images the user has loaded into the - application. - - \snippet widgets/icons/mainwindow.cpp 8 - \snippet widgets/icons/mainwindow.cpp 9 - \snippet widgets/icons/mainwindow.cpp 10 - - We also extract the image file's name using the - QTableWidgetItem::data() function. This function takes a - Qt::DataItemRole as an argument to retrieve the right data - (remember that an item can hold several pieces of information) - and returns it as a QVariant. Then we use the - QVariant::toString() function to get the file name as a QString. - - To create a pixmap from the file, we need to first create an - image and then convert this image into a pixmap using - QPixmap::fromImage(). Once we have the final pixmap, we add it, - with its associated mode and state, to the QIcon's set of - available pixmaps. - - \snippet widgets/icons/mainwindow.cpp 11 - - After running through the entire list of images, we change the - icon of the preview area to the one we just created. - - \snippet widgets/icons/mainwindow.cpp 20 - - In the \c removeAllImages() slot, we simply set the table widget's - row count to zero, automatically removing all the images the user - has loaded into the application. Then we update the set of pixmaps - available to the preview area's icon using the \c changeIcon() - slot. - - \image icons_images_groupbox.png Screenshot of the images group box - - The \c createImagesGroupBox() function is implemented to simplify - the constructor. The main purpose of the function is to create a - QTableWidget that will keep track of the images the user has - loaded into the application. - - \snippet widgets/icons/mainwindow.cpp 21 - - First we create a group box that will contain the table widget. - Then we create a QTableWidget and customize it to suit our - purposes. - - We call QAbstractItemView::setSelectionMode() to prevent the user - from selecting items. - - The QAbstractItemView::setItemDelegate() call sets the item - delegate for the table widget. We create a \c ImageDelegate that - we make the item delegate for our view. - - The QItemDelegate class can be used to provide an editor for an item view - class that is subclassed from QAbstractItemView. Using a delegate - for this purpose allows the editing mechanism to be customized and - developed independently from the model and view. - - In this example we derive \c ImageDelegate from QItemDelegate. - QItemDelegate usually provides line editors, while our subclass - \c ImageDelegate, provides comboboxes for the mode and state - fields. - - \snippet widgets/icons/mainwindow.cpp 22 - \snippet widgets/icons/mainwindow.cpp 23 - - Then we customize the QTableWidget's horizontal header, and hide - the vertical header. - - \snippet widgets/icons/mainwindow.cpp 24 - \snippet widgets/icons/mainwindow.cpp 25 - - At the end, we connect the QTableWidget::itemChanged() signal to - the \c changeIcon() slot to ensuret that the preview area is in - sync with the image table. - - \image icons_size_groupbox.png Screenshot of the icon size group box - - The \c createIconSizeGroupBox() function is called from the - constructor. It creates the widgets controlling the size of the - preview area's icon. - - \snippet widgets/icons/mainwindow.cpp 26 - - First we create a group box that will contain all the widgets; - then we create the radio buttons and the spin box. - - The spin box is not a regular QSpinBox but an \c IconSizeSpinBox. - The \c IconSizeSpinBox class inherits QSpinBox and reimplements - two functions: QSpinBox::textFromValue() and - QSpinBox::valueFromText(). The \c IconSizeSpinBox is designed to - handle icon sizes, e.g., "32 x 32", instead of plain integer - values. - - \snippet widgets/icons/mainwindow.cpp 27 - - Then we connect all of the radio buttons - \l{QRadioButton::toggled()}{toggled()} signals and the spin box's - \l {QSpinBox::valueChanged()}{valueChanged()} signal to the \c - changeSize() slot to make sure that the size of the preview - area's icon is updated whenever the user changes the icon size. - In the end we put the widgets in a layout that we install on the - group box. - - \snippet widgets/icons/mainwindow.cpp 28 - - In the \c createActions() function we create and customize all the - actions needed to implement the functionality associated with the - menu entries in the application. - - In particular we create the \c styleActionGroup based on the - currently available GUI styles using - QStyleFactory. QStyleFactory::keys() returns a list of valid keys, - typically including "windows", "motif", "cde", and - "plastique". Depending on the platform, "windowsxp" and - "macintosh" may be available. - - We create one action for each key, and adds the action to the - action group. Also, for each action, we call QAction::setData() - with the style name. We will retrieve it later using - QAction::data(). - - \snippet widgets/icons/mainwindow.cpp 29 - - In the \c createMenu() function, we add the previously created - actions to the \uicontrol File, \uicontrol View and \uicontrol Help menus. - - The QMenu class provides a menu widget for use in menu bars, - context menus, and other popup menus. We put each menu in the - application's menu bar, which we retrieve using - QMainWindow::menuBar(). - - \snippet widgets/icons/mainwindow.cpp 30 - - QWidgets have a \l{QWidget::contextMenuPolicy}{contextMenuPolicy} - property that controls how the widget should behave when the user - requests a context menu (e.g., by right-clicking). We set the - QTableWidget's context menu policy to Qt::ActionsContextMenu, - meaning that the \l{QAction}s associated with the widget should - appear in its context menu. - - Then we add the \uicontrol{Add Image} and \uicontrol{Remove All Images} - actions to the table widget. They will then appear in the table - widget's context menu. - - \snippet widgets/icons/mainwindow.cpp 31 - - In the \c checkCurrentStyle() function we go through the group of - style actions, looking for the current GUI style. - - For each action, we first extract the style name using - QAction::data(). Since this is only a QStyleFactory key (e.g., - "macintosh"), we cannot compare it directly to the current - style's class name. We need to create a QStyle object using the - static QStyleFactory::create() function and compare the class - name of the created QStyle object with that of the current style. - As soon as we are done with a QStyle candidate, we delete it. - - For all QObject subclasses that use the \c Q_OBJECT macro, the - class name of an object is available through its - \l{QObject::metaObject()}{meta-object}. - - We can assume that the style is supported by - QStyleFactory, but to be on the safe side we use the \c - Q_ASSERT() macro to make sure that QStyleFactory::create() - returned a valid pointer. - - \section2 IconSizeSpinBox Class Definition - - \snippet widgets/icons/iconsizespinbox.h 0 - - The \c IconSizeSpinBox class is a subclass of QSpinBox. A plain - QSpinBox can only handle integers. But since we want to display - the spin box's values in a more sophisticated way, we need to - subclass QSpinBox and reimplement the QSpinBox::textFromValue() - and QSpinBox::valueFromText() functions. - - \image icons_size_spinbox.png Screenshot of the icon size spinbox - - \section2 IconSizeSpinBox Class Implementation - - \snippet widgets/icons/iconsizespinbox.cpp 0 - - The constructor is trivial. - - \snippet widgets/icons/iconsizespinbox.cpp 2 - - QSpinBox::textFromValue() is used by the spin box whenever it - needs to display a value. The default implementation returns a - base 10 representation of the \c value parameter. - - Our reimplementation returns a QString of the form "32 x 32". - - \snippet widgets/icons/iconsizespinbox.cpp 1 - - The QSpinBox::valueFromText() function is used by the spin box - whenever it needs to interpret text typed in by the user. Since - we reimplement the \c textFromValue() function we also need to - reimplement the \c valueFromText() function to interpret the - parameter text and return the associated int value. - - We parse the text using a regular expression (a QRegExp). We - define an expression that matches one or several digits, - optionally followed by whitespace, an "x" or the times symbol, - whitespace and one or several digits again. - - The first digits of the regular expression are captured using - parentheses. This enables us to use the QRegExp::cap() or - QRegExp::capturedTexts() functions to extract the matched - characters. If the first and second numbers of the spin box value - differ (e.g., "16 x 24"), we use the first number. - - When the user presses \uicontrol Enter, QSpinBox first calls - QSpinBox::valueFromText() to interpret the text typed by the - user, then QSpinBox::textFromValue() to present it in a canonical - format (e.g., "16 x 16"). - - \section2 ImageDelegate Class Definition - - \snippet widgets/icons/imagedelegate.h 0 - - The \c ImageDelegate class is a subclass of QItemDelegate. The - QItemDelegate class provides display and editing facilities for - data items from a model. A single QItemDelegate object is - responsible for all items displayed in a item view (in our case, - a QTableWidget). - - A QItemDelegate can be used to provide an editor for an item view - class that is subclassed from QAbstractItemView. Using a delegate - for this purpose allows the editing mechanism to be customized and - developed independently from the model and view. - - \snippet widgets/icons/imagedelegate.h 1 - - The default implementation of QItemDelegate creates a QLineEdit. - Since we want the editor to be a QComboBox, we need to subclass - QItemDelegate and reimplement the QItemDelegate::createEditor(), - QItemDelegate::setEditorData() and QItemDelegate::setModelData() - functions. - - \snippet widgets/icons/imagedelegate.h 2 - - The \c emitCommitData() slot is used to emit the - QImageDelegate::commitData() signal with the appropriate - argument. - - \section2 ImageDelegate Class Implementation - - \snippet widgets/icons/imagedelegate.cpp 0 - - The constructor is trivial. - - \snippet widgets/icons/imagedelegate.cpp 1 - - The default QItemDelegate::createEditor() implementation returns - the widget used to edit the item specified by the model and item - index for editing. The parent widget and style option are used to - control the appearance of the editor widget. - - Our reimplementation create and populate a combobox instead of - the default line edit. The contents of the combobox depends on - the column in the table for which the editor is requested. Column - 1 contains the QIcon modes, whereas column 2 contains the QIcon - states. - - In addition, we connect the combobox's \l - {QComboBox::activated()}{activated()} signal to the \c - emitCommitData() slot to emit the - QAbstractItemDelegate::commitData() signal whenever the user - chooses an item using the combobox. This ensures that the rest of - the application notices the change and updates itself. - - \snippet widgets/icons/imagedelegate.cpp 2 - - The QItemDelegate::setEditorData() function is used by - QTableWidget to transfer data from a QTableWidgetItem to the - editor. The data is stored as a string; we use - QComboBox::findText() to locate it in the combobox. - - Delegates work in terms of models, not items. This makes it - possible to use them with any item view class (e.g., QListView, - QListWidget, QTreeView, etc.). The transition between model and - items is done implicitly by QTableWidget; we don't need to worry - about it. - - \snippet widgets/icons/imagedelegate.cpp 3 - - The QItemDelegate::setEditorData() function is used by QTableWidget - to transfer data back from the editor to the \l{QTableWidgetItem}. - - \snippet widgets/icons/imagedelegate.cpp 4 - - The \c emitCommitData() slot simply emit the - QAbstractItemDelegate::commitData() signal for the editor that - triggered the slot. This signal must be emitted when the editor - widget has completed editing the data, and wants to write it back - into the model. -*/ diff --git a/examples/widgets/doc/imagecomposition.qdoc b/examples/widgets/doc/imagecomposition.qdoc deleted file mode 100644 index 3f06f377b4..0000000000 --- a/examples/widgets/doc/imagecomposition.qdoc +++ /dev/null @@ -1,165 +0,0 @@ -/**************************************************************************** -** -** 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 painting/imagecomposition - \title Image Composition Example - - The Image Composition example lets the user combine images - together using any composition mode supported by QPainter, described - in detail in \l{QPainter#Composition Modes}{Composition Modes}. - - \image imagecomposition-example.png - - \section1 Setting Up The Resource File - - The Image Composition example requires two source images, - \e butterfly.png and \e checker.png that are embedded within - \e imagecomposition.qrc. The file contains the following code: - - \quotefile painting/imagecomposition/imagecomposition.qrc - - For more information on resource files, see \l{The Qt Resource System}. - - \section1 ImageComposer Class Definition - - The \c ImageComposer class is a subclass of QWidget that implements three - private slots, \c chooseSource(), \c chooseDestination(), and - \c recalculateResult(). - - \snippet painting/imagecomposition/imagecomposer.h 0 - - In addition, \c ImageComposer consists of five private functions, - \c addOp(), \c chooseImage(), \c loadImage(), \c currentMode(), and - \c imagePos(), as well as private instances of QToolButton, QComboBox, - QLabel, and QImage. - - \snippet painting/imagecomposition/imagecomposer.h 1 - - \section1 ImageComposer Class Implementation - - We declare a QSize object, \c resultSize, as a static constant with width - and height equal to 200. - - \snippet painting/imagecomposition/imagecomposer.cpp 0 - - Within the constructor, we instantiate a QToolButton object, - \c sourceButton and set its \l{QAbstractButton::setIconSize()}{iconSize} - property to \c resultSize. The \c operatorComboBox is instantiated and - then populated using the \c addOp() function. This function accepts a - QPainter::CompositionMode, \a mode, and a QString, \a name, representing - the name of the composition mode. - - \snippet painting/imagecomposition/imagecomposer.cpp 1 - - The \c destinationButton is instantiated and its - \l{QAbstractButton::setIconSize()}{iconSize} property is set to - \c resultSize as well. The \l{QLabel}s \c equalLabel and \c resultLabel - are created and \c{resultLabel}'s \l{QWidget::setMinimumWidth()} - {minimumWidth} is set. - - \snippet painting/imagecomposition/imagecomposer.cpp 2 - - We connect the following signals to their corresponding slots: - \list - \li \c{sourceButton}'s \l{QPushButton::clicked()}{clicked()} signal is - connected to \c chooseSource(), - \li \c{operatorComboBox}'s \l{QComboBox::activated()}{activated()} - signal is connected to \c recalculateResult(), and - \li \c{destinationButton}'s \l{QToolButton::clicked()}{clicked()} signal - is connected to \c chooseDestination(). - \endlist - - \snippet painting/imagecomposition/imagecomposer.cpp 3 - - A QGridLayout, \c mainLayout, is used to place all the widgets. Note - that \c{mainLayout}'s \l{QLayout::setSizeConstraint()}{sizeConstraint} - property is set to QLayout::SetFixedSize, which means that - \c{ImageComposer}'s size cannot be resized at all. - - \snippet painting/imagecomposition/imagecomposer.cpp 4 - - We create a QImage, \c resultImage, and we invoke \c loadImage() twice - to load both the image files in our \e imagecomposition.qrc file. Then, - we set the \l{QWidget::setWindowTitle()}{windowTitle} property to - "Image Composition". - - \snippet painting/imagecomposition/imagecomposer.cpp 5 - - The \c chooseSource() and \c chooseDestination() functions are - convenience functions that invoke \c chooseImage() with specific - parameters. - - \snippet painting/imagecomposition/imagecomposer.cpp 6 - \codeline - \snippet painting/imagecomposition/imagecomposer.cpp 7 - - The \c chooseImage() function loads an image of the user's choice, - depending on the \a title, \a image, and \a button. - - \snippet painting/imagecomposition/imagecomposer.cpp 10 - - The \c recalculateResult() function is used to calculate amd display the - result of combining the two images together with the user's choice of - composition mode. - - \snippet painting/imagecomposition/imagecomposer.cpp 8 - - The \c addOp() function adds an item to the \c operatorComboBox using - \l{QComboBox}'s \l{QComboBox::addItem()}{addItem} function. This function - accepts a QPainter::CompositionMode, \a mode, and a QString, \a name. The - rectangle is filled with Qt::Transparent and both the \c sourceImage and - \c destinationImage are painted, before displaying it on \c resultLabel. - - \snippet painting/imagecomposition/imagecomposer.cpp 9 - - The \c loadImage() function paints a transparent background using - \l{QPainter::fillRect()}{fillRect()} and draws \c image in a - centralized position using \l{QPainter::drawImage()}{drawImage()}. - This \c image is then set as the \c{button}'s icon. - - \snippet painting/imagecomposition/imagecomposer.cpp 11 - - The \c currentMode() function returns the composition mode currently - selected in \c operatorComboBox. - - \snippet painting/imagecomposition/imagecomposer.cpp 12 - - We use the \c imagePos() function to ensure that images loaded onto the - QToolButton objects, \c sourceButton and \c destinationButton, are - centralized. - - \snippet painting/imagecomposition/imagecomposer.cpp 13 - - \section1 The \c main() Function - - The \c main() function instantiates QApplication and \c ImageComposer - and invokes its \l{QWidget::show()}{show()} function. - - \snippet painting/imagecomposition/main.cpp 0 - - */ diff --git a/examples/widgets/doc/images/itemviewspuzzle-example.png b/examples/widgets/doc/images/itemviewspuzzle-example.png new file mode 100644 index 0000000000..05ae28be81 Binary files /dev/null and b/examples/widgets/doc/images/itemviewspuzzle-example.png differ diff --git a/examples/widgets/doc/imageviewer.qdoc b/examples/widgets/doc/imageviewer.qdoc deleted file mode 100644 index 3556d52f7e..0000000000 --- a/examples/widgets/doc/imageviewer.qdoc +++ /dev/null @@ -1,337 +0,0 @@ -/**************************************************************************** -** -** 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/imageviewer - \title Image Viewer Example - - The example shows how to combine QLabel and QScrollArea to - display an image. QLabel is typically used for displaying text, - but it can also display an image. QScrollArea provides a - scrolling view around another widget. If the child widget exceeds - the size of the frame, QScrollArea automatically provides scroll - bars. - - The example demonstrates how QLabel's ability to scale its - contents (QLabel::scaledContents), and QScrollArea's ability to - automatically resize its contents (QScrollArea::widgetResizable), - can be used to implement zooming and scaling features. In - addition the example shows how to use QPainter to print an image. - - \image imageviewer-example.png Screenshot of the Image Viewer example - - With the Image Viewer application, the users can view an image of - their choice. The \uicontrol File menu gives the user the possibility - to: - - \list - \li \uicontrol{Open...} - Open an image file - \li \uicontrol{Print...} - Print an image - \li \uicontrol{Exit} - Exit the application - \endlist - - Once an image is loaded, the \uicontrol View menu allows the users to: - - \list - \li \uicontrol{Zoom In} - Scale the image up by 25% - \li \uicontrol{Zoom Out} - Scale the image down by 25% - \li \uicontrol{Normal Size} - Show the image at its original size - \li \uicontrol{Fit to Window} - Stretch the image to occupy the entire window - \endlist - - In addition the \uicontrol Help menu provides the users with information - about the Image Viewer example in particular, and about Qt in - general. - - \section1 ImageViewer Class Definition - - \snippet widgets/imageviewer/imageviewer.h 0 - - The \c ImageViewer class inherits from QMainWindow. We reimplement - the constructor, and create several private slots to facilitate - the menu entries. In addition we create four private functions. - - We use \c createActions() and \c createMenus() when constructing - the \c ImageViewer widget. We use the \c updateActions() function - to update the menu entries when a new image is loaded, or when - the \uicontrol {Fit to Window} option is toggled. The zoom slots use \c - scaleImage() to perform the zooming. In turn, \c - scaleImage() uses \c adjustScrollBar() to preserve the focal point after - scaling an image. - - \section1 ImageViewer Class Implementation - - \snippet widgets/imageviewer/imageviewer.cpp 0 - - In the constructor we first create the label and the scroll area. - - We set \c {imageLabel}'s size policy to \l - {QSizePolicy::Ignored}{ignored}, making the users able to scale - the image to whatever size they want when the \uicontrol {Fit to Window} - option is turned on. Otherwise, the default size polizy (\l - {QSizePolicy::Preferred}{preferred}) will make scroll bars appear - when the scroll area becomes smaller than the label's minimum size - hint. - - We ensure that the label will scale its contents to fill all - available space, to enable the image to scale properly when - zooming. If we omitted to set the \c {imageLabel}'s \l - {QLabel::scaledContents}{scaledContents} property, zooming in - would enlarge the QLabel, but leave the pixmap at - its original size, exposing the QLabel's background. - - We make \c imageLabel the scroll area's child widget, and we make - \c scrollArea the central widget of the QMainWindow. At the end - we create the associated actions and menus, and customize the \c - {ImageViewer}'s appearance. - - \snippet widgets/imageviewer/imageviewer.cpp 1 - \snippet widgets/imageviewer/imageviewer.cpp 2 - - In the \c open() slot, we show a file dialog to the user. The - easiest way to create a QFileDialog is to use the static - convenience functions. QFileDialog::getOpenFileName() returns an - existing file selected by the user. If the user presses \uicontrol - Cancel, QFileDialog returns an empty string. - - Unless the file name is a empty string, we check if the file's - format is an image format by constructing a QImage which tries to - load the image from the file. If the constructor returns a null - image, we use a QMessageBox to alert the user. - - The QMessageBox class provides a modal dialog with a short - message, an icon, and some buttons. As with QFileDialog the - easiest way to create a QMessageBox is to use its static - convenience functions. QMessageBox provides a range of different - messages arranged along two axes: severity (question, - information, warning and critical) and complexity (the number of - necessary response buttons). In this particular example an - information message with an \uicontrol OK button (the default) is - sufficient, since the message is part of a normal operation. - - \snippet widgets/imageviewer/imageviewer.cpp 3 - \snippet widgets/imageviewer/imageviewer.cpp 4 - - If the format is supported, we display the image in \c imageLabel - by setting the label's \l {QLabel::pixmap}{pixmap}. Then we enable - the \uicontrol Print and \uicontrol {Fit to Window} menu entries and update - the rest of the view menu entries. The \uicontrol Open and \uicontrol Exit - entries are enabled by default. - - If the \uicontrol {Fit to Window} option is turned off, the - QScrollArea::widgetResizable property is \c false and it is - our responsibility (not QScrollArea's) to give the QLabel a - reasonable size based on its contents. We call - \{QWidget::adjustSize()}{adjustSize()} to achieve this, which is - essentially the same as - - \code - imageLabel->resize(imageLabel->pixmap()->size()); - \endcode - - In the \c print() slot, we first make sure that an image has been - loaded into the application: - - \snippet widgets/imageviewer/imageviewer.cpp 5 - \snippet widgets/imageviewer/imageviewer.cpp 6 - - If the application is built in debug mode, the \c Q_ASSERT() macro - will expand to - - \code - if (!imageLabel->pixmap()) - qFatal("ASSERT: "imageLabel->pixmap()" in file ..."); - \endcode - - In release mode, the macro simply disappear. The mode can be set - in the application's \c .pro file. One way to do so is to add an - option to \uicontrol qmake when building the application: - - \code - qmake "CONFIG += debug" foo.pro - \endcode - - or - - \code - qmake "CONFIG += release" foo.pro - \endcode - - Another approach is to add this line directly to the \c .pro - file. - - \snippet widgets/imageviewer/imageviewer.cpp 7 - \snippet widgets/imageviewer/imageviewer.cpp 8 - - Then we present a print dialog allowing the user to choose a - printer and to set a few options. We construct a painter with a - QPrinter as the paint device. We set the painter's window - and viewport in such a way that the image is as large as possible - on the paper, but without altering its - \l{Qt::KeepAspectRatio}{aspect ratio}. - - In the end we draw the pixmap at position (0, 0). - - \snippet widgets/imageviewer/imageviewer.cpp 9 - \snippet widgets/imageviewer/imageviewer.cpp 10 - - We implement the zooming slots using the private \c scaleImage() - function. We set the scaling factors to 1.25 and 0.8, - respectively. These factor values ensure that a \uicontrol {Zoom In} - action and a \uicontrol {Zoom Out} action will cancel each other (since - 1.25 * 0.8 == 1), and in that way the normal image size can be - restored using the zooming features. - - The screenshots below show an image in its normal size, and the - same image after zooming in: - - \table - \row - \li \inlineimage imageviewer-original_size.png - \li \inlineimage imageviewer-zoom_in_1.png - \li \inlineimage imageviewer-zoom_in_2.png - \endtable - - \snippet widgets/imageviewer/imageviewer.cpp 11 - \snippet widgets/imageviewer/imageviewer.cpp 12 - - When zooming, we use the QLabel's ability to scale its contents. - Such scaling doesn't change the actual size hint of the contents. - And since the \l {QLabel::adjustSize()}{adjustSize()} function - use those size hint, the only thing we need to do to restore the - normal size of the currently displayed image is to call \c - adjustSize() and reset the scale factor to 1.0. - - \snippet widgets/imageviewer/imageviewer.cpp 13 - \snippet widgets/imageviewer/imageviewer.cpp 14 - - The \c fitToWindow() slot is called each time the user toggled - the \uicontrol {Fit to Window} option. If the slot is called to turn on - the option, we tell the scroll area to resize its child widget - with the QScrollArea::setWidgetResizable() function. Then we - disable the \uicontrol {Zoom In}, \uicontrol {Zoom Out} and \uicontrol {Normal - Size} menu entries using the private \c updateActions() function. - - If the \l {QScrollArea::widgetResizable} property is set to \c - false (the default), the scroll area honors the size of its child - widget. If this property is set to \c true, the scroll area will - automatically resize the widget in order to avoid scroll bars - where they can be avoided, or to take advantage of extra space. - But the scroll area will honor the minimum size hint of its child - widget independent of the widget resizable property. So in this - example we set \c {imageLabel}'s size policy to \l - {QSizePolicy::Ignored}{ignored} in the constructor, to avoid that - scroll bars appear when the scroll area becomes smaller than the - label's minimum size hint. - - The screenshots below shows an image in its normal size, and the - same image with the \uicontrol {Fit to window} option turned on. - Enlarging the window will stretch the image further, as shown in - the third screenshot. - - \table - \row - \li \inlineimage imageviewer-original_size.png - \li \inlineimage imageviewer-fit_to_window_1.png - \li \inlineimage imageviewer-fit_to_window_2.png - \endtable - - If the slot is called to turn off the option, the - {QScrollArea::setWidgetResizable} property is set to \c false. We - also restore the image pixmap to its normal size by adjusting the - label's size to its content. And in the end we update the view - menu entries. - - \snippet widgets/imageviewer/imageviewer.cpp 15 - \snippet widgets/imageviewer/imageviewer.cpp 16 - - We implement the \c about() slot to create a message box - describing what the example is designed to show. - - \snippet widgets/imageviewer/imageviewer.cpp 17 - \snippet widgets/imageviewer/imageviewer.cpp 18 - - In the private \c createAction() function, we create the - actions providing the application features. - - We assign a short-cut key to each action and connect them to the - appropriate slots. We only enable the \c openAct and \c exitAct at - the time of creation, the others are updated once an image has - been loaded into the application. In addition we make the \c - fitToWindowAct \l {QAction::checkable}{checkable}. - - \snippet widgets/imageviewer/imageviewer.cpp 19 - \snippet widgets/imageviewer/imageviewer.cpp 20 - - In the private \c createMenu() function, we add the previously - created actions to the \uicontrol File, \uicontrol View and \uicontrol Help menus. - - The QMenu class provides a menu widget for use in menu bars, - context menus, and other popup menus. The QMenuBar class provides - a horizontal menu bar that consists of a list of pull-down menu - items. So at the end we put the menus in the \c {ImageViewer}'s - menu bar which we retrieve with the QMainWindow::menuBar() - function. - - \snippet widgets/imageviewer/imageviewer.cpp 21 - \snippet widgets/imageviewer/imageviewer.cpp 22 - - The private \c updateActions() function enables or disables the - \uicontrol {Zoom In}, \uicontrol {Zoom Out} and \uicontrol {Normal Size} menu - entries depending on whether the \uicontrol {Fit to Window} option is - turned on or off. - - \snippet widgets/imageviewer/imageviewer.cpp 23 - \snippet widgets/imageviewer/imageviewer.cpp 24 - - In \c scaleImage(), we use the \c factor parameter to calculate - the new scaling factor for the displayed image, and resize \c - imageLabel. Since we set the - \l{QLabel::scaledContents}{scaledContents} property to \c true in - the constructor, the call to QWidget::resize() will scale the - image displayed in the label. We also adjust the scroll bars to - preserve the focal point of the image. - - At the end, if the scale factor is less than 33.3% or greater - than 300%, we disable the respective menu entry to prevent the - image pixmap from becoming too large, consuming too much - resources in the window system. - - \snippet widgets/imageviewer/imageviewer.cpp 25 - \snippet widgets/imageviewer/imageviewer.cpp 26 - - Whenever we zoom in or out, we need to adjust the scroll bars in - consequence. It would have been tempting to simply call - - \code - scrollBar->setValue(int(factor * scrollBar->value())); - \endcode - - but this would make the top-left corner the focal point, not the - center. Therefore we need to take into account the scroll bar - handle's size (the \l{QScrollBar::pageStep}{page step}). -*/ diff --git a/examples/widgets/doc/interview.qdoc b/examples/widgets/doc/interview.qdoc deleted file mode 100644 index 35721ccfae..0000000000 --- a/examples/widgets/doc/interview.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/interview - \title Interview - - The Interview example explores the flexibility and scalability of the - model/view framework by presenting an infinitely deep data structure using a model - and three different types of view. - - \image interview-demo.png -*/ diff --git a/examples/widgets/doc/itemviewspuzzle.qdoc b/examples/widgets/doc/itemviewspuzzle.qdoc deleted file mode 100644 index ca8288cf1c..0000000000 --- a/examples/widgets/doc/itemviewspuzzle.qdoc +++ /dev/null @@ -1,43 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/puzzle - \title Item Views Puzzle Example - - The Puzzle example shows how to enable drag and drop with a custom model - to allow items to be transferred between a view and another widget. - - \image itemviewspuzzle-example.png - - This example is an implementation of a simple jigsaw puzzle game using the - built-in support for drag and drop provided by Qt's model/view framework. - The \l{Drag and Drop Puzzle Example}{Drag and Drop Puzzle} example shows - many of the same features, but takes an alternative approach that uses Qt's - drag and drop API at the application level to handle drag and drop - operations. -*/ diff --git a/examples/widgets/doc/licensewizard.qdoc b/examples/widgets/doc/licensewizard.qdoc deleted file mode 100644 index 125e0fec8f..0000000000 --- a/examples/widgets/doc/licensewizard.qdoc +++ /dev/null @@ -1,218 +0,0 @@ -/**************************************************************************** -** -** 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 dialogs/licensewizard - \title License Wizard Example - - The License Wizard example shows how to implement complex wizards in - Qt. - - \image licensewizard-example.png Screenshot of the License Wizard example - - Most wizards have a linear structure, with page 1 followed by - page 2 and so on until the last page. The - \l{dialogs/classwizard}{Class Wizard} example shows how to create - such wizards. - - Some wizards are more complex in that they allow different - traversal paths based on the information provided by the user. - The License Wizard example illustrates this. It provides five - wizard pages; depending on which options are selected, the user - can reach different pages. - - \image licensewizard-flow.png The License Wizard pages - - The example consists of the following classes: - - \list - \li \c LicenseWizard inherits QWizard and implements a non-linear - five-page wizard that leads the user through the process of - choosing a license agreement. - \li \c IntroPage, \c EvaluatePage, \c RegisterPage, \c - DetailsPage, and \c ConclusionPage are QWizardPage subclasses - that implement the wizard pages. - \endlist - - \section1 The LicenseWizard Class - - The \c LicenseWizard class derives from QWizard and provides a - five-page wizard that guides the user through the process of - registering their copy of a fictitious software product. Here's - the class definition: - - \snippet dialogs/licensewizard/licensewizard.h 1 - - The class's public API is limited to a constructor and an enum. - The enum defines the IDs associated with the various pages: - - \table - \header \li Class name \li Enum value \li Page ID - \row \li \c IntroPage \li \c Page_Intro \li 0 - \row \li \c EvaluatePage \li \c Page_Evaluate \li 1 - \row \li \c RegisterPage \li \c Page_Register \li 2 - \row \li \c DetailsPage \li \c Page_Details \li 3 - \row \li \c ConclusionPage \li \c Page_Conclusion \li 4 - \endtable - - For this example, the IDs are arbitrary. The only constraints are - that they must be unique and different from -1. IDs allow us to - refer to pages. - - \snippet dialogs/licensewizard/licensewizard.cpp 2 - - In the constructor, we create the five pages, insert them into - the wizard using QWizard::setPage(), and set \c Page_Intro to be - the first page. - - \snippet dialogs/licensewizard/licensewizard.cpp 3 - \snippet dialogs/licensewizard/licensewizard.cpp 4 - - We set the style to \l{QWizard::}{ModernStyle} on all platforms - except Mac OS X, - - \snippet dialogs/licensewizard/licensewizard.cpp 5 - \snippet dialogs/licensewizard/licensewizard.cpp 6 - - We configure the QWizard to show a \uicontrol Help button, which is - connected to our \c showHelp() slot. We also set the - \l{QWizard::}{LogoPixmap} for all pages that have a header (i.e., - \c EvaluatePage, \c RegisterPage, and \c DetailsPage). - - \snippet dialogs/licensewizard/licensewizard.cpp 9 - \snippet dialogs/licensewizard/licensewizard.cpp 11 - \dots - \snippet dialogs/licensewizard/licensewizard.cpp 13 - - In \c showHelp(), we display help texts that are appropriate for - the current page. If the user clicks \uicontrol Help twice for the same - page, we say, "Sorry, I already gave what help I could. Maybe you - should try asking a human?" - - \section1 The IntroPage Class - - The pages are defined in \c licensewizard.h and implemented in \c - licensewizard.cpp, together with \c LicenseWizard. - - Here's the definition and implementation of \c{IntroPage}: - - \snippet dialogs/licensewizard/licensewizard.h 4 - \codeline - \snippet dialogs/licensewizard/licensewizard.cpp 16 - - A page inherits from QWizardPage. We set a - \l{QWizardPage::}{title} and a - \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting - any \l{QWizardPage::}{subTitle}, we ensure that no header is - displayed for this page. (On Windows, it is customary for wizards - to display a watermark pixmap on the first and last pages, and to - have a header on the other pages.) - - \snippet dialogs/licensewizard/licensewizard.cpp 17 - \snippet dialogs/licensewizard/licensewizard.cpp 19 - - The \c nextId() function returns the ID for \c EvaluatePage if - the \uicontrol{Evaluate the product for 30 days} option is checked; - otherwise it returns the ID for \c RegisterPage. - - \section1 The EvaluatePage Class - - The \c EvaluatePage is slightly more involved: - - \snippet dialogs/licensewizard/licensewizard.h 5 - \codeline - \snippet dialogs/licensewizard/licensewizard.cpp 20 - \dots - \snippet dialogs/licensewizard/licensewizard.cpp 21 - \dots - \snippet dialogs/licensewizard/licensewizard.cpp 22 - - First, we set the page's \l{QWizardPage::}{title} - and \l{QWizardPage::}{subTitle}. - - Then we create the child widgets, create \l{Registering and Using - Fields}{wizard fields} associated with them, and put them into - layouts. The fields are created with an asterisk (\c - *) next to their name. This makes them \l{mandatory fields}, that - is, fields that must be filled before the user can press the - \uicontrol Next button (\uicontrol Continue on Mac OS X). The fields' values - can be accessed from any other page using QWizardPage::field(). - - Resetting the page amounts to clearing the two text fields. - - \snippet dialogs/licensewizard/licensewizard.cpp 23 - - The next page is always the \c ConclusionPage. - - \section1 The ConclusionPage Class - - The \c RegisterPage and \c DetailsPage are very similar to \c - EvaluatePage. Let's go directly to the \c ConclusionPage: - - \snippet dialogs/licensewizard/licensewizard.h 6 - - This time, we reimplement QWizardPage::initializePage() and - QWidget::setVisible(), in addition to - \l{QWizardPage::}{nextId()}. We also declare a private slot: - \c printButtonClicked(). - - \snippet dialogs/licensewizard/licensewizard.cpp 18 - - The default implementation of QWizardPage::nextId() returns - the page with the next ID, or -1 if the current page has the - highest ID. This behavior would work here, because \c - Page_Conclusion equals 5 and there is no page with a higher ID, - but to avoid relying on such subtle behavior, we reimplement - \l{QWizardPage::}{nextId()} to return -1. - - \snippet dialogs/licensewizard/licensewizard.cpp 27 - - We use QWizard::hasVisitedPage() to determine the type of - license agreement the user has chosen. If the user filled the \c - EvaluatePage, the license text refers to an Evaluation License - Agreement. If the user filled the \c DetailsPage, the license - text is a First-Time License Agreement. If the user provided an - upgrade key and skipped the \c DetailsPage, the license text is - an Update License Agreement. - - \snippet dialogs/licensewizard/licensewizard.cpp 28 - - We want to display a \uicontrol Print button in the wizard when the \c - ConclusionPage is up. One way to accomplish this is to reimplement - QWidget::setVisible(): - - \list - \li If the page is shown, we set the \l{QWizard::}{CustomButton1} button's - text to \uicontrol{\underline{P}rint}, we enable the \l{QWizard::}{HaveCustomButton1} - option, and we connect the QWizard's \l{QWizard::}{customButtonClicked()} - signal to our \c printButtonClicked() slot. - \li If the page is hidden, we disable the \l{QWizard::}{HaveCustomButton1} - option and disconnect the \c printButtonClicked() slot. - \endlist - - \sa QWizard, {Class Wizard Example}, {Trivial Wizard Example} -*/ diff --git a/examples/widgets/doc/lighting.qdoc b/examples/widgets/doc/lighting.qdoc deleted file mode 100644 index aafa70f38c..0000000000 --- a/examples/widgets/doc/lighting.qdoc +++ /dev/null @@ -1,33 +0,0 @@ -/**************************************************************************** -** -** 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 effects/lighting - \title Lighting Effect Example - - \image lightingeffect-example.png -*/ diff --git a/examples/widgets/doc/lineedits.qdoc b/examples/widgets/doc/lineedits.qdoc deleted file mode 100644 index c9cb7b5f43..0000000000 --- a/examples/widgets/doc/lineedits.qdoc +++ /dev/null @@ -1,161 +0,0 @@ -/**************************************************************************** -** -** 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/lineedits - \title Line Edits Example - - The Line Edits example demonstrates the many ways that QLineEdit can be used, and - shows the effects of various properties and validators on the input and output - supplied by the user. - - \image lineedits-example.png - - The example consists of a single \c Window class, containing a selection of - line edits with different input constraints and display properties that can be - changed by selecting items from comboboxes. Presenting these together helps - developers choose suitable properties to use with line edits, and makes it easy - to compare the effects of each validator on user input. - - \section1 Window Class Definition - - The \c Window class inherits QWidget and contains a constructor and several - slots: - - \snippet widgets/lineedits/window.h 0 - - The slots are used to update the type of validator used for a given line edit when - a new validator has been selected in the associated combobox. The line edits - are stored in the window for use in these slots. - - \section1 Window Class Implementation - - The \c Window constructor is used to set up the line edits, validators, - and comboboxes, connect signals from the comboboxes to slots in the \c Window - class, and arrange the child widgets in layouts. - - We begin by constructing a \l{QGroupBox}{group box} to hold a label, combobox, - and line edit so that we can demonstrate the QLineEdit::echoMode property: - - \snippet widgets/lineedits/window.cpp 0 - - At this point, none of these widgets have been arranged in layouts. Eventually, - the \c echoLabel, \c echoComboBox, and \c echoLineEdit will be placed in a - vertical layout inside the \c echoGroup group box. - - Similarly, we construct group boxes and collections of widgets to show the - effects of QIntValidator and QDoubleValidator on a line edit's contents: - - \snippet widgets/lineedits/window.cpp 1 - - Text alignment is demonstrated by another group of widgets: - - \snippet widgets/lineedits/window.cpp 2 - - QLineEdit supports the use of \l{QLineEdit::inputMask}{input masks}. - These only allow the user to type characters into the line edit that - follow a simple specification. We construct a group of widgets to - demonstrate a selection of predefined masks: - - \snippet widgets/lineedits/window.cpp 3 - - Another useful feature of QLineEdit is its ability to make its contents - read-only. This property is used to control access to a line edit in the - following group of widgets: - - \snippet widgets/lineedits/window.cpp 4 - - Now that all the child widgets have been constructed, we connect signals - from the comboboxes to slots in the \c Window object: - - \snippet widgets/lineedits/window.cpp 5 - - Each of these connections use the QComboBox::activated() signal that - supplies an integer to the slot. This will be used to efficiently - make changes to the appropriate line edit in each slot. - - We place each combobox, line edit, and label in a layout for each group - box, beginning with the layout for the \c echoGroup group box: - - \snippet widgets/lineedits/window.cpp 6 - - The other layouts are constructed in the same way: - - \snippet widgets/lineedits/window.cpp 7 - - Finally, we place each group box in a grid layout for the \c Window object - and set the window title: - - \snippet widgets/lineedits/window.cpp 8 - - The slots respond to signals emitted when the comboboxes are changed by the - user. - - When the combobox for the \uicontrol{Echo} group box is changed, the \c echoChanged() - slot is called: - - \snippet widgets/lineedits/window.cpp 9 - - The slot updates the line edit in the same group box to use an echo mode that - corresponds to the entry described in the combobox. - - When the combobox for the \uicontrol{Validator} group box is changed, the - \c validatorChanged() slot is called: - - \snippet widgets/lineedits/window.cpp 10 - - The slot either creates a new validator for the line edit to use, or it removes - the validator in use by calling QLineEdit::setValidator() with a zero pointer. - We clear the line edit in this case to ensure that the new validator is - initially given valid input to work with. - - When the combobox for the \uicontrol{Alignment} group box is changed, the - \c alignmentChanged() slot is called: - - \snippet widgets/lineedits/window.cpp 11 - - This changes the way that text is displayed in the line edit to correspond with - the description selected in the combobox. - - The \c inputMaskChanged() slot handles changes to the combobox in the - \uicontrol{Input Mask} group box: - - \snippet widgets/lineedits/window.cpp 12 - - Each entry in the relevant combobox is associated with an input mask. We set - a new mask by calling the QLineEdit::setMask() function with a suitable string; - the mask is disabled if an empty string is used. - - The \c accessChanged() slot handles changes to the combobox in the - \uicontrol{Access} group box: - - \snippet widgets/lineedits/window.cpp 13 - - Here, we simply associate the \uicontrol{False} and \uicontrol{True} entries in the combobox - with \c false and \c true values to be passed to QLineEdit::setReadOnly(). This - allows the user to enable and disable input to the line edit. -*/ diff --git a/examples/widgets/doc/mainwindow.qdoc b/examples/widgets/doc/mainwindow.qdoc deleted file mode 100644 index b4f6aebed1..0000000000 --- a/examples/widgets/doc/mainwindow.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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 mainwindows/mainwindow - \title Main Window - - The Main Window example shows Qt's extensive support for tool bars, - dock windows, menus, and other standard application features. - - \image mainwindow-demo.png -*/ diff --git a/examples/widgets/doc/mdi.qdoc b/examples/widgets/doc/mdi.qdoc deleted file mode 100644 index e8b1b5c9ef..0000000000 --- a/examples/widgets/doc/mdi.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** 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 mainwindows/mdi - \title MDI Example - - The MDI example shows how to implement a Multiple Document Interface using Qt's - QMdiArea class. - - \image mdi-example.png - -*/ diff --git a/examples/widgets/doc/menus.qdoc b/examples/widgets/doc/menus.qdoc deleted file mode 100644 index 3531e439c1..0000000000 --- a/examples/widgets/doc/menus.qdoc +++ /dev/null @@ -1,218 +0,0 @@ -/**************************************************************************** -** -** 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 mainwindows/menus - \title Menus Example - - The Menus example demonstrates how menus can be used in a main - window application. - - A menu widget can be either a pull-down menu in a menu bar or a - standalone context menu. Pull-down menus are shown by the menu bar - when the user clicks on the respective item or presses the - specified shortcut key. Context menus are usually invoked by some - special keyboard key or by right-clicking. - - \image menus-example.png - - A menu consists of a list of \e action items. In applications, - many common commands can be invoked via menus, toolbar buttons as - well as keyboard shortcuts. Since the user expects the commands to - be performed in the same way, regardless of the user interface - used, it is useful to represent each command as an action. - - The Menus example consists of one single class, \c MainWindow, derived - from the QMainWindow class. When choosing one of the - action items in our application, it will display the item's path - in its central widget. - - \section1 MainWindow Class Definition - - QMainWindow provides a main application window, with a menu bar, - tool bars, dock widgets and a status bar around a large central - widget. - - \snippet mainwindows/menus/mainwindow.h 0 - - In this example, we will see how to implement pull-down menus as - well as a context menu. In order to implement a custom context - menu we must reimplement QWidget's \l - {QWidget::}{contextMenuEvent()} function to receive the context - menu events for our main window. - - \snippet mainwindows/menus/mainwindow.h 1 - - We must also implement a collection of private slots to respond to - the user activating any of our menu entries. Note that these - slots are left out of this documentation since they are trivial, - i.e., most of them are only displaying the action's path in the - main window's central widget. - - \snippet mainwindows/menus/mainwindow.h 2 - - We have chosen to simplify the constructor by implementing two - private convenience functions to create the various actions, to - add them to menus and to insert the menus into our main window's - menu bar. - - \snippet mainwindows/menus/mainwindow.h 3 - - Finally, we declare the various menus and actions as well as a - simple information label in the application wide scope. - - The QMenu class provides a menu widget for use in menu bars, - context menus, and other popup menus while the QAction class - provides an abstract user interface action that can be inserted - into widgets. - - In some situations it is useful to group actions together, e.g., - we have a \uicontrol {Left Align} action, a \uicontrol {Right Align} action, a - \uicontrol {Justify} action, and a \uicontrol {Center} action, and we want - only one of these actions to be active at any one time. One simple - way of achieving this is to group the actions together in an - action group using the QActionGroup class. - - \section1 MainWindow Class Implementation - - In the constructor, we start off by creating a regular QWidget and - make it our main window's central widget. Note that the main - window takes ownership of the widget pointer and deletes it at the - appropriate time. - - \snippet mainwindows/menus/mainwindow.cpp 0 - \codeline - \snippet mainwindows/menus/mainwindow.cpp 1 - - Then we create the information label as well as a top and bottom - filler that we add to a layout which we install on the central - widget. QMainWindow objects come with their own customized layout - and setting a layout on a the actual main window, or creating a - layout with a main window as a parent, is considered an error. You - should always set your own layout on the central widget instead. - - \snippet mainwindows/menus/mainwindow.cpp 2 - - To create the actions and menus we call our two convenience - functions: \c createActions() and \c createMenus(). We will get - back to these shortly. - - QMainWindow's \l {QMainWindow::statusBar()}{statusBar()} function - returns the status bar for the main window (if the status bar does - not exist, this function will create and return an empty status - bar). We initialize the status bar and window title, resize the - window to an appropriate size as well as ensure that the main - window cannot be resized to a smaller size than the given - one. - - Now, let's take a closer look at the \c createActions() convenience - function that creates the various actions: - - \snippet mainwindows/menus/mainwindow.cpp 4 - \dots - - A QAction object may contain an icon, a text, a shortcut, a status - tip, a "What's This?" text, and a tooltip. Most of these can be - set in the constructor, but they can also be set independently - using the provided convenience functions. - - In the \c createActions() function, we first create a \c newAct - action. We make \uicontrol Ctrl+N its shortcut using the - QAction::setShortcut() function, and we set its status tip using the - QAction::setStatusTip() function (the status tip is displayed on all - status bars provided by the action's top-level parent widget). We - also connect its \l {QAction::}{triggered()} signal to the \c - newFile() slot. - - The rest of the actions are created in a similar manner. Please - see the source code for details. - - \snippet mainwindows/menus/mainwindow.cpp 7 - - - Once we have created the \uicontrol {Left Align}, \uicontrol {Right Align}, - \uicontrol {Justify}, and a \uicontrol {Center} actions, we can also create - the previously mentioned action group. - - Each action is added to the group using QActionGroup's \l - {QActionGroup::}{addAction()} function. Note that an action also - can be added to a group by creating it with the group as its - parent. Since an action group is exclusive by default, only one of - the actions in the group is checked at any one time (this can be - altered using the QActionGroup::setExclusive() function). - - When all the actions are created, we use the \c createMenus() - function to add the actions to the menus and to insert the menus - into the menu bar: - - \snippet mainwindows/menus/mainwindow.cpp 8 - - QMenuBar's \l {QMenuBar::addMenu()}{addMenu()} function appends a - new QMenu with the given title, to the menu bar (note that the - menu bar takes ownership of the menu). We use QWidget's \l - {QWidget::addAction()}{addAction()} function to add each action to - the corresponding menu. - - Alternatively, the QMenu class provides several \l - {QMenu::addAction()}{addAction()} convenience functions that create - and add new actions from given texts and/or icons. You can also - provide a member that will automatically connect to the new - action's \l {QAction::triggered()}{triggered()} signal, and a - shortcut represented by a QKeySequence instance. - - The QMenu::addSeparator() function creates and returns a new - separator action, i.e. an action for which QAction::isSeparator() - returns true, and adds the new action to the menu's list of - actions. - - \snippet mainwindows/menus/mainwindow.cpp 12 - - Note the \uicontrol Format menu. First of all, it is added as a submenu - to the \uicontrol Edit Menu using QMenu's \l - {QMenu::addMenu()}{addMenu()} function. Secondly, take a look at the - alignment actions: In the \c createActions() function we added the - \c leftAlignAct, \c rightAlignAct, \c justifyAct and \c centerAct - actions to an action group. Nevertheless, we must add each action - to the menu separately while the action group does its magic - behind the scene. - - \snippet mainwindows/menus/mainwindow.cpp 3 - - To provide a custom context menu, we must reimplement QWidget's \l - {QWidget::}{contextMenuEvent()} function to receive the widget's - context menu events (note that the default implementation simply - ignores these events). - - Whenever we receive such an event, we create a menu containing the - \uicontrol Cut, \uicontrol Copy and \uicontrol Paste actions. Context menus can be - executed either asynchronously using the \l {QMenu::}{popup()} - function or synchronously using the \l {QMenu::}{exec()} - function. In this example, we have chosen to show the menu using - its \l {QMenu::}{exec()} function. By passing the event's position - as argument we ensure that the context menu appears at the - expected position. -*/ diff --git a/examples/widgets/doc/moveblocks.qdoc b/examples/widgets/doc/moveblocks.qdoc deleted file mode 100644 index 8c12280989..0000000000 --- a/examples/widgets/doc/moveblocks.qdoc +++ /dev/null @@ -1,214 +0,0 @@ -/**************************************************************************** -** -** 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 animation/moveblocks - \title Move Blocks Example - - The Move Blocks example shows how to animate items in a - QGraphicsScene using a QStateMachine with a custom transition. - - \image moveblocks-example.png - - The example animates the blue blocks that you can see in the image - above. The animation moves the blocks between four preset positions. - - The example consists of the following classes: - - \list - \li \c StateSwitcher inherits QState and can add - \c {StateSwitchTransition}s to other states. - When entered, it will randomly transition to one of these - states. - \li \c StateSwitchTransition is a custom transition that - triggers on \c{StateSwitchEvent}s. - \li \c StateSwitchEvent is a QEvent that triggers \c{StateSwitchTransition}s. - \li \c QGraphicsRectWidget is a QGraphicsWidget that simply - paints its background in a solid \l{Qt::}{blue} color. - \endlist - - The blocks are instances of \c QGraphicsRectWidget and are - animated in a QGraphicsScene. We do this by building a state - graph, which we insert animations into. The graph is then executed - in a QStateMachine. All this is done in \c main(). - Let's look at the \c main() function first. - - \section1 The \c main() Function - - After QApplication has been initialized, we set up the - QGraphicsScene with its \c{QGraphicsRectWidget}s. - - \snippet animation/moveblocks/main.cpp 1 - - After adding the scene to a QGraphicsView, it is time to build the - state graph. Let's first look at a statechart of what we are - trying to build. - - \image move-blocks-chart.png - - Note that the \c group has seven sub states, but we have only - included three of them in the diagram. The code that builds this - graph will be examined line-by-line, and will show how the graph - works. First off, we construct the \c group state: - - \snippet animation/moveblocks/main.cpp 2 - - The timer is used to add a delay between each time the blocks are - moved. The timer is started when \c group is entered. As we will - see later, \c group has a transition back to the \c StateSwitcher - when the timer times out. \c group is the initial state in the - machine, so an animation will be scheduled when the example is - started. - - \snippet animation/moveblocks/main.cpp 3 - \dots - \snippet animation/moveblocks/main.cpp 4 - - \c createGeometryState() returns a QState that will set the - geometry of our items upon entry. It also assigns \c group as the - parent of this state. - - A QPropertyAnimation inserted into a transition will use the - values assigned to a QState (with QState::assignProperty()), i.e., - the animation will interpolate between the current values of the - properties and the values in the target state. We add animated - transitions to the state graph later. - - \snippet animation/moveblocks/main.cpp 5 - - We move the items in parallel. Each item is added to \c - animationGroup, which is the animation that is inserted into the - transitions. - - \snippet animation/moveblocks/main.cpp 6 - - The sequential animation group, \c subGroup, helps us insert a - delay between the animation of each item. - - \snippet animation/moveblocks/main.cpp 7 - \dots - \snippet animation/moveblocks/main.cpp 8 - - A StateSwitchTransition is added to the state switcher - in \c StateSwitcher::addState(). We also add the animation in this - function. Since QPropertyAnimation uses the values from the - states, we can insert the same QPropertyAnimation instance in all - \c {StateSwitchTransition}s. - - As mentioned previously, we add a transition to the state switcher - that triggers when the timer times out. - - \snippet animation/moveblocks/main.cpp 9 - - Finally, we can create the state machine, add our initial state, - and start execution of the state graph. - - \section2 The \c createGeometryState() Function - - In \c createGeometryState(), we set up the geometry for each - graphics item. - - \snippet animation/moveblocks/main.cpp 13 - - As mentioned before, QAbstractTransition will set up an animation - added with \l{QAbstractTransition::}{addAnimation()} using - property values set with \l{QState::}{assignProperty()}. - - \section1 The StateSwitcher Class - - \c StateSwitcher has state switch transitions to each \l{QState}s - we created with \c createGeometryState(). Its job is to transition - to one of these states at random when it is entered. - - All functions in \c StateSwitcher are inlined. We'll step through - its definition. - - \snippet animation/moveblocks/main.cpp 10 - - \c StateSwitcher is a state designed for a particular purpose and - will always be a top-level state. We use \c m_stateCount to keep - track of how many states we are managing, and \c m_lastIndex to - remember which state was the last state to which we transitioned. - - \snippet animation/moveblocks/main.cpp 11 - - We select the next state we are going to transition to, and post a - \c StateSwitchEvent, which we know will trigger the \c - StateSwitchTransition to the selected state. - - \snippet animation/moveblocks/main.cpp 12 - - This is where the magic happens. We assign a number to each state - added. This number is given to both a StateSwitchTransition and to - StateSwitchEvents. As we have seen, state switch events will - trigger a transition with the same number. - - \section1 The StateSwitchTransition Class - - \c StateSwitchTransition inherits QAbstractTransition and triggers - on \c{StateSwitchEvent}s. It contains only inline functions, so - let's take a look at its \l{QAbstractTransition::}{eventTest()} - function, which is the only function that we define.. - - \snippet animation/moveblocks/main.cpp 14 - - \c eventTest is called by QStateMachine when it checks whether a - transition should be triggered--a return value of true means that - it will. We simply check if our assigned number is equal to the - event's number (in which case we fire away). - - \section1 The StateSwitchEvent Class - - \c StateSwitchEvent inherits QEvent, and holds a number that has - been assigned to a state and state switch transition by - \c StateSwitcher. We have already seen how it is used to trigger - \c{StateSwitchTransition}s in \c StateSwitcher. - - \snippet animation/moveblocks/main.cpp 15 - - We only have inlined functions in this class, so a look at its - definition will do. - - \section1 The QGraphicsRectWidget Class - - QGraphicsRectWidget inherits QGraphicsWidget and simply paints its - \l{QWidget::}{rect()} blue. We inline \l{QWidget::}{paintEvent()}, - which is the only function we define. Here is the - QGraphicsRectWidget class definition: - - \snippet animation/moveblocks/main.cpp 16 - - \section1 Moving On - - The technique shown in this example works equally well for all - \l{QPropertyAnimation}s. As long as the value to be animated is a - Qt property, you can insert an animation of it into a state graph. - - QState::addAnimation() takes a QAbstractAnimation, so any type - of animation can be inserted into the graph. -*/ - diff --git a/examples/widgets/doc/movie.qdoc b/examples/widgets/doc/movie.qdoc deleted file mode 100644 index e636ce5902..0000000000 --- a/examples/widgets/doc/movie.qdoc +++ /dev/null @@ -1,38 +0,0 @@ -/**************************************************************************** -** -** 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/movie - \title Movie Example - - The Movie example demonstrates how to use QMovie and QLabel to - display animations. QMovie is mostly useful if one wants to play - a simple animation without the added complexity of a multimedia - framework to install and deploy. - - \image movie-example.png -*/ diff --git a/examples/widgets/doc/orderform.qdoc b/examples/widgets/doc/orderform.qdoc deleted file mode 100644 index ed40c65093..0000000000 --- a/examples/widgets/doc/orderform.qdoc +++ /dev/null @@ -1,364 +0,0 @@ -/**************************************************************************** -** -** 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 richtext/orderform - \title Order Form Example - - The Order Form example shows how to generate rich text documents by - combining a simple template with data input by the user in a dialog. Data - is extracted from a \c DetailsDialog object and displayed on a QTextEdit - with a QTextCursor, using various formats. Each form generated is added - to a QTabWidget for easy access. - - \image orderform-example.png - - \section1 DetailsDialog Definition - - The \c DetailsDialog class is a subclass of QDialog, implementing a slot - \c verify() to allow contents of the \c DetailsDialog to be verified later. - This is further explained in \c DetailsDialog Implementation. - - \snippet richtext/orderform/detailsdialog.h 0 - - The constructor of \c DetailsDialog accepts parameters \a title and - \a parent. The class defines four \e{getter} functions: \c orderItems(), - \c senderName(), \c senderAddress(), and \c sendOffers() to allow data - to be accessed externally. - - The class definition includes input widgets for the required - fields, \c nameEdit and \c addressEdit. Also, a QCheckBox and a - QDialogButtonBox are defined; the former to provide the user with the - option to receive information on products and offers, and the latter - to ensure that buttons used are arranged according to the user's native - platform. In addition, a QTableWidget, \c itemsTable, is used to hold - order details. - - The screenshot below shows the \c DetailsDialog we intend to create. - - \image orderform-example-detailsdialog.png - - \section1 DetailsDialog Implementation - - The constructor of \c DetailsDialog instantiates the earlier defined fields - and their respective labels. The label for \c offersCheckBox is set and the - \c setupItemsTable() function is invoked to setup and populate - \c itemsTable. The QDialogButtonBox object, \c buttonBox, is instantiated - with \uicontrol OK and \uicontrol Cancel buttons. This \c buttonBox's \c accepted() and - \c rejected() signals are connected to the \c verify() and \c reject() - slots in \c DetailsDialog. - - \snippet richtext/orderform/detailsdialog.cpp 0 - - A QGridLayout is used to place all the objects on the \c DetailsDialog. - - \snippet richtext/orderform/detailsdialog.cpp 1 - - The \c setupItemsTable() function instantiates the QTableWidget object, - \c itemsTable, and sets the number of rows based on the QStringList - object, \c items, which holds the type of items ordered. The number of - columns is set to 2, providing a "name" and "quantity" layout. A \c for - loop is used to populate the \c itemsTable and the \c name item's flag - is set to Qt::ItemIsEnabled or Qt::ItemIsSelectable. For demonstration - purposes, the \c quantity item is set to a 1 and all items in the - \c itemsTable have this value for quantity; but this can be modified by - editing the contents of the cells at run time. - - \snippet richtext/orderform/detailsdialog.cpp 2 - - The \c orderItems() function extracts data from the \c itemsTable and - returns it in the form of a QList> where each QPair - corresponds to an item and the quantity ordered. - - \snippet richtext/orderform/detailsdialog.cpp 3 - - The \c senderName() function is used to return the value of the QLineEdit - used to store the name field for the order form. - - \snippet richtext/orderform/detailsdialog.cpp 4 - - The \c senderAddress() function is used to return the value of the - QTextEdit containing the address for the order form. - - \snippet richtext/orderform/detailsdialog.cpp 5 - - The \c sendOffers() function is used to return a \c true or \c false - value that is used to determine if the customer in the order form - wishes to receive more information on the company's offers and promotions. - - \snippet richtext/orderform/detailsdialog.cpp 6 - - The \c verify() function is an additionally implemented slot used to - verify the details entered by the user into the \c DetailsDialog. If - the details entered are incomplete, a QMessageBox is displayed - providing the user the option to discard the \c DetailsDialog. Otherwise, - the details are accepted and the \c accept() function is invoked. - - \snippet richtext/orderform/detailsdialog.cpp 7 - - \section1 MainWindow Definition - - The \c MainWindow class is a subclass of QMainWindow, implementing two - slots - \c openDialog() and \c printFile(). It also contains a private - instance of QTabWidget, \c letters. - - \snippet richtext/orderform/mainwindow.h 0 - - \section1 MainWindow Implementation - - The \c MainWindow constructor sets up the \c fileMenu and the required - actions, \c newAction and \c printAction. These actions' \c triggered() - signals are connected to the additionally implemented openDialog() slot - and the default close() slot. The QTabWidget, \c letters, is - instantiated and set as the window's central widget. - - \snippet richtext/orderform/mainwindow.cpp 0 - - The \c createLetter() function creates a new QTabWidget with a QTextEdit, - \c editor, as the parent. This function accepts four parameters that - correspond to we obtained through \c DetailsDialog, in order to "fill" - the \c editor. - - \snippet richtext/orderform/mainwindow.cpp 1 - - We then obtain the cursor for the \c editor using QTextEdit::textCursor(). - The \c cursor is then moved to the start of the document using - QTextCursor::Start. - - \snippet richtext/orderform/mainwindow.cpp 2 - - Recall the structure of a \l{Rich Text Document Structure} - {Rich Text Document}, where sequences of frames and - tables are always separated by text blocks, some of which may contain no - information. - - In the case of the Order Form Example, the document structure for this portion - is described by the table below: - - \table - \row - \li {1, 8} frame with \e{referenceFrameFormat} - \row - \li block \li \c{A company} - \row - \li block - \row - \li block \li \c{321 City Street} - \row - \li block - \row - \li block \li \c{Industry Park} - \row - \li block - \row - \li block \li \c{Another country} - \endtable - - This is accomplished with the following code: - - \snippet richtext/orderform/mainwindow.cpp 3 - - Note that \c topFrame is the \c {editor}'s top-level frame and is not shown - in the document structure. - - We then set the \c{cursor}'s position back to its last position in - \c topFrame and fill in the customer's name (provided by the constructor) - and address - using a \c foreach loop to traverse the QString, \c address. - - \snippet richtext/orderform/mainwindow.cpp 4 - - The \c cursor is now back in \c topFrame and the document structure for - the above portion of code is: - - \table - \row - \li block \li \c{Donald} - \row - \li block \li \c{47338 Park Avenue} - \row - \li block \li \c{Big City} - \endtable - - For spacing purposes, we invoke \l{QTextCursor::insertBlock()} - {insertBlock()} twice. The \l{QDate::currentDate()}{currentDate()} is - obtained and displayed. We use \l{QTextFrameFormat::setWidth()} - {setWidth()} to increase the width of \c bodyFrameFormat and we insert - a new frame with that width. - - \snippet richtext/orderform/mainwindow.cpp 5 - - The following code inserts standard text into the order form. - - \snippet richtext/orderform/mainwindow.cpp 6 - \snippet richtext/orderform/mainwindow.cpp 7 - - This part of the document structure now contains the date, a frame with - \c bodyFrameFormat, as well as the standard text. - - \table - \row - \li block - \row - \li block - \row - \li block \li \c{Date: 25 May 2007} - \row - \li block - \row - \li {1, 4} frame with \e{bodyFrameFormat} - \row - \li block \li \c{I would like to place an order for the following items:} - \row - \li block - \row - \li block - \endtable - - A QTextTableFormat object, \c orderTableFormat, is used to hold the type - of item and the quantity ordered. - - \snippet richtext/orderform/mainwindow.cpp 8 - - We use \l{QTextTable::cellAt()}{cellAt()} to set the headers for the - \c orderTable. - - \snippet richtext/orderform/mainwindow.cpp 9 - - Then, we iterate through the QList of QPair objects to populate - \c orderTable. - - \snippet richtext/orderform/mainwindow.cpp 10 - - The resulting document structure for this section is: - - \table - \row - \li {1, 11} \c{orderTable} with \e{orderTableFormat} - \row - \li block \li \c{Product} - \row - \li block \li \c{Quantity} - \row - \li block \li \c{T-shirt} - \row - \li block \li \c{4} - \row - \li block \li \c{Badge} - \row - \li block \li \c{3} - \row - \li block \li \c{Reference book} - \row - \li block \li \c{2} - \row - \li block \li \c{Coffee cup} - \row - \li block \li \c{5} - \endtable - - The \c cursor is then moved back to \c{topFrame}'s - \l{QTextFrame::lastPosition()}{lastPosition()} and more standard text - is inserted. - - \snippet richtext/orderform/mainwindow.cpp 11 - \snippet richtext/orderform/mainwindow.cpp 12 - - Another QTextTable is inserted, to display the customer's - preference regarding offers. - - \snippet richtext/orderform/mainwindow.cpp 13 - - The document structure for this portion is: - - \table - \row - \li block - \row - \li block\li \c{Please update my...} - \row - \li {1, 5} block - \row - \li {1, 4} \c{offersTable} - \row - \li block \li \c{I want to receive...} - \row - \li block \li \c{I do not want to receive...} - \row - \li block \li \c{X} - \endtable - - The \c cursor is moved to insert "Sincerely" along with the customer's - name. More blocks are inserted for spacing purposes. The \c printAction - is enabled to indicate that an order form can now be printed. - - \snippet richtext/orderform/mainwindow.cpp 14 - - The bottom portion of the document structure is: - - \table - \row - \li block - \row - \li {1, 5} block\li \c{Sincerely,} - \row - \li block - \row - \li block - \row - \li block - \row - \li block \li \c{Donald} - \endtable - - The \c createSample() function is used for illustration purposes, to create - a sample order form. - - \snippet richtext/orderform/mainwindow.cpp 15 - - The \c openDialog() function opens a \c DetailsDialog object. If the - details in \c dialog are accepted, the \c createLetter() function is - invoked using the parameters extracted from \c dialog. - - \snippet richtext/orderform/mainwindow.cpp 16 - - In order to print out the order form, a \c printFile() function is - included, as shown below: - - \snippet richtext/orderform/mainwindow.cpp 17 - - This function also allows the user to print a selected area with - QTextCursor::hasSelection(), instead of printing the entire document. - - \section1 \c main() Function - - The \c main() function instantiates \c MainWindow and sets its size to - 640x480 pixels before invoking the \c show() function and - \c createSample() function. - - \snippet richtext/orderform/main.cpp 0 - -*/ diff --git a/examples/widgets/doc/padnavigator.qdoc b/examples/widgets/doc/padnavigator.qdoc deleted file mode 100644 index 8b1da516b5..0000000000 --- a/examples/widgets/doc/padnavigator.qdoc +++ /dev/null @@ -1,583 +0,0 @@ -/**************************************************************************** -** -** 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 graphicsview/padnavigator - \title Pad Navigator Example - - The Pad Navigator Example shows how you can use Graphics View together with - embedded widgets and Qt's \l{State Machine Framework} to create a simple - but useful, dynamic, animated user interface. - - \image padnavigator-example.png - - The interface consists of a flippable, rotating pad with icons that can be - selected using the arrow keys on your keyboard or keypad. Pressing enter - will flip the pad around and reveal its back side, which has a form - embedded into a QGraphicsProxyWidget. You can interact with the form, and - press the enter key to flip back to the front side of the pad at any time. - - Graphics View provides the QGraphicsScene class for managing and - interacting with a large number of custom-made 2D graphical items derived - from the QGraphicsItem class, and a QGraphicsView widget for visualizing - the items, with support for zooming and rotation. - - This example consists of a \c RoundRectItem class, a \c FlippablePad class, - a \c PadNavigator class, a \c SplashItem class, and a \c main() function. - - \section1 RoundRectItem Class Definition - - The \c RoundRectItem class is used by itself to display the icons on the - pad, and as a base class for \c FlippablePad, the class for the pad itself. - The role of the class is to paint a round rectangle of a specified size and - gradient color, and optionally to paint a pixmap icon on top. To support \c - FlippablePad it also allows filling its contents with a plain window - background color. - - Let's start by reviewing the \c RoundRectItem class declaration. - - \snippet graphicsview/padnavigator/roundrectitem.h 0 - - \c RoundRectItem inherits QGraphicsObject, which makes it easy to control - its properties using QPropertyAnimation. Its constructor takes a rectangle - to determine its bounds, and a color. - - Besides implementing the mandatory \l{QGraphicsItem::paint()}{paint()} and - \l{QGraphicsItem::boundingRect()}{boundingRect()} pure virtual functions, - it also provides the \c pixmap and \c fill properties. - - The \c pixmap property sets an optional pixmap that is drawn on top of the - round rectangle. The \c fill property will, when true, fill the round - rectangle contents with a fixed QPalette::Window background color. - Otherwise the contents are filled using a gradient based on the color - passed to \c RoundRectItem's constructor. - - \snippet graphicsview/padnavigator/roundrectitem.h 1 - - The private data members are: - - \list - \li \c pix: The optional pixmap that is drawn on top of the rectangle. - \li \c fillRect: Corresponds to the \c fill property. - \li \c color: The configurable gradient color fill of the rectangle. - \li \c bounds: The bounds of the rectangle. - \li \c gradient: A precalculated gradient used to fill the rectangle. - \endlist - - We will now review the \c RoundRectItem implementation. Let's start by - looking at its constructor: - - \snippet graphicsview/padnavigator/roundrectitem.cpp 0 - - The constructor initializes its member variables and forwards the \c parent - argument to QGraphicsObject's constructor. It then constructs the linear - gradient that is used in \l{QGraphicsItem::paint()}{paint()} to draw the - round rectangle's gradient background. The linear gradient's starting point - is at the top-left corner of the bounds, and the end is at the bottom-left - corner. The start color is identical to the color passed as an argument, - and a slightly darker color is chosen for the final stop. - - We store this gradient as a member variable to avoid having to recreate the - gradient every time the item is repainted. - - Finally we set the cache mode - \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache}. This mode - causes the item's rendering to be cached into an off-screen pixmap that - remains persistent as we move and transform the item. This mode is ideal - for this example, and works particularly well with OpenGL and OpenGL ES. - - \snippet graphicsview/padnavigator/roundrectitem.cpp 1 - - The \c pixmap property implementation simple returns the member pixmap, or - sets it and then calls \l{QGraphicsItem::update()}{update()}. - - \snippet graphicsview/padnavigator/roundrectitem.cpp 2 - - As the \l{QGraphicsItem::paint()}{paint()} implementation below draws a - simple drop shadow down and to the right of the item, we return a slightly - adjusted rectangle from \l{QGraphicsItem::boundingRect()}{boundingRect()}. - - \snippet graphicsview/padnavigator/roundrectitem.cpp 3 - - The \l{QGraphicsItem::paint()}{paint()} implementation starts by rendering - a semi transparent black round rectangle drop shadow, two units down and to - the right of the main item. - - \snippet graphicsview/padnavigator/roundrectitem.cpp 4 - - We then draw the "foreground" round rectangle itself. The fill depends on - the \c fill property; if true, we will with a plain QPalette::Window color. - We get the current brush from QApplication::palette(). We assign a single - unit wide pen for the stroke, assign the brush, and then draw the - rectangle. - - \snippet graphicsview/padnavigator/roundrectitem.cpp 5 - - If a pixmap has been assigned to the \e pixmap property, we draw this - pixmap in the center of the rectangle item. The pixmaps are scaled to match - the size of the icons; in arguably a better approach would have been to - store the icons with the right size in the first places. - - \snippet graphicsview/padnavigator/roundrectitem.cpp 6 - - Finally, for completeness we include the \c fill property implementation. - It returns the \c fill member variable's value, and when assigned to, it - calls \l{QGraphicsItem::update()}{update()}. - - As mentioned already, \c RoundRectItem is the base class for \c - FlippablePad, which is the class representing the tilting pad itself. We - will proceed to reviewing \c FlippablePad. - - \section1 FlippablePad Class Definition - - \c FlippablePad is, in addition to its inherited \c RoundRectItem - responsibilities, responsible for creating and managing a grid of icons. - - \snippet graphicsview/padnavigator/flippablepad.h 0 - - Its declaration is very simple: It inherits \c RoundRectItem and does not - need any special polymorphic behavior. It's suitable to declare its own - constructor, and a getter-function that allows \c PadNavigator to access - the icons in the grid by (row, column). - - The example has no "real" behavior or logic of any kind, and because of - that, the icons do not need to provide any \e behavior or special - interactions management. In a real application, however, it would be - natural for the \c FlippablePad and its icons to handle more of the - navigation logic. In this example, we have chosen to leave this to - the \c PadNavigator class, which we will get back to below. - - We will now review the \c FlippablePad implementation. This implementation - starts with two helper functions: \c boundsFromSize() and \c - posForLocation(): - - \snippet graphicsview/padnavigator/flippablepad.cpp 0 - - \c boundsForSize() takes a QSize argument, and returns the bounding - rectangle of the flippable pad item. The QSize determines how many rows and - columns the icon grid should have. Each icon is given 150x150 units of - space, and this determines the bounds. - - \snippet graphicsview/padnavigator/flippablepad.cpp 1 - - \c posForLocation() returns the position of an icon given its row and - column position. Like \c boundsForSize(), the function assumes each icon is - given 150x150 units of space, and that all icons are centered around the - flippable pad item's origin (0, 0). - - \snippet graphicsview/padnavigator/flippablepad.cpp 2 - - The \c FlippablePad constructor passes suitable bounds (using \c - boundsForSize()) and specific color to \c RoundRectItem's constructor. - - \snippet graphicsview/padnavigator/flippablepad.cpp 3 - - It then loads pixmaps from compiled-in resources to use for its icons. - QDirIterator is very useful in this context, as it allows us to fetch all - resource "*.png" files inside the \c :/images directory without explicitly - naming the files. - - We also make sure not to load more pixmaps than we need. - - \snippet graphicsview/padnavigator/flippablepad.cpp 4 - - Now that we have the pixmaps, we can create icons, position then and assign - pixmaps. We start by finding a suitable size and color for the icons, and - initializing a convenient grid structure for storing the icons. This \c - iconGrid is also used later to find the icon for a specific (column, row) - location. - - For each row and column in our grid, we proceed to constructing each icon - as an instance of \c RoundRectItem. The item is placed by using the \c - posForLocation() helper function. To make room for the slip-behind - selection item, we give each icon a \l{QGraphicsItem::zValue()}{Z-value} of - 1. The pixmaps are distributed to the icons in round-robin fasion. - - Again, this approach is only suitable for example purposes. In a real-life - application where each icon represents a specific action, it would be more - natural to assign the pixmaps directly, or that the icons themselves - provide suitable pixmaps. - - \snippet graphicsview/padnavigator/flippablepad.cpp 5 - - Finally, the \c iconAt() function returns a pointer to the icon at a - specific row and column. It makes a somewhat bold assumption that the input - is valid, which is fair because the \c PadNavigator class only calls this - function with correct input. - - We will now review the \c SplashItem class. - - \section1 SplashItem Class Definition - - The \c SplashItem class represents the "splash window", a semitransparent - white overlay with text that appears immediately after the application has - started, and disappears after pressing any key. The animation is controlled - by \c PadNavigator; this class is very simple by itself. - - \snippet graphicsview/padnavigator/splashitem.h 0 - - The class declaration shows that \c SplashItem inherits QGraphicsObject to - allow it to be controlled by QPropertyAnimation. It reimplements the - mandatory \l{QGraphicsItem::paint()}{paint()} and - \l{QGraphicsItem::boundingRect()}{boundingRect()} pure virtual functions, - and keeps a \c text member variable which will contain the information text - displayed on this splash item. - - Let's look at its implementation. - - \snippet graphicsview/padnavigator/splashitem.cpp 0 - - The constructor forwards to QGraphicsObject as expected, assigns a text - message to the \c text member variable, and enables - \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache}. This cache - mode is suitable because the splash item only moves and is never - transformed, and because it contains text, it's important that it has a - pixel perfect visual appearance (in constrast to - \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache}, where the - visual appearance is not as good). - - We use caching to avoid having to relayout and rerender the text for each - frame. An alterative approach would be to use the new QStaticText class. - - \snippet graphicsview/padnavigator/splashitem.cpp 1 - - \c SplashItem's bounding rectangle is fixed at (400x175). - - \snippet graphicsview/padnavigator/splashitem.cpp 2 - - The \l{QGraphicsItem::paint()}{paint()} implementation draws a clipped - round rectangle with a thick 2-unit border and a semi-transparent white - background. It proceeds to finding a suitable text area by adjusting the - splash item's bounding rectangle with 10 units in each side. The text is - rendered inside this rectangle, with top-left alignment, and with word - wrapping enabled. - - The main class now remains. We will proceed to reviewing \c PadNavigator. - - \section1 PadNavigator Class Definition - - \c PadNavigator represents the main window of our Pad Navigator Example - application. It creates and controls a somewhat complex state machine, and - several animations. Its class declaration is very simple: - - \snippet graphicsview/padnavigator/padnavigator.h 0 - - It inherits QGraphicsView and reimplements only one function: - \l{QGraphicsView::resizeEvent()}{resizeEvent()}, to ensure the scene is - scaled to fit inside the view when resizing the main window. - - The \c PadNavigator constructor takes a QSize argument that determines the - number or rows and columns in the grid. - - It also keeps a private member instance, \c form, which is the generated - code for the pad's back side item's QGraphicsProxyWidget-embedded form. - - \snippet graphicsview/padnavigator/padnavigator.cpp 0 - - \c PadNavigator's constructor is a bit long. In short, its job is to create - all items, including the \c FlippablePad, the \c SplashItem and the - QGraphicsProxyWidget \c backItem, and then to set up all animations, states - and transitions that control the behavior of the application. - - It starts out simple, by forwarding to QGraphicsView's constructor. - - \snippet graphicsview/padnavigator/padnavigator.cpp 1 - - The first item to be created is \c SplashItem. This is going to be a top-level - item in the scene, next to \c FlippablePad, and stacked on top of it, so we - assign it a \l{QGraphicsItem::zValue()}{Z-value} of 1. - - \snippet graphicsview/padnavigator/padnavigator.cpp 2 - - Now we construct the \c FlippablePad item, passing its column-row count to - its constructor. - - The pad is controlled by three transformations, and we create one - QGraphicsRotation object for each of these. - - \list - \li \c flipRotation: Rotates the grid around its Qt::YAxis. This rotation is - animated from 0 to 180, and eventually back, when enter is pressed on the - keyboard, flipping the pad around. - \li \c xRotation: Rotates the grid around its Qt::XAxis. This is used to - tilt the pad vertically corresponding to which item is currently selected. - This way, the selected item is always kept in front. - \li \c yRotation: Rotates the grid around its Qt::YAxis. This is used to - tilt the pad horizontally corresponding to which item is selected. This - way, the selected item is always kept in front. - \endlist - - The combination of all three rotations is assigned via - QGraphicsItem::setTransformations(). - - \snippet graphicsview/padnavigator/padnavigator.cpp 3 - - Now we construct the QGraphicsProxyWidget-embedded \c backItem. The proxy - widget is created as a child of the pad. We create a new QWidget and - populate it with the \c form member. To ensure the \c hostName line edit is - the first to receive input focus when this item is shown, we call - \l{QWidget::setFocus()}{setFocus()} immediately. This will not give the - widget focus right away; it will only prepare the item to automatically - receive focus once it is shown. - - The QWidget based form is embedded into the proxy widget. The proxy is - hidden initially; we only want to show it when the pad is rotated at least - 90 degrees, and we also rotate the proxy itself by 180 degrees. This way we - give the impression that the proxy widget is "behind" the flipped pad, when - in fact, it's actually \e{on top of it}. - - We enable \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache} to - ensure the flip animation can run smoothly. - - \snippet graphicsview/padnavigator/padnavigator.cpp 4 - - We now create the selection item. This is simply another instance of \c - RoundRectItem that is slightly larger than the icons on the pad. We create - it as an immediate child of the \c FlippablePad, so the selection item is a - sibling to all the icons. By giving it a - \l{QGraphicsItem::zValue()}{Z-value} of 0.5 we ensure it will slide between - the pad and its icons. - - What follows now is a series of animation initializations. - - \snippet graphicsview/padnavigator/padnavigator.cpp 5 - - We begin with the animations that apply to the splash item. The first - animation, \c smoothSplashMove, ensures that the "y" property of \c splash - will be animated with a 250-millisecond duration - \l{QEasingCurve::InQuad}{InQuad} easing function. \c smoothSplashOpacity - ensures the opacity of \c splash eases in and out in 250 milliseconds. - - The values are assigned by \c PadNavigator's state machine, which is - created later. - - \snippet graphicsview/padnavigator/padnavigator.cpp 6 - - These are the animations that control the selection item's movement and the - \c xRotation and \c yRotation QGraphicsRotation objects that tilt the pad. - All animations have a duration of 125 milliseconds, and they all use the - \l{QEasingCurve::InOutQuad}{InOutQuad} easing function. - - \snippet graphicsview/padnavigator/padnavigator.cpp 7 - - We now create the animations that control the flip-effect when you press - the enter key. The main goal is to rotate the pad by 180 degrees or back, - but we also need to make sure the selection item's tilt rotations are reset - back to 0 when the pad is flipped, and restored back to their original - values when flipped back: - - \list - \li \c smoothFlipRotation: Animates the main 180 degree rotation of the pad. - \li \c smoothFlipScale: Scales the pad out and then in again while the pad is rotating. - \li \c smoothFlipXRotation: Animates the selection item's X-tilt to 0 and back. - \li \c smoothFlipYRotation: Animates the selection item's Y-tilt to 0 and back. - \li \c flipAnimation: A parallel animation group that ensures all the above animations are run in parallel. - \endlist - - All animations are given a 500 millisecond duration and an - \l{QEasingCurve::InOutQuad}{InOutQuad} easing function. - - It's worth taking a close look at \c smoothFlipScale. This animation's - start and end values are both 1.0, but at animation step 0.5 the - animation's value is 0.7. This means that after 50% of the animation's - duration, or 250 milliseconds, the pad will be scaled down to 0.7x of its - original size, which gives a great visual effect while flipping. - - \snippet graphicsview/padnavigator/padnavigator.cpp 8 - - This section uses a trick to ensure that certain properties are assigned - precisely when the flip animation passes 50%, or 90 degrees, rotation. In - short, the pad's icons and selection item are all hidden, the pad's \c fill - property is enabled, and \c backItem is shown when flipping over. When - flipping back, the reverse properties are applied. - - The way this is achieved is by running a sequential animation in parallel - to the other animations. This sequence, dubbed \c setVariablesSequence, - starts with a 250 millisecond pause, and then executes several animations - with a duration of 0. Each animation will ensure that properties are set - immediate at this point. - - This approach can also be used to call functions or set any other - properties at a specific time while an animation is running. - - \snippet graphicsview/padnavigator/padnavigator.cpp 9 - - We will now create the state machine. The whole \c PadNavigator state - machinery is controlled by one single state machine that has a - straight-forward state structure. The state engine itself is created - as a child of the \c PadNavigator itself. We then create three top level - states: - - \list - \li \c splashState: The initial state where the splash item is visible. - \li \c frontState: The base state where the splash is gone and we can see - the front side of the pad, and navigate the selection item. - \li \c backState: The flipped state where the \c backItem is visible, and we - can interact with the QGraphicsProxyWidget-embedded form. - \endlist - - \snippet graphicsview/padnavigator/padnavigator.cpp 10 - - Each state assigns specific properties to objects on entry. Most - interesting perhaps is the assignment of the value 0.0 to the pad's \c - flipRotation angle property when in \c frontState, and 180.0 when in \c - backState. At the end of this section we register default animations with - the state engine; these animations will apply to their respective objects - and properties for any state transition. Otherwise it's common to assign - animations to specific transitions. - - The \c splashState state is set as the initial state. This is required - before we start the state engine. We proceed with creating some - transitions. - - \snippet graphicsview/padnavigator/padnavigator.cpp 11 - - QEventTransition defines a very flexible transition type. You can use this - class to trigger a transition based on an object receiving an event of a - specific type. In this case, we would like to transition from \c - splashState into \c frontState if \c PadNavigator receives any key press - event (QEvent::KeyPress). - - We register the \c splashItem's animations to this transition to ensure they - are used to animate the item's movement and opacity. - - \snippet graphicsview/padnavigator/padnavigator.cpp 12 - - We use QKeyEventTransition to capture specific key events. In this case, we - detect that the user presses Qt::Key_Return or Qt::Key_Enter, and use this - to trigger transitions between \c frontState and backState. We register \c - flipAnimation, our complex parallel animation group, with these - transitions. - - We continue by defining the states for each of the icons in the grid. - - \snippet graphicsview/padnavigator/padnavigator.cpp 13 - - We will use state groups to control transitions between icons. Each icon - represents a \e substate of \c frontState. We will then define transitions - between the states by detecting key presses, using QKeyEventTransition. - - We start by creating all the substates, and at the same time we create a - temporary grid structure for the states to make it easier to find which - states represents icons that are up, down, left and to the right each - other. - - Once the first substate is known, we set this up as the initial substate of - \c frontState. We will use the (0, 0), or top-left, icon for the initial - substate. We initialze the selection item's position to be exactly where - the top-left icon is. - - \snippet graphicsview/padnavigator/padnavigator.cpp 14 - - We can now create four transitions for each icon. Each transition ensures - that we move to the state corresponding to which arrow key has been - pressed. It's clear from this techinique that we could design any other - specific transitions to and from each of the sub states depending on these - and other keys. - - \snippet graphicsview/padnavigator/padnavigator.cpp 15 - - Also, for each of the icons, we assign suitable values to the \c xRotation - and \c yRotation objects' "angle"-properties. If you recall, these - properties "tilt" the pad corresponding to which item is currently - selected. We ensure each icon is invisible when the pad is flipped, and - visible when the pad is not flipped. To ensure the visible property is - assigned at the right time, we add property-controlling animations to the - \c setVariableSequence animation defined earlier. - - \snippet graphicsview/padnavigator/padnavigator.cpp 16 - - We are now finished with all states, transitions, and animations. We now - create the scene that will contain all our items. The scene gets a defined - background pixmap, and we disable item indexing (as most items in this - scene are animated). We add our \c pad item to the scene, and use its - bounding rectangle to fixate the scene rectangle. This rectangle is used by - the view to find a suitable size for the application window. - - Then the scene is assigned to the view, or in our case, \c PadNavigator - itself. - - \snippet graphicsview/padnavigator/padnavigator.cpp 17 - - Now that the scene has received its final size, we can position the splash - item at the very top, find its fade-out position, and add it to the scene. - - \snippet graphicsview/padnavigator/padnavigator.cpp 18 - - The view toggles a few necessary properties: - - \list - \li It disables its scroll bars - this application has no use for scroll bars. - \li It assigns a minimum size. This is necessary to avoid numerical errors - in our fit-in-view \c resizeEvent() implementation. - \li It sets \l{QGraphicsView::FullViewportUpdate}{FullViewportUpdate}, to - ensure QGraphicsView doesn't spend time figuring out precisely what needs - to be redrawn. This application is very simple - if anything changes, - everything is updated. - \li It enables background caching - this makes no performance difference - with OpenGL, but without OpenGL it avoids unnecessary re-scaling of the - background pixmap. - \li It sets render hints that increase rendering quality. - \li If OpenGL is supported, a QGLWidget viewport is assigned to the view. - \endlist - - Finally, we start the state engine. - - \snippet graphicsview/padnavigator/padnavigator.cpp 19 - - The \l{QGraphicsView::resizeEvent()}{resizeEvent()} implementation calls - the base implementation, and then calls QGraphicsView::fitInView() to scale - the scene so that it fits perfectly inside the view. - - By resizing the main application window, you can see this effect yourself. - The scene contents grow when you make the window larger, and shrink when - you make it smaller, while keeping the aspect ratio intact. - - \section1 The main() Function - - \snippet graphicsview/padnavigator/main.cpp 0 - - The \c main function creates the QApplication instance, uses - Q_INIT_RESOURCE to ensure our compiled-in resources aren't removed by the - linker, and then creates a 3x3 \c PadNavigator instance and shows it. - - Our flippable pad shows up with a suitable splash item once control returns - to the event loop. - - \section1 Performance Notes - - The example uses OpenGL if this is available, to achieve optimal - performance; otherwise perspective tranformations can be quite costly. - - Although this example does use QGraphicsProxyWidget to demonstrate - integration of Qt widget components integrated into Graphics View, using - QGraphicsProxyWidget comes with a performance penalty, and is therefore not - recommended for embedded development. - - This example uses extensive item caching to avoid rerendering of static - elements, at the expense of graphics memory. -*/ diff --git a/examples/widgets/doc/painterpaths.qdoc b/examples/widgets/doc/painterpaths.qdoc deleted file mode 100644 index 45b0697cee..0000000000 --- a/examples/widgets/doc/painterpaths.qdoc +++ /dev/null @@ -1,418 +0,0 @@ -/**************************************************************************** -** -** 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 painting/painterpaths - \title Painter Paths Example - - The Painter Paths example shows how painter paths can be used to - build complex shapes for rendering. - - \image painterpaths-example.png - - The QPainterPath class provides a container for painting - operations, enabling graphical shapes to be constructed and - reused. - - A painter path is an object composed of a number of graphical - building blocks (such as rectangles, ellipses, lines, and curves), - and can be used for filling, outlining, and clipping. The main - advantage of painter paths over normal drawing operations is that - complex shapes only need to be created once, but they can be drawn - many times using only calls to QPainter::drawPath(). - - The example consists of two classes: - - \list - \li The \c RenderArea class which is a custom widget displaying - a single painter path. - \li The \c Window class which is the applications main window - displaying several \c RenderArea widgets, and allowing the user - to manipulate the painter paths' filling, pen, color - and rotation angle. - \endlist - - First we will review the \c Window class, then we will take a look - at the \c RenderArea class. - - \section1 Window Class Definition - - The \c Window class inherits QWidget, and is the applications main - window displaying several \c RenderArea widgets, and allowing the - user to manipulate the painter paths' filling, pen, color and - rotation angle. - - \snippet painting/painterpaths/window.h 0 - - We declare three private slots to respond to user input regarding - filling and color: \c fillRuleChanged(), \c fillGradientChanged() - and \c penColorChanged(). - - When the user changes the pen width and the rotation angle, the - new value is passed directly on to the \c RenderArea widgets using - the QSpinBox::valueChanged() signal. The reason why we must - implement slots to update the filling and color, is that QComboBox - doesn't provide a similar signal passing the new value as - argument; so we need to retrieve the new value, or values, before - we can update the \c RenderArea widgets. - - \snippet painting/painterpaths/window.h 1 - - We also declare a couple of private convenience functions: \c - populateWithColors() populates a given QComboBox with items - corresponding to the color names Qt knows about, and \c - currentItemData() returns the current item for a given QComboBox. - - \snippet painting/painterpaths/window.h 2 - - Then we declare the various components of the main window - widget. We also declare a convenience constant specifying the - number of \c RenderArea widgets. - - \section1 Window Class Implementation - - In the implementation of the \c Window class we first declare the - constant \c Pi with six significant figures: - - \snippet painting/painterpaths/window.cpp 0 - - In the constructor, we then define the various painter paths and - create corresponding \c RenderArea widgets which will render the - graphical shapes: - - \snippet painting/painterpaths/window.cpp 1 - - We construct a rectangle with sharp corners using the - QPainterPath::moveTo() and QPainterPath::lineTo() - functions. - - QPainterPath::moveTo() moves the current point to the point passed - as argument. A painter path is an object composed of a number of - graphical building blocks, i.e. subpaths. Moving the current point - will also start a new subpath (implicitly closing the previously - current path when the new one is started). The - QPainterPath::lineTo() function adds a straight line from the - current point to the given end point. After the line is drawn, the - current point is updated to be at the end point of the line. - - We first move the current point starting a new subpath, and we - draw three of the rectangle's sides. Then we call the - QPainterPath::closeSubpath() function which draws a line to the - beginning of the current subpath. A new subpath is automatically - begun when the current subpath is closed. The current point of the - new path is (0, 0). We could also have called - QPainterPath::lineTo() to draw the last line as well, and then - explicitly start a new subpath using the QPainterPath::moveTo() - function. - - QPainterPath also provide the QPainterPath::addRect() convenience - function, which adds a given rectangle to the path as a closed - subpath. The rectangle is added as a clockwise set of lines. The - painter path's current position after the rect has been added is - at the top-left corner of the rectangle. - - \snippet painting/painterpaths/window.cpp 2 - - Then we construct a rectangle with rounded corners. As before, we - use the QPainterPath::moveTo() and QPainterPath::lineTo() - functions to draw the rectangle's sides. To create the rounded - corners we use the QPainterPath::arcTo() function. - - QPainterPath::arcTo() creates an arc that occupies the given - rectangle (specified by a QRect or the rectangle's coordinates), - beginning at the given start angle and extending the given degrees - counter-clockwise. Angles are specified in degrees. Clockwise arcs - can be specified using negative angles. The function connects the - current point to the starting point of the arc if they are not - already connected. - - \snippet painting/painterpaths/window.cpp 3 - - We also use the QPainterPath::arcTo() function to construct the - ellipse path. First we move the current point starting a new - path. Then we call QPainterPath::arcTo() with starting angle 0.0 - and 360.0 degrees as the last argument, creating an ellipse. - - Again, QPainterPath provides a convenience function ( - QPainterPath::addEllipse()) which creates an ellipse within a - given bounding rectangle and adds it to the painter path. If the - current subpath is closed, a new subpath is started. The ellipse - is composed of a clockwise curve, starting and finishing at zero - degrees (the 3 o'clock position). - - \snippet painting/painterpaths/window.cpp 4 - - When constructing the pie chart path we continue to use a - combination of the mentioned functions: First we move the current - point, starting a new subpath. Then we create a line from the - center of the chart to the arc, and the arc itself. When we close - the subpath, we implicitly construct the last line back to the - center of the chart. - - \snippet painting/painterpaths/window.cpp 5 - - Constructing a polygon is equivalent to constructing a rectangle. - - QPainterPath also provide the QPainterPath::addPolygon() - convenience function which adds the given polygon to the path as a - new subpath. Current position after the polygon has been added is - the last point in polygon. - - \snippet painting/painterpaths/window.cpp 6 - - Then we create a path consisting of a group of subpaths: First we - move the current point, and create a circle using the - QPainterPath::arcTo() function with starting angle 0.0, and 360 - degrees as the last argument, as we did when we created the - ellipse path. Then we move the current point again, starting a - new subpath, and construct three sides of a square using the - QPainterPath::lineTo() function. - - Now, when we call the QPainterPath::closeSubpath() function the - last side is created. Remember that the - QPainterPath::closeSubpath() function draws a line to the - beginning of the \e current subpath, i.e the square. - - QPainterPath provide a convenience function, - QPainterPath::addPath() which adds a given path to the path that - calls the function. - - \snippet painting/painterpaths/window.cpp 7 - - When creating the text path, we first create the font. Then we set - the font's style strategy which tells the font matching algorithm - what type of fonts should be used to find an appropriate default - family. QFont::ForceOutline forces the use of outline fonts. - - To construct the text, we use the QPainterPath::addText() function - which adds the given text to the path as a set of closed subpaths - created from the supplied font. The subpaths are positioned so - that the left end of the text's baseline lies at the specified - point. - - \snippet painting/painterpaths/window.cpp 8 - - To create the Bezier path, we use the QPainterPath::cubicTo() - function which adds a Bezier curve between the current point and - the given end point with the given control point. After the curve - is added, the current point is updated to be at the end point of - the curve. - - In this case we omit to close the subpath so that we only have a - simple curve. But there is still a logical line from the curve's - endpoint back to the beginning of the subpath; it becomes visible - when filling the path as can be seen in the applications main - window. - - \snippet painting/painterpaths/window.cpp 9 - - The final path that we construct shows that you can use - QPainterPath to construct rather complex shapes using only the - previous mentioned QPainterPath::moveTo(), QPainterPath::lineTo() - and QPainterPath::closeSubpath() functions. - - \snippet painting/painterpaths/window.cpp 10 - - Now that we have created all the painter paths that we need, we - create a corresponding \c RenderArea widget for each. In the end, - we make sure that the number of render areas is correct using the - Q_ASSERT() macro. - - \snippet painting/painterpaths/window.cpp 11 - - Then we create the widgets associated with the painter paths' fill - rule. - - There are two available fill rules in Qt: The Qt::OddEvenFill rule - determine whether a point is inside the shape by drawing a - horizontal line from the point to a location outside the shape, - and count the number of intersections. If the number of - intersections is an odd number, the point is inside the - shape. This rule is the default. - - The Qt::WindingFill rule determine whether a point is inside the - shape by drawing a horizontal line from the point to a location - outside the shape. Then it determines whether the direction of the - line at each intersection point is up or down. The winding number - is determined by summing the direction of each intersection. If - the number is non zero, the point is inside the shape. - - The Qt::WindingFill rule can in most cases be considered as the - intersection of closed shapes. - - \snippet painting/painterpaths/window.cpp 12 - - We also create the other widgets associated with the filling, the - pen and the rotation angle. - - \snippet painting/painterpaths/window.cpp 16 - - We connect the comboboxes \l {QComboBox::activated()}{activated()} - signals to the associated slots in the \c Window class, while we - connect the spin boxes \l - {QSpinBox::valueChanged()}{valueChanged()} signal directly to the - \c RenderArea widget's respective slots. - - \snippet painting/painterpaths/window.cpp 17 - - We add the \c RenderArea widgets to a separate layout which we - then add to the main layout along with the rest of the widgets. - - \snippet painting/painterpaths/window.cpp 18 - - Finally, we initialize the \c RenderArea widgets by calling the \c - fillRuleChanged(), \c fillGradientChanged() and \c - penColorChanged() slots, and we set the initial pen width and - window title. - - \snippet painting/painterpaths/window.cpp 19 - \codeline - \snippet painting/painterpaths/window.cpp 20 - \codeline - \snippet painting/painterpaths/window.cpp 21 - - The private slots are implemented to retrieve the new value, or - values, from the associated comboboxes and update the RenderArea - widgets. - - First we determine the new value, or values, using the private \c - currentItemData() function and the qvariant_cast() template - function. Then we call the associated slot for each of the \c - RenderArea widgets to update the painter paths. - - \snippet painting/painterpaths/window.cpp 22 - - The \c populateWithColors() function populates the given combobox - with items corresponding to the color names Qt knows about - provided by the static QColor::colorNames() function. - - \snippet painting/painterpaths/window.cpp 23 - - The \c currentItemData() function simply return the current item - of the given combobox. - - \section1 RenderArea Class Definition - - The \c RenderArea class inherits QWidget, and is a custom widget - displaying a single painter path. - - \snippet painting/painterpaths/renderarea.h 0 - - We declare several public slots updating the \c RenderArea - widget's associated painter path. In addition we reimplement the - QWidget::minimumSizeHint() and QWidget::sizeHint() functions to - give the \c RenderArea widget a reasonable size within our - application, and we reimplement the QWidget::paintEvent() event - handler to draw its painter path. - - \snippet painting/painterpaths/renderarea.h 1 - - Each instance of the \c RenderArea class has a QPainterPath, a - couple of fill colors, a pen width, a pen color and a rotation - angle. - - \section1 RenderArea Class Implementation - - The constructor takes a QPainterPath as argument (in addition to - the optional QWidget parent): - - \snippet painting/painterpaths/renderarea.cpp 0 - - In the constructor we initialize the \c RenderArea widget with the - QPainterPath parameter as well as initializing the pen width and - rotation angle. We also set the widgets \l - {QWidget::backgroundRole()}{background role}; QPalette::Base is - typically white. - - \snippet painting/painterpaths/renderarea.cpp 1 - \codeline - \snippet painting/painterpaths/renderarea.cpp 2 - - Then we reimplement the QWidget::minimumSizeHint() and - QWidget::sizeHint() functions to give the \c RenderArea widget a - reasonable size within our application. - - \snippet painting/painterpaths/renderarea.cpp 3 - \codeline - \snippet painting/painterpaths/renderarea.cpp 4 - \codeline - \snippet painting/painterpaths/renderarea.cpp 5 - \codeline - \snippet painting/painterpaths/renderarea.cpp 6 - \codeline - \snippet painting/painterpaths/renderarea.cpp 7 - - The various public slots updates the \c RenderArea widget's - painter path by setting the associated property and make a call to - the QWidget::update() function, forcing a repaint of the widget - with the new rendering preferences. - - The QWidget::update() slot does not cause an immediate repaint; - instead it schedules a paint event for processing when Qt returns - to the main event loop. - - \snippet painting/painterpaths/renderarea.cpp 8 - - A paint event is a request to repaint all or parts of the - widget. The paintEvent() function is an event handler that can be - reimplemented to receive the widget's paint events. We reimplement - the event handler to render the \c RenderArea widget's painter - path. - - First, we create a QPainter for the \c RenderArea instance, and - set the painter's render hints. The QPainter::RenderHints are used - to specify flags to QPainter that may, or may not, be respected by - any given engine. QPainter::Antialiasing indicates that the engine - should anti-alias the edges of primitives if possible, i.e. put - additional pixels around the original ones to smooth the edges. - - \snippet painting/painterpaths/renderarea.cpp 9 - - Then we scale the QPainter's coordinate system to ensure that the - painter path is rendered in the right size, i.e that it grows with - the \c RenderArea widget when the application is resized. When we - constructed the various painter paths, they were all rnedered - within a square with a 100 pixel width which is equivalent to \c - RenderArea::sizeHint(). The QPainter::scale() function scales the - coordinate system by the \c RenderArea widget's \e current width - and height divided by 100. - - Now, when we are sure that the painter path has the right size, we - can translate the coordinate system to make the painter path - rotate around the \c RenderArea widget's center. After we have - performed the rotation, we must remember to translate the - coordinate system back again. - - \snippet painting/painterpaths/renderarea.cpp 10 - - Then we set the QPainter's pen with the instance's rendering - preferences. We create a QLinearGradient and set its colors - corresponding to the \c RenderArea widget's fill colors. Finally, - we set the QPainter's brush (the gradient is automatically - converted into a QBrush), and draw the \c RenderArea widget's - painter path using the QPainter::drawPath() function. -*/ diff --git a/examples/widgets/doc/pathstroke.qdoc b/examples/widgets/doc/pathstroke.qdoc deleted file mode 100644 index 89a0182934..0000000000 --- a/examples/widgets/doc/pathstroke.qdoc +++ /dev/null @@ -1,47 +0,0 @@ -/**************************************************************************** -** -** 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 painting/pathstroke - \title Path Stroking - - In this example we show some of the various types of pens that can be - used in Qt. - - \image pathstroke-demo.png - - Qt defines cap styles for how the end points are treated and join - styles for how path segments are joined together. A standard set of - predefined dash patterns are also included that can be used with - QPen. - - In addition to the predefined patterns available in - QPen we also demonstrate direct use of the - QPainterPathStroker class which can be used to define - custom dash patterns. You can see this by enabling the - \e{Custom Pattern} option. -*/ diff --git a/examples/widgets/doc/pingpong.qdoc b/examples/widgets/doc/pingpong.qdoc deleted file mode 100644 index c56085d8cf..0000000000 --- a/examples/widgets/doc/pingpong.qdoc +++ /dev/null @@ -1,93 +0,0 @@ -/**************************************************************************** -** -** 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 statemachine/pingpong - \title Ping Pong States Example - - The Ping Pong States example shows how to use parallel states together - with custom events and transitions in \l{The State Machine Framework}. - - This example implements a statechart where two states communicate by - posting events to the state machine. The state chart looks as follows: - - \image pingpong-example.png - \omit - \caption This is a caption - \endomit - - The \c pinger and \c ponger states are parallel states, i.e. they are - entered simultaneously and will take transitions independently of - eachother. - - The \c pinger state will post the first \c ping event upon entry; the \c - ponger state will respond by posting a \c pong event; this will cause the - \c pinger state to post a new \c ping event; and so on. - - \snippet statemachine/pingpong/main.cpp 0 - - Two custom events are defined, \c PingEvent and \c PongEvent. - - \snippet statemachine/pingpong/main.cpp 1 - - The \c Pinger class defines a state that posts a \c PingEvent to the state - machine when the state is entered. - - \snippet statemachine/pingpong/main.cpp 2 - - The \c PingTransition class defines a transition that is triggered by - events of type \c PingEvent, and that posts a \c PongEvent (with a delay - of 500 milliseconds) to the state machine when the transition is - triggered. - - \snippet statemachine/pingpong/main.cpp 3 - - The \c PongTransition class defines a transition that is triggered by - events of type \c PongEvent, and that posts a \c PingEvent (with a delay - of 500 milliseconds) to the state machine when the transition is - triggered. - - \snippet statemachine/pingpong/main.cpp 4 - - The main() function begins by creating a state machine and a parallel - state group. - - \snippet statemachine/pingpong/main.cpp 5 - - Next, the \c pinger and \c ponger states are created, with the parallel - state group as their parent state. Note that the transitions are \e - targetless. When such a transition is triggered, the source state won't be - exited and re-entered; only the transition's onTransition() function will - be called, and the state machine's configuration will remain the same, - which is precisely what we want in this case. - - \snippet statemachine/pingpong/main.cpp 6 - - Finally, the group is added to the state machine, the machine is started, - and the application event loop is entered. - - */ diff --git a/examples/widgets/doc/pixelator.qdoc b/examples/widgets/doc/pixelator.qdoc deleted file mode 100644 index 099c382c82..0000000000 --- a/examples/widgets/doc/pixelator.qdoc +++ /dev/null @@ -1,255 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/pixelator - \title Pixelator Example - - The Pixelator example shows how delegates can be used to customize the way that - items are rendered in standard item views. - - \image pixelator-example.png - - By default, QTreeView, QTableView, and QListView use a standard item delegate - to display and edit a set of common data types that are sufficient for many - applications. However, an application may need to represent items of data in a - particular way, or provide support for rendering more specialized data types, - and this often requires the use of a custom delegate. - - In this example, we show how to use custom delegates to modify the appearance - of standard views. To do this, we implement the following components: - - \list - \li A model which represents each pixel in an image as an item of data, where each - item contains a value for the brightness of the corresponding pixel. - \li A custom delegate that uses the information supplied by the model to represent - each pixel as a black circle on a white background, where the radius of the - circle corresponds to the darkness of the pixel. - \endlist - - This example may be useful for developers who want to implement their own table - models or custom delegates. The process of creating custom delegates for editing - item data is covered in the \l{Spin Box Delegate Example}{Spin Box Delegate} - example. - - \section1 ImageModel Class Definition - - The \c ImageModel class is defined as follows: - - \snippet itemviews/pixelator/imagemodel.h 0 - - Since we only require a simple, read-only table model, we only need to implement - functions to indicate the dimensions of the image and supply data to other - components. - - \section1 ImageModel Class Implementation - - The constructor is trivial: - - \snippet itemviews/pixelator/imagemodel.cpp 0 - - The \c setImage() function sets the image that will be used by the model: - - \snippet itemviews/pixelator/imagemodel.cpp 1 - - The QAbstractItemModel::reset() call tells the view(s) that the model - has changed. - - The \c rowCount() and \c columnCount() functions return the height and width of - the image respectively: - - \snippet itemviews/pixelator/imagemodel.cpp 2 - \snippet itemviews/pixelator/imagemodel.cpp 3 - - Since the image is a simple two-dimensional structure, the \c parent arguments - to these functions are unused. They both simply return the relevant size from - the underlying image object. - - The \c data() function returns data for the item that corresponds to a given - model index in a format that is suitable for a particular role: - - \snippet itemviews/pixelator/imagemodel.cpp 4 - - In this implementation, we only check that the model index is valid, and that - the role requested is the \l{Qt::ItemDataRole}{DisplayRole}. If so, the function - returns the grayscale value of the relevant pixel in the image; otherwise, a null - model index is returned. - - This model can be used with QTableView to display the integer brightness values - for the pixels in the image. However, we will implement a custom delegate to - display this information in a more artistic way. - - The \c headerData() function is also reimplemented: - - \snippet itemviews/pixelator/imagemodel.cpp 5 - - We return (1, 1) as the size hint for a header item. If we - didn't, the headers would default to a larger size, preventing - us from displaying really small items (which can be specified - using the \uicontrol{Pixel size} combobox). - - \section1 PixelDelegate Class Definition - - The \c PixelDelegate class is defined as follows: - - \snippet itemviews/pixelator/pixeldelegate.h 0 - - This class provides only basic features for a delegate so, unlike the - \l{Spin Box Delegate Example}{Spin Box Delegate} example, we subclass - QAbstractItemDelegate instead of QItemDelegate. - - We only need to reimplement \l{QAbstractItemDelegate::paint()}{paint()} and - \l{QAbstractItemDelegate::sizeHint()}{sizeHint()} in this class. - However, we also provide a delegate-specific \c setPixelSize() function so - that we can change the delegate's behavior via the signals and slots mechanism. - - \section1 PixelDelegate Class Implementation - - The \c PixelDelegate constructor is used to set up a default value for - the size of each "pixel" that it renders. The base class constructor is - also called to ensure that the delegate is set up with a parent object, - if one is supplied: - - \snippet itemviews/pixelator/pixeldelegate.cpp 0 - - Each item is rendered by the delegate's - \l{QAbstractItemDelegate::paint()}{paint()} function. The view calls this - function with a ready-to-use QPainter object, style information that the - delegate should use to correctly draw the item, and an index to the item in - the model: - - \snippet itemviews/pixelator/pixeldelegate.cpp 1 - - The first task the delegate has to perform is to draw the item's background - correctly. Usually, selected items appear differently to non-selected items, - so we begin by testing the state passed in the style option and filling the - background if necessary. - - The radius of each circle is calculated in the following lines of code: - - \snippet itemviews/pixelator/pixeldelegate.cpp 3 - \snippet itemviews/pixelator/pixeldelegate.cpp 4 - - First, the largest possible radius of the circle is determined by taking the - smallest dimension of the style option's \c rect attribute. - Using the model index supplied, we obtain a value for the brightness of the - relevant pixel in the image. The radius of the circle is calculated by - scaling the brightness to fit within the item and subtracting it from the - largest possible radius. - - \snippet itemviews/pixelator/pixeldelegate.cpp 5 - \snippet itemviews/pixelator/pixeldelegate.cpp 6 - \snippet itemviews/pixelator/pixeldelegate.cpp 7 - - We save the painter's state, turn on antialiasing (to obtain smoother - curves), and turn off the pen. - - \snippet itemviews/pixelator/pixeldelegate.cpp 8 - \snippet itemviews/pixelator/pixeldelegate.cpp 9 - - The foreground of the item (the circle representing a pixel) must be - rendered using an appropriate brush. For unselected items, we will use a - solid black brush; selected items are drawn using a predefined brush from - the style option's palette. - - \snippet itemviews/pixelator/pixeldelegate.cpp 10 - - Finally, we paint the circle within the rectangle specified by the style - option and we call \l{QPainter::}{restore()} on the painter. - - The \c paint() function does not have to be particularly complicated; it is - only necessary to ensure that the state of the painter when the function - returns is the same as it was when it was called. This usually - means that any transformations applied to the painter must be preceded by - a call to QPainter::save() and followed by a call to QPainter::restore(). - - The delegate's \l{QAbstractItemDelegate::}{sizeHint()} function - returns a size for the item based on the predefined pixel size, initially set - up in the constructor: - - \snippet itemviews/pixelator/pixeldelegate.cpp 11 - - The delegate's size is updated whenever the pixel size is changed. - We provide a custom slot to do this: - - \snippet itemviews/pixelator/pixeldelegate.cpp 12 - - \section1 Using The Custom Delegate - - In this example, we use a main window to display a table of data, using the - custom delegate to render each cell in a particular way. Much of the - \c MainWindow class performs tasks that are not related to item views. Here, - we only quote the parts that are relevant. You can look at the rest of the - implementation by following the links to the code at the top of this - document. - - In the constructor, we set up a table view, turn off its grid, and hide its - headers: - - \snippet itemviews/pixelator/mainwindow.cpp 0 - \dots - \snippet itemviews/pixelator/mainwindow.cpp 1 - - This enables the items to be drawn without any gaps between them. Removing - the headers also prevents the user from adjusting the sizes of individual - rows and columns. - - We also set the minimum section size to 1 on the headers. If we - didn't, the headers would default to a larger size, preventing - us from displaying really small items (which can be specified - using the \uicontrol{Pixel size} combobox). - - The custom delegate is constructed with the main window as its parent, so - that it will be deleted correctly later, and we set it on the table view. - - \snippet itemviews/pixelator/mainwindow.cpp 2 - - Each item in the table view will be rendered by the \c PixelDelegate - instance. - - We construct a spin box to allow the user to change the size of each "pixel" - drawn by the delegate: - - \snippet itemviews/pixelator/mainwindow.cpp 3 - - This spin box is connected to the custom slot we implemented in the - \c PixelDelegate class. This ensures that the delegate always draws each - pixel at the currently specified size: - - \snippet itemviews/pixelator/mainwindow.cpp 4 - \dots - \snippet itemviews/pixelator/mainwindow.cpp 5 - - We also connect the spin box to a slot in the \c MainWindow class. This - forces the view to take into account the new size hints for each item; - these are provided by the delegate in its \c sizeHint() function. - - \snippet itemviews/pixelator/mainwindow.cpp 6 - - We explicitly resize the columns and rows to match the - \uicontrol{Pixel size} combobox. -*/ diff --git a/examples/widgets/doc/recentfiles.qdoc b/examples/widgets/doc/recentfiles.qdoc deleted file mode 100644 index e2e876b088..0000000000 --- a/examples/widgets/doc/recentfiles.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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 mainwindows/recentfiles - \title Recent Files Example - - The Recent Files example shows how a standard File menu can be extended to show - the most recent files loaded by a main window application. - - \image recentfiles-example.png -*/ diff --git a/examples/widgets/doc/rogue.qdoc b/examples/widgets/doc/rogue.qdoc deleted file mode 100644 index 4c65dd2d6e..0000000000 --- a/examples/widgets/doc/rogue.qdoc +++ /dev/null @@ -1,208 +0,0 @@ -/**************************************************************************** -** -** 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 statemachine/rogue - \title Rogue Example - - The Rogue example shows how to use the Qt state machine for event - handling. - - \image rogue-example.png - - This example implements a simple text based game. Do you see the - \c{@} in the screenshot? That's you, the rogue. The \c{#} - characters are walls, and the dots represent floor. In a real - game, other ASCII characters would represent all kinds of objects - and creatures, for instance, ancient dragons (\c{D}s) or food - rations (\c{%}s). But let's not get carried away. In this game, - the rogue is simply running around in an empty room. - - The rogue is moved with the keypad (2, 4, 8, 6). That aside, we - have implemented a \c quit command that triggers if the player - types \c {q}. The player is then asked if he/she really wants to - quit. - - Most games have commands that need more than one key press (we - think of consecutive presses, i.e., not of several keys being - pressed at the same time). In this game, only the \c quit command - falls under this category, but for the sake of argument, let's - imagine a fully-fledged game with a rich set of commands. If we - were to implement these by catching key events in - \l{QWidget::}{keyPressEvent()}, we would have to keep a lot of - class member variables to track the sequence of keys already typed - (or find some other way of deducing the current state of a - command). This can easily lead to spaghetti, which is--as we all - well know, I'm sure--unpleasant. With a state machine, on the - other hand, separate states can wait for a single key press, and - that makes our lives a lot simpler. - - The example consists of two classes: - - \list - \li \c Window draws the text display of the game and sets - up the state machine. The window also has a status bar - above the area in which the rouge moves. - \li \c MovementTransition is a transition that carries out - a single move of the rogue. - \endlist - - Before we embark on a code walkthrough, it is necessary to take a - closer look at the design of the machine. Here is a state chart - that shows what we want to achieve: - - \image rogue-statechart.png - - The input state waits for a key press to start a new command. - When receiving a key it recognizes, it transitions to one of the - two commands of the game; though, as we will see, movement is - handled by the transition itself. The quit state waits for the - player to answer yes or no (by typing \c y or \c n) when asked - whether he/she really wants to quit the game. - - The chart demonstrates how we use one state to wait for a single - key press. The press received may trigger one of the transitions - connected to the state. - - \section1 Window Class Definition - - The \c Window class is a widget that draws the text display of the - game. It also sets up the state machine, i.e., creates and - connects the states in the machine. It is the key events from this - widget that are used by the machine. - - \snippet statemachine/rogue/window.h 0 - - \c Direction specifies the direction in which the rogue is to - move. We use this in \c movePlayer(), which moves the rogue and - repaints the window. The game has a status line above the area in - which the rogue moves. The \c status property contains the text of - this line. We use a property because the QState class allows - setting any Qt \l{Qt's Property System}{property} when entered. - More on this later. - - \snippet statemachine/rogue/window.h 1 - - The \c map is an array with the characters that are currently - displayed. We set up the array in \c setupMap(), and update it - when the rogue is moved. \c pX and \c pY is the current position - of the rogue. \c WIDTH and \c HEIGHT are macros specifying the - dimensions of the map. - - The \c paintEvent() function is left out of this walkthrough. We - also do not discuss other code that does not concern the state - machine (the \c setupMap(), \c status(), \c setStatus(), \c - movePlayer(), and \c sizeHint() functions). If you wish to take a - look at the code, click on the link for the \c window.cpp file at - the top of this page. - - \section1 Window Class Implementation - - Here is the constructor of \c Window: - - \snippet statemachine/rogue/window.cpp 0 - \dots - \snippet statemachine/rogue/window.cpp 1 - - The player starts off at position (5, 5). We then set up the map - and statemachine. Let's proceed with the \c buildMachine() - function: - - \snippet statemachine/rogue/window.cpp 2 - - We enter \c inputState when the machine is started and from the \c - quitState if the user wants to continue playing. We then set the - status to a helpful reminder of how to play the game. - - First, the \c Movement transition is added to the input state. - This will enable the rogue to be moved with the keypad. Notice - that we don't set a target state for the movement transition. This - will cause the transition to be triggered (and the - \l{QAbstractTransition::}{onTransition()} function to be invoked), - but the machine will not leave the \c inputState. If we had set \c - inputState as the target state, we would first have left and then - entered the \c inputState again. - - \snippet statemachine/rogue/window.cpp 3 - - When we enter \c quitState, we update the status bar of the - window. - - \c QKeyEventTransition is a utility class that removes the hassle - of implementing transitions for \l{QKeyEvent}s. We simply need to - specify the key on which the transition should trigger and the - target state of the transition. - - \snippet statemachine/rogue/window.cpp 4 - - The transition from \c inputState allows triggering the quit state - when the player types \c {q}. - - \snippet statemachine/rogue/window.cpp 5 - - The machine is set up, so it's time to start it. - - \section1 The MovementTransition Class - - \c MovementTransition is triggered when the player request the - rogue to be moved (by typing 2, 4, 6, or 8) when the machine is in - the \c inputState. - - \snippet statemachine/rogue/movementtransition.h 0 - - In the constructor, we tell QEventTransition to only send - \l{QEvent::}{KeyPress} events to the - \l{QAbstractTransition::}{eventTest()} function: - - \snippet statemachine/rogue/movementtransition.h 1 - - The KeyPress events come wrapped in \l{QStateMachine::WrappedEvent}s. \c event - must be confirmed to be a wrapped event because Qt uses other - events internally. After that, it is simply a matter of checking - which key has been pressed. - - Let's move on to the \c onTransition() function: - - \snippet statemachine/rogue/movementtransition.h 2 - - When \c onTransition() is invoked, we know that we have a - \l{QEvent::}{KeyPress} event with 2, 4, 6, or 8, and can ask \c - Window to move the player. - - \section1 The Roguelike Tradition - - You might have been wondering why the game features a rogue. Well, - these kinds of text based dungeon exploration games date back to a - game called, yes, "Rogue". Although outflanked by the technology - of modern 3D computer games, roguelikes have a solid community of - hard-core, devoted followers. - - Playing these games can be surprisingly addictive (despite the - lack of graphics). Angband, the perhaps most well-known rougelike, - is found here: \l{http://rephial.org/}. -*/ - diff --git a/examples/widgets/doc/screenshot.qdoc b/examples/widgets/doc/screenshot.qdoc deleted file mode 100644 index 2d41cf0d85..0000000000 --- a/examples/widgets/doc/screenshot.qdoc +++ /dev/null @@ -1,247 +0,0 @@ -/**************************************************************************** -** -** 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 desktop/screenshot - \title Screenshot Example - - The Screenshot example shows how to take a screenshot of the - desktop using QApplication and QDesktopWidget. It also shows how - to use QTimer to provide a single-shot timer, and how to - reimplement the QWidget::resizeEvent() event handler to make sure - that an application resizes smoothly and without data loss. - - \image screenshot-example.png - - With the application the users can take a screenshot of their - desktop. They are provided with a couple of options: - - \list - \li Delaying the screenshot, giving them time to rearrange - their desktop. - \li Hiding the application's window while the screenshot is taken. - \endlist - - In addition the application allows the users to save their - screenshot if they want to. - - \section1 Screenshot Class Definition - - \snippet desktop/screenshot/screenshot.h 0 - - The \c Screenshot class inherits QWidget and is the application's - main widget. It displays the application options and a preview of - the screenshot. - - We reimplement the QWidget::resizeEvent() function to make sure - that the preview of the screenshot scales properly when the user - resizes the application widget. We also need several private slots - to facilitate the options: - - \list - \li The \c newScreenshot() slot prepares a new screenshot. - \li The \c saveScreenshot() slot saves the last screenshot. - \li The \c shootScreen() slot takes the screenshot. - \li The \c updateCheckBox() slot enables or disables the - \uicontrol {Hide This Window} option. - \endlist - - We also declare some private functions: We use the \c - createOptionsGroupBox(), \c createButtonsLayout() and \c - createButton() functions when we construct the widget. And we call - the private \c updateScreenshotLabel() function whenever a new - screenshot is taken or when a resize event changes the size of the - screenshot preview label. - - In addition we need to store the screenshot's original pixmap. The - reason is that when we display the preview of the screenshot, we - need to scale its pixmap, storing the original we make sure that - no data are lost in that process. - - \section1 Screenshot Class Implementation - - \snippet desktop/screenshot/screenshot.cpp 0 - - In the constructor we first create the QLabel displaying the - screenshot preview. - - We set the QLabel's size policy to be QSizePolicy::Expanding both - horizontally and vertically. This means that the QLabel's size - hint is a sensible size, but the widget can be shrunk and still be - useful. Also, the widget can make use of extra space, so it should - get as much space as possible. Then we make sure the QLabel is - aligned in the center of the \c Screenshot widget, and set its - minimum size. - - We create the applications's buttons and the group box containing - the application's options, and put it all into a main - layout. Finally we take the initial screenshot, and set the initial - delay and the window title, before we resize the widget to a - suitable size. - - \snippet desktop/screenshot/screenshot.cpp 1 - - The \c resizeEvent() function is reimplemented to receive the - resize events dispatched to the widget. The purpose is to scale - the preview screenshot pixmap without deformation of its content, - and also make sure that the application can be resized smoothly. - - To achieve the first goal, we scale the screenshot pixmap using - Qt::KeepAspectRatio. We scale the pixmap to a rectangle as large - as possible inside the current size of the screenshot preview - label, preserving the aspect ratio. This means that if the user - resizes the application window in only one direction, the preview - screenshot keeps the same size. - - To reach our second goal, we make sure that the preview screenshot - only is repainted (using the private \c updateScreenshotLabel() - function) when it actually changes its size. - - \snippet desktop/screenshot/screenshot.cpp 2 - - The private \c newScreenshot() slot is called when the user - requests a new screenshot; but the slot only prepares a new - screenshot. - - First we see if the \uicontrol {Hide This Window} option is checked, if - it is we hide the \c Screenshot widget. Then we disable the \uicontrol - {New Screenshot} button, to make sure the user only can request - one screenshot at a time. - - We create a timer using the QTimer class which provides repetitive - and single-shot timers. We set the timer to time out only once, - using the static QTimer::singleShot() function. This function - calls the private \c shootScreen() slot after the time interval - specified by the \uicontrol {Screenshot Delay} option. It is \c - shootScreen() that actually performs the screenshot. - - \snippet desktop/screenshot/screenshot.cpp 3 - - The \c saveScreenshot() slot is called when the user push the \uicontrol - Save button, and it presents a file dialog using the QFileDialog - class. - - QFileDialog enables a user to traverse the file system in order to - select one or many files or a directory. The easiest way to create - a QFileDialog is to use the convenience static - functions. - - We define the default file format to be png, and we make the file - dialog's initial path the path the application is run from. We - create the file dialog using the static - QFileDialog::getSaveFileName() function which returns a file name - selected by the user. The file does not have to exist. If the file - name is valid, we use the QPixmap::save() function to save the - screenshot's original pixmap in that file. - - \snippet desktop/screenshot/screenshot.cpp 4 - - The \c shootScreen() slot is called to take the screenshot. If the - user has chosen to delay the screenshot, we make the application - beep when the screenshot is taken using the static - QApplication::beep() function. - - The QApplication class manages the GUI application's control flow - and main settings. It contains the main event loop, where all - events from the window system and other sources are processed and - dispatched. - - \snippet desktop/screenshot/screenshot.cpp 5 - - Using the static function QApplication::primaryScreen(), we - obtain the QScreen object for the application's main screen. - - We take the screenshot using the QScreen::grabWindow() - function. The function grabs the contents of the window passed as - an argument, makes a pixmap out of it and returns that pixmap. - The window id can be obtained with QWidget::winId() or QWindow::winId(). - Here, however, we just pass 0 as the window id, indicating that we - want to grab the entire screen. - - We update the screenshot preview label using the private \c - updateScreenshotLabel() function. Then we enable the \uicontrol {New - Screenshot} button, and finally we make the \c Screenshot widget - visible if it was hidden during the screenshot. - - \snippet desktop/screenshot/screenshot.cpp 6 - - The \uicontrol {Hide This Window} option is enabled or disabled - depending on the delay of the screenshot. If there is no delay, - the application window cannot be hidden and the option's checkbox - is disabled. - - The \c updateCheckBox() slot is called whenever the user changes - the delay using the \uicontrol {Screenshot Delay} option. - - \snippet desktop/screenshot/screenshot.cpp 7 - - The private \c createOptionsGroupBox() function is called from the - constructor. - - First we create a group box that will contain all of the options' - widgets. Then we create a QSpinBox and a QLabel for the \uicontrol - {Screenshot Delay} option, and connect the spinbox to the \c - updateCheckBox() slot. Finally, we create a QCheckBox for the \uicontrol - {Hide This Window} option, add all the options' widgets to a - QGridLayout and install the layout on the group box. - - Note that we don't have to specify any parents for the widgets - when we create them. The reason is that when we add a widget to a - layout and install the layout on another widget, the layout's - widgets are automatically reparented to the widget the layout is - installed on. - - \snippet desktop/screenshot/screenshot.cpp 8 - - The private \c createButtonsLayout() function is called from the - constructor. We create the application's buttons using the private - \c createButton() function, and add them to a QHBoxLayout. - - \snippet desktop/screenshot/screenshot.cpp 9 - - The private \c createButton() function is called from the \c - createButtonsLayout() function. It simply creates a QPushButton - with the provided text, connects it to the provided receiver and - slot, and returns a pointer to the button. - - \snippet desktop/screenshot/screenshot.cpp 10 - - The private \c updateScreenshotLabel() function is called whenever - the screenshot changes, or when a resize event changes the size of - the screenshot preview label. It updates the screenshot preview's - label using the QLabel::setPixmap() and QPixmap::scaled() - functions. - - QPixmap::scaled() returns a copy of the given pixmap scaled to a - rectangle of the given size according to the given - Qt::AspectRatioMode and Qt::TransformationMode. - - We scale the original pixmap to fit the current screenshot label's - size, preserving the aspect ratio and giving the resulting pixmap - smoothed edges. -*/ - diff --git a/examples/widgets/doc/scribble.qdoc b/examples/widgets/doc/scribble.qdoc deleted file mode 100644 index 5749b9ed07..0000000000 --- a/examples/widgets/doc/scribble.qdoc +++ /dev/null @@ -1,417 +0,0 @@ -/**************************************************************************** -** -** 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/scribble - \title Scribble Example - - The Scribble example shows how to reimplement some of QWidget's - event handlers to receive the events generated for the - application's widgets. - - We reimplement the mouse event handlers to implement drawing, the - paint event handler to update the application and the resize event - handler to optimize the application's appearance. In addition we - reimplement the close event handler to intercept the close events - before terminating the application. - - The example also demonstrates how to use QPainter to draw an image - in real time, as well as to repaint widgets. - - \image scribble-example.png Screenshot of the Scribble example - - With the Scribble application the users can draw an image. The - \uicontrol File menu gives the users the possibility to open and edit an - existing image file, save an image and exit the application. While - drawing, the \uicontrol Options menu allows the users to to choose the - pen color and pen width, as well as clear the screen. In addition - the \uicontrol Help menu provides the users with information about the - Scribble example in particular, and about Qt in general. - - The example consists of two classes: - - \list - \li \c ScribbleArea is a custom widget that displays a QImage and - allows to the user to draw on it. - \li \c MainWindow provides a menu above the \c ScribbleArea. - \endlist - - We will start by reviewing the \c ScribbleArea class. Then we will - review the \c MainWindow class, which uses \c ScribbleArea. - - \section1 ScribbleArea Class Definition - - \snippet widgets/scribble/scribblearea.h 0 - - The \c ScribbleArea class inherits from QWidget. We reimplement - the \c mousePressEvent(), \c mouseMoveEvent() and \c - mouseReleaseEvent() functions to implement the drawing. We - reimplement the \c paintEvent() function to update the scribble - area, and the \c resizeEvent() function to ensure that the QImage - on which we draw is at least as large as the widget at any time. - - We need several public functions: \c openImage() loads an image - from a file into the scribble area, allowing the user to edit the - image; \c save() writes the currently displayed image to file; \c - clearImage() slot clears the image displayed in the scribble - area. We need the private \c drawLineTo() function to actually do - the drawing, and \c resizeImage() to change the size of a - QImage. The \c print() slot handles printing. - - We also need the following private variables: - - \list - \li \c modified is \c true if there are unsaved - changes to the image displayed in the scribble area. - \li \c scribbling is \c true while the user is pressing - the left mouse button within the scribble area. - \li \c penWidth and \c penColor hold the currently - set width and color for the pen used in the application. - \li \c image stores the image drawn by the user. - \li \c lastPoint holds the position of the cursor at the last - mouse press or mouse move event. - \endlist - - \section1 ScribbleArea Class Implementation - - \snippet widgets/scribble/scribblearea.cpp 0 - - In the constructor, we set the Qt::WA_StaticContents - attribute for the widget, indicating that the widget contents are - rooted to the top-left corner and don't change when the widget is - resized. Qt uses this attribute to optimize paint events on - resizes. This is purely an optimization and should only be used - for widgets whose contents are static and rooted to the top-left - corner. - - \snippet widgets/scribble/scribblearea.cpp 1 - \snippet widgets/scribble/scribblearea.cpp 2 - - In the \c openImage() function, we load the given image. Then we - resize the loaded QImage to be at least as large as the widget in - both directions using the private \c resizeImage() function and - we set the \c image member variable to be the loaded image. At - the end, we call QWidget::update() to schedule a repaint. - - \snippet widgets/scribble/scribblearea.cpp 3 - \snippet widgets/scribble/scribblearea.cpp 4 - - The \c saveImage() function creates a QImage object that covers - only the visible section of the actual \c image and saves it using - QImage::save(). If the image is successfully saved, we set the - scribble area's \c modified variable to \c false, because there is - no unsaved data. - - \snippet widgets/scribble/scribblearea.cpp 5 - \snippet widgets/scribble/scribblearea.cpp 6 - \codeline - \snippet widgets/scribble/scribblearea.cpp 7 - \snippet widgets/scribble/scribblearea.cpp 8 - - The \c setPenColor() and \c setPenWidth() functions set the - current pen color and width. These values will be used for future - drawing operations. - - \snippet widgets/scribble/scribblearea.cpp 9 - \snippet widgets/scribble/scribblearea.cpp 10 - - The public \c clearImage() slot clears the image displayed in the - scribble area. We simply fill the entire image with white, which - corresponds to RGB value (255, 255, 255). As usual when we modify - the image, we set \c modified to \c true and schedule a repaint. - - \snippet widgets/scribble/scribblearea.cpp 11 - \snippet widgets/scribble/scribblearea.cpp 12 - - For mouse press and mouse release events, we use the - QMouseEvent::button() function to find out which button caused - the event. For mose move events, we use QMouseEvent::buttons() - to find which buttons are currently held down (as an OR-combination). - - If the users press the left mouse button, we store the position - of the mouse cursor in \c lastPoint. We also make a note that the - user is currently scribbling. (The \c scribbling variable is - necessary because we can't assume that a mouse move and mouse - release event is always preceded by a mouse press event on the - same widget.) - - If the user moves the mouse with the left button pressed down or - releases the button, we call the private \c drawLineTo() function - to draw. - - \snippet widgets/scribble/scribblearea.cpp 13 - \snippet widgets/scribble/scribblearea.cpp 14 - - In the reimplementation of the \l - {QWidget::paintEvent()}{paintEvent()} function, we simply create - a QPainter for the scribble area, and draw the image. - - At this point, you might wonder why we don't just draw directly - onto the widget instead of drawing in a QImage and copying the - QImage onto screen in \c paintEvent(). There are at least three - good reasons for this: - - \list - \li The window system requires us to be able to redraw the widget - \e{at any time}. For example, if the window is minimized and - restored, the window system might have forgotten the contents - of the widget and send us a paint event. In other words, we - can't rely on the window system to remember our image. - - \li Qt normally doesn't allow us to paint outside of \c - paintEvent(). In particular, we can't paint from the mouse - event handlers. (This behavior can be changed using the - Qt::WA_PaintOnScreen widget attribute, though.) - - \li If initialized properly, a QImage is guaranteed to use 8-bit - for each color channel (red, green, blue, and alpha), whereas - a QWidget might have a lower color depth, depending on the - monitor configuration. This means that if we load a 24-bit or - 32-bit image and paint it onto a QWidget, then copy the - QWidget into a QImage again, we might lose some information. - \endlist - - \snippet widgets/scribble/scribblearea.cpp 15 - \snippet widgets/scribble/scribblearea.cpp 16 - - When the user starts the Scribble application, a resize event is - generated and an image is created and displayed in the scribble - area. We make this initial image slightly larger than the - application's main window and scribble area, to avoid always - resizing the image when the user resizes the main window (which - would be very inefficient). But when the main window becomes - larger than this initial size, the image needs to be resized. - - \snippet widgets/scribble/scribblearea.cpp 17 - \snippet widgets/scribble/scribblearea.cpp 18 - - In \c drawLineTo(), we draw a line from the point where the mouse - was located when the last mouse press or mouse move occurred, we - set \c modified to true, we generate a repaint event, and we - update \c lastPoint so that next time \c drawLineTo() is called, - we continue drawing from where we left. - - We could call the \c update() function with no parameter, but as - an easy optimization we pass a QRect that specifies the rectangle - inside the scribble are needs updating, to avoid a complete - repaint of the widget. - - \snippet widgets/scribble/scribblearea.cpp 19 - \snippet widgets/scribble/scribblearea.cpp 20 - - QImage has no nice API for resizing an image. There's a - QImage::copy() function that could do the trick, but when used to - expand an image, it fills the new areas with black, whereas we - want white. - - So the trick is to create a brand new QImage with the right size, - to fill it with white, and to draw the old image onto it using - QPainter. The new image is given the QImage::Format_RGB32 - format, which means that each pixel is stored as 0xffRRGGBB - (where RR, GG, and BB are the red, green and blue - color channels, ff is the hexadecimal value 255). - - Printing is handled by the \c print() slot: - - \snippet widgets/scribble/scribblearea.cpp 21 - - We construct a high resolution QPrinter object for the required - output format, using a QPrintDialog to ask the user to specify a - page size and indicate how the output should be formatted on the page. - - If the dialog is accepted, we perform the task of printing to the paint - device: - - \snippet widgets/scribble/scribblearea.cpp 22 - - Printing an image to a file in this way is simply a matter of - painting onto the QPrinter. We scale the image to fit within the - available space on the page before painting it onto the paint - device. - - \section1 MainWindow Class Definition - - \snippet widgets/scribble/mainwindow.h 0 - - The \c MainWindow class inherits from QMainWindow. We reimplement - the \l{QWidget::closeEvent()}{closeEvent()} handler from QWidget. - The \c open(), \c save(), \c penColor() and \c penWidth() - slots correspond to menu entries. In addition we create four - private functions. - - We use the boolean \c maybeSave() function to check if there are - any unsaved changes. If there are unsaved changes, we give the - user the opportunity to save these changes. The function returns - \c false if the user clicks \uicontrol Cancel. We use the \c saveFile() - function to let the user save the image currently displayed in - the scribble area. - - \section1 MainWindow Class Implementation - - \snippet widgets/scribble/mainwindow.cpp 0 - - In the constructor, we create a scribble area which we make the - central widget of the \c MainWindow widget. Then we create the - associated actions and menus. - - \snippet widgets/scribble/mainwindow.cpp 1 - \snippet widgets/scribble/mainwindow.cpp 2 - - Close events are sent to widgets that the users want to close, - usually by clicking \uicontrol{File|Exit} or by clicking the \uicontrol X - title bar button. By reimplementing the event handler, we can - intercept attempts to close the application. - - In this example, we use the close event to ask the user to save - any unsaved changes. The logic for that is located in the \c - maybeSave() function. If \c maybeSave() returns true, there are - no modifications or the users successfully saved them, and we - accept the event. The application can then terminate normally. If - \c maybeSave() returns false, the user clicked \uicontrol Cancel, so we - "ignore" the event, leaving the application unaffected by it. - - \snippet widgets/scribble/mainwindow.cpp 3 - \snippet widgets/scribble/mainwindow.cpp 4 - - In the \c open() slot we first give the user the opportunity to - save any modifications to the currently displayed image, before a - new image is loaded into the scribble area. Then we ask the user - to choose a file and we load the file in the \c ScribbleArea. - - \snippet widgets/scribble/mainwindow.cpp 5 - \snippet widgets/scribble/mainwindow.cpp 6 - - The \c save() slot is called when the users choose the \uicontrol {Save - As} menu entry, and then choose an entry from the format menu. The - first thing we need to do is to find out which action sent the - signal using QObject::sender(). This function returns the sender - as a QObject pointer. Since we know that the sender is an action - object, we can safely cast the QObject. We could have used a - C-style cast or a C++ \c static_cast<>(), but as a defensive - programming technique we use a qobject_cast(). The advantage is - that if the object has the wrong type, a null pointer is - returned. Crashes due to null pointers are much easier to diagnose - than crashes due to unsafe casts. - - Once we have the action, we extract the chosen format using - QAction::data(). (When the actions are created, we use - QAction::setData() to set our own custom data attached to the - action, as a QVariant. More on this when we review \c - createActions().) - - Now that we know the format, we call the private \c saveFile() - function to save the currently displayed image. - - \snippet widgets/scribble/mainwindow.cpp 7 - \snippet widgets/scribble/mainwindow.cpp 8 - - We use the \c penColor() slot to retrieve a new color from the - user with a QColorDialog. If the user chooses a new color, we - make it the scribble area's color. - - \snippet widgets/scribble/mainwindow.cpp 9 - \snippet widgets/scribble/mainwindow.cpp 10 - - To retrieve a new pen width in the \c penWidth() slot, we use - QInputDialog. The QInputDialog class provides a simple - convenience dialog to get a single value from the user. We use - the static QInputDialog::getInt() function, which combines a - QLabel and a QSpinBox. The QSpinBox is initialized with the - scribble area's pen width, allows a range from 1 to 50, a step of - 1 (meaning that the up and down arrow increment or decrement the - value by 1). - - The boolean \c ok variable will be set to \c true if the user - clicked \uicontrol OK and to \c false if the user pressed \uicontrol Cancel. - - \snippet widgets/scribble/mainwindow.cpp 11 - \snippet widgets/scribble/mainwindow.cpp 12 - - We implement the \c about() slot to create a message box - describing what the example is designed to show. - - \snippet widgets/scribble/mainwindow.cpp 13 - \snippet widgets/scribble/mainwindow.cpp 14 - - In the \c createAction() function we create the actions - representing the menu entries and connect them to the appropriate - slots. In particular we create the actions found in the \uicontrol - {Save As} sub-menu. We use QImageWriter::supportedImageFormats() - to get a list of the supported formats (as a QList). - - Then we iterate through the list, creating an action for each - format. We call QAction::setData() with the file format, so we - can retrieve it later as QAction::data(). We could also have - deduced the file format from the action's text, by truncating the - "...", but that would have been inelegant. - - \snippet widgets/scribble/mainwindow.cpp 15 - \snippet widgets/scribble/mainwindow.cpp 16 - - In the \c createMenu() function, we add the previously created - format actions to the \c saveAsMenu. Then we add the rest of the - actions as well as the \c saveAsMenu sub-menu to the \uicontrol File, - \uicontrol Options and \uicontrol Help menus. - - The QMenu class provides a menu widget for use in menu bars, - context menus, and other popup menus. The QMenuBar class provides - a horizontal menu bar with a list of pull-down \l{QMenu}s. At the - end we put the \uicontrol File and \uicontrol Options menus in the \c - {MainWindow}'s menu bar, which we retrieve using the - QMainWindow::menuBar() function. - - \snippet widgets/scribble/mainwindow.cpp 17 - \snippet widgets/scribble/mainwindow.cpp 18 - - In \c mayBeSave(), we check if there are any unsaved changes. If - there are any, we use QMessageBox to give the user a warning that - the image has been modified and the opportunity to save the - modifications. - - As with QColorDialog and QFileDialog, the easiest way to create a - QMessageBox is to use its static functions. QMessageBox provides - a range of different messages arranged along two axes: severity - (question, information, warning and critical) and complexity (the - number of necessary response buttons). Here we use the \c - warning() function sice the message is rather important. - - If the user chooses to save, we call the private \c saveFile() - function. For simplicitly, we use PNG as the file format; the - user can always press \uicontrol Cancel and save the file using another - format. - - The \c maybeSave() function returns \c false if the user clicks - \uicontrol Cancel; otherwise it returns \c true. - - \snippet widgets/scribble/mainwindow.cpp 19 - \snippet widgets/scribble/mainwindow.cpp 20 - - In \c saveFile(), we pop up a file dialog with a file name - suggestion. The static QFileDialog::getSaveFileName() function - returns a file name selected by the user. The file does not have - to exist. -*/ diff --git a/examples/widgets/doc/sdi.qdoc b/examples/widgets/doc/sdi.qdoc deleted file mode 100644 index b686888797..0000000000 --- a/examples/widgets/doc/sdi.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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 mainwindows/sdi - \title SDI Example - - The SDI example shows how to create a Single Document Interface. It uses a number of - top-level windows to display the contents of different text files. - - \image sdi-example.png -*/ diff --git a/examples/widgets/doc/shapedclock.qdoc b/examples/widgets/doc/shapedclock.qdoc deleted file mode 100644 index 8d7b856fd6..0000000000 --- a/examples/widgets/doc/shapedclock.qdoc +++ /dev/null @@ -1,131 +0,0 @@ -/**************************************************************************** -** -** 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/shapedclock - \title Shaped Clock Example - - The Shaped Clock example shows how to apply a widget mask to a top-level - widget to produce a shaped window. - - \image shapedclock-example.png - - Widget masks are used to customize the shapes of top-level widgets by restricting - the available area for painting. On some window systems, setting certain window flags - will cause the window decoration (title bar, window frame, buttons) to be disabled, - allowing specially-shaped windows to be created. In this example, we use this feature - to create a circular window containing an analog clock. - - Since this example's window does not provide a \uicontrol File menu or a close - button, we provide a context menu with an \uicontrol Exit entry so that the example - can be closed. Click the right mouse button over the window to open this menu. - - \section1 ShapedClock Class Definition - - The \c ShapedClock class is based on the \c AnalogClock class defined in the - \l{Analog Clock Example}{Analog Clock} example. The whole class definition is - presented below: - - \snippet widgets/shapedclock/shapedclock.h 0 - - The \l{QWidget::paintEvent()}{paintEvent()} implementation is the same as that found - in the \c AnalogClock class. We implement \l{QWidget::sizeHint()}{sizeHint()} - so that we don't have to resize the widget explicitly. We also provide an event - handler for resize events. This allows us to update the mask if the clock is resized. - - Since the window containing the clock widget will have no title bar, we provide - implementations for \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} and - \l{QWidget::mousePressEvent()}{mousePressEvent()} to allow the clock to be dragged - around the screen. The \c dragPosition variable lets us keep track of where the user - last clicked on the widget. - - \section1 ShapedClock Class Implementation - - The \c ShapedClock constructor performs many of the same tasks as the \c AnalogClock - constructor. We set up a timer and connect it to the widget's update() slot: - - \snippet widgets/shapedclock/shapedclock.cpp 0 - - We inform the window manager that the widget is not to be decorated with a window - frame by setting the Qt::FramelessWindowHint flag on the widget. As a result, we need - to provide a way for the user to move the clock around the screen. - - Mouse button events are delivered to the \c mousePressEvent() handler: - - \snippet widgets/shapedclock/shapedclock.cpp 1 - - If the left mouse button is pressed over the widget, we record the displacement in - global (screen) coordinates between the top-left position of the widget's frame (even - when hidden) and the point where the mouse click occurred. This displacement will be - used if the user moves the mouse while holding down the left button. Since we acted - on the event, we accept it by calling its \l{QEvent::accept()}{accept()} function. - - \image shapedclock-dragging.png - - The \c mouseMoveEvent() handler is called if the mouse is moved over the widget. - - \snippet widgets/shapedclock/shapedclock.cpp 2 - - If the left button is held down while the mouse is moved, the top-left corner of the - widget is moved to the point given by subtracting the \c dragPosition from the current - cursor position in global coordinates. If we drag the widget, we also accept the event. - - The \c paintEvent() function is given for completeness. See the - \l{Analog Clock Example}{Analog Clock} example for a description of the process used - to render the clock. - - \snippet widgets/shapedclock/shapedclock.cpp 3 - - In the \c resizeEvent() handler, we re-use some of the code from the \c paintEvent() - to determine the region of the widget that is visible to the user: - - \snippet widgets/shapedclock/shapedclock.cpp 4 - - Since the clock face is a circle drawn in the center of the widget, this is the region - we use as the mask. - - Although the lack of a window frame may make it difficult for the user to resize the - widget on some platforms, it will not necessarily be impossible. The \c resizeEvent() - function ensures that the widget mask will always be updated if the widget's dimensions - change, and additionally ensures that it will be set up correctly when the widget is - first displayed. - - Finally, we implement the \c sizeHint() for the widget so that it is given a reasonable - default size when it is first shown: - - \snippet widgets/shapedclock/shapedclock.cpp 5 - - \section1 Notes on Widget Masks - - Since QRegion allows arbitrarily complex regions to be created, widget masks can be - made to suit the most unconventionally-shaped windows, and even allow widgets to be - displayed with holes in them. - - Widget masks can also be constructed by using the contents of pixmap to define the - opaque part of the widget. For a pixmap with an alpha channel, a suitable mask can be - obtained with QPixmap::mask(). -*/ diff --git a/examples/widgets/doc/simpledommodel.qdoc b/examples/widgets/doc/simpledommodel.qdoc deleted file mode 100644 index 2564c654fa..0000000000 --- a/examples/widgets/doc/simpledommodel.qdoc +++ /dev/null @@ -1,280 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/simpledommodel - \title Simple DOM Model Example - - The Simple DOM Model example shows how an existing class can be adapted for use with - the model/view framework. - - \image simpledommodel-example.png - - Qt provides two complementary sets of classes for reading XML files: The classes based - around QXmlReader provide a SAX-style API for incremental reading of large files, and - the classes based around QDomDocument enable developers to access the contents of XML - files using a Document Object Model (DOM) API. - - In this example, we create a model that uses the DOM API to expose the structure and - contents of XML documents to views via the standard QAbstractModel interface. - - \section1 Design and Concepts - - Reading an XML document with Qt's DOM classes is a straightforward process. Typically, - the contents of a file are supplied to QDomDocument, and nodes are accessed using the - functions provided by QDomNode and its subclasses. - - \omit - For example, the following code - snippet reads the contents of a file into a QDomDocument object and traverses the - document, reading all the plain text that can be found: - - \snippet doc/src/snippets/code/doc_src_examples_simpledommodel.cpp 0 - - In principle, the functions provided by QDomNode can be used to navigate from any - given starting point in a document to the piece of data requested by another component. - Since QDomDocument maintains information about the structure of a document, we can - use this to implement the required virtual functions in a QAbstractItemModel subclass. - \endomit - - The aim is to use the structure provided by QDomDocument by wrapping QDomNode objects - in item objects similar to the \c TreeItem objects used in the - \l{Simple Tree Model Example}{Simple Tree Model} example. - - \section1 DomModel Class Definition - - Let us begin by examining the \c DomModel class: - - \snippet itemviews/simpledommodel/dommodel.h 0 - - The class definition contains all the basic functions that are needed for a - read-only model. Only the constructor and \c document() function are specific to - this model. The private \c domDocument variable is used to hold the document - that is exposed by the model; the \c rootItem variable contains a pointer to - the root item in the model. - - \section1 DomItem Class Definition - - The \c DomItem class is used to hold information about a specific QDomNode in - the document: - - \snippet itemviews/simpledommodel/domitem.h 0 - - Each \c DomItem provides a wrapper for a QDomNode obtained from the underlying - document which contains a reference to the node, it's location in the parent node's - list of child nodes, and a pointer to a parent wrapper item. - - The \c parent(), \c child(), and \c row() functions are convenience functions for - the \c DomModel to use that provide basic information about the item to be discovered - quickly. The node() function provides access to the underlying QDomNode object. - - As well as the information supplied in the constructor, the class maintains a cache - of information about any child items. This is used to provide a collection of - persistent item objects that the model can identify consistently and improve the - performance of the model when accessing child items. - - \section1 DomItem Class Implementation - - Since the \c DomItem class is only a thin wrapper around QDomNode objects, with a - few additional features to help improve performance and memory usage, we can provide - a brief outline of the class before discussing the model itself. - - The constructor simply records details of the QDomNode that needs to be wrapped: - - \snippet itemviews/simpledommodel/domitem.cpp 0 - \snippet itemviews/simpledommodel/domitem.cpp 1 - - As a result, functions to provide the parent wrapper, the row number occupied by - the item in its parent's list of children, and the underlying QDomNode for each item - are straightforward to write: - - \snippet itemviews/simpledommodel/domitem.cpp 4 - \codeline - \snippet itemviews/simpledommodel/domitem.cpp 6 - \codeline - \snippet itemviews/simpledommodel/domitem.cpp 3 - - It is necessary to maintain a collection of items which can be consistently identified - by the model. For that reason, we maintain a hash of child wrapper items that, to - minimize memory usage, is initially empty. The model uses the item's \c child() - function to help create model indexes, and this constructs wrappers for the children - of the item's QDomNode, relating the row number of each child to the newly-constructed - wrapper: - - \snippet itemviews/simpledommodel/domitem.cpp 5 - - If a QDomNode was previously wrapped, the cached wrapper is returned; otherwise, a - new wrapper is constructed and stored for valid children, and zero is returned for - invalid ones. - - The class's destructor deletes all the child items of the wrapper: - - \snippet itemviews/simpledommodel/domitem.cpp 2 - - These, in turn, will delete their children and free any QDomNode objects in use. - - \section1 DomModel Class Implementation - - The structure provided by the \c DomItem class makes the implementation of \c DomModel - similar to the \c TreeModel shown in the - \l{Simple Tree Model Example}{Simple Tree Model} example. - - The constructor accepts an existing document and a parent object for the model: - - \snippet itemviews/simpledommodel/dommodel.cpp 0 - - A shallow copy of the document is stored for future reference, and a root item is - created to provide a wrapper around the document. We assign the root item a row - number of zero only to be consistent since the root item will have no siblings. - - Since the model only contains information about the root item, the destructor only - needs to delete this one item: - - \snippet itemviews/simpledommodel/dommodel.cpp 1 - - All of the child items in the tree will be deleted by the \c DomItem destructor as - their parent items are deleted. - - \section2 Basic Properties of The Model - - Some aspects of the model do not depend on the structure of the underlying document, - and these are simple to implement. - - The number of columns exposed by the model is returned by the \c columnCount() - function: - - \snippet itemviews/simpledommodel/dommodel.cpp 2 - - This value is fixed, and does not depend on the location or type of the underlying - node in the document. We will use these three columns to display different kinds of - data from the underlying document. - - Since we only implement a read-only model, the \c flags() function is straightforward - to write: - - \snippet itemviews/simpledommodel/dommodel.cpp 5 - - Since the model is intended for use in a tree view, the \c headerData() function only - provides a horizontal header: - - \snippet itemviews/simpledommodel/dommodel.cpp 6 - - The model presents the names of nodes in the first column, element attributes in the - second, and any node values in the third. - - \section2 Navigating The Document - - The index() function creates a model index for the item with the given row, column, - and parent in the model: - - \snippet itemviews/simpledommodel/dommodel.cpp 7 - - The function first has to relate the parent index to an item that contains a node - from the underlying document. If the parent index is invalid, it refers to the root - node in the document, so we retrieve the root item that wraps it; otherwise, we - obtain a pointer to the relevant item using the QModelIndex::internalPointer() - function. We are able to extract a pointer in this way because any valid model index - will have been created by this function, and we store pointers to item objects in - any new indexes that we create with QAbstractItemModel::createIndex(): - - \snippet itemviews/simpledommodel/dommodel.cpp 8 - - A child item for the given row is provided by the parent item's \c child() function. - If a suitable child item was found then we call - \l{QAbstractItemModel::createIndex()}{createIndex()} to produce a model index for the - requested row and column, passing a pointer to the child item for it to store - internally. If no suitable child item is found, an invalid model index is returned. - - Note that the items themselves maintain ownership of their child items. This means - that the model does not need to keep track of the child items that have been created, - and can let the items themselves tidy up when they are deleted. - - The number of rows beneath a given item in the model is returned by the \c rowCount() - function, and is the number of child nodes contained by the node that corresponds to - the specified model index: - - \snippet itemviews/simpledommodel/dommodel.cpp 10 - - To obtain the relevant node in the underlying document, we access the item via the - internal pointer stored in the model index. If an invalid index is supplied, the - root item is used instead. We use the item's \c node() function to access the node - itself, and simply count the number of child nodes it contains. - - Since the model is used to represent a hierarchical data structure, it needs to - provide an implementation for the \c parent() function. This returns a model index - that corresponds to the parent of a child model index supplied as its argument: - - \snippet itemviews/simpledommodel/dommodel.cpp 9 - - For valid indexes other than the index corresponding to the root item, we obtain - a pointer to the relevant item using the method described in the \c index() function, - and use the item's \c parent() function to obtain a pointer to the parent item. - - If no valid parent item exists, or if the parent item is the root item, we can simply - follow convention and return an invalid model index. For all other parent items, we - create a model index containing the appropriate row and column numbers, and a pointer - to the parent item we just obtained. - - Data is provided by the \c data() function. For simplicity, we only provide data for - the \l{Qt::DisplayRole}{display role}, returning an invalid variant for all other - requests: - - \snippet itemviews/simpledommodel/dommodel.cpp 3 - - As before, we obtain an item pointer for the index supplied, and use it to obtain - the underlying document node. Depending on the column specified, the data we return - is obtained in different ways: - - \snippet itemviews/simpledommodel/dommodel.cpp 4 - - For the first column, we return the node's name. For the second column, we read any - attributes that the node may have, and return a string that contains a space-separated - list of attribute-value assignments. For the third column, we return any value that - the node may have; this allows the contents of text nodes to be displayed in a view. - - If data from any other column is requested, an invalid variant is returned. - - \section1 Implementation Notes - - Ideally, we would rely on the structure provided by QDomDocument to help us write - the \l{QAbstractItemModel::parent()}{parent()} and - \l{QAbstractItemModel::index()}{index()} functions that are required when subclassing - QAbstractItemModel. However, since Qt's DOM classes use their own system for - dynamically allocating memory for DOM nodes, we cannot guarantee that the QDomNode - objects returned for a given piece of information will be the same for subsequent - accesses to the document. - - We use item wrappers for each QDomNode to provide consistent pointers that the model - can use to navigate the document structure. - \omit - Since these items contain value references to the QDomNode objects themselves, this - has the side effect that the DOM nodes themselves can be used to reliably navigate - the document [not sure about this - QDom* may return different QDomNode objects for - the same piece of information]. However, this advantage is redundant since we need to - use wrapper items to obtain it. [Possible use of QDomNode cache in the model itself.] - \endomit -*/ diff --git a/examples/widgets/doc/simpletreemodel.qdoc b/examples/widgets/doc/simpletreemodel.qdoc deleted file mode 100644 index c054352cb8..0000000000 --- a/examples/widgets/doc/simpletreemodel.qdoc +++ /dev/null @@ -1,341 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/simpletreemodel - \title Simple Tree Model Example - - The Simple Tree Model example shows how to create a basic, read-only - hierarchical model to use with Qt's standard view classes. For a - description of simple non-hierarchical list and table models, see the - \l{Model/View Programming} overview. - - \image simpletreemodel-example.png - - Qt's model/view architecture provides a standard way for views to - manipulate information in a data source, using an abstract model - of the data to simplify and standardize the way it is accessed. - Simple models represent data as a table of items, and allow views - to access this data via an - \l{Model/View Programming#Models}{index-based} system. More generally, - models can be used to represent data in the form of a tree structure - by allowing each item to act as a parent to a table of child items. - - Before attempting to implement a tree model, it is worth considering whether - the data is supplied by an external source, or whether it is going to be - maintained within the model itself. In this example, we will implement an - internal structure to hold data rather than discuss how to package data from - an external source. - - \section1 Design and Concepts - - The data structure that we use to represent the structure of the data takes - the form of a tree built from \c TreeItem objects. Each \c TreeItem - represents an item in a tree view, and contains several columns of data. - - \target SimpleTreeModelStructure - \table - \row \li \inlineimage treemodel-structure.png - \li \b{Simple Tree Model Structure} - - The data is stored internally in the model using \c TreeItem objects that - are linked together in a pointer-based tree structure. Generally, each - \c TreeItem has a parent item, and can have a number of child items. - However, the root item in the tree structure has no parent item and it - is never referenced outside the model. - - Each \c TreeItem contains information about its place in the tree - structure; it can return its parent item and its row number. Having - this information readily available makes implementing the model easier. - - Since each item in a tree view usually contains several columns of data - (a title and a summary in this example), it is natural to store this - information in each item. For simplicity, we will use a list of QVariant - objects to store the data for each column in the item. - \endtable - - The use of a pointer-based tree structure means that, when passing a - model index to a view, we can record the address of the corresponding - item in the index (see QAbstractItemModel::createIndex()) and retrieve - it later with QModelIndex::internalPointer(). This makes writing the - model easier and ensures that all model indexes that refer to the same - item have the same internal data pointer. - - With the appropriate data structure in place, we can create a tree model - with a minimal amount of extra code to supply model indexes and data to - other components. - - \section1 TreeItem Class Definition - - The \c TreeItem class is defined as follows: - - \snippet itemviews/simpletreemodel/treeitem.h 0 - - The class is a basic C++ class. It does not inherit from QObject or - provide signals and slots. It is used to hold a list of QVariants, - containing column data, and information about its position in the tree - structure. The functions provide the following features: - - \list - \li The \c appendChildItem() is used to add data when the model is first - constructed and is not used during normal use. - \li The \c child() and \c childCount() functions allow the model to obtain - information about any child items. - \li Information about the number of columns associated with the item is - provided by \c columnCount(), and the data in each column can be - obtained with the data() function. - \li The \c row() and \c parent() functions are used to obtain the item's - row number and parent item. - \endlist - - The parent item and column data are stored in the \c parentItem and - \c itemData private member variables. The \c childItems variable contains - a list of pointers to the item's own child items. - - \section1 TreeItem Class Implementation - - The constructor is only used to record the item's parent and the data - associated with each column. - - \snippet itemviews/simpletreemodel/treeitem.cpp 0 - - A pointer to each of the child items belonging to this item will be - stored in the \c childItems private member variable. When the class's - destructor is called, it must delete each of these to ensure that - their memory is reused: - - \snippet itemviews/simpletreemodel/treeitem.cpp 1 - - Since each of the child items are constructed when the model is initially - populated with data, the function to add child items is straightforward: - - \snippet itemviews/simpletreemodel/treeitem.cpp 2 - - Each item is able to return any of its child items when given a suitable - row number. For example, in the \l{#SimpleTreeModelStructure}{above diagram}, - the item marked with the letter "A" corresponds to the child of the root item - with \c{row = 0}, the "B" item is a child of the "A" item with \c{row = 1}, - and the "C" item is a child of the root item with \c{row = 1}. - - The \c child() function returns the child that corresponds to - the specified row number in the item's list of child items: - - \snippet itemviews/simpletreemodel/treeitem.cpp 3 - - The number of child items held can be found with \c childCount(): - - \snippet itemviews/simpletreemodel/treeitem.cpp 4 - - The \c TreeModel uses this function to determine the number of rows that - exist for a given parent item. - - The \c row() function reports the item's location within its parent's - list of items: - - \snippet itemviews/simpletreemodel/treeitem.cpp 8 - - Note that, although the root item (with no parent item) is automatically - assigned a row number of 0, this information is never used by the model. - - The number of columns of data in the item is trivially returned by the - \c columnCount() function. - - \snippet itemviews/simpletreemodel/treeitem.cpp 5 - - Column data is returned by the \c data() function, taking advantage of - QList's ability to provide sensible default values if the column number - is out of range: - - \snippet itemviews/simpletreemodel/treeitem.cpp 6 - - The item's parent is found with \c parent(): - - \snippet itemviews/simpletreemodel/treeitem.cpp 7 - - Note that, since the root item in the model will not have a parent, this - function will return zero in that case. We need to ensure that the model - handles this case correctly when we implement the \c TreeModel::parent() - function. - - \section1 TreeModel Class Definition - - The \c TreeModel class is defined as follows: - - \snippet itemviews/simpletreemodel/treemodel.h 0 - - This class is similar to most other subclasses of QAbstractItemModel that - provide read-only models. Only the form of the constructor and the - \c setupModelData() function are specific to this model. In addition, we - provide a destructor to clean up when the model is destroyed. - - \section1 TreeModel Class Implementation - - For simplicity, the model does not allow its data to be edited. As a - result, the constructor takes an argument containing the data that the - model will share with views and delegates: - - \snippet itemviews/simpletreemodel/treemodel.cpp 0 - - It is up to the constructor to create a root item for the model. This - item only contains vertical header data for convenience. We also use it - to reference the internal data structure that contains the model data, - and it is used to represent an imaginary parent of top-level items in - the model. - - The model's internal data structure is populated with items by the - \c setupModelData() function. We will examine this function separately - at the end of this document. - - The destructor ensures that the root item and all of its descendants - are deleted when the model is destroyed: - - \snippet itemviews/simpletreemodel/treemodel.cpp 1 - - Since we cannot add data to the model after it is constructed and set - up, this simplifies the way that the internal tree of items is managed. - - Models must implement an \c index() function to provide indexes for - views and delegates to use when accessing data. Indexes are created - for other components when they are referenced by their row and column - numbers, and their parent model index. If an invalid model - index is specified as the parent, it is up to the model to return an - index that corresponds to a top-level item in the model. - - When supplied with a model index, we first check whether it is valid. - If it is not, we assume that a top-level item is being referred to; - otherwise, we obtain the data pointer from the model index with its - \l{QModelIndex::internalPointer()}{internalPointer()} function and use - it to reference a \c TreeItem object. Note that all the model indexes - that we construct will contain a pointer to an existing \c TreeItem, - so we can guarantee that any valid model indexes that we receive will - contain a valid data pointer. - - \snippet itemviews/simpletreemodel/treemodel.cpp 6 - - Since the row and column arguments to this function refer to a - child item of the corresponding parent item, we obtain the item using - the \c TreeItem::child() function. The - \l{QAbstractItemModel::createIndex()}{createIndex()} function is used - to create a model index to be returned. We specify the row and column - numbers, and a pointer to the item itself. The model index can be used - later to obtain the item's data. - - The way that the \c TreeItem objects are defined makes writing the - \c parent() function easy: - - \snippet itemviews/simpletreemodel/treemodel.cpp 7 - - We only need to ensure that we never return a model index corresponding - to the root item. To be consistent with the way that the \c index() - function is implemented, we return an invalid model index for the - parent of any top-level items in the model. - - When creating a model index to return, we must specify the row and - column numbers of the parent item within its own parent. We can - easily discover the row number with the \c TreeItem::row() function, - but we follow a convention of specifying 0 as the column number of - the parent. The model index is created with - \l{QAbstractItemModel::createIndex()}{createIndex()} in the same way - as in the \c index() function. - - The \c rowCount() function simply returns the number of child items - for the \c TreeItem that corresponds to a given model index, or the - number of top-level items if an invalid index is specified: - - \snippet itemviews/simpletreemodel/treemodel.cpp 8 - - Since each item manages its own column data, the \c columnCount() - function has to call the item's own \c columnCount() function to - determine how many columns are present for a given model index. - As with the \c rowCount() function, if an invalid model index is - specified, the number of columns returned is determined from the - root item: - - \snippet itemviews/simpletreemodel/treemodel.cpp 2 - - Data is obtained from the model via \c data(). Since the item manages - its own columns, we need to use the column number to retrieve the data - with the \c TreeItem::data() function: - - \snippet itemviews/simpletreemodel/treemodel.cpp 3 - - Note that we only support the \l{Qt::ItemDataRole}{DisplayRole} - in this implementation, and we also return invalid QVariant objects for - invalid model indexes. - - We use the \c flags() function to ensure that views know that the - model is read-only: - - \snippet itemviews/simpletreemodel/treemodel.cpp 4 - - The \c headerData() function returns data that we conveniently stored - in the root item: - - \snippet itemviews/simpletreemodel/treemodel.cpp 5 - - This information could have been supplied in a different way: either - specified in the constructor, or hard coded into the \c headerData() - function. - - \section1 Setting Up the Data in the Model - - We use the \c setupModelData() function to set up the initial data in - the model. This function parses a text file, extracting strings of - text to use in the model, and creates item objects that record both - the data and the overall model structure. - Naturally, this function works in a way that is very specific to - this model. We provide the following description of its behavior, - and refer the reader to the example code itself for more information. - - We begin with a text file in the following format: - - \code - Getting Started How to familiarize yourself with Qt Designer - Launching Designer Running the Qt Designer application - The User Interface How to interact with Qt Designer - \endcode - \dots - \code - Connection Editing Mode Connecting widgets together with signals and slots - Connecting Objects Making connections in Qt Designer - Editing Connections Changing existing connections - \endcode - - We process the text file with the following two rules: - - \list - \li For each pair of strings on each line, create an item (or node) - in a tree structure, and place each string in a column of data - in the item. - \li When the first string on a line is indented with respect to the - first string on the previous line, make the item a child of the - previous item created. - \endlist - - To ensure that the model works correctly, it is only necessary to - create instances of \c TreeItem with the correct data and parent item. -*/ diff --git a/examples/widgets/doc/simplewidgetmapper.qdoc b/examples/widgets/doc/simplewidgetmapper.qdoc deleted file mode 100644 index 2b7cd2d79a..0000000000 --- a/examples/widgets/doc/simplewidgetmapper.qdoc +++ /dev/null @@ -1,125 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/simplewidgetmapper - \title Simple Widget Mapper Example - - The Simple Widget Mapper example shows how to use a widget mapper to display - data from a model in a collection of widgets. - - \image simplewidgetmapper-example.png - - The QDataWidgetMapper class allows information obtained from a - \l{Model Classes}{model} to be viewed and edited in a collection of - widgets instead of in an \l{View Classes}{item view}. - Any model derived from QAbstractItemModel can be used as the source of - data and almost any input widget can be used to display it. - - The example itself is very simple: we create \c Window, a QWidget subclass - that we use to hold the widgets used to present the data, and show it. The - \c Window class will provide buttons that the user can click to show - different records from the model. - - \section1 Window Class Definition - - The class provides a constructor, a slot to keep the buttons up to date, - and a private function to set up the model: - - \snippet itemviews/simplewidgetmapper/window.h Window definition - - In addition to the QDataWidgetMapper object and the controls used to make - up the user interface, we use a QStandardItemModel to hold our data. - We could use a custom model, but this standard implementation is sufficient - for our purposes. - - \section1 Window Class Implementation - - The constructor of the \c Window class can be explained in three parts. - In the first part, we set up the widgets used for the user interface: - - \snippet itemviews/simplewidgetmapper/window.cpp Set up widgets - - We also set up the buddy relationships between various labels and the - corresponding input widgets. - - Next, we set up the widget mapper, relating each input widget to a column - in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}: - - \snippet itemviews/simplewidgetmapper/window.cpp Set up the mapper - - We also connect the mapper to the \uicontrol{Next} and \uicontrol{Previous} buttons - via its \l{QDataWidgetMapper::}{toNext()} and - \l{QDataWidgetMapper::}{toPrevious()} slots. The mapper's - \l{QDataWidgetMapper::}{currentIndexChanged()} signal is connected to the - \c{updateButtons()} slot in the window which we'll show later. - - In the final part of the constructor, we set up the layout, placing each - of the widgets in a grid (we could also use a QFormLayout for this): - - \snippet itemviews/simplewidgetmapper/window.cpp Set up the layout - - Lastly, we set the window title and initialize the mapper by setting it to - refer to the first row in the model. - - The model is initialized in the window's \c{setupModel()} function. Here, - we create a standard model with 5 rows and 3 columns, and we insert some - sample names, addresses and ages into each row: - - \snippet itemviews/simplewidgetmapper/window.cpp Set up the model - - As a result, each row can be treated like a record in a database, and the - widget mapper will read the data from each row, using the column numbers - specified earlier to access the correct data for each widget. This is - shown in the following diagram: - - \image widgetmapper-simple-mapping.png - - Since the user can navigate using the buttons in the user interface, the - example is fully-functional at this point, but to make it a bit more - user-friendly, we implement the \c{updateButtons()} slot to show when the - user is viewing the first or last records: - - \snippet itemviews/simplewidgetmapper/window.cpp Slot for updating the buttons - - If the mapper is referring to the first row in the model, the \uicontrol{Previous} - button is disabled. Similarly, the \uicontrol{Next} button is disabled if the - mapper reaches the last row in the model. - - \section1 More Complex Mappings - - The QDataWidgetMapper class makes it easy to relate information from a - model to widgets in a user interface. However, it is sometimes necessary - to use input widgets which offer choices to the user, such as QComboBox, - in conjunction with a widget mapper. - - In these situations, although the mapping to input widgets remains simple, - more work needs to be done to expose additional data to the widget mapper. - This is covered by the \l{Combo Widget Mapper Example}{Combo Widget Mapper} - and \l{SQL Widget Mapper Example}{SQL Widget Mapper} - examples. -*/ diff --git a/examples/widgets/doc/sipdialog.qdoc b/examples/widgets/doc/sipdialog.qdoc deleted file mode 100644 index b5f18cb4be..0000000000 --- a/examples/widgets/doc/sipdialog.qdoc +++ /dev/null @@ -1,127 +0,0 @@ -/**************************************************************************** -** -** 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 dialogs/sipdialog - \title SIP Dialog Example - \ingroup qtce - - The SIP Dialog example shows how to create a dialog that is aware of - the Windows Mobile SIP (Software Input Panel) and reacts to it. - - \table - \row \li \inlineimage sipdialog-closed.png - \li \inlineimage sipdialog-opened.png - \endtable - - Sometimes it is necessary for a dialog to take the SIP into account, - as the SIP may hide important input widgets. The SIP Dialog Example - shows how a \c Dialog object, \c dialog, can be resized accordingly - if the SIP is opened, by embedding the contents of \c dialog in a - QScrollArea. - - \section1 Dialog Class Definition - - The \c Dialog class is a subclass of QDialog that implements a public - slot, \c desktopResized(), and a public function, \c reactToSIP(). Also, - it holds a private instance of QRect, \c desktopGeometry. - - \snippet dialogs/sipdialog/dialog.h Dialog header - - \section1 Dialog Class Implementation - - In the constructor of \c Dialog, we start by obtaining the - available geometry of the screen with - \l{QDesktopWidget::availableGeometry()}{availableGeometry()}. The - parameter used is \c 0 to indicate that we require the primary screen. - - \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part1 - - We set the window's title to "SIP Dialog Example" and declare a QScrollArea - object, \c scrollArea. Next we instantiate a QGroupBox, \c groupBox, with - \c scrollArea as its parent. The title of \c groupBox is also set to - "SIP Dialog Example". A QGridLayout object, \c gridLayout, is then used - as \c{groupBox}'s layout. - - We create a QLineEdit, a QLabel and a QPushButton and we set the - \l{QWidget::setMinimumWidth()}{minimumWidth} property to 220 pixels, - respectively. - - \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part2 - - Also, all three widgets' text are set accordingly. The - \l{QGridLayout::setVerticalSpacing()}{verticalSpacing} property of - \c gridLayout is set based on the height of \c desktopGeometry. This - is to adapt to the different form factors of Windows Mobile. Then, we - add our widgets to the layout. - - \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part3 - - The \c{scrollArea}'s widget is set to \c groupBox. We use a QHBoxLayout - object, \c layout, to contain \c scrollArea. The \c{Dialog}'s layout - is set to \c layout and the scroll area's horizontal scroll bar is turned - off. - - \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part4 - - The following signals are connected to their respective slots: - \list - \li \c{button}'s \l{QPushButton::pressed()}{pressed()} signal to - \l{QApplication}'s \l{QApplication::closeAllWindows()} - {closeAllWindows()} slot, - \li \l{QDesktopWidget}'s \l{QDesktopWidget::workAreaResized()} - {workAreaResized()} signal to \c{dialog}'s \c desktopResized() slot. - \endlist - - \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part5 - - The \c desktopResized() function accepts an integer, \a screen, - corresponding to the screen's index. We only invoke \c reactToSIP() - if \a screen is the primary screen (e.g. index = 0). - - \snippet dialogs/sipdialog/dialog.cpp desktopResized() function - - The \c reactToSIP() function resizes \c dialog accordingly if the - desktop's available geometry changed vertically, as this change signifies - that the SIP may have been opened or closed. - - \snippet dialogs/sipdialog/dialog.cpp reactToSIP() function - - If the height has decreased, we unset the maximized window state. - Otherwise, we set the maximized window state. Lastly, we update - \c desktopGeometry to the desktop's available geometry. - - \section1 The \c main() function - - The \c main() function for the SIP Dialog example instantiates \c Dialog - and invokes its \l{QDialog::exec()}{exec()} function. - - \snippet dialogs/sipdialog/main.cpp main() function - - \note Although this example uses a dialog, the techniques used here apply to - all top-level widgets respectively. -*/ diff --git a/examples/widgets/doc/sliders.qdoc b/examples/widgets/doc/sliders.qdoc deleted file mode 100644 index 209d81198d..0000000000 --- a/examples/widgets/doc/sliders.qdoc +++ /dev/null @@ -1,255 +0,0 @@ -/**************************************************************************** -** -** 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/sliders - \title Sliders Example - - Qt provides three types of slider-like widgets: QSlider, - QScrollBar and QDial. They all inherit most of their - functionality from QAbstractSlider, and can in theory replace - each other in an application since the differences only concern - their look and feel. This example shows what they look like, how - they work and how their behavior and appearance can be - manipulated through their properties. - - The example also demonstrates how signals and slots can be used to - synchronize the behavior of two or more widgets. - - \image sliders-example.png Screenshot of the Sliders example - - The Sliders example consists of two classes: - - \list - - \li \c SlidersGroup is a custom widget. It combines a QSlider, a - QScrollBar and a QDial. - - \li \c Window is the main widget combining a QGroupBox and a - QStackedWidget. In this example, the QStackedWidget provides a - stack of two \c SlidersGroup widgets. The QGroupBox contain - several widgets that control the behavior of the slider-like - widgets. - - \endlist - - First we will review the \c Window class, then we - will take a look at the \c SlidersGroup class. - - \section1 Window Class Definition - - \snippet widgets/sliders/window.h 0 - - The \c Window class inherits from QWidget. It displays the slider - widgets and allows the user to set their minimum, maximum and - current values and to customize their appearance, key bindings - and orientation. We use a private \c createControls() function to - create the widgets that provide these controlling mechanisms and - to connect them to the slider widgets. - - \section1 Window Class Implementation - - \snippet widgets/sliders/window.cpp 0 - - In the constructor we first create the two \c SlidersGroup - widgets that display the slider widgets horizontally and - vertically, and add them to the QStackedWidget. QStackedWidget - provides a stack of widgets where only the top widget is visible. - With \c createControls() we create a connection from a - controlling widget to the QStackedWidget, making the user able to - choose between horizontal and vertical orientation of the slider - widgets. The rest of the controlling mechanisms is implemented by - the same function call. - - \snippet widgets/sliders/window.cpp 1 - \snippet widgets/sliders/window.cpp 2 - - Then we connect the \c horizontalSliders, \c verticalSliders and - \c valueSpinBox to each other, so that the slider widgets and the - control widget will behave synchronized when the current value of - one of them changes. The \c valueChanged() signal is emitted with - the new value as argument. The \c setValue() slot sets the - current value of the widget to the new value, and emits \c - valueChanged() if the new value is different from the old one. - - We put the group of control widgets and the stacked widget in a - horizontal layout before we initialize the minimum, maximum and - current values. The initialization of the current value will - propagate to the slider widgets through the connection we made - between \c valueSpinBox and the \c SlidersGroup widgets. The - minimum and maximum values propagate through the connections we - created with \c createControls(). - - \snippet widgets/sliders/window.cpp 3 - \snippet widgets/sliders/window.cpp 4 - - In the private \c createControls() function, we let a QGroupBox - (\c controlsGroup) display the control widgets. A group box can - provide a frame, a title and a keyboard shortcut, and displays - various other widgets inside itself. The group of control widgets - is composed by two checkboxes, three spin boxes (with labels) and - one combobox. - - After creating the labels, we create the two checkboxes. - Checkboxes are typically used to represent features in an - application that can be enabled or disabled. When \c - invertedAppearance is enabled, the slider values are inverted. - The table below shows the appearance for the different - slider-like widgets: - - \table - \header \li \li{2,1} QSlider \li{2,1} QScrollBar \li{2,1} QDial - \header \li \li Normal \li Inverted \li Normal \li Inverted \li Normal \li Inverted - \row \li Qt::Horizontal \li Left to right \li Right to left \li Left to right \li Right to left \li Clockwise \li Counterclockwise - \row \li Qt::Vertical \li Bottom to top \li Top to bottom \li Top to bottom \li Bottom to top \li Clockwise \li Counterclockwise - \endtable - - It is common to invert the appearance of a vertical QSlider. A - vertical slider that controls volume, for example, will typically - go from bottom to top (the non-inverted appearance), whereas a - vertical slider that controls the position of an object on screen - might go from top to bottom, because screen coordinates go from - top to bottom. - - When the \c invertedKeyBindings option is enabled (corresponding - to the QAbstractSlider::invertedControls property), the slider's - wheel and key events are inverted. The normal key bindings mean - that scrolling the mouse wheel "up" or using keys like page up - will increase the slider's current value towards its maximum. - Inverted, the same wheel and key events will move the value - toward the slider's minimum. This can be useful if the \e - appearance of a slider is inverted: Some users might expect the - keys to still work the same way on the value, whereas others - might expect \uicontrol PageUp to mean "up" on the screen. - - Note that for horizontal and vertical scroll bars, the key - bindings are inverted by default: \uicontrol PageDown increases the - current value, and \uicontrol PageUp decreases it. - - \snippet widgets/sliders/window.cpp 5 - \snippet widgets/sliders/window.cpp 6 - - Then we create the spin boxes. QSpinBox allows the user to choose - a value by clicking the up and down buttons or pressing the \uicontrol - Up and \uicontrol Down keys on the keyboard to modify the value - currently displayed. The user can also type in the value - manually. The spin boxes control the minimum, maximum and current - values for the QSlider, QScrollBar, and QDial widgets. - - We create a QComboBox that allows the user to choose the - orientation of the slider widgets. The QComboBox widget is a - combined button and popup list. It provides a means of presenting - a list of options to the user in a way that takes up the minimum - amount of screen space. - - \snippet widgets/sliders/window.cpp 7 - \snippet widgets/sliders/window.cpp 8 - - We synchronize the behavior of the control widgets and the slider - widgets through their signals and slots. We connect each control - widget to both the horizontal and vertical group of slider - widgets. We also connect \c orientationCombo to the - QStackedWidget, so that the correct "page" is shown. Finally, we - lay out the control widgets in a QGridLayout within the \c - controlsGroup group box. - - \section1 SlidersGroup Class Definition - - \snippet widgets/sliders/slidersgroup.h 0 - - The \c SlidersGroup class inherits from QGroupBox. It provides a - frame and a title, and contains a QSlider, a QScrollBar and a - QDial. - - We provide a \c valueChanged() signal and a public \c setValue() - slot with equivalent functionality to the ones in QAbstractSlider - and QSpinBox. In addition, we implement several other public - slots to set the minimum and maximum value, and invert the slider - widgets' appearance as well as key bindings. - - \section1 SlidersGroup Class Implementation - - \snippet widgets/sliders/slidersgroup.cpp 0 - - First we create the slider-like widgets with the appropriate - properties. In particular we set the focus policy for each - widget. Qt::FocusPolicy is an enum type that defines the various - policies a widget can have with respect to acquiring keyboard - focus. The Qt::StrongFocus policy means that the widget accepts - focus by both tabbing and clicking. - - Then we connect the widgets with each other, so that they will - stay synchronized when the current value of one of them changes. - - \snippet widgets/sliders/slidersgroup.cpp 1 - \snippet widgets/sliders/slidersgroup.cpp 2 - - We connect \c {dial}'s \c valueChanged() signal to the - \c{SlidersGroup}'s \c valueChanged() signal, to notify the other - widgets in the application (i.e., the control widgets) of the - changed value. - - \snippet widgets/sliders/slidersgroup.cpp 3 - \codeline - \snippet widgets/sliders/slidersgroup.cpp 4 - - Finally, depending on the \l {Qt::Orientation}{orientation} given - at the time of construction, we choose and create the layout for - the slider widgets within the group box. - - \snippet widgets/sliders/slidersgroup.cpp 5 - \snippet widgets/sliders/slidersgroup.cpp 6 - - The \c setValue() slot sets the value of the QSlider. We don't - need to explicitly call - \l{QAbstractSlider::setValue()}{setValue()} on the QScrollBar and - QDial widgets, since QSlider will emit the - \l{QAbstractSlider::valueChanged()}{valueChanged()} signal when - its value changes, triggering a domino effect. - - \snippet widgets/sliders/slidersgroup.cpp 7 - \snippet widgets/sliders/slidersgroup.cpp 8 - \codeline - \snippet widgets/sliders/slidersgroup.cpp 9 - \snippet widgets/sliders/slidersgroup.cpp 10 - - The \c setMinimum() and \c setMaximum() slots are used by the \c - Window class to set the range of the QSlider, QScrollBar, and - QDial widgets. - - \snippet widgets/sliders/slidersgroup.cpp 11 - \snippet widgets/sliders/slidersgroup.cpp 12 - \codeline - \snippet widgets/sliders/slidersgroup.cpp 13 - \snippet widgets/sliders/slidersgroup.cpp 14 - - The \c invertAppearance() and \c invertKeyBindings() slots - control the child widgets' - \l{QAbstractSlider::invertedAppearance}{invertedAppearance} and - \l{QAbstractSlider::invertedControls}{invertedControls} - properties. -*/ diff --git a/examples/widgets/doc/spinboxdelegate.qdoc b/examples/widgets/doc/spinboxdelegate.qdoc deleted file mode 100644 index 258811cc4c..0000000000 --- a/examples/widgets/doc/spinboxdelegate.qdoc +++ /dev/null @@ -1,141 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/spinboxdelegate - \title Spin Box Delegate Example - - The Spin Box Delegate example shows how to create an editor for a custom delegate in - the model/view framework by reusing a standard Qt editor widget. - - The model/view framework provides a standard delegate that is used by default - with the standard view classes. For most purposes, the selection of editor - widgets available through this delegate is sufficient for editing text, boolean - values, and other simple data types. However, for specific data types, it is - sometimes necessary to use a custom delegate to either display the data in a - specific way, or allow the user to edit it with a custom control. - - \image spinboxdelegate-example.png - - This concepts behind this example are covered in the - \l{Model/View Programming#Delegate Classes}{Delegate Classes} chapter - of the \l{Model/View Programming} overview. - - \section1 SpinBoxDelegate Class Definition - - The definition of the delegate is as follows: - - \snippet itemviews/spinboxdelegate/delegate.h 0 - - The delegate class declares only those functions that are needed to - create an editor widget, display it at the correct location in a view, - and communicate with a model. Custom delegates can also provide their - own painting code by reimplementing the \c paintEvent() function. - Furthermore it is also possible to reuse (and avoid deleting) the editor - widget by reimplementing the \a destroyEditor() function. A reused widget - could be a mutable member created in the constructor and deleted in - the destructor. - - \section1 SpinBoxDelegate Class Implementation - - Delegates are often stateless. The constructor only needs to - call the base class's constructor with the parent QObject as its - argument: - - \snippet itemviews/spinboxdelegate/delegate.cpp 0 - - Since the delegate is a subclass of QStyledItemDelegate, the data it retrieves - from the model is displayed in a default style, and we do not need to - provide a custom \c paintEvent(). - - The \c createEditor() function returns an editor widget, in this case a - spin box that restricts values from the model to integers from 0 to 100 - inclusive. - - \snippet itemviews/spinboxdelegate/delegate.cpp 1 - - We install an event filter on the spin box to ensure that it behaves in - a way that is consistent with other delegates. The implementation for - the event filter is provided by the base class. - - The \c setEditorData() function reads data from the model, converts it - to an integer value, and writes it to the editor widget. - - \snippet itemviews/spinboxdelegate/delegate.cpp 2 - - Since the view treats delegates as ordinary QWidget instances, we have - to use a static cast before we can set the value in the spin box. - - The \c setModelData() function reads the contents of the spin box, and - writes it to the model. - - \snippet itemviews/spinboxdelegate/delegate.cpp 3 - - We call \l{QSpinBox::interpretText()}{interpretText()} to make sure that - we obtain the most up-to-date value in the spin box. - - The \c updateEditorGeometry() function updates the editor widget's - geometry using the information supplied in the style option. This is the - minimum that the delegate must do in this case. - - \snippet itemviews/spinboxdelegate/delegate.cpp 4 - - More complex editor widgets may divide the rectangle available in - \c{option.rect} between different child widgets if required. - - \section1 The Main Function - - This example is written in a slightly different way to many of the - other examples supplied with Qt. To demonstrate the use of a custom - editor widget in a standard view, it is necessary to set up a model - containing some arbitrary data and a view to display it. - - We set up the application in the normal way, construct a standard item - model to hold some data, set up a table view to use the data in the - model, and construct a custom delegate to use for editing: - - \snippet itemviews/spinboxdelegate/main.cpp 0 - - The table view is informed about the delegate, and will use it to - display each of the items. Since the delegate is a subclass of - QStyledItemDelegate, each cell in the table will be rendered using standard - painting operations. - - We insert some arbitrary data into the model for demonstration purposes: - - \snippet itemviews/spinboxdelegate/main.cpp 1 - \snippet itemviews/spinboxdelegate/main.cpp 2 - - Finally, the table view is displayed with a window title, and we start - the application's event loop: - - \snippet itemviews/spinboxdelegate/main.cpp 3 - - Each of the cells in the table can now be edited in the usual way, but - the spin box ensures that the data returned to the model is always - constrained by the values allowed by the spin box delegate. -*/ diff --git a/examples/widgets/doc/spinboxes.qdoc b/examples/widgets/doc/spinboxes.qdoc deleted file mode 100644 index ed4eea6a60..0000000000 --- a/examples/widgets/doc/spinboxes.qdoc +++ /dev/null @@ -1,191 +0,0 @@ -/**************************************************************************** -** -** 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/spinboxes - \title Spin Boxes Example - - The Spin Boxes example shows how to use the many different types of spin boxes - available in Qt, from a simple QSpinBox widget to more complex editors like - the QDateTimeEdit widget. - - \image spinboxes-example.png - - The example consists of a single \c Window class that is used to display the - different spin box-based widgets available with Qt. - - \section1 Window Class Definition - - The \c Window class inherits QWidget and contains two slots that are used - to provide interactive features: - - \snippet widgets/spinboxes/window.h 0 - - The private functions are used to set up each type of spin box in the window. - We use member variables to keep track of various widgets so that they can - be reconfigured when required. - - \section1 Window Class Implementation - - The constructor simply calls private functions to set up the different types - of spin box used in the example, and places each group in a layout: - - \snippet widgets/spinboxes/window.cpp 0 - - We use the layout to manage the arrangement of the window's child widgets, - and change the window title. - - The \c createSpinBoxes() function constructs a QGroupBox and places three - QSpinBox widgets inside it with descriptive labels to indicate the types of - input they expect. - - \snippet widgets/spinboxes/window.cpp 1 - - The first spin box shows the simplest way to use QSpinBox. It accepts values - from -20 to 20, the current value can be increased or decreased by 1 with - either the arrow buttons or \uicontrol{Up} and \uicontrol{Down} keys, and the default - value is 0. - - The second spin box uses a larger step size and displays a suffix to - provide more information about the type of data the number represents: - - \snippet widgets/spinboxes/window.cpp 2 - - This spin box also displays a - \l{QAbstractSpinBox::specialValueText}{special value} instead of the minimum - value defined for it. This means that it will never show \uicontrol{0%}, but will - display \uicontrol{Automatic} when the minimum value is selected. - - The third spin box shows how a prefix can be used: - - \snippet widgets/spinboxes/window.cpp 4 - - For simplicity, we show a spin box with a prefix and no suffix. It is also - possible to use both at the same time. - - \snippet widgets/spinboxes/window.cpp 5 - - The rest of the function sets up a layout for the group box and places each - of the widgets inside it. - - The \c createDateTimeEdits() function constructs another group box with a - selection of spin boxes used for editing dates and times. - - \snippet widgets/spinboxes/window.cpp 6 - - The first spin box is a QDateEdit widget that is able to accept dates - within a given range specified using QDate values. The arrow buttons and - \uicontrol{Up} and \uicontrol{Down} keys can be used to increase and decrease the - values for year, month, and day when the cursor is in the relevant section. - - The second spin box is a QTimeEdit widget: - - \snippet widgets/spinboxes/window.cpp 7 - - Acceptable values for the time are defined using QTime values. - - The third spin box is a QDateTimeEdit widget that can display both date and - time values, and we place a label above it to indicate the range of allowed - times for a meeting. These widgets will be updated when the user changes a - format string. - - \snippet widgets/spinboxes/window.cpp 8 - - The format string used for the date time editor, which is also shown in the - string displayed by the label, is chosen from a set of strings in a combobox: - - \snippet widgets/spinboxes/window.cpp 9 - \codeline - \snippet widgets/spinboxes/window.cpp 10 - - A signal from this combobox is connected to a slot in the \c Window class - (shown later). - - \snippet widgets/spinboxes/window.cpp 11 - - Each child widget of the group box in placed in a layout. - - The \c setFormatString() slot is called whenever the user selects a new - format string in the combobox. The display format for the QDateTimeEdit - widget is set using the raw string passed by the signal: - - \snippet widgets/spinboxes/window.cpp 12 - - Depending on the visible sections in the widget, we set a new date or time - range, and update the associated label to provide relevant information for - the user: - - \snippet widgets/spinboxes/window.cpp 13 - - When the format string is changed, there will be an appropriate label and - entry widget for dates, times, or both types of input. - - The \c createDoubleSpinBoxes() function constructs three spin boxes that are - used to input double-precision floating point numbers: - - \snippet widgets/spinboxes/window.cpp 14 - - Before the QDoubleSpinBox widgets are constructed, we create a spin box to - control how many decimal places they show. By default, only two decimal places - are shown in the following spin boxes, each of which is the equivalent of a - spin box in the group created by the \c createSpinBoxes() function. - - The first double spin box shows a basic double-precision spin box with the - same range, step size, and default value as the first spin box in the - \c createSpinBoxes() function: - - \snippet widgets/spinboxes/window.cpp 15 - - However, this spin box also allows non-integer values to be entered. - - The second spin box displays a suffix and shows a special value instead - of the minimum value: - - \snippet widgets/spinboxes/window.cpp 16 - - The third spin box displays a prefix instead of a suffix: - - \snippet widgets/spinboxes/window.cpp 17 - - We connect the QSpinBox widget that specifies the precision to a slot in - the \c Window class. - - \snippet widgets/spinboxes/window.cpp 18 - - The rest of the function places each of the widgets into a layout for the - group box. - - The \c changePrecision() slot is called when the user changes the value in - the precision spin box: - - \snippet widgets/spinboxes/window.cpp 19 - - This function simply uses the integer supplied by the signal to specify the - number of decimal places in each of the QDoubleSpinBox widgets. Each one - of these will be updated automatically when their - \l{QDoubleSpinBox::decimals}{decimals} property is changed. -*/ diff --git a/examples/widgets/doc/spreadsheet.qdoc b/examples/widgets/doc/spreadsheet.qdoc deleted file mode 100644 index 7364f022cb..0000000000 --- a/examples/widgets/doc/spreadsheet.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/spreadsheet - \title Spreadsheet - - The Spreadsheet example shows how a table view can be used to create a - simple spreadsheet application. Custom delegates are used to render different - types of data in distinctive colors. - - \image spreadsheet-demo.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{}, 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/src/addressbook.qdoc b/examples/widgets/doc/src/addressbook.qdoc new file mode 100644 index 0000000000..9b4ede5775 --- /dev/null +++ b/examples/widgets/doc/src/addressbook.qdoc @@ -0,0 +1,442 @@ +/**************************************************************************** +** +** 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 itemviews/addressbook + \title Address Book Example + + The address book example shows how to use proxy models to display + different views onto data from a single model. + + \image addressbook-example.png Screenshot of the Address Book example + + This example provides an address book that allows contacts to be + grouped alphabetically into 9 groups: ABC, DEF, GHI, ... , VW, + ..., XYZ. This is achieved by using multiple views on the same + model, each of which is filtered using an instance of the + QSortFilterProxyModel class. + + + \section1 Overview + + The address book contains 5 classes: \c MainWindow, + \c AddressWidget, \c TableModel, \c NewAddressTab and + \c AddDialog. The \c MainWindow class uses \c AddressWidget as + its central widget and provides \uicontrol File and \uicontrol Tools menus. + + \image addressbook-classes.png Diagram for Address Book Example + + The \c AddressWidget class is a QTabWidget subclass that is used + to manipulate the 10 tabs displayed in the example: the 9 + alphabet group tabs and an instance of \c NewAddressTab. + The \c NewAddressTab class is a subclass of QWidget that + is only used whenever the address book is empty, prompting the + user to add some contacts. \c AddressWidget also interacts with + an instance of \c TableModel to add, edit and remove entries to + the address book. + + \c TableModel is a subclass of QAbstractTableModel that provides + the standard model/view API to access data. It also holds a + QList of \l{QPair}s corresponding to the contacts added. + However, this data is not all visible in a single tab. Instead, + QTableView is used to provide 9 different views of the same + data, according to the alphabet groups. + + QSortFilterProxyModel is the class responsible for filtering + the contacts for each group of contacts. Each proxy model uses + a QRegExp to filter out contacts that do not belong in the + corresponding alphabetical group. The \c AddDialog class is + used to obtain information from the user for the address book. + This QDialog subclass is instantiated by \c NewAddressTab to + add contacts, and by \c AddressWidget to add and edit contacts. + + We begin by looking at the \c TableModel implementation. + + + \section1 TableModel Class Definition + + The \c TableModel class provides standard API to access data in + its QList of \l{QPair}s by subclassing QAbstractTableModel. The + basic functions that must be implemented in order to do so are: + \c rowCount(), \c columnCount(), \c data(), \c headerData(). + For TableModel to be editable, it has to provide implementations + \c insertRows(), \c removeRows(), \c setData() and \c flags() + functions. + + \snippet itemviews/addressbook/tablemodel.h 0 + + Two constructors are used, a default constructor which uses + \c TableModel's own \c {QList>} and one + that takes \c {QList} as an argument, + for convenience. + + + \section1 TableModel Class Implementation + + We implement the two constructors as defined in the header file. + The second constructor initializes the list of pairs in the + model, with the parameter value. + + \snippet itemviews/addressbook/tablemodel.cpp 0 + + The \c rowCount() and \c columnCount() functions return the + dimensions of the model. Whereas, \c rowCount()'s value will vary + depending on the number of contacts added to the address book, + \c columnCount()'s value is always 2 because we only need space + for the \b Name and \b Address columns. + + \note The \c Q_UNUSED() macro prevents the compiler from + generating warnings regarding unused parameters. + + \snippet itemviews/addressbook/tablemodel.cpp 1 + + The \c data() function returns either a \b Name or + \b {Address}, based on the contents of the model index + supplied. The row number stored in the model index is used to + reference an item in the list of pairs. Selection is handled + by the QItemSelectionModel, which will be explained with + \c AddressWidget. + + \snippet itemviews/addressbook/tablemodel.cpp 2 + + The \c headerData() function displays the table's header, + \b Name and \b Address. If you require numbered entries + for your address book, you can use a vertical header which we + have hidden in this example (see the \c AddressWidget + implementation). + + \snippet itemviews/addressbook/tablemodel.cpp 3 + + The \c insertRows() function is called before new data is added, + otherwise the data will not be displayed. The + \c beginInsertRows() and \c endInsertRows() functions are called + to ensure all connected views are aware of the changes. + + \snippet itemviews/addressbook/tablemodel.cpp 4 + + The \c removeRows() function is called to remove data. Again, + \l{QAbstractItemModel::}{beginRemoveRows()} and + \l{QAbstractItemModel::}{endRemoveRows()} are called to ensure + all connected views are aware of the changes. + + \snippet itemviews/addressbook/tablemodel.cpp 5 + + The \c setData() function is the function that inserts data into + the table, item by item and not row by row. This means that to + fill a row in the address book, \c setData() must be called + twice, as each row has 2 columns. It is important to emit the + \l{QAbstractItemModel::}{dataChanged()} signal as it tells all + connected views to update their displays. + + \snippet itemviews/addressbook/tablemodel.cpp 6 + + The \c flags() function returns the item flags for the given + index. + + \snippet itemviews/addressbook/tablemodel.cpp 7 + + We set the Qt::ItemIsEditable flag because we want to allow the + \c TableModel to be edited. Although for this example we don't + use the editing features of the QTableView object, we enable + them here so that we can reuse the model in other programs. + + The last function in \c {TableModel}, \c getList() returns the + QList> object that holds all the + contacts in the address book. We use this function later to + obtain the list of contacts to check for existing entries, write + the contacts to a file and read them back. Further explanation is + given with \c AddressWidget. + + \snippet itemviews/addressbook/tablemodel.cpp 8 + + + \section1 AddressWidget Class Definition + + The \c AddressWidget class is technically the main class + involved in this example as it provides functions to add, edit + and remove contacts, to save the contacts to a file and to load + them from a file. + + \snippet itemviews/addressbook/addresswidget.h 0 + + \c AddressWidget extends QTabWidget in order to hold 10 tabs + (\c NewAddressTab and the 9 alphabet group tabs) and also + manipulates \c table, the \c TableModel object, \c proxyModel, + the QSortFilterProxyModel object that we use to filter the + entries, and \c tableView, the QTableView object. + + + \section1 AddressWidget Class Implementation + + The \c AddressWidget constructor accepts a parent widget and + instantiates \c NewAddressTab, \c TableModel and + QSortFilterProxyModel. The \c NewAddressTab object, which is + used to indicate that the address book is empty, is added + and the rest of the 9 tabs are set up with \c setupTabs(). + + \snippet itemviews/addressbook/addresswidget.cpp 0 + + The \c setupTabs() function is used to set up the 9 alphabet + group tabs, table views and proxy models in + \c AddressWidget. Each proxy model in turn is set to filter + contact names according to the relevant alphabet group using a + \l{Qt::CaseInsensitive}{case-insensitive} QRegExp object. The + table views are also sorted in ascending order using the + corresponding proxy model's \l{QSortFilterProxyModel::}{sort()} + function. + + Each table view's \l{QTableView::}{selectionMode} is set to + QAbstractItemView::SingleSelection and + \l{QTableView::}{selectionBehavior} is set to + QAbstractItemView::SelectRows, allowing the user to select + all the items in one row at the same time. Each QTableView object + is automatically given a QItemSelectionModel that keeps track + of the selected indexes. + + \snippet itemviews/addressbook/addresswidget.cpp 1 + + The QItemSelectionModel class provides a + \l{QItemSelectionModel::selectionChanged()}{selectionChanged} + signal that is connected to \c{AddressWidget}'s + \c selectionChanged() signal. This signal to signal connection + is necessary to enable the \uicontrol{Edit Entry...} and + \uicontrol{Remove Entry} actions in \c MainWindow's Tools menu. This + connection is further explained in \c MainWindow's + implementation. + + Each table view in the address book is added as a tab to the + QTabWidget with the relevant label, obtained from the QStringList + of groups. + + \image addressbook-signals.png Signals and Slots Connections + + We provide 2 \c addEntry() functions: 1 which is intended to be + used to accept user input, and the other which performs the actual + task of adding new entries to the address book. We divide the + responsibility of adding entries into two parts to allow + \c newAddressTab to insert data without having to popup a dialog. + + The first \c addEntry() function is a slot connected to the + \c MainWindow's \uicontrol{Add Entry...} action. This function creates an + \c AddDialog object and then calls the second \c addEntry() + function to actually add the contact to \c table. + + \snippet itemviews/addressbook/addresswidget.cpp 2 + + Basic validation is done in the second \c addEntry() function to + prevent duplicate entries in the address book. As mentioned with + \c TableModel, this is part of the reason why we require the + getter method \c getList(). + + \snippet itemviews/addressbook/addresswidget.cpp 3 + + If the model does not already contain an entry with the same name, + we call \c setData() to insert the name and address into the + first and second columns. Otherwise, we display a QMessageBox + to inform the user. + + \note The \c newAddressTab is removed once a contact is added + as the address book is no longer empty. + + Editing an entry is a way to update the contact's address only, + as the example does not allow the user to change the name of an + existing contact. + + Firstly, we obtain the active tab's QTableView object using + QTabWidget::currentWidget(). Then we extract the + \c selectionModel from the \c tableView to obtain the selected + indexes. + + \snippet itemviews/addressbook/addresswidget.cpp 4a + + Next we extract data from the row the user intends to + edit. This data is displayed in an instance of \c AddDialog + with a different window title. The \c table is only + updated if changes have been made to data in \c aDialog. + + \snippet itemviews/addressbook/addresswidget.cpp 4b + + \image addressbook-editdialog.png Screenshot of Dialog to Edit a Contact + + Entries are removed using the \c removeEntry() function. + The selected row is removed by accessing it through the + QItemSelectionModel object, \c selectionModel. The + \c newAddressTab is re-added to the \c AddressWidget only if + the user removes all the contacts in the address book. + + \snippet itemviews/addressbook/addresswidget.cpp 5 + + The \c writeToFile() function is used to save a file containing + all the contacts in the address book. The file is saved in a + custom \c{.dat} format. The contents of the QList of \l{QPair}s + are written to \c file using QDataStream. If the file cannot be + opened, a QMessageBox is displayed with the related error message. + + \snippet itemviews/addressbook/addresswidget.cpp 6 + + The \c readFromFile() function loads a file containing all the + contacts in the address book, previously saved using + \c writeToFile(). QDataStream is used to read the contents of a + \c{.dat} file into a list of pairs and each of these is added + using \c addEntry(). + + \snippet itemviews/addressbook/addresswidget.cpp 7 + + + \section1 NewAddressTab Class Definition + + The \c NewAddressTab class provides an informative tab telling + the user that the address book is empty. It appears and + disappears according to the contents of the address book, as + mentioned in \c{AddressWidget}'s implementation. + + \image addressbook-newaddresstab.png Screenshot of NewAddressTab + + The \c NewAddressTab class extends QWidget and contains a QLabel + and QPushButton. + + \snippet itemviews/addressbook/newaddresstab.h 0 + + + \section1 NewAddressTab Class Implementation + + The constructor instantiates the \c addButton, + \c descriptionLabel and connects the \c{addButton}'s signal to + the \c{addEntry()} slot. + + \snippet itemviews/addressbook/newaddresstab.cpp 0 + + The \c addEntry() function is similar to \c AddressWidget's + \c addEntry() in the sense that both functions instantiate an + \c AddDialog object. Data from the dialog is extracted and sent + to \c AddressWidget's \c addEntry() slot by emitting the + \c sendDetails() signal. + + \snippet itemviews/addressbook/newaddresstab.cpp 1 + + \image signals-n-slots-aw-nat.png + + + \section1 AddDialog Class Definition + + The \c AddDialog class extends QDialog and provides the user + with a QLineEdit and a QTextEdit to input data into the + address book. + + \snippet itemviews/addressbook/adddialog.h 0 + + \image addressbook-adddialog.png + + + \section1 AddDialog Class Implementation + + The \c AddDialog's constructor sets up the user interface, + creating the necessary widgets and placing them into layouts. + + \snippet itemviews/addressbook/adddialog.cpp 0 + + To give the dialog the desired behavior, we connect the \uicontrol OK + and \uicontrol Cancel buttons to the dialog's \l{QDialog::}{accept()} and + \l{QDialog::}{reject()} slots. Since the dialog only acts as a + container for name and address information, we do not need to + implement any other functions for it. + + + \section1 MainWindow Class Definition + + The \c MainWindow class extends QMainWindow and implements the + menus and actions necessary to manipulate the address book. + + \table + \row \li \inlineimage addressbook-filemenu.png + \li \inlineimage addressbook-toolsmenu.png + \endtable + + \snippet itemviews/addressbook/mainwindow.h 0 + + The \c MainWindow class uses an \c AddressWidget as its central + widget and provides the File menu with \uicontrol Open, \uicontrol Close and + \uicontrol Exit actions, as well as the \uicontrol Tools menu with + \uicontrol{Add Entry...}, \uicontrol{Edit Entry...} and \uicontrol{Remove Entry} + actions. + + + \section1 MainWindow Class Implementation + + The constructor for \c MainWindow instantiates AddressWidget, + sets it as its central widget and calls the \c createMenus() + function. + + \snippet itemviews/addressbook/mainwindow.cpp 0 + + The \c createMenus() function sets up the \uicontrol File and + \uicontrol Tools menus, connecting the actions to their respective slots. + Both the \uicontrol{Edit Entry...} and \uicontrol{Remove Entry} actions are + disabled by default as such actions cannot be carried out on an empty + address book. They are only enabled when one or more contacts + are added. + + \snippet itemviews/addressbook/mainwindow.cpp 1a + \dots + \codeline + \snippet itemviews/addressbook/mainwindow.cpp 1b + + Apart from connecting all the actions' signals to their + respective slots, we also connect \c AddressWidget's + \c selectionChanged() signal to its \c updateActions() slot. + + The \c openFile() function allows the user to choose a file with + the \l{QFileDialog::getOpenFileName()}{open file dialog}. The chosen + file has to be a custom \c{.dat} file that contains address book + contacts. This function is a slot connected to \c openAct in the + \uicontrol File menu. + + \snippet itemviews/addressbook/mainwindow.cpp 2 + + The \c saveFile() function allows the user to save a file with + the \l{QFileDialog::getSaveFileName()}{save file dialog}. This function + is a slot connected to \c saveAct in the \uicontrol File menu. + + \snippet itemviews/addressbook/mainwindow.cpp 3 + + The \c updateActions() function enables and disables + \uicontrol{Edit Entry...} and \uicontrol{Remove Entry} depending on the contents of + the address book. If the address book is empty, these actions + are disabled; otherwise, they are enabled. This function is a slot + is connected to the \c AddressWidget's \c selectionChanged() + signal. + + \snippet itemviews/addressbook/mainwindow.cpp 4 + + + \section1 main() Function + + The main function for the address book instantiates QApplication + and opens a \c MainWindow before running the event loop. + + \snippet itemviews/addressbook/main.cpp 0 +*/ diff --git a/examples/widgets/doc/src/affine.qdoc b/examples/widgets/doc/src/affine.qdoc new file mode 100644 index 0000000000..c69794d511 --- /dev/null +++ b/examples/widgets/doc/src/affine.qdoc @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** 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 painting/affine + \title Affine Transformations + + In this example we show Qt's ability to perform affine transformations + on painting operations. + + \image affine-demo.png + + Transformations can be performed on any kind of graphics drawn using QPainter. + The transformations used to display the vector graphics, images, and text can be adjusted + in the following ways: + + \list + \li Dragging the red circle in the centre of each drawing moves it to a new position. + \li Dragging the displaced red circle causes the current drawing to be rotated about the + central circle. Rotation can also be controlled with the \uicontrol Rotate slider. + \li Scaling is controlled with the \uicontrol Scale slider. + \li Each drawing can be sheared with the \uicontrol Shear slider. + \endlist +*/ diff --git a/examples/widgets/doc/src/analogclock.qdoc b/examples/widgets/doc/src/analogclock.qdoc new file mode 100644 index 0000000000..bb4bdb54ae --- /dev/null +++ b/examples/widgets/doc/src/analogclock.qdoc @@ -0,0 +1,154 @@ +/**************************************************************************** +** +** 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/analogclock + \title Analog Clock Example + + The Analog Clock example shows how to draw the contents of a custom + widget. + + \image analogclock-example.png Screenshot of the Analog Clock example + + This example also demonstrates how the transformation and scaling + features of QPainter can be used to make drawing custom widgets + easier. + + \section1 AnalogClock Class Definition + + The \c AnalogClock class provides a clock widget with hour and minute + hands that is automatically updated every few seconds. + We subclass \l QWidget and reimplement the standard + \l{QWidget::paintEvent()}{paintEvent()} function to draw the clock face: + + \snippet widgets/analogclock/analogclock.h 0 + + \section1 AnalogClock Class Implementation + + \snippet widgets/analogclock/analogclock.cpp 1 + + When the widget is constructed, we set up a one-second timer to + keep track of the current time, and we connect it to the standard + \l{QWidget::update()}{update()} slot so that the clock face is + updated when the timer emits the \l{QTimer::timeout()}{timeout()} + signal. + + Finally, we resize the widget so that it is displayed at a + reasonable size. + + \snippet widgets/analogclock/analogclock.cpp 8 + \snippet widgets/analogclock/analogclock.cpp 10 + + The \c paintEvent() function is called whenever the widget's + contents need to be updated. This happens when the widget is + first shown, and when it is covered then exposed, but it is also + executed when the widget's \l{QWidget::update()}{update()} slot + is called. Since we connected the timer's + \l{QTimer::timeout()}{timeout()} signal to this slot, it will be + called at least once every five seconds. + + Before we set up the painter and draw the clock, we first define + two lists of \l {QPoint}s and two \l{QColor}s that will be used + for the hour and minute hands. The minute hand's color has an + alpha component of 191, meaning that it's 75% opaque. + + We also determine the length of the widget's shortest side so that we + can fit the clock face inside the widget. It is also useful to determine + the current time before we start drawing. + + \snippet widgets/analogclock/analogclock.cpp 11 + \snippet widgets/analogclock/analogclock.cpp 12 + \snippet widgets/analogclock/analogclock.cpp 13 + \snippet widgets/analogclock/analogclock.cpp 14 + + The contents of custom widgets are drawn with a QPainter. + Painters can be used to draw on any QPaintDevice, but they are + usually used with widgets, so we pass the widget instance to the + painter's constructor. + + We call QPainter::setRenderHint() with QPainter::Antialiasing to + turn on antialiasing. This makes drawing of diagonal lines much + smoother. + + The translation moves the origin to the center of the widget, and + the scale operation ensures that the following drawing operations + are scaled to fit within the widget. We use a scale factor that + let's us use x and y coordinates between -100 and 100, and that + ensures that these lie within the length of the widget's shortest + side. + + To make our code simpler, we will draw a fixed size clock face that will + be positioned and scaled so that it lies in the center of the widget. + + The painter takes care of all the transformations made during the + paint event, and ensures that everything is drawn correctly. Letting + the painter handle transformations is often easier than performing + manual calculations just to draw the contents of a custom widget. + + \image analogclock-viewport.png + + We draw the hour hand first, using a formula that rotates the coordinate + system counterclockwise by a number of degrees determined by the current + hour and minute. This means that the hand will be shown rotated clockwise + by the required amount. + + \snippet widgets/analogclock/analogclock.cpp 15 + \snippet widgets/analogclock/analogclock.cpp 16 + + We set the pen to be Qt::NoPen because we don't want any outline, + and we use a solid brush with the color appropriate for + displaying hours. Brushes are used when filling in polygons and + other geometric shapes. + + \snippet widgets/analogclock/analogclock.cpp 17 + \snippet widgets/analogclock/analogclock.cpp 19 + + We save and restore the transformation matrix before and after the + rotation because we want to place the minute hand without having to + take into account any previous rotations. + + \snippet widgets/analogclock/analogclock.cpp 20 + \codeline + \snippet widgets/analogclock/analogclock.cpp 21 + + We draw markers around the edge of the clock for each hour. We + draw each marker then rotate the coordinate system so that the + painter is ready for the next one. + + \snippet widgets/analogclock/analogclock.cpp 22 + \snippet widgets/analogclock/analogclock.cpp 23 + + The minute hand is rotated in a similar way to the hour hand. + + \snippet widgets/analogclock/analogclock.cpp 25 + \codeline + \snippet widgets/analogclock/analogclock.cpp 26 + + Again, we draw markers around the edge of the clock, but this + time to indicate minutes. We skip multiples of 5 to avoid drawing + minute markers on top of hour markers. +*/ diff --git a/examples/widgets/doc/src/animatedtiles.qdoc b/examples/widgets/doc/src/animatedtiles.qdoc new file mode 100644 index 0000000000..4fe25388cf --- /dev/null +++ b/examples/widgets/doc/src/animatedtiles.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 animation/animatedtiles + \title Animated Tiles Example + + The Animated Tiles example animates items in a graphics scene. + + \image animatedtiles-example.png +*/ + diff --git a/examples/widgets/doc/src/appchooser.qdoc b/examples/widgets/doc/src/appchooser.qdoc new file mode 100644 index 0000000000..092db7c29e --- /dev/null +++ b/examples/widgets/doc/src/appchooser.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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 animation/appchooser + \title Application Chooser Example + + The Application Chooser example shows how to use the Qt state + machine and the animation framework to select between + applications. + + \image appchooser-example.png + +*/ diff --git a/examples/widgets/doc/src/application.qdoc b/examples/widgets/doc/src/application.qdoc new file mode 100644 index 0000000000..5465f99e99 --- /dev/null +++ b/examples/widgets/doc/src/application.qdoc @@ -0,0 +1,400 @@ +/**************************************************************************** +** +** 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 mainwindows/application + \title Application Example + + The Application example shows how to implement a standard GUI + application with menus, toolbars, and a status bar. The example + itself is a simple text editor program built around QPlainTextEdit. + + \image application.png Screenshot of the Application example + + Nearly all of the code for the Application example is in the \c + MainWindow class, which inherits QMainWindow. QMainWindow + provides the framework for windows that have menus, toolbars, + dock windows, and a status bar. The application provides + \uicontrol{File}, \uicontrol{Edit}, and \uicontrol{Help} entries in the menu + bar, with the following popup menus: + + \image application-menus.png The Application example's menu system + + The status bar at the bottom of the main window shows a + description of the menu item or toolbar button under the cursor. + + To keep the example simple, recently opened files aren't shown in + the \uicontrol{File} menu, even though this feature is desired in 90% + of applications. The \l{mainwindows/recentfiles}{Recent Files} + example shows how to implement this. Furthermore, this example + can only load one file at a time. The \l{mainwindows/sdi}{SDI} + and \l{mainwindows/mdi}{MDI} examples shows how to lift these + restrictions. + + \section1 MainWindow Class Definition + + Here's the class definition: + + \snippet mainwindows/application/mainwindow.h 0 + + The public API is restricted to the constructor. In the \c + protected section, we reimplement QWidget::closeEvent() to detect + when the user attempts to close the window, and warn the user + about unsaved changes. In the \c{private slots} section, we + declare slots that correspond to menu entries, as well as a + mysterious \c documentWasModified() slot. Finally, in the \c + private section of the class, we have various members that will + be explained in due time. + + \section1 MainWindow Class Implementation + + \snippet mainwindows/application/mainwindow.cpp 0 + + We start by including \c , a header file that contains the + definition of all classes in the \l QtCore and \l QtGui + libraries. This saves us from the trouble of having to include + every class individually. We also include \c mainwindow.h. + + You might wonder why we don't include \c in \c + mainwindow.h and be done with it. The reason is that including + such a large header from another header file can rapidly degrade + performances. Here, it wouldn't do any harm, but it's still + generally a good idea to include only the header files that are + strictly necessary from another header file. + + \snippet mainwindows/application/mainwindow.cpp 1 + \snippet mainwindows/application/mainwindow.cpp 2 + + In the constructor, we start by creating a QPlainTextEdit widget as a + child of the main window (the \c this object). Then we call + QMainWindow::setCentralWidget() to tell that this is going to be + the widget that occupies the central area of the main window, + between the toolbars and the status bar. + + Then we call \c createActions(), \c createMenus(), \c + createToolBars(), and \c createStatusBar(), four private + functions that set up the user interface. After that, we call \c + readSettings() to restore the user's preferences. + + We establish a signal-slot connection between the QPlainTextEdit's + document object and our \c documentWasModified() slot. Whenever + the user modifies the text in the QPlainTextEdit, we want to update + the title bar to show that the file was modified. + + At the end, we set the window title using the private + \c setCurrentFile() function. We'll come back to this later. + + \target close event handler + \snippet mainwindows/application/mainwindow.cpp 3 + \snippet mainwindows/application/mainwindow.cpp 4 + + When the user attempts to close the window, we call the private + function \c maybeSave() to give the user the possibility to save + pending changes. The function returns true if the user wants the + application to close; otherwise, it returns false. In the first + case, we save the user's preferences to disk and accept the close + event; in the second case, we ignore the close event, meaning + that the application will stay up and running as if nothing + happened. + + \snippet mainwindows/application/mainwindow.cpp 5 + \snippet mainwindows/application/mainwindow.cpp 6 + + The \c newFile() slot is invoked when the user selects + \uicontrol{File|New} from the menu. We call \c maybeSave() to save any + pending changes and if the user accepts to go on, we clear the + QPlainTextEdit and call the private function \c setCurrentFile() to + update the window title and clear the + \l{QWidget::windowModified}{windowModified} flag. + + \snippet mainwindows/application/mainwindow.cpp 7 + \snippet mainwindows/application/mainwindow.cpp 8 + + The \c open() slot is invoked when the user clicks + \uicontrol{File|Open}. We pop up a QFileDialog asking the user to + choose a file. If the user chooses a file (i.e., \c fileName is + not an empty string), we call the private function \c loadFile() + to actually load the file. + + \snippet mainwindows/application/mainwindow.cpp 9 + \snippet mainwindows/application/mainwindow.cpp 10 + + The \c save() slot is invoked when the user clicks + \uicontrol{File|Save}. If the user hasn't provided a name for the file + yet, we call \c saveAs(); otherwise, we call the private function + \c saveFile() to actually save the file. + + \snippet mainwindows/application/mainwindow.cpp 11 + \snippet mainwindows/application/mainwindow.cpp 12 + + In \c saveAs(), we start by popping up a QFileDialog asking the + user to provide a name. If the user clicks \uicontrol{Cancel}, the + returned file name is empty, and we do nothing. + + \snippet mainwindows/application/mainwindow.cpp 13 + \snippet mainwindows/application/mainwindow.cpp 14 + + The application's About box is done using one statement, using + the QMessageBox::about() static function and relying on its + support for an HTML subset. + + The \l{QObject::tr()}{tr()} call around the literal string marks + the string for translation. It is a good habit to call + \l{QObject::tr()}{tr()} on all user-visible strings, in case you + later decide to translate your application to other languages. + The \l{Internationalization with Qt} overview covers + \l{QObject::tr()}{tr()} in more detail. + + \snippet mainwindows/application/mainwindow.cpp 15 + \snippet mainwindows/application/mainwindow.cpp 16 + + The \c documentWasModified() slot is invoked each time the text + in the QPlainTextEdit changes because of user edits. We call + QWidget::setWindowModified() to make the title bar show that the + file was modified. How this is done varies on each platform. + + \snippet mainwindows/application/mainwindow.cpp 17 + \snippet mainwindows/application/mainwindow.cpp 18 + \dots + \snippet mainwindows/application/mainwindow.cpp 22 + + The \c createActions() private function, which is called from the + \c MainWindow constructor, creates \l{QAction}s. The code is very + repetitive, so we show only the actions corresponding to + \uicontrol{File|New}, \uicontrol{File|Open}, and \uicontrol{Help|About Qt}. + + A QAction is an object that represents one user action, such as + saving a file or invoking a dialog. An action can be put in a + QMenu or a QToolBar, or both, or in any other widget that + reimplements QWidget::actionEvent(). + + An action has a text that is shown in the menu, an icon, a + shortcut key, a tooltip, a status tip (shown in the status bar), + a "What's This?" text, and more. It emits a + \l{QAction::triggered()}{triggered()} signal whenever the user + invokes the action (e.g., by clicking the associated menu item or + toolbar button). We connect this signal to a slot that performs + the actual action. + + The code above contains one more idiom that must be explained. + For some of the actions, we specify an icon as a QIcon to the + QAction constructor. The QIcon constructor takes the file name + of an image that it tries to load. Here, the file name starts + with \c{:}. Such file names aren't ordinary file names, but + rather path in the executable's stored resources. We'll come back + to this when we review the \c application.qrc file that's part of + the project. + + \snippet mainwindows/application/mainwindow.cpp 23 + \snippet mainwindows/application/mainwindow.cpp 24 + + The \uicontrol{Edit|Cut} and \uicontrol{Edit|Copy} actions must be available + only when the QPlainTextEdit contains selected text. We disable them + by default and connect the QPlainTextEdit::copyAvailable() signal to + the QAction::setEnabled() slot, ensuring that the actions are + disabled when the text editor has no selection. + + \snippet mainwindows/application/mainwindow.cpp 25 + \snippet mainwindows/application/mainwindow.cpp 27 + + Creating actions isn't sufficient to make them available to the + user; we must also add them to the menu system. This is what \c + createMenus() does. We create a \uicontrol{File}, an \uicontrol{Edit}, and + a \uicontrol{Help} menu. QMainWindow::menuBar() lets us access the + window's menu bar widget. We don't have to worry about creating + the menu bar ourselves; the first time we call this function, the + QMenuBar is created. + + Just before we create the \uicontrol{Help} menu, we call + QMenuBar::addSeparator(). This has no effect for most widget + styles (e.g., Windows and Mac OS X styles), but for Motif-based + styles this makes sure that \uicontrol{Help} is pushed to the right + side of the menu bar. Try running the application with various + styles and see the results: + + \code + application -style=windows + application -style=motif + application -style=cde + \endcode + + Let's now review the toolbars: + + \snippet mainwindows/application/mainwindow.cpp 30 + + Creating toolbars is very similar to creating menus. The same + actions that we put in the menus can be reused in the toolbars. + + \snippet mainwindows/application/mainwindow.cpp 32 + \snippet mainwindows/application/mainwindow.cpp 33 + + QMainWindow::statusBar() returns a pointer to the main window's + QStatusBar widget. Like with \l{QMainWindow::menuBar()}, the + widget is automatically created the first time the function is + called. + + \snippet mainwindows/application/mainwindow.cpp 34 + \snippet mainwindows/application/mainwindow.cpp 36 + + The \c readSettings() function is called from the constructor to + load the user's preferences and other application settings. The + QSettings class provides a high-level interface for storing + settings permanently on disk. On Windows, it uses the (in)famous + Windows registry; on Mac OS X, it uses the native XML-based + CFPreferences API; on Unix/X11, it uses text files. + + The QSettings constructor takes arguments that identify your + company and the name of the product. This ensures that the + settings for different applications are kept separately. + + We use QSettings::value() to extract the value of the "pos" and + "size" settings. The second argument to QSettings::value() is + optional and specifies a default value for the setting if there + exists none. This value is used the first time the application is + run. + + When restoring the position and size of a window, it's important + to call QWidget::resize() before QWidget::move(). The reason why + is given in the \l{Window Geometry} overview. + + \snippet mainwindows/application/mainwindow.cpp 37 + \snippet mainwindows/application/mainwindow.cpp 39 + + The \c writeSettings() function is called from \c closeEvent(). + Writing settings is similar to reading them, except simpler. The + arguments to the QSettings constructor must be the same as in \c + readSettings(). + + \snippet mainwindows/application/mainwindow.cpp 40 + \snippet mainwindows/application/mainwindow.cpp 41 + + The \c maybeSave() function is called to save pending changes. If + there are pending changes, it pops up a QMessageBox giving the + user to save the document. The options are QMessageBox::Yes, + QMessageBox::No, and QMessageBox::Cancel. The \uicontrol{Yes} button is + made the default button (the button that is invoked when the user + presses \uicontrol{Return}) using the QMessageBox::Default flag; the + \uicontrol{Cancel} button is made the escape button (the button that is + invoked when the user presses \uicontrol{Esc}) using the + QMessageBox::Escape flag. + + The \c maybeSave() function returns \c true in all cases, except + when the user clicks \uicontrol{Cancel}. The caller must check the + return value and stop whatever it was doing if the return value + is \c false. + + \snippet mainwindows/application/mainwindow.cpp 42 + \snippet mainwindows/application/mainwindow.cpp 43 + + In \c loadFile(), we use QFile and QTextStream to read in the + data. The QFile object provides access to the bytes stored in a + file. + + We start by opening the file in read-only mode. The QFile::Text + flag indicates that the file is a text file, not a binary file. + On Unix and Mac OS X, this makes no difference, but on Windows, + it ensures that the "\\r\\n" end-of-line sequence is converted to + "\\n" when reading. + + If we successfully opened the file, we use a QTextStream object + to read in the data. QTextStream automatically converts the 8-bit + data into a Unicode QString and supports various encodings. If no + encoding is specified, QTextStream assumes the file is written + using the system's default 8-bit encoding (for example, Latin-1; + see QTextCodec::codecForLocale() for details). + + Since the call to QTextStream::readAll() might take some time, we + set the cursor to be Qt::WaitCursor for the entire application + while it goes on. + + At the end, we call the private \c setCurrentFile() function, + which we'll cover in a moment, and we display the string "File + loaded" in the status bar for 2 seconds (2000 milliseconds). + + \snippet mainwindows/application/mainwindow.cpp 44 + \snippet mainwindows/application/mainwindow.cpp 45 + + Saving a file is very similar to loading one. Here, the + QFile::Text flag ensures that on Windows, "\\n" is converted into + "\\r\\n" to conform to the Windows convension. + + \snippet mainwindows/application/mainwindow.cpp 46 + \snippet mainwindows/application/mainwindow.cpp 47 + + The \c setCurrentFile() function is called to reset the state of + a few variables when a file is loaded or saved, or when the user + starts editing a new file (in which case \c fileName is empty). + We update the \c curFile variable, clear the + QTextDocument::modified flag and the associated \c + QWidget:windowModified flag, and update the window title to + contain the new file name (or \c untitled.txt). + + The \c strippedName() function call around \c curFile in the + QWidget::setWindowTitle() call shortens the file name to exclude + the path. Here's the function: + + \snippet mainwindows/application/mainwindow.cpp 48 + \snippet mainwindows/application/mainwindow.cpp 49 + + \section1 The main() Function + + The \c main() function for this application is typical of + applications that contain one main window: + + \snippet mainwindows/application/main.cpp 0 + + \section1 The Resource File + + As you will probably recall, for some of the actions, we + specified icons with file names starting with \c{:} and mentioned + that such file names aren't ordinary file names, but path in the + executable's stored resources. These resources are compiled + + The resources associated with an application are specified in a + \c .qrc file, an XML-based file format that lists files on the + disk. Here's the \c application.qrc file that's used by the + Application example: + + \quotefile mainwindows/application/application.qrc + + The \c .png files listed in the \c application.qrc file are files + that are part of the Application example's source tree. Paths are + relative to the directory where the \c application.qrc file is + located (the \c mainwindows/application directory). + + The resource file must be mentioned in the \c application.pro + file so that \c qmake knows about it: + + \snippet mainwindows/application/application.pro 0 + + \c qmake will produce make rules to generate a file called \c + qrc_application.cpp that is linked into the application. This + file contains all the data for the images and other resources as + static C++ arrays of compressed binary data. See + \l{resources.html}{The Qt Resource System} for more information + about resources. +*/ 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/src/basicdrawing.qdoc b/examples/widgets/doc/src/basicdrawing.qdoc new file mode 100644 index 0000000000..899aa361f8 --- /dev/null +++ b/examples/widgets/doc/src/basicdrawing.qdoc @@ -0,0 +1,454 @@ +/**************************************************************************** +** +** 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 painting/basicdrawing + \title Basic Drawing Example + + The Basic Drawing example shows how to display basic graphics + primitives in a variety of styles using the QPainter class. + + QPainter performs low-level painting on widgets and other paint + devices. The class can draw everything from simple lines to + complex shapes like pies and chords. It can also draw aligned text + and pixmaps. Normally, it draws in a "natural" coordinate system, + but it can in addition do view and world transformation. + + \image basicdrawing-example.png + + The example provides a render area, displaying the currently + active shape, and lets the user manipulate the rendered shape and + its appearance using the QPainter parameters: The user can change + the active shape (\uicontrol Shape), and modify the QPainter's pen (\uicontrol + {Pen Width}, \uicontrol {Pen Style}, \uicontrol {Pen Cap}, \uicontrol {Pen Join}), + brush (\uicontrol {Brush Style}) and render hints (\uicontrol + Antialiasing). In addition the user can rotate a shape (\uicontrol + Transformations); behind the scenes we use QPainter's ability to + manipulate the coordinate system to perform the rotation. + + The Basic Drawing example consists of two classes: + + \list + \li \c RenderArea is a custom widget that renders multiple + copies of the currently active shape. + \li \c Window is the application's main window displaying a + \c RenderArea widget in addition to several parameter widgets. + \endlist + + First we will review the \c Window class, then we will take a + look at the \c RenderArea class. + + \section1 Window Class Definition + + The Window class inherits QWidget, and is the application's main + window displaying a \c RenderArea widget in addition to several + parameter widgets. + + \snippet painting/basicdrawing/window.h 0 + + We declare the various widgets, and three private slots updating + the \c RenderArea widget: The \c shapeChanged() slot updates the + \c RenderArea widget when the user changes the currently active + shape. We call the \c penChanged() slot when either of the + QPainter's pen parameters changes. And the \c brushChanged() slot + updates the \c RenderArea widget when the user changes the + painter's brush style. + + \section1 Window Class Implementation + + In the constructor we create and initialize the various widgets + appearing in the main application window. + + \snippet painting/basicdrawing/window.cpp 1 + + First we create the \c RenderArea widget that will render the + currently active shape. Then we create the \uicontrol Shape combobox, + and add the associated items (i.e. the different shapes a QPainter + can draw). + + \snippet painting/basicdrawing/window.cpp 2 + + QPainter's pen is a QPen object; the QPen class defines how a + painter should draw lines and outlines of shapes. A pen has + several properties: Width, style, cap and join. + + A pen's width can be \e zero or greater, but the most common width + is zero. Note that this doesn't mean 0 pixels, but implies that + the shape is drawn as smoothly as possible although perhaps not + mathematically correct. + + We create a QSpinBox for the \uicontrol {Pen Width} parameter. + + \snippet painting/basicdrawing/window.cpp 3 + + The pen style defines the line type. The default style is solid + (Qt::SolidLine). Setting the style to none (Qt::NoPen) tells the + painter to not draw lines or outlines. The pen cap defines how + the end points of lines are drawn. And the pen join defines how + two lines join when multiple connected lines are drawn. The cap + and join only apply to lines with a width of 1 pixel or greater. + + We create \l {QComboBox}es for each of the \uicontrol {Pen Style}, \uicontrol + {Pen Cap} and \uicontrol {Pen Join} parameters, and adds the associated + items (i.e the values of the Qt::PenStyle, Qt::PenCapStyle and + Qt::PenJoinStyle enums respectively). + + \snippet painting/basicdrawing/window.cpp 4 + + The QBrush class defines the fill pattern of shapes drawn by a + QPainter. The default brush style is Qt::NoBrush. This style tells + the painter to not fill shapes. The standard style for filling is + Qt::SolidPattern. + + We create a QComboBox for the \uicontrol {Brush Style} parameter, and add + the associated items (i.e. the values of the Qt::BrushStyle enum). + + \snippet painting/basicdrawing/window.cpp 5 + \snippet painting/basicdrawing/window.cpp 6 + + Antialiasing is a feature that "smoothes" the pixels to create + more even and less jagged lines, and can be applied using + QPainter's render hints. QPainter::RenderHints are used to specify + flags to QPainter that may or may not be respected by any given + engine. + + We simply create a QCheckBox for the \uicontrol Antialiasing option. + + \snippet painting/basicdrawing/window.cpp 7 + + The \uicontrol Transformations option implies a manipulation of the + coordinate system that will appear as if the rendered shape is + rotated in three dimensions. + + We use the QPainter::translate(), QPainter::rotate() and + QPainter::scale() functions to implement this feature represented + in the main application window by a simple QCheckBox. + + \snippet painting/basicdrawing/window.cpp 8 + + Then we connect the parameter widgets with their associated slots + using the static QObject::connect() function, ensuring that the \c + RenderArea widget is updated whenever the user changes the shape, + or any of the other parameters. + + \snippet painting/basicdrawing/window.cpp 9 + \snippet painting/basicdrawing/window.cpp 10 + + Finally, we add the various widgets to a layout, and call the \c + shapeChanged(), \c penChanged(), and \c brushChanged() slots to + initialize the application. We also turn on antialiasing. + + \snippet painting/basicdrawing/window.cpp 11 + + The \c shapeChanged() slot is called whenever the user changes the + currently active shape. + + First we retrieve the shape the user has chosen using the + QComboBox::itemData() function. This function returns the data for + the given role in the given index in the combobox. We use + QComboBox::currentIndex() to retrieve the index of the shape, and + the role is defined by the Qt::ItemDataRole enum; \c IdRole is an + alias for Qt::UserRole. + + Note that Qt::UserRole is only the first role that can be used for + application-specific purposes. If you need to store different data + in the same index, you can use different roles by simply + incrementing the value of Qt::UserRole, for example: 'Qt::UserRole + + 1' and 'Qt::UserRole + 2'. However, it is a good programming + practice to give each role their own name: 'myFirstRole = + Qt::UserRole + 1' and 'mySecondRole = Qt::UserRole + 2'. Even + though we only need a single role in this particular example, we + add the following line of code to the beginning of the \c + window.cpp file. + + \snippet painting/basicdrawing/window.cpp 0 + + The QComboBox::itemData() function returns the data as a QVariant, + so we need to cast the data to \c RenderArea::Shape. If there is + no data for the given role, the function returns + QVariant::Invalid. + + In the end we call the \c RenderArea::setShape() slot to update + the \c RenderArea widget. + + \snippet painting/basicdrawing/window.cpp 12 + + We call the \c penChanged() slot whenever the user changes any of + the pen parameters. Again we use the QComboBox::itemData() + function to retrieve the parameters, and then we call the \c + RenderArea::setPen() slot to update the \c RenderArea widget. + + \snippet painting/basicdrawing/window.cpp 13 + + The brushChanged() slot is called whenever the user changes the + brush parameter which we retrieve using the QComboBox::itemData() + function as before. + + \snippet painting/basicdrawing/window.cpp 14 + + If the brush parameter is a gradient fill, special actions are + required. + + The QGradient class is used in combination with QBrush to specify + gradient fills. Qt currently supports three types of gradient + fills: linear, radial and conical. Each of these is represented by + a subclass of QGradient: QLinearGradient, QRadialGradient and + QConicalGradient. + + So if the brush style is Qt::LinearGradientPattern, we first + create a QLinearGradient object with interpolation area between + the coordinates passed as arguments to the constructor. The + positions are specified using logical coordinates. Then we set the + gradient's colors using the QGradient::setColorAt() function. The + colors is defined using stop points which are composed by a + position (between 0 and 1) and a QColor. The set of stop points + describes how the gradient area should be filled. A gradient can + have an arbitrary number of stop points. + + In the end we call \c RenderArea::setBrush() slot to update the \c + RenderArea widget's brush with the QLinearGradient object. + + \snippet painting/basicdrawing/window.cpp 15 + + A similar pattern of actions, as the one used for QLinearGradient, + is used in the cases of Qt::RadialGradientPattern and + Qt::ConicalGradientPattern. + + The only difference is the arguments passed to the constructor: + Regarding the QRadialGradient constructor the first argument is + the center, and the second the radial gradient's radius. The third + argument is optional, but can be used to define the focal point of + the gradient inside the circle (the default focal point is the + circle center). Regarding the QConicalGradient constructor, the + first argument specifies the center of the conical, and the second + specifies the start angle of the interpolation. + + \snippet painting/basicdrawing/window.cpp 16 + + If the brush style is Qt::TexturePattern we create a QBrush from a + QPixmap. Then we call \c RenderArea::setBrush() slot to update the + \c RenderArea widget with the newly created brush. + + \snippet painting/basicdrawing/window.cpp 17 + + Otherwise we simply create a brush with the given style and a + green color, and then call \c RenderArea::setBrush() slot to + update the \c RenderArea widget with the newly created brush. + + \section1 RenderArea Class Definition + + The \c RenderArea class inherits QWidget, and renders multiple + copies of the currently active shape using a QPainter. + + \snippet painting/basicdrawing/renderarea.h 0 + + First we define a public \c Shape enum to hold the different + shapes that can be rendered by the widget (i.e the shapes that can + be rendered by a QPainter). Then we reimplement the constructor as + well as two of QWidget's public functions: \l + {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l + {QWidget::sizeHint()}{sizeHint()}. + + We also reimplement the QWidget::paintEvent() function to be able + to draw the currently active shape according to the specified + parameters. + + We declare several private slots: The \c setShape() slot changes + the \c RenderArea's shape, the \c setPen() and \c setBrush() slots + modify the widget's pen and brush, and the \c setAntialiased() and + \c setTransformed() slots modify the widget's respective + properties. + + \section1 RenderArea Class Implementation + + In the constructor we initialize some of the widget's variables. + + \snippet painting/basicdrawing/renderarea.cpp 0 + + We set its shape to be a \uicontrol Polygon, its antialiased property to + be false and we load an image into the widget's pixmap + variable. In the end we set the widget's background role, defining + the brush from the widget's \l {QWidget::palette}{palette} that + will be used to render the background. QPalette::Base is typically + white. + + \snippet painting/basicdrawing/renderarea.cpp 2 + + The \c RenderArea inherits QWidget's \l + {QWidget::sizeHint()}{sizeHint} property holding the recommended + size for the widget. If the value of this property is an invalid + size, no size is recommended. + + The default implementation of the QWidget::sizeHint() function + returns an invalid size if there is no layout for the widget, and + returns the layout's preferred size otherwise. + + Our reimplementation of the function returns a QSize with a 400 + pixels width and a 200 pixels height. + + \snippet painting/basicdrawing/renderarea.cpp 1 + + \c RenderArea also inherits QWidget's + \l{QWidget::minimumSizeHint()}{minimumSizeHint} property holding + the recommended minimum size for the widget. Again, if the value + of this property is an invalid size, no size is recommended. + + The default implementation of QWidget::minimumSizeHint() returns + an invalid size if there is no layout for the widget, and returns + the layout's minimum size otherwise. + + Our reimplementation of the function returns a QSize with a 100 + pixels width and a 100 pixels height. + + \snippet painting/basicdrawing/renderarea.cpp 3 + \codeline + \snippet painting/basicdrawing/renderarea.cpp 4 + \codeline + \snippet painting/basicdrawing/renderarea.cpp 5 + + The public \c setShape(), \c setPen() and \c setBrush() slots are + called whenever we want to modify a \c RenderArea widget's shape, + pen or brush. We set the shape, pen or brush according to the + slot parameter, and call QWidget::update() to make the changes + visible in the \c RenderArea widget. + + The QWidget::update() slot does not cause an immediate + repaint; instead it schedules a paint event for processing when Qt + returns to the main event loop. + + \snippet painting/basicdrawing/renderarea.cpp 6 + \codeline + \snippet painting/basicdrawing/renderarea.cpp 7 + + With the \c setAntialiased() and \c setTransformed() slots we + change the state of the properties according to the slot + parameter, and call the QWidget::update() slot to make the changes + visible in the \c RenderArea widget. + + \snippet painting/basicdrawing/renderarea.cpp 8 + + Then we reimplement the QWidget::paintEvent() function. The first + thing we do is to create the graphical objects we will need to + draw the various shapes. + + We create a vector of four \l {QPoint}s. We use this vector to + render the \uicontrol Points, \uicontrol Polyline and \uicontrol Polygon + shapes. Then we create a QRect, defining a rectangle in the plane, + which we use as the bounding rectangle for all the shapes excluding + the \uicontrol Path and the \uicontrol Pixmap. + + We also create a QPainterPath. The QPainterPath class provides a + container for painting operations, enabling graphical shapes to be + constructed and reused. A painter path is an object composed of a + number of graphical building blocks, such as rectangles, ellipses, + lines, and curves. For more information about the QPainterPath + class, see the \l {painting/painterpaths}{Painter Paths} + example. In this example, we create a painter path composed of one + straight line and a Bezier curve. + + In addition we define a start angle and an arc length that we will + use when drawing the \uicontrol Arc, \uicontrol Chord and \uicontrol Pie shapes. + + \snippet painting/basicdrawing/renderarea.cpp 9 + + We create a QPainter for the \c RenderArea widget, and set the + painters pen and brush according to the \c RenderArea's pen and + brush. If the \uicontrol Antialiasing parameter option is checked, we + also set the painter's render hints. QPainter::Antialiasing + indicates that the engine should antialias edges of primitives if + possible. + + \snippet painting/basicdrawing/renderarea.cpp 10 + + Finally, we render the multiple copies of the \c RenderArea's + shape. The number of copies is depending on the size of the \c + RenderArea widget, and we calculate their positions using two \c + for loops and the widgets height and width. + + For each copy we first save the current painter state (pushes the + state onto a stack). Then we translate the coordinate system, + using the QPainter::translate() function, to the position + determined by the variables of the \c for loops. If we omit this + translation of the coordinate system all the copies of the shape + will be rendered on top of each other in the top left cormer of + the \c RenderArea widget. + + \snippet painting/basicdrawing/renderarea.cpp 11 + + If the \uicontrol Transformations parameter option is checked, we do an + additional translation of the coordinate system before we rotate + the coordinate system 60 degrees clockwise using the + QPainter::rotate() function and scale it down in size using the + QPainter::scale() function. In the end we translate the coordinate + system back to where it was before we rotated and scaled it. + + Now, when rendering the shape, it will appear as if it was rotated + in three dimensions. + + \snippet painting/basicdrawing/renderarea.cpp 12 + + Next, we identify the \c RenderArea's shape, and render it using + the associated QPainter drawing function: + + \list + \li QPainter::drawLine(), + \li QPainter::drawPoints(), + \li QPainter::drawPolyline(), + \li QPainter::drawPolygon(), + \li QPainter::drawRect(), + \li QPainter::drawRoundedRect(), + \li QPainter::drawEllipse(), + \li QPainter::drawArc(), + \li QPainter::drawChord(), + \li QPainter::drawPie(), + \li QPainter::drawPath(), + \li QPainter::drawText() or + \li QPainter::drawPixmap() + \endlist + + Before we started rendering, we saved the current painter state + (pushes the state onto a stack). The rationale for this is that we + calculate each shape copy's position relative to the same point in + the coordinate system. When translating the coordinate system, we + lose the knowledge of this point unless we save the current + painter state \e before we start the translating process. + + \snippet painting/basicdrawing/renderarea.cpp 13 + + Then, when we are finished rendering a copy of the shape we can + restore the original painter state, with its associated coordinate + system, using the QPainter::restore() function. In this way we + ensure that the next shape copy will be rendered in the correct + position. + + We could translate the coordinate system back using + QPainter::translate() instead of saving the painter state. But + since we in addition to translating the coordinate system (when + the \uicontrol Transformation parameter option is checked) both rotate + and scale the coordinate system, the easiest solution is to save + the current painter state. +*/ diff --git a/examples/widgets/doc/src/basicgraphicslayouts.qdoc b/examples/widgets/doc/src/basicgraphicslayouts.qdoc new file mode 100644 index 0000000000..9f52b3eafa --- /dev/null +++ b/examples/widgets/doc/src/basicgraphicslayouts.qdoc @@ -0,0 +1,164 @@ +/**************************************************************************** +** +** 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 graphicsview/basicgraphicslayouts + \title Basic Graphics Layouts Example + + The Basic Graphics Layouts example shows how to use the layout classes + in QGraphicsView: QGraphicsLinearLayout and QGraphicsGridLayout. + In addition to that it shows how to write your own custom layout item. + + \image basicgraphicslayouts-example.png Screenshot of the Basic Layouts Example + + \section1 Window Class Definition + + The \c Window class is a subclass of QGraphicsWidget. It has a + constructor with a QGraphicsWidget \a parent as its parameter. + + \snippet graphicsview/basicgraphicslayouts/window.h 0 + + \section1 Window Class Implementation + + The constructor of \c Window instantiates a QGraphicsLinearLayout object, + \c windowLayout, with vertical orientation. We instantiate another + QGraphicsLinearLayout object, \c linear, whose parent is \c windowLayout. + Next, we create a \c LayoutItem object, \c item and add it to \c linear + with the \l{QGraphicsLinearLayout::}{addItem()} function. We also provide + \c item with a \l{QGraphicsLinearLayout::setStretchFactor()} + {stretchFactor}. + + \snippet graphicsview/basicgraphicslayouts/window.cpp 0 + + We repeat the process: + + \list + \li create a new \c LayoutItem, + \li add the item \c linear, and + \li provide a stretch factor. + \endlist + + \snippet graphicsview/basicgraphicslayouts/window.cpp 1 + + We then add \c linear to \c windowLayout, nesting two + QGraphicsLinearLayout objects. Apart from the QGraphicsLinearLayout, we + also use a QGraphicsGridLayout object, \c grid, which is a 4x3 grid with + some cells spanning to other rows. + + We create seven \c LayoutItem objects and place them into \c grid with + the \l{QGraphicsGridLayout::}{addItem()} function as shown in the code + snippet below: + + \snippet graphicsview/basicgraphicslayouts/window.cpp 2 + + The first item we add to \c grid is placed in the top left cell, + spanning four rows. The next two items are placed in the second column, + and they span two rows. Each item's \l{QGraphicsWidget::}{maximumHeight()} + and \l{QGraphicsWidget::}{minimumHeight()} are set to be equal so that + they do not expand vertically. As a result, these items will not + fit vertically in their cells. So, we specify that they should be + vertically aligned in the center of the cell using Qt::AlignVCenter. + + Finally, \c grid itself is added to \c windowLayout. Unlike + QGridLayout::addItem(), QGraphicsGridLayout::addItem() requires a row + and a column for its argument, specifying which cell the item should be + positioned in. Also, if the \c rowSpan and \c columnSpan arguments + are omitted, they will default to 1. + + Note that we do not specify a parent for each \c LayoutItem that we + construct, as all these items will be added to \c windowLayout. When we + add an item to a layout, it will be automatically reparented to the widget + on which the layout is installed. + + \snippet graphicsview/basicgraphicslayouts/window.cpp 3 + + Now that we have set up \c grid and added it to \c windowLayout, we + install \c windowLayout onto the window object using + QGraphicsWidget::setLayout() and we set the window title. + + \section1 LayoutItem Class Definition + + The \c LayoutItem class is a subclass of QGraphicsLayoutItem and + QGraphicsItem. It has a constructor, a destructor, and some required + reimplementations. + Since it inherits QGraphicsLayoutItem it must reimplement + {QGraphicsLayoutItem::setGeometry()}{setGeometry()} and + {QGraphicsLayoutItem::sizeHint()}{sizeHint()}. + In addition to that it inherits QGraphicsItem, so it must reimplement + {QGraphicsItem::boundingRect()}{boundingRect()} and + {QGraphicsItem::paint()}{paint()}. + + \snippet graphicsview/basicgraphicslayouts/layoutitem.h 0 + + The \c LayoutItem class also has a private instance of QPixmap, \c m_pix. + + \section1 LayoutItem Class Implementation + + In \c{LayoutItem}'s constructor, \c m_pix is instantiated and the + \c{block.png} image is loaded into it. + + \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 0 + + We use the Q_UNUSED() macro to prevent the compiler from generating + warnings regarding unused parameters. + + \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 1 + + The idea behind the \c paint() function is to paint the + background rect then paint a rect around the pixmap. + + \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 2 + + The reimplementation of \l{QGraphicsItem::}{boundingRect()} + will set the top left corner at (0,0), and the size of it will be + the size of the layout items + \l{QGraphicsLayoutItem::}{geometry()}. This is the area that + we paint within. + + \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 3 + + + The reimplementation of \l{QGraphicsLayoutItem::setGeometry()}{setGeometry()} + simply calls its baseclass implementation. However, since this will change + the boundingRect we must also call + \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()}. + Finally, we move the item according to \c geom.topLeft(). + + \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 4 + + + Since we don't want the size of the item to be smaller than the pixmap, we + must make sure that we return a size hint that is larger than \c m_pix. + We also add some extra space around for borders that we will paint later. + Alternatively, you could scale the pixmap to prevent the item from + becoming smaller than the pixmap. + The preferred size is the same as the minimum size hint, while we set + maximum to be a large value + + \snippet graphicsview/basicgraphicslayouts/layoutitem.cpp 5 + +*/ diff --git a/examples/widgets/doc/src/basiclayouts.qdoc b/examples/widgets/doc/src/basiclayouts.qdoc new file mode 100644 index 0000000000..a0f083ba58 --- /dev/null +++ b/examples/widgets/doc/src/basiclayouts.qdoc @@ -0,0 +1,190 @@ +/**************************************************************************** +** +** 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 layouts/basiclayouts + \title Basic Layouts Example + + The Basic Layouts example shows how to use the standard layout + managers that are available in Qt: QBoxLayout, QGridLayout and + QFormLayout. + + \image basiclayouts-example.png Screenshot of the Basic Layouts example + + The QBoxLayout class lines up widgets horizontally or vertically. + QHBoxLayout and QVBoxLayout are convenience subclasses of QBoxLayout. + QGridLayout lays out widgets in cells by dividing the available space + into rows and columns. QFormLayout, on the other hand, lays out its + children in a two-column form with labels in the left column and + input fields in the right column. + + \section1 Dialog Class Definition + + \snippet layouts/basiclayouts/dialog.h 0 + + The \c Dialog class inherits QDialog. It is a custom widget that + displays its child widgets using the geometry managers: + QHBoxLayout, QVBoxLayout, QGridLayout and QFormLayout. + + We declare four private functions to simplify the class + constructor: The \c createMenu(), \c createHorizontalGroupBox(), + \c createGridGroupBox() and \c createFormGroupBox() functions create + several widgets that the example uses to demonstrate how the layout + affects their appearances. + + \section1 Dialog Class Implementation + + \snippet layouts/basiclayouts/dialog.cpp 0 + + In the constructor, we first use the \c createMenu() function to + create and populate a menu bar and the \c createHorizontalGroupBox() + function to create a group box containing four buttons with a + horizontal layout. Next we use the \c createGridGroupBox() function + to create a group box containing several line edits and a small text + editor which are displayed in a grid layout. Finally, we use the + \c createFormGroupBox() function to create a group box with + three labels and three input fields: a line edit, a combo box and + a spin box. + + \snippet layouts/basiclayouts/dialog.cpp 1 + + We also create a big text editor and a dialog button box. The + QDialogButtonBox class is a widget that presents buttons in a + layout that is appropriate to the current widget style. The + preferred buttons can be specified as arguments to the + constructor, using the QDialogButtonBox::StandardButtons enum. + + Note that we don't have to specify a parent for the widgets when + we create them. The reason is that all the widgets we create here + will be added to a layout, and when we add a widget to a layout, + it is automatically reparented to the widget the layout is + installed on. + + \snippet layouts/basiclayouts/dialog.cpp 2 + + The main layout is a QVBoxLayout object. QVBoxLayout is a + convenience class for a box layout with vertical orientation. + + In general, the QBoxLayout class takes the space it gets (from its + parent layout or from the parent widget), divides it up into a + series of boxes, and makes each managed widget fill one box. If + the QBoxLayout's orientation is Qt::Horizontal the boxes are + placed in a row. If the orientation is Qt::Vertical, the boxes are + placed in a column. The corresponding convenience classes are + QHBoxLayout and QVBoxLayout, respectively. + + \snippet layouts/basiclayouts/dialog.cpp 3 + + When we call the QLayout::setMenuBar() function, the layout places + the provided menu bar at the top of the parent widget, and outside + the widget's \l {QWidget::contentsRect()}{content margins}. All + child widgets are placed below the bottom edge of the menu bar. + + \snippet layouts/basiclayouts/dialog.cpp 4 + + We use the QBoxLayout::addWidget() function to add the widgets to + the end of layout. Each widget will get at least its minimum size + and at most its maximum size. It is possible to specify a stretch + factor in the \l {QBoxLayout::addWidget()}{addWidget()} function, + and any excess space is shared according to these stretch + factors. If not specified, a widget's stretch factor is 0. + + \snippet layouts/basiclayouts/dialog.cpp 5 + + We install the main layout on the \c Dialog widget using the + QWidget::setLayout() function, and all of the layout's widgets are + automatically reparented to be children of the \c Dialog widget. + + \snippet layouts/basiclayouts/dialog.cpp 6 + + In the private \c createMenu() function we create a menu bar, and + add a pull-down \uicontrol File menu containing an \uicontrol Exit option. + + \snippet layouts/basiclayouts/dialog.cpp 7 + + When we create the horizontal group box, we use a QHBoxLayout as + the internal layout. We create the buttons we want to put in the + group box, add them to the layout and install the layout on the + group box. + + \snippet layouts/basiclayouts/dialog.cpp 8 + + In the \c createGridGroupBox() function we use a QGridLayout which + lays out widgets in a grid. It takes the space made available to + it (by its parent layout or by the parent widget), divides it up + into rows and columns, and puts each widget it manages into the + correct cell. + + \snippet layouts/basiclayouts/dialog.cpp 9 + + For each row in the grid we create a label and an associated line + edit, and add them to the layout. The QGridLayout::addWidget() + function differ from the corresponding function in QBoxLayout: It + needs the row and column specifying the grid cell to put the + widget in. + + \snippet layouts/basiclayouts/dialog.cpp 10 + + QGridLayout::addWidget() can in addition take arguments + specifying the number of rows and columns the cell will be + spanning. In this example, we create a small editor which spans + three rows and one column. + + For both the QBoxLayout::addWidget() and QGridLayout::addWidget() + functions it is also possible to add a last argument specifying + the widget's alignment. By default it fills the whole cell. But we + could, for example, align a widget with the right edge by + specifying the alignment to be Qt::AlignRight. + + \snippet layouts/basiclayouts/dialog.cpp 11 + + Each column in a grid layout has a stretch factor. The stretch + factor is set using QGridLayout::setColumnStretch() and determines + how much of the available space the column will get over and above + its necessary minimum. + + In this example, we set the stretch factors for columns 1 and 2. + The stretch factor is relative to the other columns in this grid; + columns with a higher stretch factor take more of the available + space. So column 2 in our grid layout will get more of the + available space than column 1, and column 0 will not grow at all + since its stretch factor is 0 (the default). + + Columns and rows behave identically; there is an equivalent + stretch factor for rows, as well as a QGridLayout::setRowStretch() + function. + + \snippet layouts/basiclayouts/dialog.cpp 12 + + In the \c createFormGroupBox() function, we use a QFormLayout + to neatly arrange objects into two columns - name and field. + There are three QLabel objects for names with three + corresponding input widgets as fields: a QLineEdit, a QComboBox + and a QSpinBox. Unlike QBoxLayout::addWidget() and + QGridLayout::addWidget(), we use QFormLayout::addRow() to add widgets + to the layout. +*/ diff --git a/examples/widgets/doc/src/basicsortfiltermodel.qdoc b/examples/widgets/doc/src/basicsortfiltermodel.qdoc new file mode 100644 index 0000000000..0ecf4a0629 --- /dev/null +++ b/examples/widgets/doc/src/basicsortfiltermodel.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 itemviews/basicsortfiltermodel + \title Basic Sort/Filter Model Example + + The Basic Sort/Filter Model example illustrates how to use + QSortFilterProxyModel to perform basic sorting and filtering. + + \image basicsortfiltermodel-example.png Screenshot of the Basic Sort/Filter Model Example + +*/ diff --git a/examples/widgets/doc/src/blurpicker.qdoc b/examples/widgets/doc/src/blurpicker.qdoc new file mode 100644 index 0000000000..bd57acb061 --- /dev/null +++ b/examples/widgets/doc/src/blurpicker.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** 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 effects/blurpicker + \title Blur Picker Effect Example + + \image blurpickereffect-example.png +*/ diff --git a/examples/widgets/doc/src/borderlayout.qdoc b/examples/widgets/doc/src/borderlayout.qdoc new file mode 100644 index 0000000000..aaff2dda1d --- /dev/null +++ b/examples/widgets/doc/src/borderlayout.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 layouts/borderlayout + \title Border Layout Example + + The Border Layout example shows how to create a custom layout that arranges + child widgets according to a simple set of rules. + + \image borderlayout-example.png +*/ diff --git a/examples/widgets/doc/src/boxes.qdoc b/examples/widgets/doc/src/boxes.qdoc new file mode 100644 index 0000000000..aa34a61bc3 --- /dev/null +++ b/examples/widgets/doc/src/boxes.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** 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 graphicsview/boxes + \title Boxes + + This demo shows Qt's ability to combine advanced OpenGL rendering with the + the \l{Graphics View Framework}. + + \image boxes-demo.png + + Elements in the demo can be controlled using the mouse in the following + ways: + \list + \li Dragging the mouse while pressing the left mouse button rotates the + box in the center. + \li Dragging the mouse while pressing the right mouse button rotates the + satellite boxes. + \li Scrolling the mouse wheel zooms in and out of the scene. + \endlist + + The options pane can be used to fine-tune various parameters in the demo, + including colors and pixel shaders. +*/ diff --git a/examples/widgets/doc/src/calculator.qdoc b/examples/widgets/doc/src/calculator.qdoc new file mode 100644 index 0000000000..8480d90477 --- /dev/null +++ b/examples/widgets/doc/src/calculator.qdoc @@ -0,0 +1,375 @@ +/**************************************************************************** +** +** 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/calculator + \title Calculator Example + + The example shows how to use signals and slots to implement the + functionality of a calculator widget, and how to use QGridLayout + to place child widgets in a grid. + + \image calculator-example.png Screenshot of the Calculator example + + The example consists of two classes: + + \list + \li \c Calculator is the calculator widget, with all the + calculator functionality. + \li \c Button is the widget used for each of the calculator + button. It derives from QToolButton. + \endlist + + We will start by reviewing \c Calculator, then we will take a + look at \c Button. + + \section1 Calculator Class Definition + + \snippet widgets/calculator/calculator.h 0 + + The \c Calculator class provides a simple calculator widget. It + inherits from QDialog and has several private slots associated + with the calculator's buttons. QObject::eventFilter() is + reimplemented to handle mouse events on the calculator's display. + + Buttons are grouped in categories according to their behavior. + For example, all the digit buttons (labeled \uicontrol 0 to \uicontrol 9) + append a digit to the current operand. For these, we connect + multiple buttons to the same slot (e.g., \c digitClicked()). The + categories are digits, unary operators (\uicontrol{Sqrt}, \uicontrol{x\unicode{178}}, + \uicontrol{1/x}), additive operators (\uicontrol{+}, \uicontrol{-}), and + multiplicative operators (\uicontrol{\unicode{215}}, \uicontrol{\unicode{247}}). The other buttons + have their own slots. + + \snippet widgets/calculator/calculator.h 1 + \snippet widgets/calculator/calculator.h 2 + + The private \c createButton() function is used as part of the + widget construction. \c abortOperation() is called whenever a + division by zero occurs or when a square root operation is + applied to a negative number. \c calculate() applies a binary + operator (\uicontrol{+}, \uicontrol{-}, \uicontrol{\unicode{215}}, or \uicontrol{\unicode{247}}). + + \snippet widgets/calculator/calculator.h 3 + \snippet widgets/calculator/calculator.h 4 + \snippet widgets/calculator/calculator.h 5 + \snippet widgets/calculator/calculator.h 6 + \snippet widgets/calculator/calculator.h 7 + \snippet widgets/calculator/calculator.h 8 + + These variables, together with the contents of the calculator + display (a QLineEdit), encode the state of the calculator: + + \list + \li \c sumInMemory contains the value stored in the calculator's memory + (using \uicontrol{MS}, \uicontrol{M+}, or \uicontrol{MC}). + \li \c sumSoFar stores the value accumulated so far. When the user + clicks \uicontrol{=}, \c sumSoFar is recomputed and shown on the + display. \uicontrol{Clear All} resets \c sumSoFar to zero. + \li \c factorSoFar stores a temporary value when doing + multiplications and divisions. + \li \c pendingAdditiveOperator stores the last additive operator + clicked by the user. + \li \c pendingMultiplicativeOperator stores the last multiplicative operator + clicked by the user. + \li \c waitingForOperand is \c true when the calculator is + expecting the user to start typing an operand. + \endlist + + Additive and multiplicative operators are treated differently + because they have different precedences. For example, \uicontrol{1 + 2 \unicode{247} + 3} is interpreted as \uicontrol{1 + (2 \unicode{247} 3)} because \uicontrol{\unicode{247}} has higher + precedence than \uicontrol{+}. + + The table below shows the evolution of the calculator state as + the user enters a mathematical expression. + + \table + \header \li User Input \li Display \li Sum so Far \li Add. Op. \li Factor so Far \li Mult. Op. \li Waiting for Operand? + \row \li \li 0 \li 0 \li \li \li \li \c true + \row \li \uicontrol{1} \li 1 \li 0 \li \li \li \li \c false + \row \li \uicontrol{1 +} \li 1 \li 1 \li \uicontrol{+} \li \li \li \c true + \row \li \uicontrol{1 + 2} \li 2 \li 1 \li \uicontrol{+} \li \li \li \c false + \row \li \uicontrol{1 + 2 \unicode{247}} \li 2 \li 1 \li \uicontrol{+} \li 2 \li \uicontrol{\unicode{247}} \li \c true + \row \li \uicontrol{1 + 2 \unicode{247} 3} \li 3 \li 1 \li \uicontrol{+} \li 2 \li \uicontrol{\unicode{247}} \li \c false + \row \li \uicontrol{1 + 2 \unicode{247} 3 -} \li 1.66667 \li 1.66667 \li \uicontrol{-} \li \li \li \c true + \row \li \uicontrol{1 + 2 \unicode{247} 3 - 4} \li 4 \li 1.66667 \li \uicontrol{-} \li \li \li \c false + \row \li \uicontrol{1 + 2 \unicode{247} 3 - 4 =} \li -2.33333 \li 0 \li \li \li \li \c true + \endtable + + Unary operators, such as \uicontrol Sqrt, require no special handling; + they can be applied immediately since the operand is already + known when the operator button is clicked. + + \snippet widgets/calculator/calculator.h 9 + \codeline + \snippet widgets/calculator/calculator.h 10 + + Finally, we declare the variables associated with the display and the + buttons used to display numerals. + + \section1 Calculator Class Implementation + + \snippet widgets/calculator/calculator.cpp 0 + + In the constructor, we initialize the calculator's state. The \c + pendingAdditiveOperator and \c pendingMultiplicativeOperator + variables don't need to be initialized explicitly, because the + QString constructor initializes them to empty strings. + + \snippet widgets/calculator/calculator.cpp 1 + \snippet widgets/calculator/calculator.cpp 2 + + We create the QLineEdit representing the calculator's display and + set up some of its properties. In particular, we set it to be + read-only. + + We also enlarge \c{display}'s font by 8 points. + + \snippet widgets/calculator/calculator.cpp 4 + + For each button, we call the private \c createButton() function with + the proper text label and a slot to connect to the button. + + \snippet widgets/calculator/calculator.cpp 5 + \snippet widgets/calculator/calculator.cpp 6 + + The layout is handled by a single QGridLayout. The + QLayout::setSizeConstraint() call ensures that the \c Calculator + widget is always shown as its optimal size (its + \l{QWidget::sizeHint()}{size hint}), preventing the user from + resizing the calculator. The size hint is determined by the size + and \l{QWidget::sizePolicy()}{size policy} of the child widgets. + + Most child widgets occupy only one cell in the grid layout. For + these, we only need to pass a row and a column to + QGridLayout::addWidget(). The \c display, \c backspaceButton, \c + clearButton, and \c clearAllButton widgets occupy more than one + column; for these we must also pass a row span and a column + span. + + \snippet widgets/calculator/calculator.cpp 7 + + Pressing one of the calculator's digit buttons will emit the + button's \l{QToolButton::clicked()}{clicked()} signal, which will + trigger the \c digitClicked() slot. + + First, we find out which button sent the signal using + QObject::sender(). This function returns the sender as a QObject + pointer. Since we know that the sender is a \c Button object, we + can safely cast the QObject. We could have used a C-style cast or + a C++ \c static_cast<>(), but as a defensive programming + technique we use a \l qobject_cast(). The advantage is that if + the object has the wrong type, a null pointer is returned. + Crashes due to null pointers are much easier to diagnose than + crashes due to unsafe casts. Once we have the button, we extract + the operator using QToolButton::text(). + + The slot needs to consider two situations in particular. If \c + display contains "0" and the user clicks the \uicontrol{0} button, it + would be silly to show "00". And if the calculator is in + a state where it is waiting for a new operand, + the new digit is the first digit of that new operand; in that case, + any result of a previous calculation must be cleared first. + + At the end, we append the new digit to the value in the display. + + \snippet widgets/calculator/calculator.cpp 8 + \snippet widgets/calculator/calculator.cpp 9 + + The \c unaryOperatorClicked() slot is called whenever one of the + unary operator buttons is clicked. Again a pointer to the clicked + button is retrieved using QObject::sender(). The operator is + extracted from the button's text and stored in \c + clickedOperator. The operand is obtained from \c display. + + Then we perform the operation. If \uicontrol Sqrt is applied to a + negative number or \uicontrol{1/x} to zero, we call \c + abortOperation(). If everything goes well, we display the result + of the operation in the line edit and we set \c waitingForOperand + to \c true. This ensures that if the user types a new digit, the + digit will be considered as a new operand, instead of being + appended to the current value. + + \snippet widgets/calculator/calculator.cpp 10 + \snippet widgets/calculator/calculator.cpp 11 + + The \c additiveOperatorClicked() slot is called when the user + clicks the \uicontrol{+} or \uicontrol{-} button. + + Before we can actually do something about the clicked operator, + we must handle any pending operations. We start with the + multiplicative operators, since these have higher precedence than + additive operators: + + \snippet widgets/calculator/calculator.cpp 12 + \snippet widgets/calculator/calculator.cpp 13 + + If \uicontrol{\unicode{215}} or \uicontrol{\unicode{247}} has been clicked earlier, without clicking + \uicontrol{=} afterward, the current value in the display is the right + operand of the \uicontrol{\unicode{215}} or \uicontrol{\unicode{247}} operator and we can finally + perform the operation and update the display. + + \snippet widgets/calculator/calculator.cpp 14 + \snippet widgets/calculator/calculator.cpp 15 + + If \uicontrol{+} or \uicontrol{-} has been clicked earlier, \c sumSoFar is + the left operand and the current value in the display is the + right operand of the operator. If there is no pending additive + operator, \c sumSoFar is simply set to be the text in the + display. + + \snippet widgets/calculator/calculator.cpp 16 + \snippet widgets/calculator/calculator.cpp 17 + + Finally, we can take care of the operator that was just clicked. + Since we don't have the right-hand operand yet, we store the clicked + operator in the \c pendingAdditiveOperator variable. We will + apply the operation later, when we have a right operand, with \c + sumSoFar as the left operand. + + \snippet widgets/calculator/calculator.cpp 18 + + The \c multiplicativeOperatorClicked() slot is similar to \c + additiveOperatorClicked(). We don't need to worry about pending + additive operators here, because multiplicative operators have + precedence over additive operators. + + \snippet widgets/calculator/calculator.cpp 20 + + Like in \c additiveOperatorClicked(), we start by handing any + pending multiplicative and additive operators. Then we display \c + sumSoFar and reset the variable to zero. Resetting the variable + to zero is necessary to avoid counting the value twice. + + \snippet widgets/calculator/calculator.cpp 22 + + The \c pointClicked() slot adds a decimal point to the content in + \c display. + + \snippet widgets/calculator/calculator.cpp 24 + + The \c changeSignClicked() slot changes the sign of the value in + \c display. If the current value is positive, we prepend a minus + sign; if the current value is negative, we remove the first + character from the value (the minus sign). + + \snippet widgets/calculator/calculator.cpp 26 + + The \c backspaceClicked() removes the rightmost character in the + display. If we get an empty string, we show "0" and set \c + waitingForOperand to \c true. + + \snippet widgets/calculator/calculator.cpp 28 + + The \c clear() slot resets the current operand to zero. It is + equivalent to clicking \uicontrol Backspace enough times to erase the + entire operand. + + \snippet widgets/calculator/calculator.cpp 30 + + The \c clearAll() slot resets the calculator to its initial state. + + \snippet widgets/calculator/calculator.cpp 32 + + The \c clearMemory() slot erases the sum kept in memory, \c + readMemory() displays the sum as an operand, \c setMemory() + replace the sum in memory with the current sum, and \c + addToMemory() adds the current value to the value in memory. For + \c setMemory() and \c addToMemory(), we start by calling \c + equalClicked() to update \c sumSoFar and the value in the + display. + + \snippet widgets/calculator/calculator.cpp 34 + + The private \c createButton() function is called from the + constructor to create calculator buttons. + + \snippet widgets/calculator/calculator.cpp 36 + + The private \c abortOperation() function is called whenever a + calculation fails. It resets the calculator state and displays + "####". + + \snippet widgets/calculator/calculator.cpp 38 + + The private \c calculate() function performs a binary operation. + The right operand is given by \c rightOperand. For additive + operators, the left operand is \c sumSoFar; for multiplicative + operators, the left operand is \c factorSoFar. The function + return \c false if a division by zero occurs. + + \section1 Button Class Definition + + Let's now take a look at the \c Button class: + + \snippet widgets/calculator/button.h 0 + + The \c Button class has a convenience constructor that takes a + text label and a parent widget, and it reimplements QWidget::sizeHint() + to provide more space around the text than the amount QToolButton + normally provides. + + \section1 Button Class Implementation + + \snippet widgets/calculator/button.cpp 0 + + The buttons' appearance is determined by the layout of the + calculator widget through the size and + \l{QWidget::sizePolicy}{size policy} of the layout's child + widgets. The call to the + \l{QWidget::setSizePolicy()}{setSizePolicy()} function in the + constructor ensures that the button will expand horizontally to + fill all the available space; by default, \l{QToolButton}s don't + expand to fill available space. Without this call, the different + buttons in a same column would have different widths. + + \snippet widgets/calculator/button.cpp 1 + \snippet widgets/calculator/button.cpp 2 + + In \l{QWidget::sizeHint()}{sizeHint()}, we try to return a size + that looks good for most buttons. We reuse the size hint of the + base class (QToolButton) but modify it in the following ways: + + \list + \li We add 20 to the \l{QSize::height()}{height} component of the size hint. + \li We make the \l{QSize::width()}{width} component of the size + hint at least as much as the \l{QSize::width()}{height}. + \endlist + + This ensures that with most fonts, the digit and operator buttons + will be square, without truncating the text on the + \uicontrol{Backspace}, \uicontrol{Clear}, and \uicontrol{Clear All} buttons. + + The screenshot below shows how the \c Calculator widget would + look like if we \e didn't set the horizontal size policy to + QSizePolicy::Expanding in the constructor and if we didn't + reimplement QWidget::sizeHint(). + + \image calculator-ugly.png The Calculator example with default size policies and size hints + +*/ diff --git a/examples/widgets/doc/src/calendar.qdoc b/examples/widgets/doc/src/calendar.qdoc new file mode 100644 index 0000000000..b7fa7c8617 --- /dev/null +++ b/examples/widgets/doc/src/calendar.qdoc @@ -0,0 +1,223 @@ +/**************************************************************************** +** +** 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 richtext/calendar + \title Calendar Example + + The Calendar example shows how to create rich text content and display it using + a rich text editor. + + \image calendar-example.png + + Specifically, the example demonstrates the following: + + \list + \li Use of a text editor with a text document + \li Insertion of tables and frames into a document + \li Navigation within a table + \li Insert text in different styles + \endlist + + The rich text editor used to display the document is used within a main window + application. + + \section1 MainWindow Class Definition + + The \c MainWindow class provides a text editor widget and some controls to + allow the user to change the month and year shown. The font size used for the + text can also be adjusted. + + \snippet richtext/calendar/mainwindow.h 0 + + The private \c insertCalendar() function performs most of the work, relying on + the \c fontSize and \c selectedDate variables to write useful information to + the \c editor. + + \section1 MainWindow Class Implementation + + The \c MainWindow constructor sets up the user interface and initializes + variables used to generate a calendar for each month. + + \snippet richtext/calendar/mainwindow.cpp 0 + + We begin by setting default values for the selected date that will be highlighted + in the calendar and the font size to be used. Since we are using a QMainWindow + for the user interface, we construct a widget for use as the central widget. + + The user interface will include a line of controls above the generated calendar; + we construct a label and a combobox to allow the month to be selected, and a + spin box for the year. These widgets are configured to provide a reasonable range + of values for the user to try: + + \snippet richtext/calendar/mainwindow.cpp 1 + + We use the \c selectedDate object to obtain the current month and year, and we + set these in the combobox and spin box: + + The font size is displayed in a spin box which we restrict to a sensible range + of values: + + \snippet richtext/calendar/mainwindow.cpp 2 + + We construct an editor and use the \c insertCalendar() function to create + a calendar for it. Each calendar is displayed in the same text editor; in + this example we use a QTextBrowser since we do not allow the calendar to be + edited. + + The controls used to set the month, year, and font size will not have any + effect on the appearance of the calendar unless we make some signal-slot + connections: + + \snippet richtext/calendar/mainwindow.cpp 3 + + The signals are connected to some simple slots in the \c MainWindow class + which we will describe later. + + We create layouts to manage the widgets we constructed: + + \snippet richtext/calendar/mainwindow.cpp 4 + + Finally, the central widget is set for the window. + + Each calendar is created for the editor by the \c insertCalendar() function + which uses the date and font size, defined by the private \a selectedDate + and \c fontSize variables, to produce a suitable plan for the specified + month and year. + + \snippet richtext/calendar/mainwindow.cpp 5 + + We begin by clearing the editor's rich text document, and obtain a text + cursor from the editor that we will use to add content. We also create a + QDate object based on the currently selected date. + + The calendar is made up of a table with a gray background color that contains + seven columns: one for each day of the week. It is placed in the center of the + page with equal space to the left and right of it. All of these properties are + set in a QTextTableFormat object: + + \snippet richtext/calendar/mainwindow.cpp 6 + + Each cell in the table will be padded and spaced to make the text easier to + read. + + We want the columns to have equal widths, so we provide a vector containing + percentage widths for each of them and set the constraints in the + QTextTableFormat: + + \snippet richtext/calendar/mainwindow.cpp 7 + + The constraints used for the column widths are only useful if the table has + an appropriate number of columns. With the format for the table defined, we + construct a new table with one row and seven columns at the current cursor + position: + + \snippet richtext/calendar/mainwindow.cpp 8 + + We only need one row to start with; more can be added as we need them. Using + this approach means that we do not need to perform any date calculations + until we add cells to the table. + + When inserting objects into a document with the cursor's insertion functions, + the cursor is automatically moved inside the newly inserted object. This means + that we can immediately start modifying the table from within: + + \snippet richtext/calendar/mainwindow.cpp 9 + + Since the table has an outer frame, we obtain the frame and its format so that + we can customize it. After making the changes we want, we set the frame's format + using the modified format object. We have given the table an outer border one + pixel wide. + + \snippet richtext/calendar/mainwindow.cpp 10 + + In a similar way, we obtain the cursor's current character format and + create customized formats based on it. + + We do not set the format on the cursor because this would change the default + character format; instead, we use the customized formats explicitly when we + insert text. The following loop inserts the days of the week into the table + as bold text: + + \snippet richtext/calendar/mainwindow.cpp 11 + + For each day of the week, we obtain an existing table cell in the first row + (row 0) using the table's \l{QTextTable::cellAt()}{cellAt()} function. Since + we start counting the days of the week at day 1 (Monday), we subtract 1 from + \c weekDay to ensure that we obtain the cell for the correct column of the + table. + + Before text can be inserted into a cell, we must obtain a cursor with the + correct position in the document. The cell provides a function for this + purpose, and we use this cursor to insert text using the \c boldFormat + character format that we created earlier: + + \snippet richtext/calendar/mainwindow.cpp 12 + + Inserting text into document objects usually follows the same pattern. + Each object can provide a new cursor that corresponds to the first valid + position within itself, and this can be used to insert new content. We + continue to use this pattern as we insert the days of the month into the + table. + + Since every month has more than seven days, we insert a single row to begin + and add days until we reach the end of the month. If the current date is + encountered, it is inserted with a special format (created earlier) that + makes it stand out: + + \snippet richtext/calendar/mainwindow.cpp 13 + + We add a new row to the table at the end of each week only if the next week + falls within the currently selected month. + + For each calendar that we create, we change the window title to reflect the + currently selected month and year: + + \snippet richtext/calendar/mainwindow.cpp 14 + + The \c insertCalendar() function relies on up-to-date values for the month, + year, and font size. These are set in the following slots: + + \snippet richtext/calendar/mainwindow.cpp 15 + + The \c setFontSize() function simply changes the private \c fontSize variable + before updating the calendar. + + \snippet richtext/calendar/mainwindow.cpp 16 + + The \c setMonth slot is called when the QComboBox used to select the month is + updated. The value supplied is the currently selected row in the combobox. + We add 1 to this value to obtain a valid month number, and create a new QDate + based on the existing one. The calendar is then updated to use this new date. + + \snippet richtext/calendar/mainwindow.cpp 17 + + The \c setYear() slot is called when the QDateTimeEdit used to select the + year is updated. The value supplied is a QDate object; this makes + the construction of a new value for \c selectedDate simple. We update the + calendar afterwards to use this new date. +*/ diff --git a/examples/widgets/doc/src/calendarwidget.qdoc b/examples/widgets/doc/src/calendarwidget.qdoc new file mode 100644 index 0000000000..c6e86d1668 --- /dev/null +++ b/examples/widgets/doc/src/calendarwidget.qdoc @@ -0,0 +1,291 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \title Calendar Widget Example + \example widgets/calendarwidget + + The Calendar Widget example shows use of \c QCalendarWidget. + + \image calendarwidgetexample.png + + QCalendarWidget displays one calendar month + at a time and lets the user select a date. + The calendar consists of four components: a navigation + bar that lets the user change the month that is + displayed, a grid where each cell represents one day + in the month, and two headers that display weekday names + and week numbers. + + The Calendar Widget example displays a QCalendarWidget and lets the user + configure its appearance and behavior using + \l{QComboBox}es, \l{QCheckBox}es, and \l{QDateEdit}s. In + addition, the user can influence the formatting of individual dates + and headers. + + The properties of the QCalendarWidget are summarized in the table + below. + + \table + \header \li Property + \li Description + \row \li \l{QCalendarWidget::}{selectedDate} + \li The currently selected date. + \row \li \l{QCalendarWidget::}{minimumDate} + \li The earliest date that can be selected. + \row \li \l{QCalendarWidget::}{maximumDate} + \li The latest date that can be selected. + \row \li \l{QCalendarWidget::}{firstDayOfWeek} + \li The day that is displayed as the first day of the week + (usually Sunday or Monday). + \row \li \l{QCalendarWidget::}{gridVisible} + \li Whether the grid should be shown. + \row \li \l{QCalendarWidget::}{selectionMode} + \li Whether the user can select a date or not. + \row \li \l{QCalendarWidget::}{horizontalHeaderFormat} + \li The format of the day names in the horizontal header + (e.g., "M", "Mon", or "Monday"). + \row \li \l{QCalendarWidget::}{verticalHeaderFormat} + \li The format of the vertical header. + \row \li \l{QCalendarWidget::}{navigationBarVisible} + \li Whether the navigation bar at the top of the calendar + widget is shown. + \endtable + + The example consists of one class, \c Window, which creates and + lays out the QCalendarWidget and the other widgets that let the + user configure the QCalendarWidget. + + \section1 Window Class Definition + + Here is the definition of the \c Window class: + + \snippet widgets/calendarwidget/window.h 0 + \dots + \snippet widgets/calendarwidget/window.h 1 + + As is often the case with classes that represent self-contained + windows, most of the API is private. We will review the private + members as we stumble upon them in the implementation. + + \section1 Window Class Implementation + + Let's now review the class implementation, starting with the constructor: + + \snippet widgets/calendarwidget/window.cpp 0 + + We start by creating the four \l{QGroupBox}es and their child + widgets (including the QCalendarWidget) using four private \c + create...GroupBox() functions, described below. Then we arrange + the group boxes in a QGridLayout. + + We set the grid layout's resize policy to QLayout::SetFixedSize to + prevent the user from resizing the window. In that mode, the + window's size is set automatically by QGridLayout based on the + size hints of its contents widgets. + + To ensure that the window isn't automatically resized every time + we change a property of the QCalendarWidget (e.g., hiding the + navigation bar, trhe vertical header, or the grid), we set the + minimum height of row 0 and the minimum width of column 0 to the + initial size of the QCalendarWidget. + + Let's move on to the \c createPreviewGroupBox() function: + + \snippet widgets/calendarwidget/window.cpp 9 + + The \uicontrol Preview group box contains only one widget: the + QCalendarWidget. We set it up, connect its + \l{QCalendarWidget::}{currentPageChanged()} signal to our \c + reformatCalendarPage() slot to make sure that every new page gets + the formatting specified by the user. + + The \c createGeneralOptionsGroupBox() function is somewhat large + and several widgets are set up the same way; we look at parts of + its implementation here and skip the rest: + + \snippet widgets/calendarwidget/window.cpp 10 + \dots + + We start with the setup of the \uicontrol{Week starts on} combobox. + This combobox controls which day should be displayed as the first + day of the week. + + The QComboBox class lets us attach user data as a QVariant to + each item. The data can later be retrieved with QComboBox's + \l{QComboBox::}{itemData()} function. QVariant doesn't directly + support the Qt::DayOfWeek data type, but it supports \c int, and + C++ will happily convert any enum value to \c int. + + \dots + \snippet widgets/calendarwidget/window.cpp 11 + \dots + + After creating the widgets, we connect the signals and slots. We + connect the comboboxes to private slots of \c Window or to + public slots provided by QComboBox. + + \dots + \snippet widgets/calendarwidget/window.cpp 12 + + At the end of the function, we call the slots that update the calendar to ensure + that the QCalendarWidget is synchronized with the other widgets on startup. + + Let's now take a look at the \c createDatesGroupBox() private function: + + \snippet widgets/calendarwidget/window.cpp 13 + + In this function, we create the \uicontrol {Minimum Date}, \uicontrol {Maximum Date}, + and \uicontrol {Current Date} editor widgets, + which control the calendar's minimum, maximum, and selected dates. + The calendar's minimum and maximum dates have already been + set in \c createPrivewGroupBox(); we can then set the widgets + default values to the calendars values. + + \snippet widgets/calendarwidget/window.cpp 14 + \dots + \snippet widgets/calendarwidget/window.cpp 15 + + We connect the \c currentDateEdit's + \l{QDateEdit::}{dateChanged()} signal directly to the calendar's + \l{QCalendarWidget::}{setSelectedDate()} slot. When the calendar's + selected date changes, either as a result of a user action or + programmatically, our \c selectedDateChanged() slot updates + the \uicontrol {Current Date} editor. We also need to react when the user + changes the \uicontrol{Minimum Date} and \uicontrol{Maximum Date} editors. + + Here is the \c createTextFormatsGroup() function: + + \snippet widgets/calendarwidget/window.cpp 16 + + We set up the \uicontrol {Weekday Color} and \uicontrol {Weekend Color} comboboxes + using \c createColorCombo(), which instantiates a QComboBox and + populates it with colors ("Red", "Blue", etc.). + + \snippet widgets/calendarwidget/window.cpp 17 + + The \uicontrol {Header Text Format} combobox lets the user change the + text format (bold, italic, or plain) used for horizontal and + vertical headers. The \uicontrol {First Friday in blue} and \uicontrol {May 1 + in red} check box affect the rendering of specific dates. + + \snippet widgets/calendarwidget/window.cpp 18 + + We connect the check boxes and comboboxes to various private + slots. The \uicontrol {First Friday in blue} and \uicontrol {May 1 in red} + check boxes are both connected to \c reformatCalendarPage(), + which is also called when the calendar switches month. + + \dots + \snippet widgets/calendarwidget/window.cpp 19 + + At the end of \c createTextFormatsGroupBox(), we call private + slots to synchronize the QCalendarWidget with the other widgets. + + We're now done reviewing the four \c create...GroupBox() + functions. Let's now take a look at the other private functions + and slots. + + \snippet widgets/calendarwidget/window.cpp 20 + + In \c createColorCombo(), we create a combobox and populate it with + standard colors. The second argument to QComboBox::addItem() + is a QVariant storing user data (in this case, QColor objects). + + This function was used to set up the \uicontrol {Weekday Color} + and \uicontrol {Weekend Color} comboboxes. + + \snippet widgets/calendarwidget/window.cpp 1 + + When the user changes the \uicontrol {Week starts on} combobox's + value, \c firstDayChanged() is invoked with the index of the + combobox's new value. We retrieve the custom data item + associated with the new current item using + \l{QComboBox::}{itemData()} and cast it to a Qt::DayOfWeek. + + \c selectionModeChanged(), \c horizontalHeaderChanged(), and \c + verticalHeaderChanged() are very similar to \c firstDayChanged(), + so they are omitted. + + \snippet widgets/calendarwidget/window.cpp 2 + + The \c selectedDateChanged() updates the \uicontrol{Current Date} + editor to reflect the current state of the QCalendarWidget. + + \snippet widgets/calendarwidget/window.cpp 3 + + When the user changes the minimum date, we tell the + QCalenderWidget. We also update the \uicontrol {Maximum Date} editor, + because if the new minimum date is later than the current maximum + date, QCalendarWidget will automatically adapt its maximum date + to avoid a contradicting state. + + \snippet widgets/calendarwidget/window.cpp 4 + + \c maximumDateChanged() is implemented similarly to \c + minimumDateChanged(). + + \snippet widgets/calendarwidget/window.cpp 5 + + Each combobox item has a QColor object as user data corresponding to the + item's text. After fetching the colors from the comboboxes, we + set the text format of each day of the week. + + The text format of a column in the calendar is given as a + QTextCharFormat, which besides the foreground color lets us + specify various character formatting information. In this + example, we only show a subset of the possibilities. + + \snippet widgets/calendarwidget/window.cpp 6 + + \c weekendFormatChanged() is the same as \c + weekdayFormatChanged(), except that it affects Saturday and + Sunday instead of Monday to Friday. + + \snippet widgets/calendarwidget/window.cpp 7 + + The \c reformatHeaders() slot is called when the user + changes the text format of + the headers. We compare the current text of the \uicontrol {Header Text Format} + combobox to determine which format to apply. (An alternative would + have been to store \l{QTextCharFormat} values alongside the combobox + items.) + + \snippet widgets/calendarwidget/window.cpp 8 + + In \c reformatCalendarPage(), we set the text format of the first + Friday in the month and May 1 in the current year. The text + formats that are actually used depend on which check boxes are + checked and what the weekday/weekend formats are. + + QCalendarWidget lets us set the text format of individual dates + with the \l{QCalendarWidget::}{setDateTextFormat()}. We chose to + set the date formats when the calendar page changes - i.e. a new month is + displayed - and when the weekday/weekend format is changed. + We check which of the \c mayFirstCheckBox and \c firstDayCheckBox, if any, + are checked and set the text formats accordingly. +*/ diff --git a/examples/widgets/doc/src/charactermap.qdoc b/examples/widgets/doc/src/charactermap.qdoc new file mode 100644 index 0000000000..fee2a42156 --- /dev/null +++ b/examples/widgets/doc/src/charactermap.qdoc @@ -0,0 +1,274 @@ +/**************************************************************************** +** +** 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/charactermap +\title Character Map Example + +The Character Map example shows how to create a custom widget that can +both display its own content and respond to user input. + +The example displays an array of characters which the user can click on +to enter text in a line edit. The contents of the line edit can then be +copied into the clipboard, and pasted into other applications. The +purpose behind this sort of tool is to allow users to enter characters +that may be unavailable or difficult to locate on their keyboards. + +\image charactermap-example.png Screenshot of the Character Map example + +The example consists of the following classes: + +\list +\li \c CharacterWidget displays the available characters in the current + font and style. +\li \c MainWindow provides a standard main window that contains font and + style information, a view onto the characters, a line edit, and a push + button for submitting text to the clipboard. +\endlist + +\section1 CharacterWidget Class Definition + +The \c CharacterWidget class is used to display an array of characters in +a user-specified font and style. For flexibility, we subclass QWidget and +reimplement only the functions that we need to provide basic rendering +and interaction features. + +The class definition looks like this: + +\snippet widgets/charactermap/characterwidget.h 0 + +The widget does not contain any other widgets, so it must provide its own +size hint to allow its contents to be displayed correctly. +We reimplement \l{QWidget::paintEvent()} to draw custom content. We also +reimplement \l{QWidget::mousePressEvent()} to allow the user to interact +with the widget. + +The updateFont() and updateStyle() slots are used to update the font and +style of the characters in the widget whenever the user changes the +settings in the application. +The class defines the characterSelected() signal so that other parts +of the application are informed whenever the user selects a character in +the widget. +As a courtesy, the widget provides a tooltip that shows the current +character value. We reimplement the \l{QWidget::mouseMoveEvent()} event +handler and define showToolTip() to enable this feature. + +The \c columns, \c displayFont and \c currentKey private data members +are used to record the number of columns to be shown, the current font, +and the currently highlighted character in the widget. + +\section1 CharacterWidget Class Implementation + +Since the widget is to be used as a simple canvas, the constructor just +calls the base class constructor and defines some default values for +private data members. + +\snippet widgets/charactermap/characterwidget.cpp 0 + +We initialize \c currentKey with a value of -1 to indicate +that no character is initially selected. We enable mouse tracking to +allow us to follow the movement of the cursor across the widget. + +The class provides two functions to allow the font and style to be set up. +Each of these modify the widget's display font and call update(): + +\snippet widgets/charactermap/characterwidget.cpp 1 +\codeline +\snippet widgets/charactermap/characterwidget.cpp 2 + +We use a fixed size font for the display. Similarly, a fixed size hint is +provided by the sizeHint() function: + +\snippet widgets/charactermap/characterwidget.cpp 3 + +Three standard event functions are implemented so that the widget +can respond to clicks, provide tooltips, and render the available +characters. The paintEvent() shows how the contents of the widget are +arranged and displayed: + +\snippet widgets/charactermap/characterwidget.cpp 6 + +A QPainter is created for the widget and, in all cases, we ensure that the +widget's background is painted. The painter's font is set to the +user-specified display font. + +The area of the widget that needs to be redrawn is used to determine which +characters need to be displayed: + +\snippet widgets/charactermap/characterwidget.cpp 7 + +Using integer division, we obtain the row and column numbers of each +characters that should be displayed, and we draw a square on the widget +for each character displayed. + +\snippet widgets/charactermap/characterwidget.cpp 8 +\snippet widgets/charactermap/characterwidget.cpp 9 + +The symbols for each character in the array are drawn within each square, +with the symbol for the most recently selected character displayed in red: + +\snippet widgets/charactermap/characterwidget.cpp 10 + +We do not need to take into account the difference between the area +displayed in the viewport and the area we are drawing on because +everything outside the visible area will be clipped. + +The mousePressEvent() defines how the widget responds to mouse clicks. + +\snippet widgets/charactermap/characterwidget.cpp 5 + +We are only interested when the user clicks with the left mouse button +over the widget. When this happens, we calculate which character was +selected and emit the characterSelected() signal. +The character's number is found by dividing the x and y-coordinates of +the click by the size of each character's grid square. Since the number +of columns in the widget is defined by the \c columns variable, we +simply multiply the row index by that value and add the column number +to obtain the character number. + +If any other mouse button is pressed, the event is passed on to the +QWidget base class. This ensures that the event can be handled properly +by any other interested widgets. + +The mouseMoveEvent() maps the mouse cursor's position in global +coordinates to widget coordinates, and determines the character that +was clicked by performing the calculation + +\snippet widgets/charactermap/characterwidget.cpp 4 + +The tooltip is given a position defined in global coordinates. + +\section1 MainWindow Class Definition + +The \c MainWindow class provides a minimal user interface for the example, +with only a constructor, slots that respond to signals emitted by standard +widgets, and some convenience functions that are used to set up the user +interface. + +The class definition looks like this: + +\snippet widgets/charactermap/mainwindow.h 0 + +The main window contains various widgets that are used to control how +the characters will be displayed, and defines the findFonts() function +for clarity and convenience. The findStyles() slot is used by the widgets +to determine the styles that are available, insertCharacter() inserts +a user-selected character into the window's line edit, and +updateClipboard() synchronizes the clipboard with the contents of the +line edit. + +\section1 MainWindow Class Implementation + +In the constructor, we set up the window's central widget and fill it with +some standard widgets (two comboboxes, a line edit, and a push button). +We also construct a CharacterWidget custom widget, and add a QScrollArea +so that we can view its contents: + +\snippet widgets/charactermap/mainwindow.cpp 0 + +QScrollArea provides a viewport onto the \c CharacterWidget when we set +its widget and handles much of the work needed to provide a scrolling +viewport. + +The font combo box is automatically popuplated with a list of available +fonts. We list the available styles for the current font in the style +combobox using the following function: + +\snippet widgets/charactermap/mainwindow.cpp 1 + +The line edit and push button are used to supply text to the clipboard: + +\snippet widgets/charactermap/mainwindow.cpp 2 + +We also obtain a clipboard object so that we can send text entered by the +user to other applications. + +Most of the signals emitted in the example come from standard widgets. +We connect these signals to slots in this class, and to the slots provided +by other widgets. + +\snippet widgets/charactermap/mainwindow.cpp 4 + +The font combobox's +\l{QFontComboBox::currentFontChanged()}{currentFontChanged()} signal is +connected to the findStyles() function so that the list of available styles +can be shown for each font that is used. Since both the font and the style +can be changed by the user, the font combobox's currentFontChanged() signal +and the style combobox's +\l{QComboBox::currentIndexChanged()}{currentIndexChanged()} are connected +directly to the character widget. + +The final two connections allow characters to be selected in the character +widget, and text to be inserted into the clipboard: + +\snippet widgets/charactermap/mainwindow.cpp 5 + +The character widget emits the characterSelected() custom signal when +the user clicks on a character, and this is handled by the insertCharacter() +function in this class. The clipboard is changed when the push button emits +the clicked() signal, and we handle this with the updateClipboard() function. + +The remaining code in the constructor sets up the layout of the central widget, +and provides a window title: + +\snippet widgets/charactermap/mainwindow.cpp 6 + +The font combobox is automatically populated with a list of available font +families. The styles that can be used with each font are found by the +findStyles() function. This function is called whenever the user selects a +different font in the font combobox. + +\snippet widgets/charactermap/mainwindow.cpp 7 + +We begin by recording the currently selected style, and we clear the +style combobox so that we can insert the styles associated with the +current font family. + +\snippet widgets/charactermap/mainwindow.cpp 8 + +We use the font database to collect the styles that are available for the +current font, and insert them into the style combobox. The current item is +reset if the original style is not available for this font. + +The last two functions are slots that respond to signals from the character +widget and the main window's push button. The insertCharacter() function is +used to insert characters from the character widget when the user clicks a +character: + +\snippet widgets/charactermap/mainwindow.cpp 9 + +The character is inserted into the line edit at the current cursor position. + +The main window's "To clipboard" push button is connected to the +updateClipboard() function so that, when it is clicked, the clipboard is +updated to contain the contents of the line edit: + +\snippet widgets/charactermap/mainwindow.cpp 10 + +We copy all the text from the line edit to the clipboard, but we do not clear +the line edit. +*/ diff --git a/examples/widgets/doc/src/chart.qdoc b/examples/widgets/doc/src/chart.qdoc new file mode 100644 index 0000000000..44263d1027 --- /dev/null +++ b/examples/widgets/doc/src/chart.qdoc @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** 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 itemviews/chart + \title Chart Example + + The Chart example shows how to create a custom view for the model/view framework. + + \image chart-example.png + + In this example, the items in a table model are represented as slices in a pie chart, + relying on the flexibility of the model/view architecture to handle custom editing + and selection features. + + \b{Note that you only need to create a new view class if your data requires a + specialized representation.} You should first consider using a standard QListView, + QTableView, or QTreeView with a custom QItemDelegate subclass if you need to + represent data in a special way. + + \omit + \section1 PieView Class Definition + + The \c PieView class is a subclass of QAbstractItemView. The base class provides + much of the functionality required by view classes, so we only need to provide + implementations for three public functions: visualRect(), scrollTo(), and + indexAt(). However, the view needs to maintain strict control over its look and + feel, so we also provide implementations for a number of other functions: + + \snippet itemviews/chart/pieview.h 0 + + + + \section1 PieView Class Implementation + + The paint event renders the data from the standard item model as a pie chart. + We interpret the data in the following way: + + \list + \li Column 0 contains data in two different roles: + The \l{Qt::ItemDataRole}{DisplayRole} contains a label, and the + \l{Qt::ItemDataRole}{DecorationRole} contains the color of the pie slice. + \li Column 1 contains a quantity which we will convert to the angular extent of + the slice. + \endlist + + The figure is always drawn with the chart on the left and the key on + the right. This means that we must try and obtain an area that is wider + than it is tall. We do this by imposing a particular aspect ratio on + the chart and applying it to the available vertical space. This ensures + that we always obtain the maximum horizontal space for the aspect ratio + used. + We also apply fixed size margin around the figure. + + We use logical coordinates to draw the chart and key, and position them + on the view using viewports. + \endomit +*/ diff --git a/examples/widgets/doc/src/chip.qdoc b/examples/widgets/doc/src/chip.qdoc new file mode 100644 index 0000000000..966c16900a --- /dev/null +++ b/examples/widgets/doc/src/chip.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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 graphicsview/chip + \title 40000 Chips + + This demo shows how to visualize a huge scene with 40000 chip items + using Graphics View. It also shows Graphics View's powerful navigation + and interaction features, allowing you to zoom and rotate each of four + views independently, and you can select and move items around the scene. + + \image chip-demo.png +*/ diff --git a/examples/widgets/doc/src/classwizard.qdoc b/examples/widgets/doc/src/classwizard.qdoc new file mode 100644 index 0000000000..0c357b7286 --- /dev/null +++ b/examples/widgets/doc/src/classwizard.qdoc @@ -0,0 +1,190 @@ +/**************************************************************************** +** +** 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 dialogs/classwizard + \title Class Wizard Example + + The License Wizard example shows how to implement linear + wizards using QWizard. + + \image classwizard.png Screenshot of the Class Wizard example + + Most wizards have a linear structure, with page 1 followed by + page 2 and so on until the last page. Some wizards are more + complex in that they allow different traversal paths based on the + information provided by the user. The + \l{dialogs/licensewizard}{License Wizard} example shows how to + create such wizards. + + The Class Wizard example consists of the following classes: + + \list + \li \c ClassWizard inherits QWizard and provides a + three-step wizard that generates the skeleton of a C++ class + based on the user's input. + \li \c IntroPage, \c ClassInfoPage, \c CodeStylePage, \c + OutputFilesPage, and \c ConclusionPage are QWizardPage + subclasses that implement the wizard pages. + \endlist + + \section1 ClassWizard Class Definition + + \image classwizard-flow.png The Class Wizard pages + + We will see how to subclass QWizard to implement our own wizard. + The concrete wizard class is called \c ClassWizard and provides + five pages: + + \list + \li The first page is an introduction page, telling the user what + the wizard is going to do. + \li The second page asks for a class name and a base class, and + allows the user to specify whether the class should have a \c + Q_OBJECT macro and what constructors it should provide. + \li The third page allows the user to set some options related to the code + style, such as the macro used to protect the header file from + multiple inclusion (e.g., \c MYDIALOG_H). + \li The fourth page allows the user to specify the names of the + output files. + \li The fifth page is a conclusion page. + \endlist + + Although the program is just an example, if you press \uicontrol Finish + (\uicontrol Done on Mac OS X), actual C++ source files will actually be + generated. + + \section1 The ClassWizard Class + + Here's the \c ClassWizard definition: + + \snippet dialogs/classwizard/classwizard.h 0 + + The class reimplements QDialog's \l{QDialog::}{accept()} slot. + This slot is called when the user clicks \uicontrol{Finish}. + + Here's the constructor: + + \snippet dialogs/classwizard/classwizard.cpp 1 + + We instantiate the five pages and insert them into the wizard + using QWizard::addPage(). The order in which they are inserted + is also the order in which they will be shown later on. + + We call QWizard::setPixmap() to set the banner and the + background pixmaps for all pages. The banner is used as a + background for the page header when the wizard's style is + \l{QWizard::}{ModernStyle}; the background is used as the + dialog's background in \l{QWizard::}{MacStyle}. (See \l{Elements + of a Wizard Page} for more information.) + + \snippet dialogs/classwizard/classwizard.cpp 3 + \snippet dialogs/classwizard/classwizard.cpp 4 + \dots + \snippet dialogs/classwizard/classwizard.cpp 5 + \snippet dialogs/classwizard/classwizard.cpp 6 + + If the user clicks \uicontrol Finish, we extract the information from + the various pages using QWizard::field() and generate the files. + The code is long and tedious (and has barely anything to do with + noble art of designing wizards), so most of it is skipped here. + See the actual example in the Qt distribution for the details if + you're curious. + + \section1 The IntroPage Class + + The pages are defined in \c classwizard.h and implemented in \c + classwizard.cpp, together with \c ClassWizard. We will start with + the easiest page: + + \snippet dialogs/classwizard/classwizard.h 1 + \codeline + \snippet dialogs/classwizard/classwizard.cpp 7 + + A page inherits from QWizardPage. We set a + \l{QWizardPage::}{title} and a + \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting + any \l{QWizardPage::}{subTitle}, we ensure that no header is + displayed for this page. (On Windows, it is customary for wizards + to display a watermark pixmap on the first and last pages, and to + have a header on the other pages.) + + Then we create a QLabel and add it to a layout. + + \section1 The ClassInfoPage Class + + The second page is defined and implemented as follows: + + \snippet dialogs/classwizard/classwizard.h 2 + \codeline + \snippet dialogs/classwizard/classwizard.cpp 9 + \dots + \snippet dialogs/classwizard/classwizard.cpp 12 + \dots + \snippet dialogs/classwizard/classwizard.cpp 13 + + First, we set the page's \l{QWizardPage::}{title}, + \l{QWizardPage::}{subTitle}, and \l{QWizard::LogoPixmap}{logo + pixmap}. The logo pixmap is displayed in the page's header in + \l{QWizard::}{ClassicStyle} and \l{QWizard::}{ModernStyle}. + + Then we create the child widgets, create \l{Registering and Using + Fields}{wizard fields} associated with them, and put them into + layouts. The \c className field is created with an asterisk (\c + *) next to its name. This makes it a \l{mandatory field}, that + is, a field that must be filled before the user can press the + \uicontrol Next button (\uicontrol Continue on Mac OS X). The fields' values + can be accessed from any other page using QWizardPage::field(), + or from the wizard code using QWizard::field(). + + \section1 The CodeStylePage Class + + The third page is defined and implemented as follows: + + \snippet dialogs/classwizard/classwizard.h 3 + \codeline + \snippet dialogs/classwizard/classwizard.cpp 14 + \dots + \snippet dialogs/classwizard/classwizard.cpp 15 + \codeline + \snippet dialogs/classwizard/classwizard.cpp 16 + + The code in the constructor is very similar to what we did for \c + ClassInfoPage, so we skipped most of it. + + The \c initializePage() function is what makes this class + interesting. It is reimplemented from QWizardPage and is used to + initialize some of the page's fields with values from the + previous page (namely, \c className and \c baseClass). For + example, if the class name on page 2 is \c SuperDuperWidget, the + default macro name on page 3 is \c SUPERDUPERWIDGET_H. + + The \c OutputFilesPage and \c ConclusionPage classes are very + similar to \c CodeStylePage, so we won't review them here. + + \sa QWizard, {License Wizard Example}, {Trivial Wizard Example} +*/ diff --git a/examples/widgets/doc/src/codeeditor.qdoc b/examples/widgets/doc/src/codeeditor.qdoc new file mode 100644 index 0000000000..695ac5c4ce --- /dev/null +++ b/examples/widgets/doc/src/codeeditor.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 widgets/codeeditor + \title Code Editor Example + + The Code Editor example shows how to create a simple editor that + has line numbers and that highlights the current line. + + \image codeeditor-example.png + + As can be seen from the image, the editor displays the line + numbers in an area to the left of the area for editing. The editor + will highlight the line containing the cursor. + + We implement the editor in \c CodeEditor, which is a widget that + inherits QPlainTextEdit. We keep a separate widget in \c + CodeEditor (\c LineNumberArea) onto which we draw the line + numbers. + + QPlainTextEdit inherits from QAbstractScrollArea, and editing + takes place within its \l{QAbstractScrollArea::}{viewport()}'s + margins. We make room for our line number area by setting the left + margin of the viewport to the size we need to draw the line + numbers. + + When it comes to editing code, we prefer QPlainTextEdit over + QTextEdit because it is optimized for handling plain text. See + the QPlainTextEdit class description for details. + + QPlainTextEdit lets us add selections in addition to the + selection the user can make with the mouse or keyboard. We use + this functionality to highlight the current line. More on this + later. + + We will now move on to the definitions and implementations of \c + CodeEditor and \c LineNumberArea. Let's start with the \c + LineNumberArea class. + + \section1 The LineNumberArea Class + + We paint the line numbers on this widget, and place it over the \c + CodeEditor's \l{QAbstractScrollArea::}{viewport()}'s left margin + area. + + We need to use protected functions in QPlainTextEdit while + painting the area. So to keep things simple, we paint the area in + the \c CodeEditor class. The area also asks the editor to + calculate its size hint. + + Note that we could simply paint the line numbers directly on the + code editor, and drop the LineNumberArea class. However, the + QWidget class helps us to \l{QWidget::}{scroll()} its contents. + Also, having a separate widget is the right choice if we wish to + extend the editor with breakpoints or other code editor features. + The widget would then help in the handling of mouse events. + + \snippet widgets/codeeditor/codeeditor.h extraarea + + \section1 CodeEditor Class Definition + + Here is the code editor's class definition: + + \snippet widgets/codeeditor/codeeditor.h codeeditordefinition + + In the editor we resize and draw the line numbers on the \c + LineNumberArea. We need to do this when the number of lines in the + editor changes, and when the editor's viewport() is scrolled. Of + course, it is also done when the editor's size changes. We do + this in \c updateLineNumberWidth() and \c updateLineNumberArea(). + + Whenever, the cursor's position changes, we highlight the current + line in \c highlightCurrentLine(). + + \section1 CodeEditor Class Implementation + + We will now go through the code editors implementation, starting + off with the constructor. + + \snippet widgets/codeeditor/codeeditor.cpp constructor + + In the constructor we connect our slots to signals in + QPlainTextEdit. It is necessary to calculate the line number area + width and highlight the first line when the editor is created. + + \snippet widgets/codeeditor/codeeditor.cpp extraAreaWidth + + The \c lineNumberAreaWidth() function calculates the width of the + \c LineNumberArea widget. We take the number of digits in the last + line of the editor and multiply that with the maximum width of a + digit. + + \snippet widgets/codeeditor/codeeditor.cpp slotUpdateExtraAreaWidth + + When we update the width of the line number area, we simply call + QAbstractScrollArea::setViewportMargins(). + + \snippet widgets/codeeditor/codeeditor.cpp slotUpdateRequest + + This slot is invoked when the editors viewport has been scrolled. + The QRect given as argument is the part of the editing area that + is do be updated (redrawn). \c dy holds the number of pixels the + view has been scrolled vertically. + + \snippet widgets/codeeditor/codeeditor.cpp resizeEvent + + When the size of the editor changes, we also need to resize the + line number area. + + \snippet widgets/codeeditor/codeeditor.cpp cursorPositionChanged + + When the cursor position changes, we highlight the current line, + i.e., the line containing the cursor. + + QPlainTextEdit gives the possibility to have more than one + selection at the same time. we can set the character format + (QTextCharFormat) of these selections. We clear the cursors + selection before setting the new new + QPlainTextEdit::ExtraSelection, else several lines would get + highlighted when the user selects multiple lines with the mouse. + \omit ask someone how this works \endomit + + One sets the selection with a text cursor. When using the + FullWidthSelection property, the current cursor text block (line) + will be selected. If you want to select just a portion of the text + block, the cursor should be moved with QTextCursor::movePosition() + from a position set with \l{QTextCursor::}{setPosition()}. + + \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_0 + + The \c lineNumberAreaPaintEvent() is called from \c LineNumberArea + whenever it receives a paint event. We start off by painting the + widget's background. + + \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_1 + + We will now loop through all visible lines and paint the line + numbers in the extra area for each line. Notice that in a plain + text edit each line will consist of one QTextBlock; though, if + line wrapping is enabled, a line may span several rows in the text + edit's viewport. + + We get the top and bottom y-coordinate of the first text block, + and adjust these values by the height of the current text block in + each iteration in the loop. + + \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_2 + + Notice that we check if the block is visible in addition to check + if it is in the areas viewport - a block can, for example, be + hidden by a window placed over the text edit. + + \section1 Suggestions for Extending the Code Editor + + No self-respecting code editor is without a syntax + highligther; the \l{Syntax Highlighter Example} shows how to + create one. + + In addition to line numbers, you can add more to the extra area, + for instance, break points. + + QSyntaxHighlighter gives the possibility to add user data to each + text block with + \l{QSyntaxHighlighter::}{setCurrentBlockUserData()}. This can be + used to implement parenthesis matching. In the \c + highlightCurrentLine(), the data of the currentBlock() can be + fetched with QTextBlock::userData(). Matching parentheses can be + highlighted with an extra selection. The "Matching Parentheses + with QSyntaxHighlighter" article in Qt Quarterly 31 implements + this. You find it here: \l{http://doc.qt.nokia.com/qq/}. + +*/ diff --git a/examples/widgets/doc/src/coloreditorfactory.qdoc b/examples/widgets/doc/src/coloreditorfactory.qdoc new file mode 100644 index 0000000000..a2c02f8c1d --- /dev/null +++ b/examples/widgets/doc/src/coloreditorfactory.qdoc @@ -0,0 +1,155 @@ +/**************************************************************************** +** +** 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 itemviews/coloreditorfactory + \title Color Editor Factory Example + + This example shows how to create an editor that can be used by + a QItemDelegate. + + \image coloreditorfactoryimage.png + + When editing data in a QListView, QTableView, or QTreeView, + editors are created and displayed by a \l{Delegate + Classes}{delegate}. QItemDelegate, which is the default delegate + used by Qt's \l{View Classes}{item views}, uses a + QItemEditorFactory to create editors for it. A unique instance + provided by QItemEditorFactory is by default installed on all + item delegates. + + An item editor factory contains a collection of + QItemEditorCreatorBase instances, which are specialized factories + that produce editors for one particular QVariant data type (all + models in Qt store their data in \l{QVariant}s). An editor can be any + Qt or custom widget. + + In this example, we will create an editor (implemented in the \c + ColorListEditor class) that can edit the QColor data type and be + used by \l{QItemDelegate}s. We do this by creating a new + QItemEditorCreatorBase that produces \c ColorListEditors and + register it with a new factory, which we set as the default editor + item factory (the unique factory instance). To test our editor, we + have implemented the \c Window class, which displays a + QTableWidget in which \l{QColor}s can be edited. + + \section1 Window Class Implementation + + In the Window class, we create the item editor creator + base for our color editor and add it to the default factory. + We also create a QTableWidget in which our editor can be + tested. It is filled with some data and displayed in a window. + + We take a closer look at the constructor: + + \snippet itemviews/coloreditorfactory/window.cpp 0 + + The QStandardItemEditorCreator is a convenience class that + inherits QItemEditorCreatorBase. Its constructor takes a template + class, of which instances are returned from + \l{QItemEditorCreatorBase::}{createWidget()}. The creator uses a + constructor that takes a QWidget as its only parameter; the + template class must provide this. This way, there is no need to + subclass QStandardItemEditorCreator. + + After the new factory has been set, all standard item delegates + will use it (i.e, also delegates that were created before the new + default factory was set). + + The \c createGUI() function sets up the table and fills it + with data. + + \section1 ColorListEditor Definition + + The ColorListEditor inherits QComboBox and lets the user + select a QColor from its popup list. + + \snippet itemviews/coloreditorfactory/colorlisteditor.h 0 + + QItemDelegate manages the interaction between the editor and + the model, i.e., it retrieves data to edit from the model and + store data from the editor in the model. The data that is edited + by an editor is stored in the editor's user data property, and the + delegate uses Qt's \l{Qt's Property System}{property system} to + access it by name. We declare our user data property with the + Q_PROPERTY macro. The property is set to be the user type with the + USER keyword. + + \section1 ColorListEditor Implementation + + The constructor of \c ColorListEditor simply calls \c + populateList(), which we will look at later. We move on to the + \c color() function: + + \snippet itemviews/coloreditorfactory/colorlisteditor.cpp 0 + + We return the data that is selected in the combobox. The data + is stored in the Qt::DecorationRole as the color is then also + displayed in the popup list (as shown in the image above). + + \snippet itemviews/coloreditorfactory/colorlisteditor.cpp 1 + + The \c findData() function searches the items in the combobox + and returns the index of the item that has \c color in the + Qt::Decoration role. + + \snippet itemviews/coloreditorfactory/colorlisteditor.cpp 2 + + Qt knows some predefined colors by name. We simply loop + through these to fill our editor with items. + + \section1 Further Customization of Item View Editors + + You can customize Qt's \l{Model/View Programming}{model view + framework} in many ways. The procedure shown in this example is + usually sufficient to provide custom editors. Further + customization is achieved by subclassing QItemEditorFactory + and QItemEditorCreatorBase. It is also possible to subclass + QItemDelegate if you don't wish to use a factory at all. + + Possible suggestions are: + + \list + \li If the editor widget has no user property defined, the delegate + asks the factory for the property name, which it in turn + asks the item editor creator for. In this case, you can use + the QItemEditorCreator class, which takes the property + name to use for editing as a constructor argument. + \li If the editor requires other constructors or other + initialization than provided by QItemEditorCreatorBase, you + must reimplement + QItemEditorCreatorBase::createWidget(). + \li You could also subclass QItemEditorFactory if you only want + to provide editors for certain kinds of data or use another + method of creating the editors than using creator bases. + \endlist + + In this example, we use a standard QVariant data type. You can + also use custom types. In the \l{Star Delegate Example}, we + show how to store a custom data type in a QVariant and paint + and edit it in a class that inherits QItemDelegate. +*/ diff --git a/examples/widgets/doc/src/combowidgetmapper.qdoc b/examples/widgets/doc/src/combowidgetmapper.qdoc new file mode 100644 index 0000000000..949014930d --- /dev/null +++ b/examples/widgets/doc/src/combowidgetmapper.qdoc @@ -0,0 +1,167 @@ +/**************************************************************************** +** +** 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 itemviews/combowidgetmapper + \title Combo Widget Mapper Example + + The Combo Widget Mapper example shows how to use a custom delegate to + map information from a model to specific widgets on a form. + + \image combowidgetmapper-example.png + + In the \l{Simple Widget Mapper Example}, we showed the basic use of a + widget mapper to relate data exposed by a model to simple input widgets + in a user interface. However, sometimes we want to use input widgets that + expose data as choices to the user, such as QComboBox, and we need a way + to relate their input to the values stored in the model. + + This example is very similar to the \l{Simple Widget Mapper Example}. + Again, we create a \c Window class with an almost identical user interface, + except that, instead of providing a spin box so that each person's age + can be entered, we provide a combo box to allow their addresses to be + classified as "Home", "Work" or "Other". + + \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 itemviews/combowidgetmapper/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 constructor of the \c Window class can be explained in three parts. + In the first part, we set up the widgets used for the user interface: + + \snippet itemviews/combowidgetmapper/window.cpp Set up widgets + + Note that we set up the mapping the combo box in the same way as for other + widgets, but that we apply its own model to it so that it will display + data from its own model, the \c typeModel, rather than from the model + containing data about each person. + + Next, we set up the widget mapper, relating each input widget to a column + in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}: + + \snippet itemviews/combowidgetmapper/window.cpp Set up the mapper + + For the combo box, we pass an extra argument to tell the widget mapper + which property to relate to values from the model. As a result, the user + is able to select an item from the combo box, and the corresponding + value stored in the widget's \c currentIndex property will be stored in + the model. + + \omit + However, we also set a delegate on the mapper. As with \l{Delegate Classes}, + this changes the way that data is presented to the user. In this case, the + delegate acts as a proxy between the mapper and the input widgets, + translating the data into a suitable form for the combo box but not + interfering with the other input widgets. The implementation is shown later. + \endomit + + The rest of the constructor is very similar to that of the + \l{Simple Widget Mapper Example}: + + \snippet itemviews/combowidgetmapper/window.cpp Set up connections and layouts + + The model is initialized in the window's \c{setupModel()} function. Here, + we create a standard model with 5 rows and 3 columns. In each row, we + insert a name, address, and a value that indicates the type of address. + The address types are stored in a string list model. + + \snippet itemviews/combowidgetmapper/window.cpp Set up the model + + As we insert each row into the model, like a record in a database, we + store values that correspond to items in \c typeModel for each person's + address type. When the widget mapper reads these values from the final + column of each row, it will need to use them as references to values in + \c typeModel, as shown in the following diagram. This is where the + delegate is used. + + \image widgetmapper-combo-mapping.png + + We show the implementation of the \c{updateButtons()} slot for + completeness: + + \snippet itemviews/combowidgetmapper/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 itemviews/combowidgetmapper/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 itemviews/combowidgetmapper/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 itemviews/combowidgetmapper/delegate.cpp setModelData implementation + \endomit + + \section1 Summary and Further Reading + + The use of a separate model for the combo box provides a menu of choices + that are separate from the data stored in the main model. Using a named + mapping that relates the combo box's \c currentIndex property to a column + in the model effectively allows us to store a look-up value in the model. + + However, when reading the model outside the context of the widget mapper, + we need to know about the \c typeModel to make sense of these look-up + values. It would be useful to be able to store both the data and the + choices held by the \c typeModel in one place. + This is covered by the \l{SQL Widget Mapper Example}. +*/ diff --git a/examples/widgets/doc/src/composition.qdoc b/examples/widgets/doc/src/composition.qdoc new file mode 100644 index 0000000000..6aca01d255 --- /dev/null +++ b/examples/widgets/doc/src/composition.qdoc @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** 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 painting/composition + \title Composition Modes + + This demo shows some of the more advanced composition modes supported by Qt. + + \image composition-demo.png + + The two most common forms of composition are \b{Source} and \b{SourceOver}. + \b{Source} is used to draw opaque objects onto a paint device. In this mode, + each pixel in the source replaces the corresponding pixel in the destination. + In \b{SourceOver} composition mode, the source object is transparent and is + drawn on top of the destination. + + In addition to these standard modes, Qt defines the complete set of composition modes + as defined by X. Porter and Y. Duff. See the QPainter documentation for details. +*/ diff --git a/examples/widgets/doc/src/concentriccircles.qdoc b/examples/widgets/doc/src/concentriccircles.qdoc new file mode 100644 index 0000000000..67bc125dbe --- /dev/null +++ b/examples/widgets/doc/src/concentriccircles.qdoc @@ -0,0 +1,231 @@ +/**************************************************************************** +** +** 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 painting/concentriccircles + \title Concentric Circles Example + + The Concentric Circles example shows the improved rendering + quality that can be obtained using floating point precision and + anti-aliasing when drawing custom widgets. The example also shows + how to do simple animations. + + The application's main window displays several widgets which are + drawn using the various combinations of precision and + anti-aliasing. + + \image concentriccircles-example.png + + Anti-aliasing is one of QPainter's render hints. The + QPainter::RenderHints are used to specify flags to QPainter that + may, or may not, be respected by any given + engine. QPainter::Antialiasing indicates that the engine should + anti-alias the edges of primitives if possible, i.e. put + additional pixels around the original ones to smooth the edges. + + The difference between floating point precision and integer + precision is a matter of accuracy, and is visible in the + application's main window: Even though the logic that is + calculating the circles' geometry is the same, floating points + ensure that the white spaces between each circle are of the same + size, while integers make two and two circles appear as if they + belong together. The reason is that the integer based precision + rely on rounding off non-integer calculations. + + The example consists of two classes: + + \list + \li \c CircleWidget is a custom widget which renders several animated + concentric circles. + \li \c Window is the application's main window displaying four \c + {CircleWidget}s drawn using different combinations of precision + and aliasing. + \endlist + + First we will review the CircleWidget class, then we will take a + look at the Window class. + + \section1 CircleWidget Class Definition + + The CircleWidget class inherits QWidget, and is a custom widget + which renders several animated concentric circles. + + \snippet painting/concentriccircles/circlewidget.h 0 + + We declare the \c floatBased and \c antialiased variables to hold + whether an instance of the class should be rendered with integer + or float based precision, and whether the rendering should be + anti-aliased or not. We also declare functions setting each of + these variables. + + In addition we reimplement the QWidget::paintEvent() function to + apply the various combinations of precision and anti-aliasing when + rendering, and to support the animation. We reimplement the + QWidget::minimumSizeHint() and QWidget::sizeHint() functions to + give the widget a reasonable size within our application. + + We declare the private \c nextAnimationFrame() slot, and the + associated \c frameNo variable holding the number of "animation + frames" for the widget, to facilitate the animation. + + \section1 CircleWidget Class Implementation + + In the constructor we make the widget's rendering integer based + and aliased by default: + + \snippet painting/concentriccircles/circlewidget.cpp 0 + + We initialize the widget's \c frameNo variable, and set the + widget's background color using the QWidget::setBackgroundColor() + function which takes a \l {QPalette::ColorRole}{color role} as + argument; the QPalette::Base color role is typically white. + + Then we set the widgets size policy using the + QWidget::setSizePolicy() function. QSizePolicy::Expanding means + that the widget's \l {QWidget::sizeHint()}{sizeHint()} is a + sensible size, but that the widget can be shrunk and still be + useful. The widget can also make use of extra space, so it should + get as much space as possible. + + \snippet painting/concentriccircles/circlewidget.cpp 1 + \codeline + \snippet painting/concentriccircles/circlewidget.cpp 2 + + The public \c setFloatBased() and \c setAntialiased() functions + update the widget's rendering preferences, i.e. whether the widget + should be rendered with integer or float based precision, and + whether the rendering should be anti-aliased or not. + + The functions also generate a paint event by calling the + QWidget::update() function, forcing a repaint of the widget with + the new rendering preferences. + + \snippet painting/concentriccircles/circlewidget.cpp 3 + \codeline + \snippet painting/concentriccircles/circlewidget.cpp 4 + + The default implementations of the QWidget::minimumSizeHint() and + QWidget::sizeHint() functions return invalid sizes if there is no + layout for the widget, otherwise they return the layout's minimum and + preferred size, respectively. + + We reimplement the functions to give the widget minimum and + preferred sizes which are reasonable within our application. + + \snippet painting/concentriccircles/circlewidget.cpp 5 + + The nextAnimationFrame() slot simply increments the \c frameNo + variable's value, and calls the QWidget::update() function which + schedules a paint event for processing when Qt returns to the main + event loop. + + \snippet painting/concentriccircles/circlewidget.cpp 6 + + A paint event is a request to repaint all or part of the + widget. The \c paintEvent() function is an event handler that can + be reimplemented to receive the widget's paint events. We + reimplement the event handler to apply the various combinations of + precision and anti-aliasing when rendering the widget, and to + support the animation. + + First, we create a QPainter for the widget, and set its + antialiased flag to the widget's preferred aliasing. We also + translate the painters coordinate system, preparing to draw the + widget's cocentric circles. The translation ensures that the + center of the circles will be equivalent to the widget's center. + + \snippet painting/concentriccircles/circlewidget.cpp 7 + + When painting a circle, we use the number of "animation frames" to + determine the alpha channel of the circle's color. The alpha + channel specifies the color's transparency effect, 0 represents a + fully transparent color, while 255 represents a fully opaque + color. + + \snippet painting/concentriccircles/circlewidget.cpp 8 + + If the calculated alpha channel is fully transparent, we don't + draw anything since that would be equivalent to drawing a white + circle on a white background. Instead we skip to the next circle + still creating a white space. If the calculated alpha channel is + fully opaque, we set the pen (the QColor passed to the QPen + constructor is converted into the required QBrush by default) and + draw the circle. If the widget's preferred precision is float + based, we specify the circle's bounding rectangle using QRectF and + double values, otherwise we use QRect and integers. + + The animation is controlled by the public \c nextAnimationFrame() + slot: Whenever the \c nextAnimationFrame() slot is called the + number of frames is incremented and a paint event is + scheduled. Then, when the widget is repainted, the alpha-blending + of the circles' colors change and the circles appear as animated. + + \section1 Window Class Definition + + The Window class inherits QWidget, and is the application's main + window rendering four \c {CircleWidget}s using different + combinations of precision and aliasing. + + \snippet painting/concentriccircles/window.h 0 + + We declare the various components of the main window, i.e., the text + labels and a double array that will hold reference to the four \c + {CircleWidget}s. In addition we declare the private \c + createLabel() function to simplify the constructor. + + \section1 Window Class Implementation + + \snippet painting/concentriccircles/window.cpp 0 + + In the constructor, we first create the various labels and put + them in a QGridLayout. + + \snippet painting/concentriccircles/window.cpp 1 + + Then we create a QTimer. The QTimer class is a high-level + programming interface for timers, and provides repetitive and + single-shot timers. + + We create a timer to facilitate the animation of our concentric + circles; when we create the four CircleWidget instances (and add + them to the layout), we connect the QTimer::timeout() signal to + each of the widgets' \c nextAnimationFrame() slots. + + \snippet painting/concentriccircles/window.cpp 2 + + Before we set the layout and window title for our main window, we + make the timer start with a timeout interval of 100 milliseconds, + using the QTimer::start() function. That means that the + QTimer::timeout() signal will be emitted, forcing a repaint of the + four \c {CircleWidget}s, every 100 millisecond which is the reason + the circles appear as animated. + + \snippet painting/concentriccircles/window.cpp 3 + + The private \c createLabel() function is implemented to simlify + the constructor. +*/ diff --git a/examples/widgets/doc/src/configdialog.qdoc b/examples/widgets/doc/src/configdialog.qdoc new file mode 100644 index 0000000000..9acea72a3b --- /dev/null +++ b/examples/widgets/doc/src/configdialog.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 dialogs/configdialog + \title Config Dialog Example + + The Config Dialog examples shows how a configuration dialog can be created by + using an icon view with a stacked widget. + + \image configdialog-example.png +*/ diff --git a/examples/widgets/doc/src/customsortfiltermodel.qdoc b/examples/widgets/doc/src/customsortfiltermodel.qdoc new file mode 100644 index 0000000000..4dce820f9c --- /dev/null +++ b/examples/widgets/doc/src/customsortfiltermodel.qdoc @@ -0,0 +1,289 @@ +/**************************************************************************** +** +** 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 itemviews/customsortfiltermodel + \title Custom Sort/Filter Model Example + + The Custom Sort/Filter Model example illustrates how to subclass + QSortFilterProxyModel to perform advanced sorting and filtering. + + \image customsortfiltermodel-example.png Screenshot of the Custom Sort/Filter Model Example + + The QSortFilterProxyModel class provides support for sorting and + filtering data passed between another model and a view. + + The model transforms the structure of a source model by mapping + the model indexes it supplies to new indexes, corresponding to + different locations, for views to use. This approach allows a + given source model to be restructured as far as views are + concerned, without requiring any transformations on the underlying + data and without duplicating the data in memory. + + The Custom Sort/Filter Model example consists of two classes: + + \list + + \li The \c MySortFilterProxyModel class provides a custom proxy + model. + + \li The \c Window class provides the main application window, + using the custom proxy model to sort and filter a standard + item model. + + \endlist + + We will first take a look at the \c MySortFilterProxyModel class + to see how the custom proxy model is implemented, then we will + take a look at the \c Window class to see how the model is + used. Finally we will take a quick look at the \c main() function. + + \section1 MySortFilterProxyModel Class Definition + + The \c MySortFilterProxyModel class inherits the + QSortFilterProxyModel class. + + Since QAbstractProxyModel and its subclasses are derived from + QAbstractItemModel, much of the same advice about subclassing + normal models also applies to proxy models. + + On the other hand, it is worth noting that many of + QSortFilterProxyModel's default implementations of functions are + written so that they call the equivalent functions in the relevant + source model. This simple proxying mechanism may need to be + overridden for source models with more complex behavior; in this + example we derive from the QSortFilterProxyModel class to ensure + that our filter can recognize a valid range of dates, and to + control the sorting behavior. + + \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.h 0 + + We want to be able to filter our data by specifying a given period + of time. For that reason, we implement the custom \c + setFilterMinimumDate() and \c setFilterMaximumDate() functions as + well as the corresponding \c filterMinimumDate() and \c + filterMaximumDate() functions. We reimplement + QSortFilterProxyModel's \l + {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} + function to only accept rows with valid dates, and + QSortFilterProxyModel::lessThan() to be able to sort the senders + by their email addresses. Finally, we implement a \c dateInRange() + convenience function that we will use to determine if a date is + valid. + + \section1 MySortFilterProxyModel Class Implementation + + The \c MySortFilterProxyModel constructor is trivial, passing the + parent parameter on to the base class constructor: + + \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 0 + + The most interesting parts of the \c MySortFilterProxyModel + implementation are the reimplementations of + QSortFilterProxyModel's \l + {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} + and \l {QSortFilterProxyModel::lessThan()}{lessThan()} + functions. Let's first take a look at our customized \c lessThan() + function. + + \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 4 + + We want to sort the senders by their email addresses. The \l + {QSortFilterProxyModel::}{lessThan()} function is used as the < + operator when sorting. The default implementation handles a + collection of types including QDateTime and String, but in order + to be able to sort the senders by their email addresses we must + first identify the address within the given string: + + \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 6 + + We use QRegExp to define a pattern for the addresses we are looking + for. The QRegExp::indexIn() function attempts to find a match in + the given string and returns the position of the first match, or + -1 if there was no match. If the given string contains the + pattern, we use QRegExp's \l {QRegExp::cap()}{cap()} function to + retrieve the actual address. The \l {QRegExp::cap()}{cap()} + function returns the text captured by the \e nth + subexpression. The entire match has index 0 and the parenthesized + subexpressions have indexes starting from 1 (excluding + non-capturing parentheses). + + \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 3 + + The \l + {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} + function, on the other hand, is expected to return true if the + given row should be included in the model. In our example, a row + is accepted if either the subject or the sender contains the given + regular expression, and the date is valid. + + \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 7 + + We use our custom \c dateInRange() function to determine if a date + is valid. + + To be able to filter our data by specifying a given period of + time, we also implement functions for getting and setting the + minimum and maximum dates: + + \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 1 + \codeline + \snippet itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 2 + + The get functions, \c filterMinimumDate() and \c + filterMaximumDate(), are trivial and implemented as inline + function in the header file. + + This completes our custom proxy model. Let's see how we can use it + in an application. + + \section1 Window Class Definition + + The \c CustomFilter class inherits QWidget, and provides this + example's main application window: + + \snippet itemviews/customsortfiltermodel/window.h 0 + + We implement two private slots, \c textFilterChanged() and \c + dateFilterChanged(), to respond to the user changing the filter + pattern, case sensitivity or any of the dates. In addition, we + implement a public \c setSourceModel() convenience function to set + up the model/ view relation. + + \section1 Window Class Implementation + + In this example, we have chosen to create and set the source model + in the \c main () function (which we will come back to later). So + when constructing the main application window, we assume that a + source model already exists and start by creating an instance of + our custom proxy model: + + \snippet itemviews/customsortfiltermodel/window.cpp 0 + + We set the \l + {QSortFilterProxyModel::dynamicSortFilter}{dynamicSortFilter} + property that holds whether the proxy model is dynamically sorted + and filtered. By setting this property to true, we ensure that the + model is sorted and filtered whenever the contents of the source + model change. + + The main application window shows views of both the source model + and the proxy model. The source view is quite simple: + + \snippet itemviews/customsortfiltermodel/window.cpp 1 + + The QTreeView class provides a default model/view implementation + of a tree view; our view implements a tree representation of items + in the application's source model. + + \snippet itemviews/customsortfiltermodel/window.cpp 2 + + The QTreeView class provides a default model/view implementation + of a tree view; our view implements a tree representation of items + in the application's source model. We add our view widget to a + layout that we install on a corresponding group box. + + The proxy model view, on the other hand, contains several widgets + controlling the various aspects of transforming the source model's + data structure: + + \snippet itemviews/customsortfiltermodel/window.cpp 3 + \snippet itemviews/customsortfiltermodel/window.cpp 4 + + Note that whenever the user changes one of the filtering options, + we must explicitly reapply the filter. This is done by connecting + the various editors to functions that update the proxy model. + + \snippet itemviews/customsortfiltermodel/window.cpp 5 + + The sorting will be handled by the view. All we have to do is to + enable sorting for our proxy view by setting the + QTreeView::sortingEnabled property (which is false by + default). Then we add all the filtering widgets and the proxy view + to a layout that we install on a corresponding group box. + + \snippet itemviews/customsortfiltermodel/window.cpp 6 + + Finally, after putting our two group boxes into another layout + that we install on our main application widget, we customize the + application window. + + As mentioned above, we create the source model in the \c main () + function, calling the \c Window::setSourceModel() function to make + the application use it: + + \snippet itemviews/customsortfiltermodel/window.cpp 7 + + The QSortFilterProxyModel::setSourceModel() function makes the + proxy model process the data in the given model, in this case out + mail model. The \l {QAbstractItemView::}{setModel()} that the + view widget inherits from the QAbstractItemModel class, sets the + model for the view to present. Note that the latter function will + also create and set a new selection model. + + \snippet itemviews/customsortfiltermodel/window.cpp 8 + + The \c textFilterChanged() function is called whenever the user + changes the filter pattern or the case sensitivity. + + We first retrieve the preferred syntax (the QRegExp::PatternSyntax + enum is used to interpret the meaning of the given pattern), then + we determine the preferred case sensitivity. Based on these + preferences and the current filter pattern, we set the proxy + model's \l {QSortFilterProxyModel::}{filterRegExp} property. The + \l {QSortFilterProxyModel::}{filterRegExp} property holds the + regular expression used to filter the contents of the source + model. Note that calling QSortFilterProxyModel's \l + {QSortFilterProxyModel::}{setFilterRegExp()} function also updates + the model. + + \snippet itemviews/customsortfiltermodel/window.cpp 9 + + The \c dateFilterChanged() function is called whenever the user + modifies the range of valid dates. We retrieve the new dates from + the user interface, and call the corresponding functions (provided + by our custom proxy model) to set the proxy model's minimum and + maximum dates. As we explained above, calling these functions also + updates the model. + + \section1 The Main() Function + + In this example, we have separated the application from the source + model by creating the model in the \c main () function. First we + create the application, then we create the source model: + + \snippet itemviews/customsortfiltermodel/main.cpp 0 + + The \c createMailModel() function is a convenience function + provided to simplify the constructor. All it does is to create and + return a model describing a collection of emails. The model is an + instance of the QStandardItemModel class, i.e., a generic model + for storing custom data typically used as a repository for + standard Qt data types. Each mail description is added to the + model using \c addMail(), another convenience function. See \l + {itemviews/customsortfiltermodel/main.cpp}{main.cpp} for details. +*/ diff --git a/examples/widgets/doc/src/deform.qdoc b/examples/widgets/doc/src/deform.qdoc new file mode 100644 index 0000000000..8195f90ffa --- /dev/null +++ b/examples/widgets/doc/src/deform.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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 painting/deform + \title Vector Deformation + + This example shows how to use advanced vector techniques to draw text + using a \c QPainterPath. + + \image deform-demo.png + + We define a vector deformation field in the shape of a lens and apply + this to all points in a path. This means that what is rendered on + screen is not pixel manipulation, but modified vector representations of + the glyphs themselves. This is visible from the high quality of the + antialiased edges for the deformed glyphs. + + To get a fairly complex path we allow the user to type in text and + convert the text to paths. This is done using the + QPainterPath::addText() function. + + The lens is drawn using a single call to QPainter::drawEllipse(), + using a QRadialGradient to fill it with a specialized color + table, giving the effect of the sun's reflection and a drop + shadow. The lens is cached as a pixmap for better performance. +*/ diff --git a/examples/widgets/doc/src/diagramscene.qdoc b/examples/widgets/doc/src/diagramscene.qdoc new file mode 100644 index 0000000000..b61a936d52 --- /dev/null +++ b/examples/widgets/doc/src/diagramscene.qdoc @@ -0,0 +1,834 @@ +/**************************************************************************** +** +** 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 graphicsview/diagramscene + \title Diagram Scene Example + + This example shows use of Qt's graphics framework. + + \image diagramscene.png + + The Diagram Scene example is an application in which you can + create a flowchart diagram. It is possible to add flowchart shapes + and text and connect the shapes by arrows as shown in the image + above. The shapes, arrows, and text can be given different + colors, and it is possible to change the font, style, and + underline of the text. + + The Qt graphics view framework is designed to manage and display + custom 2D graphics items. The main classes of the framework are + QGraphicsItem, QGraphicsScene and QGraphicsView. The graphics + scene manages the items and provides a surface for them. + QGraphicsView is a widget that is used to render a scene on the + screen. See the \l{Graphics View Framework} for a more detailed + description of the framework. + + In this example we show how to create such custom graphics + scenes and items by implementing classes that inherit + QGraphicsScene and QGraphicsItem. + + In particular we show how to: + + \list + \li Create custom graphics items. + \li Handle mouse events and movement of items. + \li Implement a graphics scene that can manage our custom items. + \li Custom painting of items. + \li Create a movable and editable text item. + \endlist + + The example consists of the following classes: + \list + \li \c MainWindow creates the widgets and display + them in a QMainWindow. It also manages the interaction + between the widgets and the graphics scene, view and + items. + \li \c DiagramItem inherits QGraphicsPolygonItem and + represents a flowchart shape. + \li \c TextDiagramItem inherits QGraphicsTextItem and + represents text items in the diagram. The class adds + support for moving the item with the mouse, which is not + supported by QGraphicsTextItem. + \li \c Arrow inherits QGraphicsLineItem and is an arrow + that connect two DiagramItems. + \li \c DiagramScene inherits QGraphicsDiagramScene and + provides support for \c DiagramItem, \c Arrow and + \c DiagramTextItem (In addition to the support already + handled by QGraphicsScene). + \endlist + + \section1 MainWindow Class Definition + + \snippet graphicsview/diagramscene/mainwindow.h 0 + + The \c MainWindow class creates and lays out the widgets in a + QMainWindow. The class forwards input from the widgets to the + DiagramScene. It also updates its widgets when the diagram + scene's text item changes, or a diagram item or a diagram text item + is inserted into the scene. + + The class also deletes items from the scene and handles the + z-ordering, which decides the order in which items are drawn when + they overlap each other. + + \section1 MainWindow Class Implementation + + + We start with a look at the constructor: + + \snippet graphicsview/diagramscene/mainwindow.cpp 0 + + In the constructor we call methods to create the widgets and + layouts of the example before we create the diagram scene. + The toolbars must be created after the scene as they connect + to its signals. We then lay the widgets out in the window. + + We connect to the \c itemInserted() and \c textInserted() slots of + the diagram scenes as we want to uncheck the buttons in the tool + box when an item is inserted. When an item is selected in + the scene we receive the \c itemSelected() signal. We use this to + update the widgets that display font properties if the item + selected is a \c DiagramTextItem. + + The \c createToolBox() function creates and lays out the widgets + of the \c toolBox QToolBox. We will not examine it with a + high level of detail as it does not deal with graphics framework + specific functionality. Here is its implementation: + + \snippet graphicsview/diagramscene/mainwindow.cpp 21 + + This part of the function sets up the tabbed widget item that + contains the flowchart shapes. An exclusive QButtonGroup always + keeps one button checked; we want the group to allow all buttons + to be unchecked. + We still use a button group since we can associate user + data, which we use to store the diagram type, with each button. + The \c createCellWidget() function sets up the buttons in the + tabbed widget item and is examined later. + + The buttons of the background tabbed widget item is set up in the + same way, so we skip to the creation of the tool box: + + \snippet graphicsview/diagramscene/mainwindow.cpp 22 + + We set the preferred size of the toolbox as its maximum. This + way, more space is given to the graphics view. + + Here is the \c createActions() function: + + \snippet graphicsview/diagramscene/mainwindow.cpp 23 + + We show an example of the creation of an action. The + functionality the actions trigger is discussed in the slots we + connect the actions to. You can see the \l{Application + Example}{application example} if you need a high-level + introduction to actions. + + The is the \c createMenus() function: + + \snippet graphicsview/diagramscene/mainwindow.cpp 24 + + We create the three menus' of the example. + + The \c createToolbars() function sets up the examples tool + bars. The three \l{QToolButton}s in the \c colorToolBar, the \c + fontColorToolButton, \c fillColorToolButton, and \c + lineColorToolButton, are interesting as we create icons for them + by drawing on a QPixmap with a QPainter. We show how the \c + fillColorToolButton is created. This button lets the user select a + color for the diagram items. + + \snippet graphicsview/diagramscene/mainwindow.cpp 25 + \dots + \snippet graphicsview/diagramscene/mainwindow.cpp 26 + + We set the menu of the tool button with + \l{QToolButton::}{setMenu()}. We need the \c fillAction QAction + object to always be pointing to the selected action of the menu. + The menu is created with the \c createColorMenu() function and, as + we shall see later, contains one menu item for each color that the + items can have. When the user presses the button, which trigger + the \l{QToolButton::}{clicked()} signal, we can set the color of + the selected item to the color of \c fillAction. It is with \c + createColorToolButtonIcon() we create the icon for the button. + + \dots + \snippet graphicsview/diagramscene/mainwindow.cpp 27 + + Here is the \c createBackgroundCellWidget() function: + + \snippet graphicsview/diagramscene/mainwindow.cpp 28 + + This function creates \l{QWidget}s containing a tool button + and a label. The widgets created with this function are used for + the background tabbed widget item in the tool box. + + Here is the \c createCellWidget() function: + + \snippet graphicsview/diagramscene/mainwindow.cpp 29 + + This function returns a QWidget containing a QToolButton with + an image of one of the \c DiagramItems, i.e., flowchart shapes. + The image is created by the \c DiagramItem through the \c image() + function. The QButtonGroup class lets us attach an id (int) with + each button; we store the diagram's type, i.e., the + DiagramItem::DiagramType enum. We use the stored diagram type when + we create new diagram items for the scene. The widgets created + with this function is used in the tool box. + + Here is the \c createColorMenu() function: + + \snippet graphicsview/diagramscene/mainwindow.cpp 30 + + This function creates a color menu that is used as the + drop-down menu for the tool buttons in the \c colorToolBar. We + create an action for each color that we add to the menu. We fetch + the actions data when we set the color of items, lines, and text. + + Here is the \c createColorToolButtonIcon() function: + + \snippet graphicsview/diagramscene/mainwindow.cpp 31 + + This function is used to create the QIcon of the \c + fillColorToolButton, \c fontColorToolButton, and \c + lineColorToolButton. The \a imageFile string is either the text, + flood-fill, or line symbol that is used for the buttons. Beneath + the image we draw a filled rectangle using \a color. + + Here is the \c createColorIcon() function: + + \snippet graphicsview/diagramscene/mainwindow.cpp 32 + + This function creates an icon with a filled rectangle in the + color of \a color. It is used for creating icons for the color + menus in the \c fillColorToolButton, \c fontColorToolButton, and + \c lineColorToolButton. + + Here is the \c backgroundButtonGroupClicked() slot: + + \snippet graphicsview/diagramscene/mainwindow.cpp 1 + + In this function we set the QBrush that is used to draw the + background of the diagramscene. The background can be a grid of + squares of blue, gray, or white tiles, or no grid at all. We have + \l{QPixmap}s of the tiles from png files that we create the brush + with. + + When one of the buttons in the background tabbed widget item is + clicked we change the brush; we find out which button it is by + checking its text. + + Here is the implementation of \c buttonGroupClicked(): + + \snippet graphicsview/diagramscene/mainwindow.cpp 2 + + This slot is called when a button in \c buttonGroup is checked. + When a button is checked the user can click on the graphics view + and a \c DiagramItem of the selected type will be inserted into + the \c DiagramScene. We must loop through the buttons in the group + to uncheck other buttons as only one button is allowed to be + checked at a time. + + \c QButtonGroup assigns an id to each button. We have set the id + of each button to the diagram type, as given by DiagramItem::DiagramType + that will be inserted into the scene when it is clicked. We can + then use the button id when we set the diagram type with + \c setItemType(). In the case of text we assigned an id that has a + value that is not in the DiagramType enum. + + Here is the implementation of \c deleteItem(): + + \snippet graphicsview/diagramscene/mainwindow.cpp 3 + + This slot deletes the selected item, if any, from the scene. It + deletes the arrows first in order to avoid to delete them twice. If + the item to be deleted is a \c DiagramItem, we also need to delete + arrows connected to it; we don't want arrows in the scene that + aren't connected to items in both ends. + + This is the implementation of pointerGroupClicked(): + + \snippet graphicsview/diagramscene/mainwindow.cpp 4 + + The \c pointerTypeGroup decides whether the scene is in ItemMove + or InsertLine mode. This button group is exclusive, i.e., only + one button is checked at any time. As with the \c buttonGroup above + we have assigned an id to the buttons that matches values of the + DiagramScene::Mode enum, so that we can use the id to set the + correct mode. + + Here is the \c bringToFront() slot: + + \snippet graphicsview/diagramscene/mainwindow.cpp 5 + + Several items may collide, i.e., overlap, with each other in + the scene. This slot is called when the user requests that an + item should be placed on top of the items it collides with. + \l{QGraphicsItem}{QGrapicsItems} have a z-value that decides the + order in which items are stacked in the scene; you can think of it + as the z-axis in a 3D coordinate system. When items collide the + items with higher z-values will be drawn on top of items with + lower values. When we bring an item to the front we can loop + through the items it collides with and set a z-value that is + higher than all of them. + + Here is the \c sendToBack() slot: + + \snippet graphicsview/diagramscene/mainwindow.cpp 6 + + This slot works in the same way as \c bringToFront() described + above, but sets a z-value that is lower than items the item that + should be send to the back collides with. + + This is the implementation of \c itemInserted(): + + \snippet graphicsview/diagramscene/mainwindow.cpp 7 + + This slot is called from the \c DiagramScene when an item has been + added to the scene. We set the mode of the scene back to the mode + before the item was inserted, which is ItemMove or InsertText + depending on which button is checked in the \c pointerTypeGroup. + We must also uncheck the button in the in the \c buttonGroup. + + Here is the implementation of \c textInserted(): + + \snippet graphicsview/diagramscene/mainwindow.cpp 8 + + We simply set the mode of the scene back to the mode it had before + the text was inserted. + + Here is the \c currentFontChanged() slot: + + \snippet graphicsview/diagramscene/mainwindow.cpp 9 + + When the user requests a font change, by using one of the + widgets in the \c fontToolBar, we create a new QFont object and + set its properties to match the state of the widgets. This is done + in \c handleFontChange(), so we simply call that slot. + + Here is the \c fontSizeChanged() slot: + + \snippet graphicsview/diagramscene/mainwindow.cpp 10 + + When the user requests a font change, by using one of the + widgets in the \c fontToolBar, we create a new QFont object and + set its properties to match the state of the widgets. This is done + in \c handleFontChange(), so we simply call that slot. + + Here is the implementation of \c sceneScaleChanged(): + + \snippet graphicsview/diagramscene/mainwindow.cpp 11 + + The user can increase or decrease the scale, with the \c + sceneScaleCombo, the scene is drawn in. + It is not the scene itself that changes its scale, but only the + view. + + Here is the \c textColorChanged() slot: + + \snippet graphicsview/diagramscene/mainwindow.cpp 12 + + This slot is called when an item in the drop-down menu of the \c + fontColorToolButton is pressed. We need to change the icon on + the button to the color of the selected QAction. We keep a pointer + to the selected action in \c textAction. It is in \c + textButtonTriggered() we change the text color to the color of \c + textAction, so we call that slot. + + Here is the \c itemColorChanged() implementation: + + \snippet graphicsview/diagramscene/mainwindow.cpp 13 + + This slot handles requests for changing the color of \c + DiagramItems in the same manner as \c textColorChanged() does for + \c DiagramTextItems. + + Here is the implementation of \c lineColorChanged(): + + \snippet graphicsview/diagramscene/mainwindow.cpp 14 + + This slot handles requests for changing the color of \c Arrows in + the same manner that \c textColorChanged() does it for \c + DiagramTextItems. + + Here is the \c textButtonTriggered() slot: + + \snippet graphicsview/diagramscene/mainwindow.cpp 15 + + \c textAction points to the QAction of the currently selected menu item + in the \c fontColorToolButton's color drop-down menu. We have set + the data of the action to the QColor the action represents, so we + can simply fetch this when we set the color of text with \c + setTextColor(). + + Here is the \c fillButtonTriggered() slot: + + \snippet graphicsview/diagramscene/mainwindow.cpp 16 + + \c fillAction points to the selected menu item in the drop-down + menu of \c fillColorToolButton(). We can therefore use the data of + this action when we set the item color with \c setItemColor(). + + Here is the \c lineButtonTriggered() slot: + + \snippet graphicsview/diagramscene/mainwindow.cpp 17 + + \c lineAction point to the selected item in the drop-down menu of + \c lineColorToolButton. We use its data when we set the arrow + color with \c setLineColor(). + + Here is the \c handleFontChange() function: + + \snippet graphicsview/diagramscene/mainwindow.cpp 18 + + \c handleFontChange() is called when any of the widgets that show + font properties changes. We create a new QFont object and set its + properties based on the widgets. We then call the \c setFont() + function of \c DiagramScene; it is the scene that set the font of + the \c DiagramTextItems it manages. + + Here is the \c itemSelected() slot: + + \snippet graphicsview/diagramscene/mainwindow.cpp 19 + + This slot is called when an item in the \c DiagramScene is + selected. In the case of this example it is only text items that + emit signals when they are selected, so we do not need to check + what kind of graphics \a item is. + + We set the state of the widgets to match the properties of the + font of the selected text item. + + This is the \c about() slot: + + \snippet graphicsview/diagramscene/mainwindow.cpp 20 + + This slot displays an about box for the example when the user + selects the about menu item from the help menu. + + \section1 DiagramScene Class Definition + + The \c DiagramScene class inherits QGraphicsScene and adds + functionality to handle \c DiagramItems, \c Arrows, and \c + DiagramTextItems in addition to the items handled by its super + class. + + + \snippet graphicsview/diagramscene/diagramscene.h 0 + + In the \c DiagramScene a mouse click can give three different + actions: the item under the mouse can be moved, an item may be + inserted, or an arrow may be connected between to diagram items. + Which action a mouse click has depends on the mode, given by the + Mode enum, the scene is in. The mode is set with the \c setMode() + function. + + The scene also sets the color of its items and the font of its + text items. The colors and font used by the scene can be set with + the \c setLineColor(), \c setTextColor(), \c setItemColor() and \c + setFont() functions. The type of \c DiagramItem, given by the + DiagramItem::DiagramType function, to be created when an item is + inserted is set with the \c setItemType() slot. + + The \c MainWindow and \c DiagramScene share responsibility for + the examples functionality. \c MainWindow handles the following + tasks: the deletion of items, text, and arrows; moving diagram + items to the back and front; and setting the scale of the scene. + + \section1 DiagramScene Class Implementation + + + We start with the constructor: + + \snippet graphicsview/diagramscene/diagramscene.cpp 0 + + The scene uses \c myItemMenu to set the context menu when it + creates \c DiagramItems. We set the default mode to \c + DiagramScene::MoveItem as this gives the default behavior of + QGraphicsScene. + + Here is the \c setLineColor() function: + + \snippet graphicsview/diagramscene/diagramscene.cpp 1 + + The \c isItemChange function returns true if an \c Arrow item is + selected in the scene in which case we want to change its color. + When the \c DiagramScene creates and adds new arrows to the scene + it will also use the new \a color. + + Here is the \c setTextColor() function: + + \snippet graphicsview/diagramscene/diagramscene.cpp 2 + + This function sets the color of \c DiagramTextItems equal to the + way \c setLineColor() sets the color of \c Arrows. + + Here is the \c setItemColor() function: + + \snippet graphicsview/diagramscene/diagramscene.cpp 3 + + This function sets the color the scene will use when creating + \c DiagramItems. It also changes the color of a selected \c + DiagramItem. + + This is the implementation of \c setFont(): + + \snippet graphicsview/diagramscene/diagramscene.cpp 4 + + Set the font to use for new and selected, if a text item is + selected, \c DiagramTextItems. + + This is the implementation of \c editorLostFocus() slot: + + \snippet graphicsview/diagramscene/diagramscene.cpp 5 + + \c DiagramTextItems emit a signal when they loose focus, which is + connected to this slot. We remove the item if it has no text. + If not, we would leak memory and confuse the user as the items + will be edited when pressed on by the mouse. + + The \c mousePressEvent() function handles mouse press event's + different depending on which mode the \c DiagramScene is in. We + examine its implementation for each mode: + + \snippet graphicsview/diagramscene/diagramscene.cpp 6 + + We simply create a new \c DiagramItem and add it to the scene at + the position the mouse was pressed. Note that the origin of its + local coordinate system will be under the mouse pointer position. + + \snippet graphicsview/diagramscene/diagramscene.cpp 7 + + The user adds \c Arrows to the scene by stretching a line between + the items the arrow should connect. The start of the line is fixed + in the place the user clicked the mouse and the end follows the + mouse pointer as long as the button is held down. When the user + releases the mouse button an \c Arrow will be added to the scene + if there is a \c DiagramItem under the start and end of the line. + We will see how this is implemented later; here we simply add the + line. + + \snippet graphicsview/diagramscene/diagramscene.cpp 8 + + The \c DiagramTextItem is editable when the + Qt::TextEditorInteraction flag is set, else it is movable by the + mouse. We always want the text to be drawn on top of the other + items in the scene, so we set the value to a number higher + than other items in the scene. + + \snippet graphicsview/diagramscene/diagramscene.cpp 9 + + We are in MoveItem mode if we get to the default switch; we + can then call the QGraphicsScene implementation, which + handles movement of items with the mouse. We make this call even + if we are in another mode making it possible to add an item and + then keep the mouse button pressed down and start moving + the item. In the case of text items, this is not possible as they + do not propagate mouse events when they are editable. + + This is the \c mouseMoveEvent() function: + + \snippet graphicsview/diagramscene/diagramscene.cpp 10 + + We must draw the line if we are in InsertMode and the mouse button + is pressed down (the line is not 0). As discussed in \c + mousePressEvent() the line is drawn from the position the mouse + was pressed to the current position of the mouse. + + If we are in MoveItem mode, we call the QGraphicsScene + implementation, which handles movement of items. + + In the \c mouseReleaseEvent() function we need to check if an arrow + should be added to the scene: + + \snippet graphicsview/diagramscene/diagramscene.cpp 11 + + First we need to get the items (if any) under the line's start + and end points. The line itself is the first item at these points, + so we remove it from the lists. As a precaution, we check if the + lists are empty, but this should never happen. + + \snippet graphicsview/diagramscene/diagramscene.cpp 12 + + Now we check if there are two different \c DiagramItems under + the lines start and end points. If there are we can create an \c + Arrow with the two items. The arrow is then added to each item and + finally the scene. The arrow must be updated to adjust its start + and end points to the items. We set the z-value of the arrow to + -1000.0 because we always want it to be drawn under the items. + + \snippet graphicsview/diagramscene/diagramscene.cpp 13 + + Here is the \c isItemChange() function: + + \snippet graphicsview/diagramscene/diagramscene.cpp 14 + + The scene has single selection, i.e., only one item can be + selected at any given time. The foreach will then loop one time + with the selected item or none if no item is selected. \c + isItemChange() is used to check whether a selected item exists + and also is of the specified diagram \a type. + + \section1 DiagramItem Class Definition + + + \snippet graphicsview/diagramscene/diagramitem.h 0 + + The \c DiagramItem represents a flowchart shape in the \c + DiagramScene. It inherits QGraphicsPolygonItem and has a polygon + for each shape. The enum DiagramType has a value for each of the + flowchart shapes. + + The class has a list of the arrows that are connected to it. + This is necessary because only the item knows when it is being + moved (with the \c itemChanged() function) at which time the + arrows must be updated. The item can also draw itself onto a + QPixmap with the \c image() function. This is used for the tool + buttons in \c MainWindow, see \c createColorToolButtonIcon() in + \c MainWindow. + + The Type enum is a unique identifier of the class. It is used by + \c qgraphicsitem_cast(), which does dynamic casts of graphics + items. The UserType constant is the minimum value a custom + graphics item type can be. + + \section1 DiagramItem Class Implementation + + + We start with a look at the constructor: + + \snippet graphicsview/diagramscene/diagramitem.cpp 0 + + In the constructor we create the items polygon according to + \a diagramType. \l{QGraphicsItem}s are not movable or selectable + by default, so we must set these properties. + + Here is the \c removeArrow() function: + + \snippet graphicsview/diagramscene/diagramitem.cpp 1 + + \c removeArrow() is used to remove \c Arrow items when they + or \c DiagramItems they are connected to are removed from the + scene. + + Here is the \c removeArrows() function: + + \snippet graphicsview/diagramscene/diagramitem.cpp 2 + + This function is called when the item is removed from the scene + and removes all arrows that are connected to this item. The arrow + must be removed from the \c arrows list of both its start and end + item. + + Here is the \c addArrow() function: + + \snippet graphicsview/diagramscene/diagramitem.cpp 3 + + This function simply adds the \a arrow to the items \c arrows list. + + Here is the \c image() function: + + \snippet graphicsview/diagramscene/diagramitem.cpp 4 + + This function draws the polygon of the item onto a QPixmap. In + this example we use this to create icons for the tool buttons in + the tool box. + + Here is the \c contextMenuEvent() function: + + \snippet graphicsview/diagramscene/diagramitem.cpp 5 + + We show the context menu. As right mouse clicks, which shows the + menu, don't select items by default we set the item selected with + \l{QGraphicsItem::}{setSelected()}. This is necessary since an + item must be selected to change its elevation with the + \c bringToFront and \c sendToBack actions. + + This is the implementation of \c itemChange(): + + \snippet graphicsview/diagramscene/diagramitem.cpp 6 + + If the item has moved, we need to update the positions of the + arrows connected to it. The implementation of QGraphicsItem does + nothing, so we just return \a value. + + \section1 DiagramTextItem Class Definition + + The \c TextDiagramItem class inherits QGraphicsTextItem and + adds the possibility to move editable text items. Editable + QGraphicsTextItems are designed to be fixed in place and editing + starts when the user single clicks on the item. With \c + DiagramTextItem the editing starts with a double click leaving + single click available to interact with and move it. + + \snippet graphicsview/diagramscene/diagramtextitem.h 0 + + We use \c itemChange() and \c focusOutEvent() to notify the + \c DiagramScene when the text item loses focus and gets selected. + + We reimplement the functions that handle mouse events to make it + possible to alter the mouse behavior of QGraphicsTextItem. + + \section1 DiagramTextItem Implementation + + We start with the constructor: + + \snippet graphicsview/diagramscene/diagramtextitem.cpp 0 + + We simply set the item movable and selectable, as these flags are + off by default. + + Here is the \c itemChange() function: + + \snippet graphicsview/diagramscene/diagramtextitem.cpp 1 + + When the item is selected we emit the selectedChanged signal. The + \c MainWindow uses this signal to update the widgets that display + font properties to the font of the selected text item. + + Here is the \c focusOutEvent() function: + + \snippet graphicsview/diagramscene/diagramtextitem.cpp 2 + + \c DiagramScene uses the signal emitted when the text item looses + focus to remove the item if it is empty, i.e., it contains no + text. + + This is the implementation of \c mouseDoubleClickEvent(): + + \snippet graphicsview/diagramscene/diagramtextitem.cpp 5 + + When we receive a double click event, we make the item editable by calling + QGraphicsTextItem::setTextInteractionFlags(). We then forward the + double-click to the item itself. + + \section1 Arrow Class Definition + + The \c Arrow class is a graphics item that connects two \c + DiagramItems. It draws an arrow head to one of the items. To + achieve this the item needs to paint itself and also re implement + methods used by the graphics scene to check for collisions and + selections. The class inherits QGraphicsLine item, and draws the + arrowhead and moves with the items it connects. + + \snippet graphicsview/diagramscene/arrow.h 0 + + The item's color can be set with \c setColor(). + + \c boundingRect() and \c shape() are reimplemented + from QGraphicsLineItem and are used by the scene + to check for collisions and selections. + + Calling \c updatePosition() causes the arrow to recalculate its + position and arrow head angle. \c paint() is reimplemented so that + we can paint an arrow rather than just a line between items. + + \c myStartItem and \c myEndItem are the diagram items that the + arrow connects. The arrow is drawn with its head to the end item. + \c arrowHead is a polygon with three vertices's we use to draw the + arrow head. + + \section1 Arrow Class Implementation + + The constructor of the \c Arrow class looks like this: + + \snippet graphicsview/diagramscene/arrow.cpp 0 + + We set the start and end diagram items of the arrow. The arrow + head will be drawn where the line intersects the end item. + + Here is the \c boundingRect() function: + + \snippet graphicsview/diagramscene/arrow.cpp 1 + + We need to reimplement this function because the arrow is + larger than the bounding rectangle of the QGraphicsLineItem. The + graphics scene uses the bounding rectangle to know which regions + of the scene to update. + + Here is the \c shape() function: + + \snippet graphicsview/diagramscene/arrow.cpp 2 + + The shape function returns a QPainterPath that is the exact + shape of the item. The QGraphicsLineItem::shape() returns a path + with a line drawn with the current pen, so we only need to add + the arrow head. This function is used to check for collisions and + selections with the mouse. + + Here is the \c updatePosition() slot: + + \snippet graphicsview/diagramscene/arrow.cpp 3 + + This slot updates the arrow by setting the start and end + points of its line to the center of the items it connects. + + Here is the \c paint() function: + + \snippet graphicsview/diagramscene/arrow.cpp 4 + + If the start and end items collide we do not draw the arrow; the + algorithm we use to find the point the arrow should be drawn at + may fail if the items collide. + + We first set the pen and brush we will use for drawing the arrow. + + \snippet graphicsview/diagramscene/arrow.cpp 5 + + We then need to find the position at which to draw the + arrowhead. The head should be drawn where the line and the end + item intersects. This is done by taking the line between each + point in the polygon and check if it intersects with the line of + the arrow. Since the line start and end points are set to the + center of the items the arrow line should intersect one and only + one of the lines of the polygon. Note that the points in the + polygon are relative to the local coordinate system of the item. + We must therefore add the position of the end item to make the + coordinates relative to the scene. + + \snippet graphicsview/diagramscene/arrow.cpp 6 + + We calculate the angle between the x-axis and the line of the + arrow. We need to turn the arrow head to this angle so that it + follows the direction of the arrow. If the angle is negative we + must turn the direction of the arrow. + + We can then calculate the three points of the arrow head polygon. + One of the points is the end of the line, which now is the + intersection between the arrow line and the end polygon. Then we + clear the \c arrowHead polygon from the previous calculated arrow + head and set these new points. + + \snippet graphicsview/diagramscene/arrow.cpp 7 + + If the line is selected, we draw two dotted lines that are + parallel with the line of the arrow. We do not use the default + implementation, which uses \l{QGraphicsItem::}{boundingRect()} + because the QRect bounding rectangle is considerably larger than + the line. +*/ diff --git a/examples/widgets/doc/src/digitalclock.qdoc b/examples/widgets/doc/src/digitalclock.qdoc new file mode 100644 index 0000000000..92e8003205 --- /dev/null +++ b/examples/widgets/doc/src/digitalclock.qdoc @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** 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/digitalclock + \title Digital Clock Example + + The Digital Clock example shows how to use QLCDNumber to display a + number with LCD-like digits. + + \image digitalclock-example.png Screenshot of the Digital Clock example + + This example also demonstrates how QTimer can be used to update a widget + at regular intervals. + + \section1 DigitalClock Class Definition + + The \c DigitalClock class provides a clock widget showing the time with + hours and minutes separated by a blinking colon. We subclass QLCDNumber + and implement a private slot called \c showTime() to update the clock + display: + + \snippet widgets/digitalclock/digitalclock.h 0 + + \section1 DigitalClock Class Implementation + + \snippet widgets/digitalclock/digitalclock.cpp 0 + + In the constructor, we first change the look of the LCD numbers. The + QLCDNumber::Filled style produces raised segments filled with the + foreground color (typically black). We also set up a one-second timer + to keep track of the current time, and we connect + its \l{QTimer::timeout()}{timeout()} signal to the private \c showTime() slot + so that the display is updated every second. Then, we + call the \c showTime() slot; without this call, there would be a one-second + delay at startup before the time is shown. + + \snippet widgets/digitalclock/digitalclock.cpp 1 + \snippet widgets/digitalclock/digitalclock.cpp 2 + + The \c showTime() slot is called whenever the clock display needs + to be updated. + + The current time is converted into a string with the format "hh:mm". + When QTime::second() is a even number, the colon in the string is + replaced with a space. This makes the colon appear and vanish every + other second. + + Finally, we call QLCDNumber::display() to update the widget. +*/ diff --git a/examples/widgets/doc/src/dirview.qdoc b/examples/widgets/doc/src/dirview.qdoc new file mode 100644 index 0000000000..a4b799678a --- /dev/null +++ b/examples/widgets/doc/src/dirview.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 itemviews/dirview + \title Dir View Example + + The Dir View example shows a tree view onto the local filing system. It uses the + QDirModel class to provide file and directory information. + + \image dirview-example.png +*/ diff --git a/examples/widgets/doc/src/dockwidgets.qdoc b/examples/widgets/doc/src/dockwidgets.qdoc new file mode 100644 index 0000000000..12f18a538f --- /dev/null +++ b/examples/widgets/doc/src/dockwidgets.qdoc @@ -0,0 +1,163 @@ +/**************************************************************************** +** +** 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 mainwindows/dockwidgets + \title Dock Widgets Example + + The Dock Widgets example shows how to add dock windows to an + application. It also shows how to use Qt's rich text engine. + + \image dockwidgets-example.png Screenshot of the Dock Widgets example + + The application presents a simple business letter template, and has + a list of customer names and addresses and a list of standard + phrases in two dock windows. The user can click a customer to have + their name and address inserted into the template, and click one or + more of the standard phrases. Errors can be corrected by clicking + the Undo button. Once the letter has been prepared it can be printed + or saved as HTML. + + \section1 MainWindow Class Definition + + Here's the class definition: + + \snippet mainwindows/dockwidgets/mainwindow.h 0 + + We will now review each function in turn. + + \section1 MainWindow Class Implementation + + \snippet mainwindows/dockwidgets/mainwindow.cpp 0 + + We start by including \c , a header file that contains the + definition of all classes in the \l QtCore and \l QtGui + libraries. This saves us from having to include + every class individually and is especially convenient if we add new + widgets. We also include \c mainwindow.h. + + \snippet mainwindows/dockwidgets/mainwindow.cpp 1 + + In the constructor, we start by creating a QTextEdit widget. Then we call + QMainWindow::setCentralWidget(). This function passes ownership of + the QTextEdit to the \c MainWindow and tells the \c MainWindow that + the QTextEdit will occupy the \c MainWindow's central area. + + Then we call \c createActions(), \c createMenus(), \c + createToolBars(), \c createStatusBar(), and \c createDockWindows() + to set up the user interface. Finally we call \c setWindowTitle() to + give the application a title, and \c newLetter() to create a new + letter template. + + We won't quote the \c createActions(), \c createMenus(), \c + createToolBars(), and \c createStatusBar() functions since they + follow the same pattern as all the other Qt examples. + + \snippet mainwindows/dockwidgets/mainwindow.cpp 9 + + We create the customers dock window first, and in addition to a + window title, we also pass it a \c this pointer so that it becomes a + child of \c MainWindow. Normally we don't have to pass a parent + because widgets are parented automatically when they are laid out: + but dock windows aren't laid out using layouts. + + We've chosen to restrict the customers dock window to the left and + right dock areas. (So the user cannot drag the dock window to the + top or bottom dock areas.) The user can drag the dock window out of + the dock areas entirely so that it becomes a free floating window. + We can change this (and whether the dock window is moveable or + closable) using QDockWidget::setFeatures(). + + Once we've created the dock window we create a list widget with the + dock window as parent, then we populate the list and make it the + dock window's widget. Finally we add the dock widget to the \c + MainWindow using \c addDockWidget(), choosing to put it in the right + dock area. + + We undertake a similar process for the paragraphs dock window, + except that we don't restrict which dock areas it can be dragged to. + + Finally we set up the signal-slot connections. If the user clicks a + customer or a paragraph their \c currentTextChanged() signal will be + emitted and we connect these to \c insertCustomer() and + addParagraph() passing the text that was clicked. + + We briefly discuss the rest of the implementation, but have now + covered everything relating to dock windows. + + \snippet mainwindows/dockwidgets/mainwindow.cpp 2 + + In this function we clear the QTextEdit so that it is empty. Next we + create a QTextCursor on the QTextEdit. We move the cursor to the + start of the document and create and format a frame. We then create + some character formats and a table format. We insert a table into + the document and insert the company's name and address into a table + using the table and character formats we created earlier. Then we + insert the skeleton of the letter including two markers \c NAME and + \c ADDRESS. We will also use the \c{Yours sincerely,} text as a marker. + + \snippet mainwindows/dockwidgets/mainwindow.cpp 6 + + If the user clicks a customer we split the customer details into + pieces. We then look for the \c NAME marker using the \c find() + function. This function selects the text it finds, so when we call + \c insertText() with the customer's name the name replaces the marker. + We then look for the \c ADDRESS marker and replace it with each line + of the customer's address. Notice that we wrapped all the insertions + between a \c beginEditBlock() and \c endEditBlock() pair. This means + that the entire name and address insertion is treated as a single + operation by the QTextEdit, so a single undo will revert all the + insertions. + + \snippet mainwindows/dockwidgets/mainwindow.cpp 7 + + This function works in a similar way to \c insertCustomer(). First + we look for the marker, in this case, \c {Yours sincerely,}, and then + replace it with the standard paragraph that the user clicked. Again + we use a \c beginEditBlock() ... \c endEditBlock() pair so that the + insertion can be undone as a single operation. + + \snippet mainwindows/dockwidgets/mainwindow.cpp 3 + + Qt's QTextDocument class makes printing documents easy. We simply + take the QTextEdit's QTextDocument, set up the printer and print the + document. + + \snippet mainwindows/dockwidgets/mainwindow.cpp 4 + + QTextEdit can output its contents in HTML format, so we prompt the + user for the name of an HTML file and if they provide one we simply + write the QTextEdit's contents in HTML format to the file. + + \snippet mainwindows/dockwidgets/mainwindow.cpp 5 + + If the focus is in the QTextEdit, pressing \uicontrol Ctrl+Z undoes as + expected. But for the user's convenience we provide an + application-wide undo function that simply calls the QTextEdit's + undo: this means that the user can undo regardless of where the + focus is in the application. +*/ diff --git a/examples/widgets/doc/src/draganddroppuzzle.qdoc b/examples/widgets/doc/src/draganddroppuzzle.qdoc new file mode 100644 index 0000000000..2c90998dc1 --- /dev/null +++ b/examples/widgets/doc/src/draganddroppuzzle.qdoc @@ -0,0 +1,42 @@ +/**************************************************************************** +** +** 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/puzzle + \title Drag and Drop Puzzle Example + + The Drag and Drop Puzzle example demonstrates a way of using the drag and drop system with + item view widgets. + + \image draganddroppuzzle-example.png + + This example is an implementation of a simple jigsaw puzzle game using Qt's + drag and drop API. + The \l{Item Views Puzzle Example}{Item View Puzzle} example shows + many of the same features, but takes an alternative approach that uses Qt's + model/view framework to manage drag and drop operations. +*/ diff --git a/examples/widgets/doc/src/dragdroprobot.qdoc b/examples/widgets/doc/src/dragdroprobot.qdoc new file mode 100644 index 0000000000..60bd4eb4d8 --- /dev/null +++ b/examples/widgets/doc/src/dragdroprobot.qdoc @@ -0,0 +1,365 @@ +/**************************************************************************** +** +** 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 graphicsview/dragdroprobot + \title Drag and Drop Robot Example + + The Drag and Drop Robot example shows how to implement Drag and Drop in a + QGraphicsItem subclass, as well as how to animate items using Qt's + \l{Animation Framework}. + + \image dragdroprobot-example.png + + Graphics View provides the QGraphicsScene class for managing and + interacting with a large number of custom-made 2D graphical items derived + from the QGraphicsItem class, and a QGraphicsView widget for visualizing + the items, with support for zooming and rotation. + + This example consists of a \c Robot class, a \c ColorItem class, and a main + function: the \c Robot class describes a simple robot consisting of several + \c RobotPart derived limbs, including \c RobotHead and \c RobotLimb, the \c + ColorItem class provides a draggable colored ellipse, and the \c main() + function provides the main application window. + + We will first review the \c Robot class to see how to assemble the + different parts so that they can be individually rotated and animated using + QPropertyAnimation, and we will then review the \c ColorItem class to + demonstrate how to implement Drag and Drop between items. Finally we will + review the main() function to see how we can put all the pieces together, + to form the final application. + + \section1 Robot Class Definition + + The robot consists of three main classes: the \c RobotHead, the \c + RobotTorso, and the \c RobotLimb, which is used for the upper and lower + arms and legs. All parts derive from the \c RobotPart class, which in turn + inherits \c QGraphicsObject. The \c Robot class itself has no visual + appearance and serves only as a root node for the robot. + + Let's start with the \c RobotPart class declaration. + + \snippet graphicsview/dragdroprobot/robot.h 0 + + This base class inherits QGraphicsObject. QGraphicsObject provides signals + and slots through inheriting QObject, and it also declares QGraphicsItem's + properties using Q_PROPERTY, which makes the properties accessible for + QPropertyAnimation. + + RobotPart also implements the three most important event handlers for + accepting drop events: + \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()}, + \l{QGraphicsItem::dragLeaveEvent()}{dragLeaveEvent()}, and + \l{QGraphicsItem::dropEvent()}{dropEvent()}. + + The color is stored as a member variable, along with the \c dragOver + variable, which we will use later to indicate visually that the limb can + accept colors that are is dragged onto it. + + \snippet graphicsview/dragdroprobot/robot.cpp 0 + + \c RobotPart's constructor initializes the dragOver member and sets the + color to Qt::lightGray. In the constructor body we enable support for + accepting drop events by calling + \l{QGraphicsItem::setAcceptDrops()}{setAcceptDrops(true)}. + + The rest of this class's implementation is to support Drag and Drop. + + \snippet graphicsview/dragdroprobot/robot.cpp 1 + + The \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()} handler is called + when a Drag and Drop element is dragged into the robot part's area. + + The handler implementation determines whether or not this item as a whole + can accept the mime data assiciated with the incoming drag object. \c + RobotPart provides a base behavior for all parts that accepts color drops. + So if the incoming drag object contains a color, the event is accepted, we + set \c dragOver to \c true and call update() to help provide positive + visual feedback to the user; otherwise the event is ignored, which in turn + allows the event to propagate to parent elements. + + \snippet graphicsview/dragdroprobot/robot.cpp 2 + + The \l{QGraphicsItem::dragLeaveEvent()}{dragLeaveEvent()} handler is called + when a Drag and Drop element is dragged away from the robot part's area. + Our implementation simply resets \e dragOver to false and calls + \l{QGraphicsItem::update()}{update()} to help provide visual feedback that + the drag has left this item. + + \snippet graphicsview/dragdroprobot/robot.cpp 3 + + The \l{QGraphicsItem::dropEvent()}{dropEvent()} handler is called when a + Drag and Drop element is dropped onto an item (i.e., when the mouse button + is released over the item while dragging). + + We reset \c dragOver to false, assign the item's new color, and call + \l{QGraphicsItem::update()}{update()}. + + The declaration and implementation of \c RobotHead, \c RobotTorso, and \c + RobotLimb are practically identical. We will review \c RobotHead in detail, + as this class has one minor difference, and leave the other classes as an + exercise for the reader. + + \snippet graphicsview/dragdroprobot/robot.h 1 + + The \c RobotHead class inherits \c RobotPart and provides the necessary + implementations of \l{QGraphicsItem::boundingRect()}{boundingRect()} and + \l{QGraphicsItem::paint()}{paint()}. It also reimplements + \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()} and dropEvent() to + provide special handling of image drops. + + The class contains a private pixmap member that we can use to implement + support for accepting image drops. + + \snippet graphicsview/dragdroprobot/robot.cpp 4 + + \c RobotHead has a rather plain constructor that simply forwards to + \c RobotPart's constructor. + + \snippet graphicsview/dragdroprobot/robot.cpp 5 + + The \l{QGraphicsItem::boundingRect()}{boundingRect()} reimplementation + returns the extents for the head. Because we want the center of rotation to + be the bottom center of the item, we have chosen a bounding rectangle that + starts at (-15, -50) and extends to 30 units wide and 50 units tall. When + rotating the head, the "neck" will stay still while the top of the head + tilts from side to side. + + \snippet graphicsview/dragdroprobot/robot.cpp 6 + + In \l{QGraphicsItem::paint()}{paint()} we draw the actual head. The + implementation is split into two sections; if an image has been dropped + onto the head, we draw the image, otherwise we draw a round rectangular + robot head with simple vector graphics. + + For performance reasons, depending on the complexity of what is painted, it + can often be faster to draw the head as an image rather than using a + sequence of vector operations. + + \snippet graphicsview/dragdroprobot/robot.cpp 7 + + The robot head can accept image drops. In order to support this, its + reimplementation of \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()} + checks if the drag object contains image data, and if it does, then the + event is accepted. Otherwise we fall back to the base \c RobotPart + implementation. + + \snippet graphicsview/dragdroprobot/robot.cpp 8 + + To follow up on image support, we must also implement + \l{QGraphicsItem::dropEvent()}{dropEvent()}. We check if the drag object + contains image data, and if it does, we store this data as a member pixmap + and call \l{QGraphicsItem::update()}{update()}. This pixmap is used inside + the \l{QGraphicsItem::paint()}{paint()} implementation that we reviewed + before. + + \c RobotTorso and \c RobotLimb are similar to \c RobotHead, so let's + skip directly to the \c Robot class. + + \snippet graphicsview/dragdroprobot/robot.h 4 + + The \c Robot class also inherits \c RobotPart, and like the other parts it + also implements \l{QGraphicsItem::boundingRect()}{boundingRect()} and + \l{QGraphicsItem::paint()}{paint()}. It provides a rather special + implementation, though: + + \snippet graphicsview/dragdroprobot/robot.cpp 9 + + Because the \c Robot class is only used as a base node for the rest of the + robot, it has no visual representation. Its + \l{QGraphicsItem::boundingRect()}{boundingRect()} implementation can + therefore return a null QRectF, and its paint() function does nothing. + + \snippet graphicsview/dragdroprobot/robot.cpp 10 + + The constructor starts by setting the flag + \l{QGraphicsItem::ItemHasNoContents}{ItemHasNoContents}, which is a minor + optimization for items that have no visual appearance. + + We then construct all the robot parts (head, torso, and upper/lower arms + and legs). The stacking order is very important, and we use the + parent-child hierarchy to ensure the elements rotate and move properly. We + construct the torso first, as this is the root element. We then construct + the head and pass the torso to \c HeadItem's constructor. This will make + the head a child of the torso; if you rotate the torso, the head will + follow. The same pattern is applied to the rest of the limbs. + + \snippet graphicsview/dragdroprobot/robot.cpp 11 + + Each robot part is carefully positioned. For example, the upper left arm is + moved precisely to the top-left area of the torso, and the upper right arm + is moved to the top-right area. + + \snippet graphicsview/dragdroprobot/robot.cpp 12 + + The next section creates all animation objects. This snippet shows the two + animations that operate on the head's scale and rotation. The two + QPropertyAnimation instances simply set the object, property, and + respective start and end values. + + All animations are controlled by one top-level parallel animation group. + The scale and rotation animations are added to this group. + + The rest of the animations are defined in a similar way. + + \snippet graphicsview/dragdroprobot/robot.cpp 13 + + Finally we set an easing curve and duration on each animation, ensure the + toplevel animation group loops forever, and start the toplevel animation. + + \section1 ColorItem Class Definition + + The \c ColorItem class represents a circular item that can be pressed to + drag colors onto robot parts. + + \snippet graphicsview/dragdroprobot/coloritem.h 0 + + This class is very simple. It does not use animations, and has no need for + properties nor signals and slots, so to save resources, it's most natural + that it inherits QGraphicsItem (as opposed to QGraphicsObject). + + It declares the mandatory \l{QGraphicsItem::boundingRect()}{boundingRect()} + and \l{QGraphicsItem::paint()}{paint()} functions, and adds + reimplementations of + \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()}, + \l{QGraphicsItem::mouseMoveEvent()}{mouseMoveEvent()}, and + \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()}. It contains a + single private color member. + + Let's take a look at its implementation. + + \snippet graphicsview/dragdroprobot/coloritem.cpp 0 + + \c ColorItem's constructor assigns an opaque random color to its color + member by making use of qrand(). For improved usability, it assigns a + tooltip that provides a useful hint to the user, and it also sets a + suitable cursor. This ensures that the cursor will chance to + Qt::OpenHandCursor when the mouse pointer hovers over the item. + + Finally, we call + \l{QGraphicsItem::setAcceptedMouseButtons()}{setAcceptedMouseButtons()} to + ensure that this item can only process Qt::LeftButton. This simplifies the + mouse event handlers greatly, as we can always assume that only the left + mouse button is pressed and released. + + \snippet graphicsview/dragdroprobot/coloritem.cpp 1 + + The item's bounding rect is a fixed 30x30 units centered around the item's + origin (0, 0), and adjusted by 0.5 units in all directions to allow a + scalable pen to draw its outline. For a final visual touch the bounds + also compensate with a few units down and to the right to make room + for a simple dropshadow. + + \snippet graphicsview/dragdroprobot/coloritem.cpp 2 + + The \l{QGraphicsItem::paint()}{paint()} implementation draws an ellipse + with a 1-unit black outline, a plain color fill, and a dark gray + dropshadow. + + \snippet graphicsview/dragdroprobot/coloritem.cpp 3 + + The \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()} handler is + called when you press the mouse button inside the item's area. Our + implementation simply sets the cursor to Qt::ClosedHandCursor. + + \snippet graphicsview/dragdroprobot/coloritem.cpp 4 + + The \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()} handler is + called when you release the mouse button after having pressed it inside an + item's area. Our implementation sets the cursor back to Qt::OpenHandCursor. + The mouse press and release event handlers together provide useful visual + feedback to the user: when you move the mouse pointer over a \c CircleItem, + the cursor changes to an open hand. Pressing the item will show a closed + hand cursor. Releasing will restore to an open hand cursor again. + + \snippet graphicsview/dragdroprobot/coloritem.cpp 5 + + The \l{QGraphicsItem::mouseMoveEvent()}{mouseMoveEvent()} handler is called + when you move the mouse around after pressing the mouse button inside the + \c ColorItem's area. This implementation provides the most important piece + of logic for \c CircleItem: the code that starts and manages drags. + + The implementation starts by checking if the mouse has been dragged far + enough to eliminate mouse jitter noise. We only want to start a drag if the + mouse has been dragged farther than the application start drag distance. + + Continuing, we create a QDrag object, passing the event + \l{QGraphicsSceneEvent::widget()}{widget} (i.e., the QGraphicsView + viewport) to its constructor. Qt will ensure that this object is deleted at + the right time. We also create a QMimeData instance that can contain our + color or image data, and assign this to the drag object. + + \snippet graphicsview/dragdroprobot/coloritem.cpp 6 + + This snippet has a somewhat random outcome: once in a while, a special + image is assigned to the drag object's mime data. The pixmap is also + assiged as the drag object's pixmap. This will ensure that you can see the + image that is being dragged as a pixmap under the mouse cursor. + + \snippet graphicsview/dragdroprobot/coloritem.cpp 7 + + Otherwise, and this is the most common outcome, a simple color is assigned + to the drag object's mime data. We render this \c ColorItem into a new + pixmap to give the user visual feedback that the color is being "dragged". + + \snippet graphicsview/dragdroprobot/coloritem.cpp 8 + + Finally we execute the drag. QDrag::exec() will reenter the event loop, and + only exit if the drag has either been dropped, or canceled. In any case we + reset the cursor to Qt::OpenHandCursor. + + \section1 The main() Function + + Now that the \c Robot and \c ColorItem classes are complete, we can put all + the pieces together inside the main() function. + + \snippet graphicsview/dragdroprobot/main.cpp 0 + + We start off by constructing QApplication, and initializing the random + number generator. This ensures that the color items have different colors + every time the application starts. + + \snippet graphicsview/dragdroprobot/main.cpp 1 + + We construct a fixed size scene, and create 10 \c ColorItem instances + arranged in a circle. Each item is added to the scene. + + In the center of this circle we create one \c Robot instance. The + robot is scaled and moved up a few units. It is then added to the scene. + + \snippet graphicsview/dragdroprobot/main.cpp 2 + + Finally we create a QGraphicsView window, and assign the scene to it. + + For increased visual quality, we enable antialiasing. We also choose to use + bounding rectangle updates to simplify visual update handling. + The view is given a fixed sand-colored background, and a window title. + + We then show the view. The animations start immediately after + control enters the event loop. +*/ + 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/src/dynamiclayouts.qdoc b/examples/widgets/doc/src/dynamiclayouts.qdoc new file mode 100644 index 0000000000..318f719503 --- /dev/null +++ b/examples/widgets/doc/src/dynamiclayouts.qdoc @@ -0,0 +1,34 @@ +/**************************************************************************** +** +** 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 layouts/dynamiclayouts + \title Dynamic Layouts Example + + The Dynamic Layouts example shows how to move widgets around in + existing layouts. +*/ diff --git a/examples/widgets/doc/src/easing.qdoc b/examples/widgets/doc/src/easing.qdoc new file mode 100644 index 0000000000..7fb7f59531 --- /dev/null +++ b/examples/widgets/doc/src/easing.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 animation/easing + \title Easing Curves Example + + The Easing Curves example shows how to use easing curves to + control the speed of an animation. + + \image easing-example.png + +*/ diff --git a/examples/widgets/doc/src/editabletreemodel.qdoc b/examples/widgets/doc/src/editabletreemodel.qdoc new file mode 100644 index 0000000000..24745b77b8 --- /dev/null +++ b/examples/widgets/doc/src/editabletreemodel.qdoc @@ -0,0 +1,450 @@ +/**************************************************************************** +** +** 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 itemviews/editabletreemodel + \title Editable Tree Model Example + + This example shows how to implement a simple item-based tree model that can + be used with other classes the model/view framework. + + \image itemviews-editabletreemodel.png + + The model supports editable items, custom headers, and the ability to + insert and remove rows and columns. With these features, it is also + possible to insert new child items, and this is shown in the supporting + example code. + + \note The model only shows the basic principles used when creating an + editable, hierarchical model. You may wish to use the \l{ModelTest} + project to test production models. + + \section1 Overview + + As described in the \l{Model Subclassing Reference}, models must + provide implementations for the standard set of model functions: + \l{QAbstractItemModel::}{flags()}, \l{QAbstractItemModel::}{data()}, + \l{QAbstractItemModel::}{headerData()}, + \l{QAbstractItemModel::}{columnCount()}, and + \l{QAbstractItemModel::}{rowCount()}. In addition, hierarchical models, + such as this one, need to provide implementations of + \l{QAbstractItemModel::}{index()} and \l{QAbstractItemModel::}{parent()}. + + An editable model needs to provide implementations of + \l{QAbstractItemModel::}{setData()} and + \l{QAbstractItemModel::}{setHeaderData()}, and must return a suitable + combination of flags from its \l{QAbstractItemModel::}{flags()} function. + + Since this example allows the dimensions of the model to be changed, + we must also implement \l{QAbstractItemModel::}{insertRows()}, + \l{QAbstractItemModel::}{insertColumns()}, + \l{QAbstractItemModel::}{removeRows()}, and + \l{QAbstractItemModel::}{removeColumns()}. + + \section1 Design + + As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example, + the model simply acts as a wrapper around a collection + of instances of a \c TreeItem class. Each \c TreeItem is designed to + hold data for a row of items in a tree view, so it contains a list of + values corresponding to the data shown in each column. + + Since QTreeView provides a row-oriented view onto a model, it is + natural to choose a row-oriented design for data structures that + will supply data via a model to this kind of view. Although this makes + the tree model less flexible, and possibly less useful for use with + more sophisticated views, it makes it less complex to design and easier + to implement. + + \target Relations-between-internal-items + \table + \row \li \inlineimage itemviews-editabletreemodel-items.png + \li \b{Relations between internal items} + + When designing a data structure for use with a custom model, it is useful + to expose each item's parent via a function like + \l{TreeItem::parent}{TreeItem::parent()} because it will make + writing the model's own \l{QAbstractItemModel::}{parent()} function easier. + Similarly, a function like \l{TreeItem::child}{TreeItem::child()} is + helpful when implementing the model's \l{QAbstractItemModel::}{index()} + function. As a result, each \c TreeItem maintains information about + its parent and children, making it possible for us to traverse the tree + structure. + + The diagram shows how \c TreeItem instances are connected via their + \l{TreeItem::parent}{parent()} and \l{TreeItem::child}{child()} + functions. + + In the example shown, two top-level items, \b{A} and + \b{B}, can be obtained from the root item by calling its child() + function, and each of these items return the root node from their + parent() functions, though this is only shown for item \b{A}. + \endtable + + Each \c TreeItem stores data for each column in the row it represents + in its \c itemData private member (a list of QVariant objects). + Since there is a one-to-one mapping between each column in the view + and each entry in the list, we provide a simple + \l{TreeItem::data}{data()} function to read entries in the \c itemData + list and a \l{TreeItem::setData}{setData()} function to allow them to + be modified. + As with other functions in the item, this simplifies the implemention + of the model's \l{QAbstractItemModel::}{data()} and + \l{QAbstractItemModel::}{setData()} functions. + + We place an item at the root of the tree of items. This root item + corresponds to the null model index, \l{QModelIndex::}{QModelIndex()}, + that is used to represent the parent of a top-level item when handling + model indexes. + Although the root item does not have a visible representation in any of + the standard views, we use its internal list of QVariant objects to + store a list of strings that will be passed to views for use as + horizontal header titles. + + \table + \row \li \inlineimage itemviews-editabletreemodel-model.png + \li \b{Accessing data via the model} + + In the case shown in the diagram, the piece of information represented + by \b{a} can be obtained using the standard model/view API: + + \code + QVariant a = model->index(0, 0, QModelIndex()).data(); + \endcode + + Since each items holds pieces of data for each column in a given row, + there can be many model indexes that map to the same \c TreeItem object. + For example, the information represented by \b{b} can be obtained + using the following code: + + \code + QVariant b = model->index(1, 0, QModelIndex()).data(); + \endcode + + The same underlying \c TreeItem would be accessed to obtain information + for the other model indexes in the same row as \b{b}. + \endtable + + In the model class, \c TreeModel, we relate \c TreeItem objects to + model indexes by passing a pointer for each item when we create its + corresponding model index with QAbstractItemModel::createIndex() in + our \l{TreeModel::index}{index()} and \l{TreeModel::parent}{parent()} + implementations. + We can retrieve pointers stored in this way by calling the + \l{QModelIndex::}{internalPointer()} function on the relevant model + index - we create our own \l{TreeModel::getItem}{getItem()} function to + do this work for us, and call it from our \l{TreeModel::data}{data()} + and \l{TreeModel::parent}{parent()} implementations. + + Storing pointers to items is convenient when we control how they are + created and destroyed since we can assume that an address obtained from + \l{QModelIndex::}{internalPointer()} is a valid pointer. + However, some models need to handle items that are obtained from other + components in a system, and in many cases it is not possible to fully + control how items are created or destroyed. In such situations, a pure + pointer-based approach needs to be supplemented by safeguards to ensure + that the model does not attempt to access items that have been deleted. + + \table + \row \li \b{Storing information in the underlying data structure} + + Several pieces of data are stored as QVariant objects in the \c itemData + member of each \c TreeItem instance + + The diagram shows how pieces of information, + represented by the labels \b{a}, \b{b} and \b{c} in the + previous two diagrams, are stored in items \b{A}, \b{B} and + \b{C} in the underlying data structure. Note that pieces of + information from the same row in the model are all obtained from the + same item. Each element in a list corresponds to a piece of information + exposed by each column in a given row in the model. + + \li \inlineimage itemviews-editabletreemodel-values.png + \endtable + + Since the \c TreeModel implementation has been designed for use with + QTreeView, we have added a restriction on the way it uses \c TreeItem + instances: each item must expose the same number of columns of data. + This makes viewing the model consistent, allowing us to use the root + item to determine the number of columns for any given row, and only + adds the requirement that we create items containing enough data for + the total number of columns. As a result, inserting and removing + columns are time-consuming operations because we need to traverse the + entire tree to modify every item. + + An alternative approach would be to design the \c TreeModel class so + that it truncates or expands the list of data in individual \c TreeItem + instances as items of data are modified. However, this "lazy" resizing + approach would only allow us to insert and remove columns at the end of + each row and would not allow columns to be inserted or removed at + arbitrary positions in each row. + + \target Relating-items-using-model-indexes + \table + \row + \li \inlineimage itemviews-editabletreemodel-indexes.png + \li \b{Relating items using model indexes} + + As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example, + the \c TreeModel needs to be able to take a model index, find the + corresponding \c TreeItem, and return model indexes that correspond to + its parents and children. + + In the diagram, we show how the model's \l{TreeModel::parent}{parent()} + implementation obtains the model index corresponding to the parent of + an item supplied by the caller, using the items shown in a + \l{Relations-between-internal-items}{previous diagram}. + + A pointer to item \b{C} is obtained from the corresponding model index + using the \l{QModelIndex::internalPointer()} function. The pointer was + stored internally in the index when it was created. Since the child + contains a pointer to its parent, we use its \l{TreeItem::parent}{parent()} + function to obtain a pointer to item \b{B}. The parent model index is + created using the QAbstractItemModel::createIndex() function, passing + the pointer to item \b{B} as the internal pointer. + \endtable + + \section1 TreeItem Class Definition + + The \c TreeItem class provides simple items that contain several + pieces of data, and which can provide information about their parent + and child items: + + \snippet itemviews/editabletreemodel/treeitem.h 0 + + We have designed the API to be similar to that provided by + QAbstractItemModel by giving each item functions to return the number + of columns of information, read and write data, and insert and remove + columns. However, we make the relationship between items explicit by + providing functions to deal with "children" rather than "rows". + + Each item contains a list of pointers to child items, a pointer to its + parent item, and a list of QVariant objects that correspond to + information held in columns in a given row in the model. + + \section1 TreeItem Class Implementation + + Each \c TreeItem is constructed with a list of data and an optional + parent item: + + \snippet itemviews/editabletreemodel/treeitem.cpp 0 + + Initially, each item has no children. These are added to the item's + internal \c childItems member using the \c insertChildren() function + described later. + + The destructor ensures that each child added to the item is deleted + when the item itself is deleted: + + \snippet itemviews/editabletreemodel/treeitem.cpp 1 + + \target TreeItem::parent + Since each item stores a pointer to its parent, the \c parent() function + is trivial: + + \snippet itemviews/editabletreemodel/treeitem.cpp 9 + + \target TreeItem::child + Three functions provide information about the children of an item. + \c child() returns a specific child from the internal list of children: + + \snippet itemviews/editabletreemodel/treeitem.cpp 2 + + The \c childCount() function returns the total number of children: + + \snippet itemviews/editabletreemodel/treeitem.cpp 3 + + The \c childNumber() function is used to determine the index of the child + in its parent's list of children. It accesses the parent's \c childItems + member directly to obtain this information: + + \snippet itemviews/editabletreemodel/treeitem.cpp 4 + + The root item has no parent item; for this item, we return zero to be + consistent with the other items. + + The \c columnCount() function simply returns the number of elements in + the internal \c itemData list of QVariant objects: + + \snippet itemviews/editabletreemodel/treeitem.cpp 5 + + \target TreeItem::data + Data is retrieved using the \c data() function, which accesses the + appropriate element in the \c itemData list: + + \snippet itemviews/editabletreemodel/treeitem.cpp 6 + + \target TreeItem::setData + Data is set using the \c setData() function, which only stores values + in the \c itemData list for valid list indexes, corresponding to column + values in the model: + + \snippet itemviews/editabletreemodel/treeitem.cpp 11 + + To make implementation of the model easier, we return true to indicate + whether the data was set successfully, or false if an invalid column + + Editable models often need to be resizable, enabling rows and columns to + be inserted and removed. The insertion of rows beneath a given model index + in the model leads to the insertion of new child items in the corresponding + item, handled by the \c insertChildren() function: + + \snippet itemviews/editabletreemodel/treeitem.cpp 7 + + This ensures that new items are created with the required number of columns + and inserted at a valid position in the internal \c childItems list. + Items are removed with the \c removeChildren() function: + + \snippet itemviews/editabletreemodel/treeitem.cpp 10 + + As discussed above, the functions for inserting and removing columns are + used differently to those for inserting and removing child items because + they are expected to be called on every item in the tree. We do this by + recursively calling this function on each child of the item: + + \snippet itemviews/editabletreemodel/treeitem.cpp 8 + + \section1 TreeModel Class Definition + + The \c TreeModel class provides an implementation of the QAbstractItemModel + class, exposing the necessary interface for a model that can be edited and + resized. + + \snippet itemviews/editabletreemodel/treemodel.h 0 + + The constructor and destructor are specific to this model. + + \snippet itemviews/editabletreemodel/treemodel.h 1 + + Read-only tree models only need to provide the above functions. The + following public functions provide support for editing and resizing: + + \snippet itemviews/editabletreemodel/treemodel.h 2 + + To simplify this example, the data exposed by the model is organized into + a data structure by the model's \l{TreeModel::setupModelData}{setupModelData()} + function. Many real world models will not process the raw data at all, but + simply work with an existing data structure or library API. + + \section1 TreeModel Class Implementation + + The constructor creates a root item and initializes it with the header + data supplied: + + \snippet itemviews/editabletreemodel/treemodel.cpp 0 + + We call the internal \l{TreeModel::setupModelData}{setupModelData()} + function to convert the textual data supplied to a data structure we can + use with the model. Other models may be initialized with a ready-made + data structure, or use an API to a library that maintains its own data. + + The destructor only has to delete the root item; all child items will + be recursively deleted by the \c TreeItem destructor. + + \snippet itemviews/editabletreemodel/treemodel.cpp 1 + + \target TreeModel::getItem + Since the model's interface to the other model/view components is based + on model indexes, and the internal data structure is item-based, many of + the functions implemented by the model need to be able to convert any + given model index to its corresponding item. For convenience and + consistency, we have defined a \c getItem() function to perform this + repetitive task: + + \snippet itemviews/editabletreemodel/treemodel.cpp 4 + + This function assumes that each model index it is passed corresponds to + a valid item in memory. If the index is invalid, or its internal pointer + does not refer to a valid item, the root item is returned instead. + + The model's \c rowCount() implementation is simple: it first uses the + \c getItem() function to obtain the relevant item, then returns the + number of children it contains: + + \snippet itemviews/editabletreemodel/treemodel.cpp 8 + + By contrast, the \c columnCount() implementation does not need to look + for a particular item because all items are defined to have the same + number of columns associated with them. + + \snippet itemviews/editabletreemodel/treemodel.cpp 2 + + As a result, the number of columns can be obtained directly from the root + item. + + To enable items to be edited and selected, the \c flags() function needs + to be implemented so that it returns a combination of flags that includes + the Qt::ItemIsEditable and Qt::ItemIsSelectable flags as well as + Qt::ItemIsEnabled: + + \snippet itemviews/editabletreemodel/treemodel.cpp 3 + + \target TreeModel::index + The model needs to be able to generate model indexes to allow other + components to request data and information about its structure. This task + is performed by the \c index() function, which is used to obtain model + indexes corresponding to children of a given parent item: + + \snippet itemviews/editabletreemodel/treemodel.cpp 5 + + In this model, we only return model indexes for child items if the parent + index is invalid (corresponding to the root item) or if it has a zero + column number. + + We use the custom \l{TreeModel::getItem}{getItem()} function to obtain + a \c TreeItem instance that corresponds to the model index supplied, and + request its child item that corresponds to the specified row. + + \snippet itemviews/editabletreemodel/treemodel.cpp 6 + + Since each item contains information for an entire row of data, we create + a model index to uniquely identify it by calling + \l{QAbstractItemModel::}{createIndex()} it with the row and column numbers + and a pointer to the item. In the \l{TreeModel::data}{data()} function, + we will use the item pointer and column number to access the data + associated with the model index; in this model, the row number is not + needed to identify data. + + \target TreeModel::parent + The \c parent() function supplies model indexes for parents of items + by finding the corresponding item for a given model index, using its + \l{TreeItem::parent}{parent()} function to obtain its parent item, + then creating a model index to represent the parent. (See + \l{Relating-items-using-model-indexes}{the above diagram}). + + \snippet itemviews/editabletreemodel/treemodel.cpp 7 + + Items without parents, including the root item, are handled by returning + a null model index. Otherwise, a model index is created and returned as + in the \l{TreeModel::index}{index()} function, with a suitable row number, + but with a zero column number to be consistent with the scheme used in + the \l{TreeModel::index}{index()} implementation. + + \target TreeModel::data + \target TreeModel::setupModelData + +*/ diff --git a/examples/widgets/doc/src/elasticnodes.qdoc b/examples/widgets/doc/src/elasticnodes.qdoc new file mode 100644 index 0000000000..17f14124f8 --- /dev/null +++ b/examples/widgets/doc/src/elasticnodes.qdoc @@ -0,0 +1,430 @@ +/**************************************************************************** +** +** 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 graphicsview/elasticnodes + \title Elastic Nodes Example + + The Elastic Nodes example shows how to implement edges between nodes in a + graph, with basic interaction. You can click to drag a node around, and + zoom in and out using the mouse wheel or the keyboard. Hitting the space + bar will randomize the nodes. The example is also resolution independent; + as you zoom in, the graphics remain crisp. + + \image elasticnodes-example.png + + Graphics View provides the QGraphicsScene class for managing and + interacting with a large number of custom-made 2D graphical items derived + from the QGraphicsItem class, and a QGraphicsView widget for visualizing + the items, with support for zooming and rotation. + + This example consists of a \c Node class, an \c Edge class, a \c + GraphWidget test, and a \c main function: the \c Node class represents + draggable yellow nodes in a grid, the \c Edge class represents the lines + between the nodes, the \c GraphWidget class represents the application + window, and the \c main() function creates and shows this window, and runs + the event loop. + + \section1 Node Class Definition + + The \c Node class serves three purposes: + + \list + \li Painting a yellow gradient "ball" in two states: sunken and raised. + \li Managing connections to other nodes. + \li Calculating forces pulling and pushing the nodes in the grid. + \endlist + + Let's start by looking at the \c Node class declaration. + + \snippet graphicsview/elasticnodes/node.h 0 + + The \c Node class inherits QGraphicsItem, and reimplements the two + mandatory functions \l{QGraphicsItem::boundingRect()}{boundingRect()} and + \l{QGraphicsItem::paint()}{paint()} to provide its visual appearance. It + also reimplements \l{QGraphicsItem::shape()}{shape()} to ensure its hit + area has an elliptic shape (as opposed to the default bounding rectangle). + + For edge management purposes, the node provides a simple API for adding + edges to a node, and for listing all connected edges. + + The \l{QGraphicsItem::advance()}{advance()} reimplementation is called + whenever the scene's state advances by one step. The calculateForces() + function is called to calculate the forces that push and pull on this node + and its neighbors. + + The \c Node class also reimplements + \l{QGraphicsItem::itemChange()}{itemChange()} to react to state changes (in + this case, position changes), and + \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()} and + \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()} to update the + item's visual appearance. + + We will start reviewing the \c Node implementation by looking at its + constructor: + + \snippet graphicsview/elasticnodes/node.cpp 0 + + In the constructor, we set the + \l{QGraphicsItem::ItemIsMovable}{ItemIsMovable} flag to allow the item to + move in response to mouse dragging, and + \l{QGraphicsItem::ItemSendsGeometryChanges}{ItemSendsGeometryChanges} to + enable \l{QGraphicsItem::itemChange()}{itemChange()} notifications for + position and transformation changes. We also enable + \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache} to speed up + rendering performance. To ensure that the nodes are always stacked on top + of edges, we finally set the item's Z value to -1. + + \c Node's constructor takes a \c GraphWidget pointer and stores this as a + member variable. We will revisit this pointer later on. + + \snippet graphicsview/elasticnodes/node.cpp 1 + + The addEdge() function adds the input edge to a list of attached edges. The + edge is then adjusted so that the end points for the edge match the + positions of the source and destination nodes. + + The edges() function simply returns the list of attached edges. + + \snippet graphicsview/elasticnodes/node.cpp 2 + + There are two ways to move a node. The \c calculateForces() function + implements the elastic effect that pulls and pushes on nodes in the grid. + In addition, the user can directly move one node around with the mouse. + Because we do not want the two approaches to operate at the same time on + the same node, we start \c calculateForces() by checking if this \c Node is + the current mouse grabber item (i.e., QGraphicsScene::mouseGrabberItem()). + Because we need to find all neighboring (but not necessarily connected) + nodes, we also make sure the item is part of a scene in the first place. + + \snippet graphicsview/elasticnodes/node.cpp 3 + + The "elastic" effect comes from an algorithm that applies pushing and + pulling forces. The effect is impressive, and surprisingly simple to + implement. + + The algorithm has two steps: the first is to calculate the forces that push + the nodes apart, and the second is to subtract the forces that pull the + nodes together. First we need to find all the nodes in the graph. We call + QGraphicsScene::items() to find all items in the scene, and then use + qgraphicsitem_cast() to look for \c Node instances. + + We make use of \l{QGraphicsItem::mapFromItem()}{mapFromItem()} to create a + temporary vector pointing from this node to each other node, in \l{The + Graphics View Coordinate System}{local coordinates}. We use the decomposed + components of this vector to determine the direction and strength of force + that should apply to the node. The forces accumulate for each node, and are + then adjusted so that the closest nodes are given the strongest force, with + rapid degradation when distance increases. The sum of all forces is stored + in \c xvel (X-velocity) and \c yvel (Y-velocity). + + \snippet graphicsview/elasticnodes/node.cpp 4 + + The edges between the nodes represent forces that pull the nodes together. + By visiting each edge that is connected to this node, we can use a similar + approach as above to find the direction and strength of all pulling forces. + These forces are subtracted from \c xvel and \c yvel. + + \snippet graphicsview/elasticnodes/node.cpp 5 + + In theory, the sum of pushing and pulling forces should stabilize to + precisely 0. In practice, however, they never do. To circumvent errors in + numerical precision, we simply force the sum of forces to be 0 when they + are less than 0.1. + + \snippet graphicsview/elasticnodes/node.cpp 6 + + The final step of \c calculateForces() determines the node's new position. + We add the force to the node's current position. We also make sure the new + position stays inside of our defined boundaries. We don't actually move the + item in this function; that's done in a separate step, from \c advance(). + + \snippet graphicsview/elasticnodes/node.cpp 7 + + The \c advance() function updates the item's current position. It is called + from \c GraphWidget::timerEvent(). If the node's position changed, the + function returns true; otherwise false is returned. + + \snippet graphicsview/elasticnodes/node.cpp 8 + + The \c Node's bounding rectangle is a 20x20 sized rectangle centered around + its origin (0, 0), adjusted by 2 units in all directions to compensate for + the node's outline stroke, and by 3 units down and to the right to make + room for a simple drop shadow. + + \snippet graphicsview/elasticnodes/node.cpp 9 + + The shape is a simple ellipse. This ensures that you must click inside the + node's elliptic shape in order to drag it around. You can test this effect + by running the example, and zooming far in so that the nodes are very + large. Without reimplementing \l{QGraphicsItem::shape()}{shape()}, the + item's hit area would be identical to its bounding rectangle (i.e., + rectangular). + + \snippet graphicsview/elasticnodes/node.cpp 10 + + This function implements the node's painting. We start by drawing a simple + dark gray elliptic drop shadow at (-7, -7), that is, (3, 3) units down and + to the right from the top-left corner (-10, -10) of the ellipse. + + We then draw an ellipse with a radial gradient fill. This fill is either + Qt::yellow to Qt::darkYellow when raised, or the opposite when sunken. In + sunken state we also shift the center and focal point by (3, 3) to + emphasize the impression that something has been pushed down. + + Drawing filled ellipses with gradients can be quite slow, especially when + using complex gradients such as QRadialGradient. This is why this example + uses \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache}, a + simple yet effective measure that prevents unnecessary redrawing. + + \snippet graphicsview/elasticnodes/node.cpp 11 + + We reimplement \l{QGraphicsItem::itemChange()}{itemChange()} to adjust the + position of all connected edges, and to notify the scene that an item has + moved (i.e., "something has happened"). This will trigger new force + calculations. + + This notification is the only reason why the nodes need to keep a pointer + back to the \c GraphWidget. Another approach could be to provide such + notification using a signal; in such case, \c Node would need to inherit + from QGraphicsObject. + + \snippet graphicsview/elasticnodes/node.cpp 12 + + Because we have set the \l{QGraphicsItem::ItemIsMovable}{ItemIsMovable} + flag, we don't need to implement the logic that moves the node according to + mouse input; this is already provided for us. We still need to reimplement + the mouse press and release handlers, though, to update the nodes' visual + appearance (i.e., sunken or raised). + + \section1 Edge Class Definition + + The \c Edge class represents the arrow-lines between the nodes in this + example. The class is very simple: it maintains a source- and destination + node pointer, and provides an \c adjust() function that makes sure the line + starts at the position of the source, and ends at the position of the + destination. The edges are the only items that change continuously as + forces pull and push on the nodes. + + Let's take a look at the class declaration: + + \snippet graphicsview/elasticnodes/edge.h 0 + + \c Edge inherits from QGraphicsItem, as it's a simple class that has no use + for signals, slots, and properties (compare to QGraphicsObject). + + The constructor takes two node pointers as input. Both pointers are + mandatory in this example. We also provide get-functions for each node. + + The \c adjust() function repositions the edge, and the item also implements + \l{QGraphicsItem::boundingRect()}{boundingRect()} and + \l{QGraphicsItem::paint()}{paint()}. + + We will now review its implementation. + + \snippet graphicsview/elasticnodes/edge.cpp 0 + + The \c Edge constructor initializes its \c arrowSize data member to 10 units; + this determines the size of the arrow which is drawn in + \l{QGraphicsItem::paint()}{paint()}. + + In the constructor body, we call + \l{QGraphicsItem::setAcceptedMouseButtons()}{setAcceptedMouseButtons(0)}. + This ensures that the edge items are not considered for mouse input at all + (i.e., you cannot click the edges). Then, the source and destination + pointers are updated, this edge is registered with each node, and we call + \c adjust() to update this edge's start end end position. + + \snippet graphicsview/elasticnodes/edge.cpp 1 + + The source and destination get-functions simply return the respective + pointers. + + \snippet graphicsview/elasticnodes/edge.cpp 2 + + In \c adjust(), we define two points: \c sourcePoint, and \c destPoint, + pointing at the source and destination nodes' origins respectively. Each + point is calculated using \l{The Graphics View Coordinate System}{local + coordinates}. + + We want the tip of the edge's arrows to point to the exact outline of the + nodes, as opposed to the center of the nodes. To find this point, we first + decompose the vector pointing from the center of the source to the center + of the destination node into X and Y, and then normalize the components by + dividing by the length of the vector. This gives us an X and Y unit delta + that, when multiplied by the radius of the node (which is 10), gives us the + offset that must be added to one point of the edge, and subtracted from the + other. + + If the length of the vector is less than 20 (i.e., if two nodes overlap), + then we fix the source and destination pointer at the center of the source + node. In practice this case is very hard to reproduce manually, as the + forces between the two nodes is then at its maximum. + + It's important to notice that we call + \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()} in this + function. The reason is that the variables \c sourcePoint and \c destPoint + are used directly when painting, and they are returned from the + \l{QGraphicsItem::boundingRect()}{boundingRect()} reimplementation. We must + always call + \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()} before + changing what \l{QGraphicsItem::boundingRect()}{boundingRect()} returns, + and before these variables can be used by + \l{QGraphicsItem::paint()}{paint()}, to keep Graphics View's internal + bookkeeping clean. It's safest to call this function once, immediately + before any such variable is modified. + + \snippet graphicsview/elasticnodes/edge.cpp 3 + + The edge's bounding rectangle is defined as the smallest rectangle that + includes both the start and the end point of the edge. Because we draw an + arrow on each edge, we also need to compensate by adjusting with half the + arrow size and half the pen width in all directions. The pen is used to + draw the outline of the arrow, and we can assume that half of the outline + can be drawn outside of the arrow's area, and half will be drawn inside. + + \snippet graphicsview/elasticnodes/edge.cpp 4 + + We start the reimplementation of \l{QGraphicsItem::paint()}{paint()} by + checking a few preconditions. Firstly, if either the source or destination + node is not set, then we return immediately; there is nothing to draw. + + At the same time, we check if the length of the edge is approximately 0, + and if it is, then we also return. + + \snippet graphicsview/elasticnodes/edge.cpp 5 + + We draw the line using a pen that has round joins and caps. If you run the + example, zoom in and study the edge in detail, you will see that there are + no sharp/square edges. + + \snippet graphicsview/elasticnodes/edge.cpp 6 + + We proceed to drawing one arrow at each end of the edge. Each arrow is + drawn as a polygon with a black fill. The coordinates for the arrow are + determined using simple trigonometry. + + \section1 GraphWidget Class Definition + + \c GraphWidget is a subclass of QGraphicsView, which provides the main + window with scrollbars. + + \snippet graphicsview/elasticnodes/graphwidget.h 0 + + The class provides a basic constructor that initializes the scene, an \c + itemMoved() function to notify changes in the scene's node graph, a few + event handlers, a reimplementation of + \l{QGraphicsView::drawBackground()}{drawBackground()}, and a helper + function for scaling the view by using the mouse wheel or keyboard. + + \snippet graphicsview/elasticnodes/graphwidget.cpp 0 + + \c GraphicsWidget's constructor creates the scene, and because most items + move around most of the time, it sets QGraphicsScene::NoIndex. The scene + then gets a fixed \l{QGraphicsScene::sceneRect}{scene rectangle}, and is + assigned to the \c GraphWidget view. + + The view enables QGraphicsView::CacheBackground to cache rendering of its + static, and somewhat complex, background. Because the graph renders a close + collection of small items that all move around, it's unnecessary for + Graphics View to waste time finding accurate update regions, so we set the + QGraphicsView::BoundingRectViewportUpdate viewport update mode. The default + would work fine, but this mode is noticably faster for this example. + + To improve rendering quality, we set QPainter::Antialiasing. + + The transformation anchor decides how the view should scroll when you + transform the view, or in our case, when we zoom in or out. We have chosen + QGraphicsView::AnchorUnderMouse, which centers the view on the point under + the mouse cursor. This makes it easy to zoom towards a point in the scene + by moving the mouse over it, and then rolling the mouse wheel. + + Finally we give the window a minimum size that matches the scene's default + size, and set a suitable window title. + + \snippet graphicsview/elasticnodes/graphwidget.cpp 1 + + The last part of the constructor creates the grid of nodes and edges, and + gives each node an initial position. + + \snippet graphicsview/elasticnodes/graphwidget.cpp 2 + + \c GraphWidget is notified of node movement through this \c itemMoved() + function. Its job is simply to restart the main timer in case it's not + running already. The timer is designed to stop when the graph stabilizes, + and start once it's unstable again. + + \snippet graphicsview/elasticnodes/graphwidget.cpp 3 + + This is \c GraphWidget's key event handler. The arrow keys move the center + node around, the '+' and '-' keys zoom in and out by calling \c + scaleView(), and the enter and space keys randomize the positions of the + nodes. All other key events (e.g., page up and page down) are handled by + QGraphicsView's default implementation. + + \snippet graphicsview/elasticnodes/graphwidget.cpp 4 + + The timer event handler's job is to run the whole force calculation + machinery as a smooth animation. Each time the timer is triggered, the + handler will find all nodes in the scene, and call \c + Node::calculateForces() on each node, one at a time. Then, in a final step + it will call \c Node::advance() to move all nodes to their new positions. + By checking the return value of \c advance(), we can decide if the grid + stabilized (i.e., no nodes moved). If so, we can stop the timer. + + \snippet graphicsview/elasticnodes/graphwidget.cpp 5 + + In the wheel event handler, we convert the mouse wheel delta to a scale + factor, and pass this factor to \c scaleView(). This approach takes into + account the speed that the wheel is rolled. The faster you roll the mouse + wheel, the faster the view will zoom. + + \snippet graphicsview/elasticnodes/graphwidget.cpp 6 + + The view's background is rendered in a reimplementation of + QGraphicsView::drawBackground(). We draw a large rectangle filled with a + linear gradient, add a drop shadow, and then render text on top. The text + is rendered twice for a simple drop-shadow effect. + + This background rendering is quite expensive; this is why the view enables + QGraphicsView::CacheBackground. + + \snippet graphicsview/elasticnodes/graphwidget.cpp 7 + + The \c scaleView() helper function checks that the scale factor stays + within certain limits (i.e., you cannot zoom too far in nor too far out), + and then applies this scale to the view. + + \section1 The main() Function + + In contrast to the complexity of the rest of this example, the \c main() + function is very simple: We create a QApplication instance, seed the + randomizer using qsrand(), and then create and show an instance of \c + GraphWidget. Because all nodes in the grid are moved initially, the \c + GraphWidget timer will start immediately after control has returned to the + event loop. +*/ diff --git a/examples/widgets/doc/src/elidedlabel.qdoc b/examples/widgets/doc/src/elidedlabel.qdoc new file mode 100644 index 0000000000..2ce469d85f --- /dev/null +++ b/examples/widgets/doc/src/elidedlabel.qdoc @@ -0,0 +1,162 @@ +/**************************************************************************** +** +** 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/elidedlabel + \group all-examples + \title Elided Label Example + + This example creates a widget similar to QLabel, that elides the last + visible line, if the text is too long to fit the widget's geometry. + + \image elidedlabel-example.png Elided Label example on XPressMusic 5800 + + When text of varying length has to be displayed in a uniformly sized + area, for instance within a list or grid view where all list items have the + same size, it can be useful to give the user a visual clue when not all + text is visible. QLabel can elide text that doesn't fit within it, but only + in one line. The \c ElidedLabel widget shown in this example word wraps its + text by its width, and elides the last visible line if some text is left + out. \c TestWidget gives control to the features of \c ElidedWidget and + forms the example application. + + + \section1 ElidedLabel Class Definition + + Like QLabel, \c ElidedLabel inherits from QFrame. Here's the definition of + the \c ElidedLabel class: + + + \snippet widgets/elidedlabel/elidedlabel.h 0 + + The \c isElided property depends the font, text content and geometry of the + widget. Whenever any of these change, the \c elisionChanged() signal might + trigger. We cache the current elision value in \c elided, so that it + doesn't have to be recomputed every time it's asked for. + + + \section1 ElidedLabel Class Implementation + + Except for initializing the member variables, the constructor sets the size + policy to be horizontally expanding, since it's meant to fill the width of + its container and grow vertically. + + \snippet widgets/elidedlabel/elidedlabel.cpp 0 + + Changing the \c content require a repaint of the widget. + + \snippet widgets/elidedlabel/elidedlabel.cpp 1 + + QTextLayout is used in the \c paintEvent() to divide the \c content into + lines, that wrap on word boundaries. Each line, except the last visible + one, is drawn \c lineSpacing pixels below the previous one. The \c draw() + method of QTextLine will draw the line using the coordinate point as the + top left corner. + + \snippet widgets/elidedlabel/elidedlabel.cpp 2 + + Unfortunately, QTextLayout does not elide text, so the last visible line + has to be treated differently. This last line is elided if it is too wide. + The \c drawText() method of QPainter draws the text starting from the base + line, which is \c ascecnt() pixels below the last drawn line. + + Finally, one more line is created to see if everything fit on this line. + + \snippet widgets/elidedlabel/elidedlabel.cpp 3 + + If the text was elided and wasn't before or vice versa, cache it in + \c elided and emit the change. + + \snippet widgets/elidedlabel/elidedlabel.cpp 4 + + + \section1 TestWidget Class Definition + + \c TestWidget is a QWidget and is the main window of the example. It + contains an \c ElidedLabel which can be resized with two QSlider widgets. + + \snippet widgets/elidedlabel/testwidget.h 0 + + \section1 TestWidget Class Implementation + + The constructor initializes the whole widget. Strings of different length + are stored in \c textSamples. The user is able to switch between these. + + \snippet widgets/elidedlabel/testwidget.cpp 0 + + An \c ElidedLabel is created to contain the first of the sample strings. + The frame is made visible to make it easier to see the actual size of the + widget. + + \snippet widgets/elidedlabel/testwidget.cpp 1 + + The buttons and the elision label are created. By connecting the + \c elisionChanged() signal to the \c setVisible() slot of the \c label, + it will act as an indicator to when the text is elided or not. This signal + could, for instance, be used to make a "More" button visible, or similar. + + \snippet widgets/elidedlabel/testwidget.cpp 2 + + The \c widthSlider and \c heightSlider specify the size of the + \c elidedText. Since the y-axis is inverted, the \c heightSlider has to be + inverted to act appropriately. + + \snippet widgets/elidedlabel/testwidget.cpp 3 + + The components are all stored in a QGridLayout, which is made the layout of + the \c TestWidget. + + \snippet widgets/elidedlabel/testwidget.cpp 4 + + On the Maemo platform, windows are stuck in landscape mode by default. With + this attribute set, the window manager is aware that this window can be + rotated. + + \snippet widgets/elidedlabel/testwidget.cpp 5 + + The \c widthSlider and \c heightSlider have the exact same length as the + dimensions of the \c elidedText. The maximum value for both of them is + thus their lengths, and each tick indicates one pixel. + + \snippet widgets/elidedlabel/testwidget.cpp 6 + + The \c switchText() slot simply cycles through all the available sample + texts. + + \snippet widgets/elidedlabel/testwidget.cpp 7 + + These slots set the width and height of the \c elided text, in response to + changes in the sliders. + + \section1 The \c main() Function + + The \c main() function creates an instance of \c TestWidget fullscreen and + enters the message loop. + + \snippet widgets/elidedlabel/main.cpp 0 +*/ + diff --git a/examples/widgets/doc/src/embeddeddialogs.qdoc b/examples/widgets/doc/src/embeddeddialogs.qdoc new file mode 100644 index 0000000000..24b3abdb37 --- /dev/null +++ b/examples/widgets/doc/src/embeddeddialogs.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 graphicsview/embeddeddialogs + \title Embedded Dialogs + + This example shows how to embed standard dialogs into + Graphics View. It also shows how you can customize the + proxy class and add window shadows. + + \image embeddeddialogs-demo.png +*/ diff --git a/examples/widgets/doc/src/eventtransitions.qdoc b/examples/widgets/doc/src/eventtransitions.qdoc new file mode 100644 index 0000000000..ef3f657c3d --- /dev/null +++ b/examples/widgets/doc/src/eventtransitions.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** 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 statemachine/eventtransitions + \title Event Transitions Example + + The Event Transitions example shows how to use event transitions, a + feature of \l{The State Machine Framework}. + + \snippet statemachine/eventtransitions/main.cpp 0 + + The \c Window class's constructors begins by creating a button. + + \snippet statemachine/eventtransitions/main.cpp 1 + + Two states, \c s1 and \c s2, are created; upon entry they will assign + "Outside" and "Inside" to the button's text, respectively. + + \snippet statemachine/eventtransitions/main.cpp 2 + + When the button receives an event of type QEvent::Enter and the state + machine is in state \c s1, the machine will transition to state \c s2. + + \snippet statemachine/eventtransitions/main.cpp 3 + + When the button receives an event of type QEvent::Leave and the state + machine is in state \c s2, the machine will transition back to state \c + s1. + + \snippet statemachine/eventtransitions/main.cpp 4 + + Next, the state \c s3 is created. \c s3 will be entered when the button + receives an event of type QEvent::MouseButtonPress and the state machine + is in state \c s2. When the button receives an event of type + QEvent::MouseButtonRelease and the state machine is in state \c s3, the + machine will transition back to state \c s2. + + \snippet statemachine/eventtransitions/main.cpp 5 + + Finally, the states are added to the machine as top-level states, the + initial state is set to be \c s1 ("Outside"), and the machine is started. + + \snippet statemachine/eventtransitions/main.cpp 6 + + The main() function constructs a Window object and shows it. + +*/ diff --git a/examples/widgets/doc/src/extension.qdoc b/examples/widgets/doc/src/extension.qdoc new file mode 100644 index 0000000000..040d5d38d9 --- /dev/null +++ b/examples/widgets/doc/src/extension.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** 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 dialogs/extension + \title Extension Example + + The Extension example shows how to add an extension to a QDialog + using the QAbstractButton::toggled() signal and the + QWidget::setVisible() slot. + + \image extension-example.png Screenshot of the Extension example + + The Extension application is a dialog that allows the user to + perform a simple search as well as a more advanced search. + + The simple search has two options: \uicontrol {Match case} and \uicontrol + {Search from start}. The advanced search options include the + possibilities to search for \uicontrol {Whole words}, \uicontrol {Search + backward} and \uicontrol {Search selection}. Only the simple search is + visible when the application starts. The advanced search options + are located in the application's extension part, and can be made + visible by pressing the \uicontrol More button: + + \image extension_more.png Screenshot of the Extension example + + \section1 FindDialog Class Definition + + The \c FindDialog class inherits QDialog. The QDialog class is the + base class of dialog windows. A dialog window is a top-level + window mostly used for short-term tasks and brief communications + with the user. + + \snippet dialogs/extension/finddialog.h 0 + + The \c FindDialog widget is the main application widget, and + displays the application's search options and controlling + buttons. + + In addition to a constructor, we declare the several child + widgets: We need a QLineEdit with an associated QLabel to let the + user type a word to search for, we need several \l + {QCheckBox}{QCheckBox}es to facilitate the search options, and we + need three \l {QPushButton}{QPushButton}s: the \uicontrol Find button to + start a search and the \uicontrol More button to enable an advanced search. + Finally, we need a QWidget representing the application's extension + part. + + \section1 FindDialog Class Implementation + + In the constructor we first create the standard child widgets for + the simple search: the QLineEdit with the associated QLabel, two + of the \l {QCheckBox}{QCheckBox}es and all the \l + {QPushButton}{QPushButton}s. + + \snippet dialogs/extension/finddialog.cpp 0 + + We give the options and buttons a shortcut key using the & + character. In the \uicontrol {Find what} option's case, we also need to + use the QLabel::setBuddy() function to make the shortcut key work + as expected; then, when the user presses the shortcut key + indicated by the label, the keyboard focus is transferred to the + label's buddy widget, the QLineEdit. + + We set the \uicontrol Find button's default property to true, using the + QPushButton::setDefault() function. Then the push button will be + pressed if the user presses the Enter (or Return) key. Note that a + QDialog can only have one default button. + + \snippet dialogs/extension/finddialog.cpp 2 + + Then we create the extension widget, and the \l + {QCheckBox}{QCheckBox}es associated with the advanced search + options. + + \snippet dialogs/extension/finddialog.cpp 3 + + Now that the extension widget is created, we can connect the \uicontrol + More button's \l{QAbstractButton::toggled()}{toggled()} signal to + the extension widget's \l{QWidget::setVisible()}{setVisible()} slot. + + The QAbstractButton::toggled() signal is emitted whenever a + checkable button changes its state. The signal's argument is true + if the button is checked, or false if the button is unchecked. The + QWidget::setVisible() slot sets the widget's visible status. If + the status is true the widget is shown, otherwise the widget is + hidden. + + Since we made the \uicontrol More button checkable when we created it, + the connection makes sure that the extension widget is shown + depending on the state of \uicontrol More button. + + We also put the check boxes associated with the advanced + search options into a layout we install on the extension widget. + + \snippet dialogs/extension/finddialog.cpp 4 + + Before we create the main layout, we create several child layouts + for the widgets: First we align the QLabel and its buddy, the + QLineEdit, using a QHBoxLayout. Then we vertically align the + QLabel and QLineEdit with the check boxes associated with the + simple search, using a QVBoxLayout. We also create a QVBoxLayout + for the buttons. In the end we lay out the two latter layouts and + the extension widget using a QGridLayout. + + \snippet dialogs/extension/finddialog.cpp 5 + + Finally, we hide the extension widget using the QWidget::hide() + function, making the application only show the simple search + options when it starts. When the user wants to access the advanced + search options, the dialog only needs to change the visibility of + the extension widget. Qt's layout management takes care of the + dialog's appearance. +*/ diff --git a/examples/widgets/doc/src/factorial.qdoc b/examples/widgets/doc/src/factorial.qdoc new file mode 100644 index 0000000000..82ab5da536 --- /dev/null +++ b/examples/widgets/doc/src/factorial.qdoc @@ -0,0 +1,88 @@ +/**************************************************************************** +** +** 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 statemachine/factorial + \title Factorial States Example + + The Factorial States example shows how to use \l{The State Machine + Framework} to calculate the factorial of an integer. + + The statechart for calculating the factorial looks as follows: + + \image factorial-example.png + \omit + \caption This is a caption + \endomit + + In other words, the state machine calculates the factorial of 6 and prints + the result. + + \snippet statemachine/factorial/main.cpp 0 + + The Factorial class is used to hold the data of the computation, \c x and + \c fac. It also provides a signal that's emitted whenever the value of \c + x changes. + + \snippet statemachine/factorial/main.cpp 1 + + The FactorialLoopTransition class implements the guard (\c x > 1) and + calculations (\c fac = \c x * \c fac; \c x = \c x - 1) of the factorial + loop. + + \snippet statemachine/factorial/main.cpp 2 + + The FactorialDoneTransition class implements the guard (\c x <= 1) that + terminates the factorial computation. It also prints the final result to + standard output. + + \snippet statemachine/factorial/main.cpp 3 + + The application's main() function first creates the application object, a + Factorial object and a state machine. + + \snippet statemachine/factorial/main.cpp 4 + + The \c compute state is created, and the initial values of \c x and \c fac + are defined. A FactorialLoopTransition object is created and added to the + state. + + \snippet statemachine/factorial/main.cpp 5 + + A final state, \c done, is created, and a FactorialDoneTransition object + is created with \c done as its target state. The transition is then added + to the \c compute state. + + \snippet statemachine/factorial/main.cpp 6 + + The machine's initial state is set to be the \c compute state. We connect + the QStateMachine::finished() signal to the QCoreApplication::quit() slot, + so the application will quit when the state machine's work is + done. Finally, the state machine is started, and the application's event + loop is entered. + + */ diff --git a/examples/widgets/doc/src/fademessage.qdoc b/examples/widgets/doc/src/fademessage.qdoc new file mode 100644 index 0000000000..48f98c03ad --- /dev/null +++ b/examples/widgets/doc/src/fademessage.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 effects/fademessage + \title Fade Message Effect Example + + \div { style="text-align: center"} + \inlineimage fademessageeffect-example.png + \inlineimage fademessageeffect-example-faded.png + \enddiv + +*/ diff --git a/examples/widgets/doc/src/fetchmore.qdoc b/examples/widgets/doc/src/fetchmore.qdoc new file mode 100644 index 0000000000..7ea0b30edf --- /dev/null +++ b/examples/widgets/doc/src/fetchmore.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** 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 itemviews/fetchmore + \title Fetch More Example + + The Fetch More example shows how two add items to an item view + model on demand. + + \image fetchmore-example.png + + The user of the example can enter a directory in the \uicontrol + Directory line edit. The contents of the directory will + be listed in the list view below. + + When you have large - or perhaps even infinite - data sets, you + will need to add items to the model in batches, and preferably only + when the items are needed by the view (i.e., when they are visible + in the view). + + In this example, we implement \c FileListModel - an item view + model containing the entries of a directory. We also have \c + Window, which sets up the GUI and feeds the model with + directories. + + Let's take a tour of \c {FileListModel}'s code. + + \section1 FileListModel Class Definition + + The \c FileListModel inherits QAbstractListModel and contains the + contents of a directory. It will add items to itself only when + requested to do so by the view. + + \snippet itemviews/fetchmore/filelistmodel.h 0 + + The secret lies in the reimplementation of + \l{QAbstractItemModel::}{fetchMore()} and + \l{QAbstractItemModel::}{canFetchMore()} from QAbstractItemModel. + These functions are called by the item view when it needs more + items. + + The \c setDirPath() function sets the directory the model will + work on. We emit \c numberPopulated() each time we add a batch of + items to the model. + + We keep all directory entries in \c fileList. \c fileCount is the + number of items that have been added to the model. + + \section1 FileListModel Class Implementation + + We start by checking out the \c setDirPath(). + + \snippet itemviews/fetchmore/filelistmodel.cpp 0 + + We use a QDir to get the contents of the directory. We need to + inform QAbstractItemModel that we want to remove all items - if + any - from the model. + + \snippet itemviews/fetchmore/filelistmodel.cpp 1 + + The \c canFetchMore() function is called by the view when it needs + more items. We return true if there still are entries that we have + not added to the model; otherwise, we return false. + + And now, the \c fetchMore() function itself: + + \snippet itemviews/fetchmore/filelistmodel.cpp 2 + + We first calculate the number of items to fetch. + \l{QAbstractItemModel::}{beginInsertRows()} and + \l{QAbstractItemModel::}{endInsertRows()} are mandatory for + QAbstractItemModel to keep up with the row insertions. Finally, we + emit \c numberPopulated(), which is picked up by \c Window. + + To complete the tour, we also look at \c rowCount() and \c data(). + + \snippet itemviews/fetchmore/filelistmodel.cpp 4 + + Notice that the row count is only the items we have added so far, + i.e., not the number of entries in the directory. + + In \c data(), we return the appropriate entry from the \c + fileList. We also separate the batches with a different background + color. +*/ + diff --git a/examples/widgets/doc/src/findfiles.qdoc b/examples/widgets/doc/src/findfiles.qdoc new file mode 100644 index 0000000000..594d57472c --- /dev/null +++ b/examples/widgets/doc/src/findfiles.qdoc @@ -0,0 +1,249 @@ +/**************************************************************************** +** +** 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 dialogs/findfiles + \title Find Files Example + + The Find Files example shows how to use QProgressDialog to provide + feedback on the progress of a slow operation. The example also + shows how to use QFileDialog to facilitate browsing, how to use + QTextStream's streaming operators to read a file, and how to use + QTableWidget to provide standard table display facilities for + applications. In addition, files can be opened using the + QDesktopServices class. + + \image findfiles-example.png Screenshot of the Find Files example + + With the Find Files application the user can search for files in a + specified directory, matching a specified file name (using wild + cards if appropriate) and containing a specified text. + + The user is provided with a \uicontrol Browse option, and the result of + the search is displayed in a table with the names of the files + found and their sizes. In addition the application provides a + total count of the files found. + + \section1 Window Class Definition + + The \c Window class inherits QWidget, and is the main application + widget. It shows the search options, and displays the search + results. + + \snippet dialogs/findfiles/window.h 0 + + We need two private slots: The \c browse() slot is called whenever + the user wants to browse for a directory to search in, and the \c + find() slot is called whenever the user requests a search to be + performed by pressing the \uicontrol Find button. + + In addition we declare several private functions: We use the \c + findFiles() function to search for files matching the user's + specifications, we call the \c showFiles() function to display the + results, and we use \c createButton(), \c createComboBox() and \c + createFilesTable() when we are constructing the widget. + + \section1 Window Class Implementation + + In the constructor we first create the application's widgets. + + \snippet dialogs/findfiles/window.cpp 0 + + We create the application's buttons using the private \c + createButton() function. Then we create the comboboxes associated + with the search specifications, using the private \c + createComboBox() function. We also create the application's labels + before we use the private \c createFilesTable() function to create + the table displaying the search results. + + \snippet dialogs/findfiles/window.cpp 1 + + Then we add all the widgets to a main layout using QGridLayout. We + have, however, put the \c Find and \c Quit buttons and a + stretchable space in a separate QHBoxLayout first, to make the + buttons appear in the \c Window widget's bottom right corner. + + \snippet dialogs/findfiles/window.cpp 2 + + The \c browse() slot presents a file dialog to the user, using the + QFileDialog class. QFileDialog enables a user to traverse the file + system in order to select one or many files or a directory. The + easiest way to create a QFileDialog is to use the convenience + static functions. + + Here we use the static QFileDialog::getExistingDirectory() + function which returns an existing directory selected by the + user. Then we display the directory in the directory combobox + using the QComboBox::addItem() function, and updates the current + index. + + QComboBox::addItem() adds an item to the combobox with the given + text (if it is not already present in the list), and containing + the specified userData. The item is appended to the list of + existing items. + + \snippet dialogs/findfiles/window.cpp 3 + + The \c find() slot is called whenever the user requests a new + search by pressing the \uicontrol Find button. + + First we eliminate any previous search results by setting the + table widgets row count to zero. Then we retrieve the + specified file name, text and directory path from the respective + comboboxes. + + \snippet dialogs/findfiles/window.cpp 4 + + We use the directory's path to create a QDir; the QDir class + provides access to directory structures and their contents. We + create a list of the files (contained in the newly created QDir) + that match the specified file name. If the file name is empty + the list will contain all the files in the directory. + + Then we search through all the files in the list, using the private + \c findFiles() function, eliminating the ones that don't contain + the specified text. And finally, we display the results using the + private \c showFiles() function. + + If the user didn't specify any text, there is no reason to search + through the files, and we display the results immediately. + + \image findfiles_progress_dialog.png Screenshot of the Progress Dialog + + \snippet dialogs/findfiles/window.cpp 5 + + In the private \c findFiles() function we search through a list of + files, looking for the ones that contain a specified text. This + can be a very slow operation depending on the number of files as + well as their sizes. In case there are a large number of files, or + there exists some large files on the list, we provide a + QProgressDialog. + + The QProgressDialog class provides feedback on the progress of a + slow operation. It is used to give the user an indication of how + long an operation is going to take, and to demonstrate that the + application has not frozen. It can also give the user an + opportunity to abort the operation. + + \snippet dialogs/findfiles/window.cpp 6 + + We run through the files, one at a time, and for each file we + update the QProgressDialog value. This property holds the current + amount of progress made. We also update the progress dialog's + label. + + Then we call the QCoreApplication::processEvents() function using + the QApplication object. In this way we interleave the display of + the progress made with the process of searching through the files + so the application doesn't appear to be frozen. + + The QApplication class manages the GUI application's control flow + and main settings. It contains the main event loop, where all + events from the window system and other sources are processed and + dispatched. QApplication inherits QCoreApplication. The + QCoreApplication::processEvents() function processes all pending + events according to the specified QEventLoop::ProcessEventFlags + until there are no more events to process. The default flags are + QEventLoop::AllEvents. + + \snippet dialogs/findfiles/window.cpp 7 + + After updating the QProgressDialog, we create a QFile using the + QDir::absoluteFilePath() function which returns the absolute path + name of a file in the directory. We open the file in read-only + mode, and read one line at a time using QTextStream. + + The QTextStream class provides a convenient interface for reading + and writing text. Using QTextStream's streaming operators, you can + conveniently read and write words, lines and numbers. + + For each line we read we check if the QProgressDialog has been + canceled. If it has, we abort the operation, otherwise we check if + the line contains the specified text. When we find the text within + one of the files, we add the file's name to a list of found files + that contain the specified text, and start searching a new file. + + Finally, we return the list of the files found. + + \snippet dialogs/findfiles/window.cpp 8 + + Both the \c findFiles() and \c showFiles() functions are called from + the \c find() slot. In the \c showFiles() function we run through + the provided list of file names, adding each file name to the + first column in the table widget and retrieving the file's size using + QFile and QFileInfo for the second column. + + We also update the total number of files found. + + \snippet dialogs/findfiles/window.cpp 9 + + The private \c createButton() function is called from the + constructor. We create a QPushButton with the provided text, + connect it to the provided slot, and return a pointer to the + button. + + \snippet dialogs/findfiles/window.cpp 10 + + The private \c createComboBox() function is also called from the + contructor. We create a QComboBox with the given text, and make it + editable. + + When the user enters a new string in an editable combobox, the + widget may or may not insert it, and it can insert it in several + locations, depending on the QComboBox::InsertPolicy. The default + policy is is QComboBox::InsertAtBottom. + + Then we add the provided text to the combobox, and specify the + widget's size policies, before we return a pointer to the + combobox. + + \snippet dialogs/findfiles/window.cpp 11 + + The private \c createFilesTable() function is called from the + constructor. In this function we create the QTableWidget that + will display the search results. We set its horizontal headers and + their resize mode. + + QTableWidget inherits QTableView which provides a default + model/view implementation of a table view. The + QTableView::horizontalHeader() function returns the table view's + horizontal header as a QHeaderView. The QHeaderView class provides + a header row or header column for item views, and the + QHeaderView::setResizeMode() function sets the constraints on how + the section in the header can be resized. + + Finally, we hide the QTableWidget's vertical headers using the + QWidget::hide() function, and remove the default grid drawn for + the table using the QTableView::setShowGrid() function. + + \snippet dialogs/findfiles/window.cpp 12 + + The \c openFileOfItem() slot is invoked when the user double + clicks on a cell in the table. The QDesktopServices::openUrl() + knows how to open a file given the file name. +*/ + diff --git a/examples/widgets/doc/src/flowlayout.qdoc b/examples/widgets/doc/src/flowlayout.qdoc new file mode 100644 index 0000000000..b08b2283aa --- /dev/null +++ b/examples/widgets/doc/src/flowlayout.qdoc @@ -0,0 +1,145 @@ +/**************************************************************************** +** +** 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 layouts/flowlayout + \title Flow Layout Example + + The Flow Layout example demonstrates a custom layout that arranges child + widgets from left to right and top to bottom in a top-level widget. + + \image flowlayout-example.png Screenshot of the Flow Layout example + + The items are first laid out horizontally and then vertically when each line + in the layout runs out of space. + + The Flowlayout class mainly uses QLayout and QWidgetItem, while the + Window uses QWidget and QLabel. We will only document the definition + and implementation of \c FlowLayout below. + + \section1 FlowLayout Class Definition + + The \c FlowLayout class inherits QLayout. It is a custom layout class + that arranges its child widgets horizontally and vertically. + + \snippet layouts/flowlayout/flowlayout.h 0 + + We reimplement functions inherited from QLayout. These functions add items to + the layout and handle their orientation and geometry. + + We also declare two private methods, \c doLayout() and \c smartSpacing(). + \c doLayout() lays out the layout items, while the \c + smartSpacing() function calculates the spacing between them. + + \section1 FlowLayout Class Implementation + + We start off by looking at the constructor: + + \snippet layouts/flowlayout/flowlayout.cpp 1 + + In the constructor we call \c setContentsMargins() to set the left, top, + right and bottom margin. By default, QLayout uses values provided by + the current style (see QStyle::PixelMetric). + + \snippet layouts/flowlayout/flowlayout.cpp 2 + + In this example we reimplement \c addItem(), which is a pure virtual + function. When using \c addItem() the ownership of the layout items is + transferred to the layout, and it is therefore the layout's + responsibility to delete them. + + \snippet layouts/flowlayout/flowlayout.cpp 3 + + \c addItem() is implemented to add items to the layout. + + \snippet layouts/flowlayout/flowlayout.cpp 4 + + We implement \c horizontalSpacing() and \c verticalSpacing() to get + hold of the spacing between the widgets inside the layout. If the value + is less than or equal to 0, this value will be used. If not, + \c smartSpacing() will be called to calculate the spacing. + + \snippet layouts/flowlayout/flowlayout.cpp 5 + + We then implement \c count() to return the number of items in the + layout. To navigate the list of items we use \c itemAt() and + takeAt() to remove and return items from the list. If an item is + removed, the remaining items will be renumbered. All three + functions are pure virtual functions from QLayout. + + \snippet layouts/flowlayout/flowlayout.cpp 6 + + \c expandingDirections() returns the \l{Qt::Orientation}s in which the + layout can make use of more space than its \c sizeHint(). + + \snippet layouts/flowlayout/flowlayout.cpp 7 + + To adjust to widgets of which height is dependent on width, we implement \c + heightForWidth(). The function \c hasHeightForWidth() is used to test for this + dependency, and \c heightForWidth() passes the width on to \c doLayout() which + in turn uses the width as an argument for the layout rect, i.e., the bounds in + which the items are laid out. This rect does not include the layout margin(). + + \snippet layouts/flowlayout/flowlayout.cpp 8 + + \c setGeometry() is normally used to do the actual layout, i.e., calculate + the geometry of the layout's items. In this example, it calls \c doLayout() + and passes the layout rect. + + \c sizeHint() returns the preferred size of the layout and \c minimumSize() + returns the minimum size of the layout. + + \snippet layouts/flowlayout/flowlayout.cpp 9 + + \c doLayout() handles the layout if \c horizontalSpacing() or \c + verticalSpacing() don't return the default value. It uses + \c getContentsMargins() to calculate the area available to the + layout items. + + \snippet layouts/flowlayout/flowlayout.cpp 10 + + It then sets the proper amount of spacing for each widget in the + layout, based on the current style. + + \snippet layouts/flowlayout/flowlayout.cpp 11 + + The position of each item in the layout is then calculated by + adding the items width and the line height to the initial x and y + coordinates. This in turn lets us find out whether the next item + will fit on the current line or if it must be moved down to the next. + We also find the height of the current line based on the widgets height. + + \snippet layouts/flowlayout/flowlayout.cpp 12 + + \c smartSpacing() is designed to get the default spacing for either + the top-level layouts or the sublayouts. The default spacing for + top-level layouts, when the parent is a QWidget, will be determined + by querying the style. The default spacing for sublayouts, when + the parent is a QLayout, will be determined by querying the spacing + of the parent layout. + +*/ diff --git a/examples/widgets/doc/src/fontsampler.qdoc b/examples/widgets/doc/src/fontsampler.qdoc new file mode 100644 index 0000000000..8d7f0e0460 --- /dev/null +++ b/examples/widgets/doc/src/fontsampler.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 painting/fontsampler + \title Font Sampler Example + + The Font Sampler example shows how to preview and print multi-page documents. + + \image fontsampler-example.png +*/ diff --git a/examples/widgets/doc/src/frozencolumn.qdoc b/examples/widgets/doc/src/frozencolumn.qdoc new file mode 100644 index 0000000000..c65ce1d524 --- /dev/null +++ b/examples/widgets/doc/src/frozencolumn.qdoc @@ -0,0 +1,133 @@ +/**************************************************************************** +** +** 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 itemviews/frozencolumn + \title Frozen Column Example + + This example demonstrates how to freeze a column within a QTableView. + + \image frozencolumn-example.png "Screenshot of the example" + + We use Qt's model/view framework to implement a table with its first + column frozen. This technique can be aplied to several columns or rows, + as long as they are on the edge of the table. + + The model/view framework allows for one model to be displayed in different + ways using multiple views. For this example, we use two views on the same + model - two \l {QTableView}{table views} sharing one model. The frozen + column is a child of the main tableview, and we provide the desired visual + effect using an overlay technique which will be described step by step in + the coming sections. + + \image frozencolumn-tableview.png + + + \section1 FreezeTableWidget Class Definition + + The \c FreezeTableWidget class has a constructor and a destructor. Also, it + has two private members: the table view that we will use as an overlay, and + the shared model for both table views. Two slots are added to help keep the + section sizes in sync, as well as a function to readjust the frozen + column's geometry. In addition, we reimplement two functions: + \l{QAbstractItemView::}{resizeEvent()} and \l{QTableView::}{moveCursor()}. + + \snippet itemviews/frozencolumn/freezetablewidget.h Widget definition + + \note QAbstractItemView is \l{QTableView}'s ancestor. + + + \section1 FreezeTableWidget Class Implementation + + The constructor takes \a model as an argument and creates a table view that + we will use to display the frozen column. Then, within the constructor, we + invoke the \c init() function to set up the frozen column. Finally, we + connect the \l{QHeaderView::sectionResized()} signals (for horizontal and + vertical headers) to the appropriate slots. This ensures that our frozen + column's sections are in sync with the headers. We also connect the + vertical scrollbars together so that the frozen column scrolls vertically + with the rest of our table. + + \snippet itemviews/frozencolumn/freezetablewidget.cpp constructor + + + In the \c init() function, we ensure that the overlay table view + responsible for displaying the frozen column, is set up properly. This + means that this table view, \c frozenTableView, has to have the same model + as the main table view. However, the difference here is: \c frozenTableView's + only visible column is its first column; we hide the others using + \l{QTableView::}{setColumnHidden()} + + \snippet itemviews/frozencolumn/freezetablewidget.cpp init part1 + + + In terms of the frozen column's z-order, we stack it on top of the + viewport. This is achieved by calling \l{QWidget::}{stackUnder()} on the + viewport. For appearance's sake, we prevent the column from stealing focus + from the main tableview. Also, we make sure that both views share the same + selection model, so only one cell can be selected at a time. A few other + tweaks are done to make our application look good and behave consistently + with the main tableview. Note that we called \c updateFrozenTableGeometry() + to make the column occupy the correct spot. + + \snippet itemviews/frozencolumn/freezetablewidget.cpp init part2 + + When you resize the frozen column, the same column on the main table view + must resize accordingly, to provide seamless integration. This is + accomplished by getting the new size of the column from the \c newSize + value from the \l{QHeaderView::}{sectionResized()} signal, emitted by both + the horizontal and vertical header. + + \snippet itemviews/frozencolumn/freezetablewidget.cpp sections + + Since the width of the frozen column is modified, we adjust the geometry of + the widget accordingly by invoking \c updateFrozenTableGeometry(). This + function is further explained below. + + In our reimplementation of QTableView::resizeEvent(), we call + \c updateFrozenTableGeometry() after invoking the base class + implementation. + + \snippet itemviews/frozencolumn/freezetablewidget.cpp resize + + When navigating around the table with the keyboard, we need to ensure that + the current selection does not disappear behind the frozen column. To + synchronize this, we reimplement QTableView::moveCursor() and adjust the + scrollbar positions if needed, after calling the base class implementation. + + \snippet itemviews/frozencolumn/freezetablewidget.cpp navigate + + The frozen column's geometry calculation is based on the geometry of the + table underneath, so it always appears in the right place. Using the + QFrame::frameWidth() function helps to calculate this geometry correctly, + no matter which style is used. We rely on the geometry of the viewport and + headers to set the boundaries for the frozen column. + + \snippet itemviews/frozencolumn/freezetablewidget.cpp geometry + +*/ + diff --git a/examples/widgets/doc/src/gradients.qdoc b/examples/widgets/doc/src/gradients.qdoc new file mode 100644 index 0000000000..75f78b56ea --- /dev/null +++ b/examples/widgets/doc/src/gradients.qdoc @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** 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 painting/gradients + \title Gradients + + In this example we show the various types of gradients that can + be used in Qt. + + \image gradients-demo.png + + There are three types of gradients: + + \list + \li \b{Linear} gradients interpolate colors between start and end points. + \li \b{Radial} gradients interpolate colors between a focal point and the + points on a circle surrounding it. + \li \b{Conical} gradients interpolate colors around a center point. + \endlist + + The panel on the right contains a color table editor that defines + the colors in the gradient. The three topmost controls determine the red, + green and blue components while the last defines the alpha of the + gradient. You can move points, and add new ones, by clicking with the left + mouse button, and remove points by clicking with the right button. + + There are three default configurations available at the bottom of + the page that are provided as suggestions on how a color table could be + configured. +*/ diff --git a/examples/widgets/doc/src/groupbox.qdoc b/examples/widgets/doc/src/groupbox.qdoc new file mode 100644 index 0000000000..d7384d409a --- /dev/null +++ b/examples/widgets/doc/src/groupbox.qdoc @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** 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/groupbox + \title Group Box Example + + The Group Box example shows how to use the different kinds of group + boxes in Qt. + + Group boxes are container widgets that organize buttons into groups, + both logically and on screen. They manage the interactions between + the user and the application so that you do not have to enforce + simple constraints. + + Group boxes are usually used to organize check boxes and radio + buttons into exclusive groups. + + \image groupbox-example.png + + The Group Boxes example consists of a single \c Window class that + is used to show four group boxes: an exclusive radio button group, + a non-exclusive checkbox group, an exclusive radio button group + with an enabling checkbox, and a group box with normal push buttons. + + \section1 Window Class Definition + + The \c Window class is a subclass of \c QWidget that is used to + display a number of group boxes. The class definition contains + functions to construct each group box and populate it with different + selections of button widgets: + + \snippet widgets/groupbox/window.h 0 + + In the example, the widget will be used as a top-level window, so + the constructor is defined so that we do not have to specify a parent + widget. + + \section1 Window Class Implementation + + The constructor creates a grid layout and fills it with each of the + group boxes that are to be displayed: + + \snippet widgets/groupbox/window.cpp 0 + + The functions used to create each group box each return a + QGroupBox to be inserted into the grid layout. + + \snippet widgets/groupbox/window.cpp 1 + + The first group box contains and manages three radio buttons. Since + the group box contains only radio buttons, it is exclusive by + default, so only one radio button can be checked at any given time. + We check the first radio button to ensure that the button group + contains one checked button. + + \snippet widgets/groupbox/window.cpp 3 + + We use a vertical layout within the group box to present the + buttons in the form of a vertical list, and return the group + box to the constructor. + + The second group box is itself checkable, providing a convenient + way to disable all the buttons inside it. Initially, it is + unchecked, so the group box itself must be checked before any of + the radio buttons inside can be checked. + + \snippet widgets/groupbox/window.cpp 4 + + The group box contains three exclusive radio buttons, and an + independent checkbox. For consistency, one radio button must be + checked at all times, so we ensure that the first one is initially + checked. + + \snippet widgets/groupbox/window.cpp 5 + + The buttons are arranged in the same way as those in the first + group box. + + \snippet widgets/groupbox/window.cpp 6 + + The third group box is constructed with a "flat" style that is + better suited to certain types of dialog. + + \snippet widgets/groupbox/window.cpp 7 + + This group box contains only checkboxes, so it is non-exclusive by + default. This means that each checkbox can be checked independently + of the others. + + \snippet widgets/groupbox/window.cpp 8 + + Again, we use a vertical layout within the group box to present + the buttons in the form of a vertical list. + + \snippet widgets/groupbox/window.cpp 9 + + The final group box contains only push buttons and, like the + second group box, it is checkable. + + \snippet widgets/groupbox/window.cpp 10 + + We create a normal button, a toggle button, and a flat push button: + + \snippet widgets/groupbox/window.cpp 11 + + Push buttons can be used to display popup menus. We create one, and + attach a simple menu to it: + + \snippet widgets/groupbox/window.cpp 12 + + Finally, we lay out the widgets vertically, and return the group box + that we created: + + \snippet widgets/groupbox/window.cpp 13 +*/ diff --git a/examples/widgets/doc/src/icons.qdoc b/examples/widgets/doc/src/icons.qdoc new file mode 100644 index 0000000000..b6625db005 --- /dev/null +++ b/examples/widgets/doc/src/icons.qdoc @@ -0,0 +1,787 @@ +/**************************************************************************** +** +** 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/icons + \title Icons Example + + The Icons example shows how QIcon can generate pixmaps reflecting + an icon's state, mode and size. These pixmaps are generated from + the set of pixmaps made available to the icon, and are used by Qt + widgets to show an icon representing a particular action. + + \image icons-example.png Screenshot of the Icons example + + Contents: + + \tableofcontents + + \section1 QIcon Overview + + The QIcon class provides scalable icons in different modes and + states. An icon's state and mode are depending on the intended use + of the icon. Qt currently defines four modes: + + \table + \header \li Mode \li Description + \row + \li QIcon::Normal + \li Display the pixmap when the user is not interacting with the + icon, but the functionality represented by the icon is + available. + \row + \li QIcon::Active + \li Display the pixmap when the functionality represented by the + icon is available and the user is interacting with the icon, + for example, moving the mouse over it or clicking it. + \row + \li QIcon::Disabled + \li Display the pixmap when the functionality represented by + the icon is not available. + \row + \li QIcon::Selected + \li Display the pixmap when the icon is selected. + \endtable + + QIcon's states are QIcon::On and QIcon::Off, which will display + the pixmap when the widget is in the respective state. The most + common usage of QIcon's states are when displaying checkable tool + buttons or menu entries (see QAbstractButton::setCheckable() and + QAction::setCheckable()). When a tool button or menu entry is + checked, the QIcon's state is \l{QIcon::}{On}, otherwise it's + \l{QIcon::}{Off}. You can, for example, use the QIcon's states to + display differing pixmaps depending on whether the tool button or + menu entry is checked or not. + + A QIcon can generate smaller, larger, active, disabled, and + selected pixmaps from the set of pixmaps it is given. Such + pixmaps are used by Qt widgets to show an icon representing a + particular action. + + \section1 Overview of the Icons Application + + With the Icons application you get a preview of an icon's + generated pixmaps reflecting its different states, modes and size. + + When an image is loaded into the application, it is converted into + a pixmap and becomes a part of the set of pixmaps available to the + icon. An image can be excluded from this set by checking off the + related checkbox. The application provides a sub directory + containing sets of images explicitly designed to illustrate how Qt + renders an icon in different modes and states. + + The application allows you to manipulate the icon size with some + predefined sizes and a spin box. The predefined sizes are style + dependent, but most of the styles have the same values: Only the + Macintosh style differ by using 32 pixels, instead of 16 pixels, + for toolbar buttons. You can navigate between the available styles + using the \uicontrol View menu. + + \image icons-view-menu.png Screenshot of the View menu + + The \uicontrol View menu also provide the option to make the application + guess the icon state and mode from an image's file name. The \uicontrol + File menu provide the options of adding an image and removing all + images. These last options are also available through a context + menu that appears if you press the right mouse button within the + table of image files. In addition, the \uicontrol File menu provide an + \uicontrol Exit option, and the \uicontrol Help menu provide information about + the example and about Qt. + + \image icons_find_normal.png Screenshot of the Find Files + + The screenshot above shows the application with one image file + loaded. The \uicontrol {Guess Image Mode/State} is enabled and the + style is Plastique. + + When QIcon is provided with only one available pixmap, that + pixmap is used for all the states and modes. In this case the + pixmap's icon mode is set to normal, and the generated pixmaps + for the normal and active modes will look the same. But in + disabled and selected mode, Qt will generate a slightly different + pixmap. + + The next screenshot shows the application with an additional file + loaded, providing QIcon with two available pixmaps. Note that the + new image file's mode is set to disabled. When rendering the \uicontrol + Disabled mode pixmaps, Qt will now use the new image. We can see + the difference: The generated disabled pixmap in the first + screenshot is slightly darker than the pixmap with the originally + set disabled mode in the second screenshot. + + \image icons_find_normal_disabled.png Screenshot of the Find Files + + When Qt renders the icon's pixmaps it searches through the set of + available pixmaps following a particular algorithm. The algorithm + is documented in QIcon, but we will describe some particular cases + below. + + \image icons_monkey_active.png Screenshot of the Find Files + + In the screenshot above, we have set \c monkey_on_32x32 to be an + Active/On pixmap and \c monkey_off_64x64 to be Normal/Off. To + render the other six mode/state combinations, QIcon uses the + search algorithm described in the table below: + + \table 100% + \header \li{2,1} Requested Pixmap \li {8,1} Preferred Alternatives (mode/state) + \header \li Mode \li State \li 1 \li 2 \li 3 \li 4 \li 5 \li 6 \li 7 \li 8 + \row \li{1,2} Normal \li Off \li \b N0 \li A0 \li N1 \li A1 \li D0 \li S0 \li D1 \li S1 + \row \li On \li N1 \li \b A1 \li N0 \li A0 \li D1 \li S1 \li D0 \li S0 + \row \li{1,2} Active \li Off \li A0 \li \b N0 \li A1 \li N1 \li D0 \li S0 \li D1 \li S1 + \row \li On \li \b A1 \li N1 \li A0 \li N0 \li D1 \li S1 \li D0 \li S0 + \row \li{1,2} Disabled \li Off \li D0 \li \b {N0'} \li A0' \li D1 \li N1' \li A1' \li S0' \li S1' + \row \li On \li D1 \li N1' \li \b {A1'} \li D0 \li N0' \li A0' \li S1' \li S0' + \row \li{1,2} Selected \li Off \li S0 \li \b {N0''} \li A0'' \li S1 \li N1'' \li A1'' \li D0'' \li D1'' + \row \li On \li S1 \li N1'' \li \b {A1''} \li S0 \li N0'' \li A0'' \li D1'' \li D0'' + \endtable + + In the table, "0" and "1" stand for Off" and "On", respectively. + Single quotes indicates that QIcon generates a disabled ("grayed + out") version of the pixmap; similarly, double quuote indicate + that QIcon generates a selected ("blued out") version of the + pixmap. + + The alternatives used in the screenshot above are shown in bold. + For example, the Disabled/Off pixmap is derived by graying out + the Normal/Off pixmap (\c monkey_off_64x64). + + In the next screenshots, we loaded the whole set of monkey + images. By checking or unchecking file names from the image list, + we get different results: + + \table + \row + \li \inlineimage icons_monkey.png Screenshot of the Monkey Files + \li \inlineimage icons_monkey_mess.png Screenshot of the Monkey Files + \endtable + + For any given mode/state combination, it is possible to specify + several images at different resolutions. When rendering an + icon, QIcon will automatically pick the most suitable image + and scale it down if necessary. (QIcon never scales up images, + because this rarely looks good.) + + The screenshots below shows what happens when we provide QIcon + with three images (\c qt_extended_16x16.png, \c qt_extended_32x32.png, \c + qt_extended_48x48.png) and try to render the QIcon at various + resolutions: + + \table + \row + \li + \li \inlineimage icons_qt_extended_8x8.png Qt Extended icon at 8 x 8 + \li \inlineimage icons_qt_extended_16x16.png Qt Extended icon at 16 x 16 + \li \inlineimage icons_qt_extended_17x17.png Qt Extended icon at 17 x 17 + \row + \li + \li 8 x 8 + \li \b {16 x 16} + \li 17 x 17 + \row + \li \inlineimage icons_qt_extended_32x32.png Qt Extended icon at 32 x 32 + \li \inlineimage icons_qt_extended_33x33.png Qt Extended icon at 33 x 33 + \li \inlineimage icons_qt_extended_48x48.png Qt Extended icon at 48 x 48 + \li \inlineimage icons_qt_extended_64x64.png Qt Extended icon at 64 x 64 + \row + \li \b {32 x 32} + \li 33 x 33 + \li \b {48 x 48} + \li 64 x 64 + \endtable + + For sizes up to 16 x 16, QIcon uses \c qt_extended_16x16.png and + scales it down if necessary. For sizes between 17 x 17 and 32 x + 32, it uses \c qt_extended_32x32.png. For sizes above 32 x 32, it uses + \c qt_extended_48x48.png. + + \section1 Line-by-Line Walkthrough + + The Icons example consists of four classes: + + \list + \li \c MainWindow inherits QMainWindow and is the main application + window. + \li \c IconPreviewArea is a custom widget that displays all + combinations of states and modes for a given icon. + \li \c IconSizeSpinBox is a subclass of QSpinBox that lets the + user enter icon sizes (e.g., "48 x 48"). + \li \c ImageDelegate is a subclass of QItemDelegate that provides + comboboxes for letting the user set the mode and state + associated with an image. + \endlist + + We will start by reviewing the \c IconPreviewArea class before we + take a look at the \c MainWindow class. Finally, we will review the + \c IconSizeSpinBox and \c ImageDelegate classes. + + \section2 IconPreviewArea Class Definition + + An \c IconPreviewArea widget consists of a group box containing a grid of + QLabel widgets displaying headers and pixmaps. + + \image icons_preview_area.png Screenshot of IconPreviewArea. + + \snippet widgets/icons/iconpreviewarea.h 0 + + The \c IconPreviewArea class inherits QWidget. It displays the + generated pixmaps corresponding to an icon's possible states and + modes at a given size. + + We need two public functions to set the current icon and the + icon's size. In addition the class has three private functions: We + use the \c createHeaderLabel() and \c createPixmapLabel() + functions when constructing the preview area, and we need the \c + updatePixmapLabels() function to update the preview area when + the icon or the icon's size has changed. + + The \c NumModes and \c NumStates constants reflect \l{QIcon}'s + number of currently defined modes and states. + + \section2 IconPreviewArea Class Implementation + + \snippet widgets/icons/iconpreviewarea.cpp 0 + + In the constructor we create the labels displaying the headers and + the icon's generated pixmaps, and add them to a grid layout. + + When creating the header labels, we make sure the enums \c + NumModes and \c NumStates defined in the \c .h file, correspond + with the number of labels that we create. Then if the enums at + some point are changed, the \c Q_ASSERT() macro will alert that this + part of the \c .cpp file needs to be updated as well. + + If the application is built in debug mode, the \c Q_ASSERT() + macro will expand to + + \code + if (!condition) + qFatal("ASSERT: "condition" in file ..."); + \endcode + + In release mode, the macro simply disappear. The mode can be set + in the application's \c .pro file. One way to do so is to add an + option to \c qmake when building the application: + + \code + qmake "CONFIG += debug" icons.pro + \endcode + + or + + \code + qmake "CONFIG += release" icons.pro + \endcode + + Another approach is to add this line directly to the \c .pro + file. + + \snippet widgets/icons/iconpreviewarea.cpp 1 + \codeline + \snippet widgets/icons/iconpreviewarea.cpp 2 + + The public \c setIcon() and \c setSize() functions change the icon + or the icon size, and make sure that the generated pixmaps are + updated. + + \snippet widgets/icons/iconpreviewarea.cpp 3 + \codeline + \snippet widgets/icons/iconpreviewarea.cpp 4 + + We use the \c createHeaderLabel() and \c createPixmapLabel() + functions to create the preview area's labels displaying the + headers and the icon's generated pixmaps. Both functions return + the QLabel that is created. + + \snippet widgets/icons/iconpreviewarea.cpp 5 + + We use the private \c updatePixmapLabel() function to update the + generated pixmaps displayed in the preview area. + + For each mode, and for each state, we retrieve a pixmap using the + QIcon::pixmap() function, which generates a pixmap corresponding + to the given state, mode and size. + + \section2 MainWindow Class Definition + + The \c MainWindow widget consists of three main elements: an + images group box, an icon size group box and a preview area. + + \image icons-example.png Screenshot of the Icons example + + \snippet widgets/icons/mainwindow.h 0 + + The MainWindow class inherits from QMainWindow. We reimplement the + constructor, and declare several private slots: + + \list + \li The \c about() slot simply provides information about the example. + \li The \c changeStyle() slot changes the application's GUI style and + adjust the style dependent size options. + \li The \c changeSize() slot changes the size of the preview area's icon. + \li The \c changeIcon() slot updates the set of pixmaps available to the + icon displayed in the preview area. + \li The \c addImage() slot allows the user to load a new image into the + application. + \endlist + + In addition we declare several private functions to simplify the + constructor. + + \section2 MainWindow Class Implementation + + \snippet widgets/icons/mainwindow.cpp 0 + + In the constructor we first create the main window's central + widget and its child widgets, and put them in a grid layout. Then + we create the menus with their associated entries and actions. + + Before we resize the application window to a suitable size, we set + the window title and determine the current style for the + application. We also enable the icon size spin box by clicking the + associated radio button, making the current value of the spin box + the icon's initial size. + + \snippet widgets/icons/mainwindow.cpp 1 + + The \c about() slot displays a message box using the static + QMessageBox::about() function. In this example it displays a + simple box with information about the example. + + The \c about() function looks for a suitable icon in four + locations: It prefers its parent's icon if that exists. If it + doesn't, the function tries the top-level widget containing + parent, and if that fails, it tries the active window. As a last + resort it uses the QMessageBox's Information icon. + + \snippet widgets/icons/mainwindow.cpp 2 + + In the \c changeStyle() slot we first check the slot's + parameter. If it is false we immediately return, otherwise we find + out which style to change to, i.e. which action that triggered the + slot, using the QObject::sender() function. + + This function returns the sender as a QObject pointer. Since we + know that the sender is a QAction object, we can safely cast the + QObject. We could have used a C-style cast or a C++ \c + static_cast(), but as a defensive programming technique we use a + \l qobject_cast(). The advantage is that if the object has the + wrong type, a null pointer is returned. Crashes due to null + pointers are much easier to diagnose than crashes due to unsafe + casts. + + \snippet widgets/icons/mainwindow.cpp 3 + \snippet widgets/icons/mainwindow.cpp 4 + + Once we have the action, we extract the style name using + QAction::data(). Then we create a QStyle object using the static + QStyleFactory::create() function. + + Although we can assume that the style is supported by the + QStyleFactory: To be on the safe side, we use the \c Q_ASSERT() + macro to check if the created style is valid before we use the + QApplication::setStyle() function to set the application's GUI + style to the new style. QApplication will automatically delete + the style object when a new style is set or when the application + exits. + + The predefined icon size options provided in the application are + style dependent, so we need to update the labels in the icon size + group box and in the end call the \c changeSize() slot to update + the icon's size. + + \snippet widgets/icons/mainwindow.cpp 5 + + The \c changeSize() slot sets the size for the preview area's + icon. + + To determine the new size we first check if the spin box is + enabled. If it is, we extract the extent of the new size from the + box. If it's not, we search through the predefined size options, + extract the QStyle::PixelMetric and use the QStyle::pixelMetric() + function to determine the extent. Then we create a QSize object + based on the extent, and use that object to set the size of the + preview area's icon. + + \snippet widgets/icons/mainwindow.cpp 12 + + The first thing we do when the \c addImage() slot is called, is to + show a file dialog to the user. The easiest way to create a file + dialog is to use QFileDialog's static functions. Here we use the + \l {QFileDialog::getOpenFileNames()}{getOpenFileNames()} function + that will return one or more existing files selected by the user. + + For each of the files the file dialog returns, we add a row to the + table widget. The table widget is listing the images the user has + loaded into the application. + + \snippet widgets/icons/mainwindow.cpp 13 + \snippet widgets/icons/mainwindow.cpp 14 + + We retrieve the image name using the QFileInfo::baseName() + function that returns the base name of the file without the path, + and create the first table widget item in the row. Then we add the + file's complete name to the item's data. Since an item can hold + several information pieces, we need to assign the file name a role + that will distinguish it from other data. This role can be Qt::UserRole + or any value above it. + + We also make sure that the item is not editable by removing the + Qt::ItemIsEditable flag. Table items are editable by default. + + \snippet widgets/icons/mainwindow.cpp 15 + \snippet widgets/icons/mainwindow.cpp 16 + \snippet widgets/icons/mainwindow.cpp 17 + + Then we create the second and third items in the row making the + default mode Normal and the default state Off. But if the \uicontrol + {Guess Image Mode/State} option is checked, and the file name + contains "_act", "_dis", or "_sel", the modes are changed to + Active, Disabled, or Selected. And if the file name contains + "_on", the state is changed to On. The sample files in the + example's \c images subdirectory respect this naming convension. + + \snippet widgets/icons/mainwindow.cpp 18 + \snippet widgets/icons/mainwindow.cpp 19 + + In the end we add the items to the associated row, and use the + QTableWidget::openPersistentEditor() function to create + comboboxes for the mode and state columns of the items. + + Due to the connection between the table widget's \l + {QTableWidget::itemChanged()}{itemChanged()} signal and the \c + changeIcon() slot, the new image is automatically converted into a + pixmap and made part of the set of pixmaps available to the icon + in the preview area. So, corresponding to this fact, we need to + make sure that the new image's check box is enabled. + + \snippet widgets/icons/mainwindow.cpp 6 + \snippet widgets/icons/mainwindow.cpp 7 + + The \c changeIcon() slot is called when the user alters the set + of images listed in the QTableWidget, to update the QIcon object + rendered by the \c IconPreviewArea. + + We first create a QIcon object, and then we run through the + QTableWidget, which lists the images the user has loaded into the + application. + + \snippet widgets/icons/mainwindow.cpp 8 + \snippet widgets/icons/mainwindow.cpp 9 + \snippet widgets/icons/mainwindow.cpp 10 + + We also extract the image file's name using the + QTableWidgetItem::data() function. This function takes a + Qt::DataItemRole as an argument to retrieve the right data + (remember that an item can hold several pieces of information) + and returns it as a QVariant. Then we use the + QVariant::toString() function to get the file name as a QString. + + To create a pixmap from the file, we need to first create an + image and then convert this image into a pixmap using + QPixmap::fromImage(). Once we have the final pixmap, we add it, + with its associated mode and state, to the QIcon's set of + available pixmaps. + + \snippet widgets/icons/mainwindow.cpp 11 + + After running through the entire list of images, we change the + icon of the preview area to the one we just created. + + \snippet widgets/icons/mainwindow.cpp 20 + + In the \c removeAllImages() slot, we simply set the table widget's + row count to zero, automatically removing all the images the user + has loaded into the application. Then we update the set of pixmaps + available to the preview area's icon using the \c changeIcon() + slot. + + \image icons_images_groupbox.png Screenshot of the images group box + + The \c createImagesGroupBox() function is implemented to simplify + the constructor. The main purpose of the function is to create a + QTableWidget that will keep track of the images the user has + loaded into the application. + + \snippet widgets/icons/mainwindow.cpp 21 + + First we create a group box that will contain the table widget. + Then we create a QTableWidget and customize it to suit our + purposes. + + We call QAbstractItemView::setSelectionMode() to prevent the user + from selecting items. + + The QAbstractItemView::setItemDelegate() call sets the item + delegate for the table widget. We create a \c ImageDelegate that + we make the item delegate for our view. + + The QItemDelegate class can be used to provide an editor for an item view + class that is subclassed from QAbstractItemView. Using a delegate + for this purpose allows the editing mechanism to be customized and + developed independently from the model and view. + + In this example we derive \c ImageDelegate from QItemDelegate. + QItemDelegate usually provides line editors, while our subclass + \c ImageDelegate, provides comboboxes for the mode and state + fields. + + \snippet widgets/icons/mainwindow.cpp 22 + \snippet widgets/icons/mainwindow.cpp 23 + + Then we customize the QTableWidget's horizontal header, and hide + the vertical header. + + \snippet widgets/icons/mainwindow.cpp 24 + \snippet widgets/icons/mainwindow.cpp 25 + + At the end, we connect the QTableWidget::itemChanged() signal to + the \c changeIcon() slot to ensuret that the preview area is in + sync with the image table. + + \image icons_size_groupbox.png Screenshot of the icon size group box + + The \c createIconSizeGroupBox() function is called from the + constructor. It creates the widgets controlling the size of the + preview area's icon. + + \snippet widgets/icons/mainwindow.cpp 26 + + First we create a group box that will contain all the widgets; + then we create the radio buttons and the spin box. + + The spin box is not a regular QSpinBox but an \c IconSizeSpinBox. + The \c IconSizeSpinBox class inherits QSpinBox and reimplements + two functions: QSpinBox::textFromValue() and + QSpinBox::valueFromText(). The \c IconSizeSpinBox is designed to + handle icon sizes, e.g., "32 x 32", instead of plain integer + values. + + \snippet widgets/icons/mainwindow.cpp 27 + + Then we connect all of the radio buttons + \l{QRadioButton::toggled()}{toggled()} signals and the spin box's + \l {QSpinBox::valueChanged()}{valueChanged()} signal to the \c + changeSize() slot to make sure that the size of the preview + area's icon is updated whenever the user changes the icon size. + In the end we put the widgets in a layout that we install on the + group box. + + \snippet widgets/icons/mainwindow.cpp 28 + + In the \c createActions() function we create and customize all the + actions needed to implement the functionality associated with the + menu entries in the application. + + In particular we create the \c styleActionGroup based on the + currently available GUI styles using + QStyleFactory. QStyleFactory::keys() returns a list of valid keys, + typically including "windows", "motif", "cde", and + "plastique". Depending on the platform, "windowsxp" and + "macintosh" may be available. + + We create one action for each key, and adds the action to the + action group. Also, for each action, we call QAction::setData() + with the style name. We will retrieve it later using + QAction::data(). + + \snippet widgets/icons/mainwindow.cpp 29 + + In the \c createMenu() function, we add the previously created + actions to the \uicontrol File, \uicontrol View and \uicontrol Help menus. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus. We put each menu in the + application's menu bar, which we retrieve using + QMainWindow::menuBar(). + + \snippet widgets/icons/mainwindow.cpp 30 + + QWidgets have a \l{QWidget::contextMenuPolicy}{contextMenuPolicy} + property that controls how the widget should behave when the user + requests a context menu (e.g., by right-clicking). We set the + QTableWidget's context menu policy to Qt::ActionsContextMenu, + meaning that the \l{QAction}s associated with the widget should + appear in its context menu. + + Then we add the \uicontrol{Add Image} and \uicontrol{Remove All Images} + actions to the table widget. They will then appear in the table + widget's context menu. + + \snippet widgets/icons/mainwindow.cpp 31 + + In the \c checkCurrentStyle() function we go through the group of + style actions, looking for the current GUI style. + + For each action, we first extract the style name using + QAction::data(). Since this is only a QStyleFactory key (e.g., + "macintosh"), we cannot compare it directly to the current + style's class name. We need to create a QStyle object using the + static QStyleFactory::create() function and compare the class + name of the created QStyle object with that of the current style. + As soon as we are done with a QStyle candidate, we delete it. + + For all QObject subclasses that use the \c Q_OBJECT macro, the + class name of an object is available through its + \l{QObject::metaObject()}{meta-object}. + + We can assume that the style is supported by + QStyleFactory, but to be on the safe side we use the \c + Q_ASSERT() macro to make sure that QStyleFactory::create() + returned a valid pointer. + + \section2 IconSizeSpinBox Class Definition + + \snippet widgets/icons/iconsizespinbox.h 0 + + The \c IconSizeSpinBox class is a subclass of QSpinBox. A plain + QSpinBox can only handle integers. But since we want to display + the spin box's values in a more sophisticated way, we need to + subclass QSpinBox and reimplement the QSpinBox::textFromValue() + and QSpinBox::valueFromText() functions. + + \image icons_size_spinbox.png Screenshot of the icon size spinbox + + \section2 IconSizeSpinBox Class Implementation + + \snippet widgets/icons/iconsizespinbox.cpp 0 + + The constructor is trivial. + + \snippet widgets/icons/iconsizespinbox.cpp 2 + + QSpinBox::textFromValue() is used by the spin box whenever it + needs to display a value. The default implementation returns a + base 10 representation of the \c value parameter. + + Our reimplementation returns a QString of the form "32 x 32". + + \snippet widgets/icons/iconsizespinbox.cpp 1 + + The QSpinBox::valueFromText() function is used by the spin box + whenever it needs to interpret text typed in by the user. Since + we reimplement the \c textFromValue() function we also need to + reimplement the \c valueFromText() function to interpret the + parameter text and return the associated int value. + + We parse the text using a regular expression (a QRegExp). We + define an expression that matches one or several digits, + optionally followed by whitespace, an "x" or the times symbol, + whitespace and one or several digits again. + + The first digits of the regular expression are captured using + parentheses. This enables us to use the QRegExp::cap() or + QRegExp::capturedTexts() functions to extract the matched + characters. If the first and second numbers of the spin box value + differ (e.g., "16 x 24"), we use the first number. + + When the user presses \uicontrol Enter, QSpinBox first calls + QSpinBox::valueFromText() to interpret the text typed by the + user, then QSpinBox::textFromValue() to present it in a canonical + format (e.g., "16 x 16"). + + \section2 ImageDelegate Class Definition + + \snippet widgets/icons/imagedelegate.h 0 + + The \c ImageDelegate class is a subclass of QItemDelegate. The + QItemDelegate class provides display and editing facilities for + data items from a model. A single QItemDelegate object is + responsible for all items displayed in a item view (in our case, + a QTableWidget). + + A QItemDelegate can be used to provide an editor for an item view + class that is subclassed from QAbstractItemView. Using a delegate + for this purpose allows the editing mechanism to be customized and + developed independently from the model and view. + + \snippet widgets/icons/imagedelegate.h 1 + + The default implementation of QItemDelegate creates a QLineEdit. + Since we want the editor to be a QComboBox, we need to subclass + QItemDelegate and reimplement the QItemDelegate::createEditor(), + QItemDelegate::setEditorData() and QItemDelegate::setModelData() + functions. + + \snippet widgets/icons/imagedelegate.h 2 + + The \c emitCommitData() slot is used to emit the + QImageDelegate::commitData() signal with the appropriate + argument. + + \section2 ImageDelegate Class Implementation + + \snippet widgets/icons/imagedelegate.cpp 0 + + The constructor is trivial. + + \snippet widgets/icons/imagedelegate.cpp 1 + + The default QItemDelegate::createEditor() implementation returns + the widget used to edit the item specified by the model and item + index for editing. The parent widget and style option are used to + control the appearance of the editor widget. + + Our reimplementation create and populate a combobox instead of + the default line edit. The contents of the combobox depends on + the column in the table for which the editor is requested. Column + 1 contains the QIcon modes, whereas column 2 contains the QIcon + states. + + In addition, we connect the combobox's \l + {QComboBox::activated()}{activated()} signal to the \c + emitCommitData() slot to emit the + QAbstractItemDelegate::commitData() signal whenever the user + chooses an item using the combobox. This ensures that the rest of + the application notices the change and updates itself. + + \snippet widgets/icons/imagedelegate.cpp 2 + + The QItemDelegate::setEditorData() function is used by + QTableWidget to transfer data from a QTableWidgetItem to the + editor. The data is stored as a string; we use + QComboBox::findText() to locate it in the combobox. + + Delegates work in terms of models, not items. This makes it + possible to use them with any item view class (e.g., QListView, + QListWidget, QTreeView, etc.). The transition between model and + items is done implicitly by QTableWidget; we don't need to worry + about it. + + \snippet widgets/icons/imagedelegate.cpp 3 + + The QItemDelegate::setEditorData() function is used by QTableWidget + to transfer data back from the editor to the \l{QTableWidgetItem}. + + \snippet widgets/icons/imagedelegate.cpp 4 + + The \c emitCommitData() slot simply emit the + QAbstractItemDelegate::commitData() signal for the editor that + triggered the slot. This signal must be emitted when the editor + widget has completed editing the data, and wants to write it back + into the model. +*/ diff --git a/examples/widgets/doc/src/imagecomposition.qdoc b/examples/widgets/doc/src/imagecomposition.qdoc new file mode 100644 index 0000000000..3f06f377b4 --- /dev/null +++ b/examples/widgets/doc/src/imagecomposition.qdoc @@ -0,0 +1,165 @@ +/**************************************************************************** +** +** 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 painting/imagecomposition + \title Image Composition Example + + The Image Composition example lets the user combine images + together using any composition mode supported by QPainter, described + in detail in \l{QPainter#Composition Modes}{Composition Modes}. + + \image imagecomposition-example.png + + \section1 Setting Up The Resource File + + The Image Composition example requires two source images, + \e butterfly.png and \e checker.png that are embedded within + \e imagecomposition.qrc. The file contains the following code: + + \quotefile painting/imagecomposition/imagecomposition.qrc + + For more information on resource files, see \l{The Qt Resource System}. + + \section1 ImageComposer Class Definition + + The \c ImageComposer class is a subclass of QWidget that implements three + private slots, \c chooseSource(), \c chooseDestination(), and + \c recalculateResult(). + + \snippet painting/imagecomposition/imagecomposer.h 0 + + In addition, \c ImageComposer consists of five private functions, + \c addOp(), \c chooseImage(), \c loadImage(), \c currentMode(), and + \c imagePos(), as well as private instances of QToolButton, QComboBox, + QLabel, and QImage. + + \snippet painting/imagecomposition/imagecomposer.h 1 + + \section1 ImageComposer Class Implementation + + We declare a QSize object, \c resultSize, as a static constant with width + and height equal to 200. + + \snippet painting/imagecomposition/imagecomposer.cpp 0 + + Within the constructor, we instantiate a QToolButton object, + \c sourceButton and set its \l{QAbstractButton::setIconSize()}{iconSize} + property to \c resultSize. The \c operatorComboBox is instantiated and + then populated using the \c addOp() function. This function accepts a + QPainter::CompositionMode, \a mode, and a QString, \a name, representing + the name of the composition mode. + + \snippet painting/imagecomposition/imagecomposer.cpp 1 + + The \c destinationButton is instantiated and its + \l{QAbstractButton::setIconSize()}{iconSize} property is set to + \c resultSize as well. The \l{QLabel}s \c equalLabel and \c resultLabel + are created and \c{resultLabel}'s \l{QWidget::setMinimumWidth()} + {minimumWidth} is set. + + \snippet painting/imagecomposition/imagecomposer.cpp 2 + + We connect the following signals to their corresponding slots: + \list + \li \c{sourceButton}'s \l{QPushButton::clicked()}{clicked()} signal is + connected to \c chooseSource(), + \li \c{operatorComboBox}'s \l{QComboBox::activated()}{activated()} + signal is connected to \c recalculateResult(), and + \li \c{destinationButton}'s \l{QToolButton::clicked()}{clicked()} signal + is connected to \c chooseDestination(). + \endlist + + \snippet painting/imagecomposition/imagecomposer.cpp 3 + + A QGridLayout, \c mainLayout, is used to place all the widgets. Note + that \c{mainLayout}'s \l{QLayout::setSizeConstraint()}{sizeConstraint} + property is set to QLayout::SetFixedSize, which means that + \c{ImageComposer}'s size cannot be resized at all. + + \snippet painting/imagecomposition/imagecomposer.cpp 4 + + We create a QImage, \c resultImage, and we invoke \c loadImage() twice + to load both the image files in our \e imagecomposition.qrc file. Then, + we set the \l{QWidget::setWindowTitle()}{windowTitle} property to + "Image Composition". + + \snippet painting/imagecomposition/imagecomposer.cpp 5 + + The \c chooseSource() and \c chooseDestination() functions are + convenience functions that invoke \c chooseImage() with specific + parameters. + + \snippet painting/imagecomposition/imagecomposer.cpp 6 + \codeline + \snippet painting/imagecomposition/imagecomposer.cpp 7 + + The \c chooseImage() function loads an image of the user's choice, + depending on the \a title, \a image, and \a button. + + \snippet painting/imagecomposition/imagecomposer.cpp 10 + + The \c recalculateResult() function is used to calculate amd display the + result of combining the two images together with the user's choice of + composition mode. + + \snippet painting/imagecomposition/imagecomposer.cpp 8 + + The \c addOp() function adds an item to the \c operatorComboBox using + \l{QComboBox}'s \l{QComboBox::addItem()}{addItem} function. This function + accepts a QPainter::CompositionMode, \a mode, and a QString, \a name. The + rectangle is filled with Qt::Transparent and both the \c sourceImage and + \c destinationImage are painted, before displaying it on \c resultLabel. + + \snippet painting/imagecomposition/imagecomposer.cpp 9 + + The \c loadImage() function paints a transparent background using + \l{QPainter::fillRect()}{fillRect()} and draws \c image in a + centralized position using \l{QPainter::drawImage()}{drawImage()}. + This \c image is then set as the \c{button}'s icon. + + \snippet painting/imagecomposition/imagecomposer.cpp 11 + + The \c currentMode() function returns the composition mode currently + selected in \c operatorComboBox. + + \snippet painting/imagecomposition/imagecomposer.cpp 12 + + We use the \c imagePos() function to ensure that images loaded onto the + QToolButton objects, \c sourceButton and \c destinationButton, are + centralized. + + \snippet painting/imagecomposition/imagecomposer.cpp 13 + + \section1 The \c main() Function + + The \c main() function instantiates QApplication and \c ImageComposer + and invokes its \l{QWidget::show()}{show()} function. + + \snippet painting/imagecomposition/main.cpp 0 + + */ diff --git a/examples/widgets/doc/src/imageviewer.qdoc b/examples/widgets/doc/src/imageviewer.qdoc new file mode 100644 index 0000000000..3556d52f7e --- /dev/null +++ b/examples/widgets/doc/src/imageviewer.qdoc @@ -0,0 +1,337 @@ +/**************************************************************************** +** +** 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/imageviewer + \title Image Viewer Example + + The example shows how to combine QLabel and QScrollArea to + display an image. QLabel is typically used for displaying text, + but it can also display an image. QScrollArea provides a + scrolling view around another widget. If the child widget exceeds + the size of the frame, QScrollArea automatically provides scroll + bars. + + The example demonstrates how QLabel's ability to scale its + contents (QLabel::scaledContents), and QScrollArea's ability to + automatically resize its contents (QScrollArea::widgetResizable), + can be used to implement zooming and scaling features. In + addition the example shows how to use QPainter to print an image. + + \image imageviewer-example.png Screenshot of the Image Viewer example + + With the Image Viewer application, the users can view an image of + their choice. The \uicontrol File menu gives the user the possibility + to: + + \list + \li \uicontrol{Open...} - Open an image file + \li \uicontrol{Print...} - Print an image + \li \uicontrol{Exit} - Exit the application + \endlist + + Once an image is loaded, the \uicontrol View menu allows the users to: + + \list + \li \uicontrol{Zoom In} - Scale the image up by 25% + \li \uicontrol{Zoom Out} - Scale the image down by 25% + \li \uicontrol{Normal Size} - Show the image at its original size + \li \uicontrol{Fit to Window} - Stretch the image to occupy the entire window + \endlist + + In addition the \uicontrol Help menu provides the users with information + about the Image Viewer example in particular, and about Qt in + general. + + \section1 ImageViewer Class Definition + + \snippet widgets/imageviewer/imageviewer.h 0 + + The \c ImageViewer class inherits from QMainWindow. We reimplement + the constructor, and create several private slots to facilitate + the menu entries. In addition we create four private functions. + + We use \c createActions() and \c createMenus() when constructing + the \c ImageViewer widget. We use the \c updateActions() function + to update the menu entries when a new image is loaded, or when + the \uicontrol {Fit to Window} option is toggled. The zoom slots use \c + scaleImage() to perform the zooming. In turn, \c + scaleImage() uses \c adjustScrollBar() to preserve the focal point after + scaling an image. + + \section1 ImageViewer Class Implementation + + \snippet widgets/imageviewer/imageviewer.cpp 0 + + In the constructor we first create the label and the scroll area. + + We set \c {imageLabel}'s size policy to \l + {QSizePolicy::Ignored}{ignored}, making the users able to scale + the image to whatever size they want when the \uicontrol {Fit to Window} + option is turned on. Otherwise, the default size polizy (\l + {QSizePolicy::Preferred}{preferred}) will make scroll bars appear + when the scroll area becomes smaller than the label's minimum size + hint. + + We ensure that the label will scale its contents to fill all + available space, to enable the image to scale properly when + zooming. If we omitted to set the \c {imageLabel}'s \l + {QLabel::scaledContents}{scaledContents} property, zooming in + would enlarge the QLabel, but leave the pixmap at + its original size, exposing the QLabel's background. + + We make \c imageLabel the scroll area's child widget, and we make + \c scrollArea the central widget of the QMainWindow. At the end + we create the associated actions and menus, and customize the \c + {ImageViewer}'s appearance. + + \snippet widgets/imageviewer/imageviewer.cpp 1 + \snippet widgets/imageviewer/imageviewer.cpp 2 + + In the \c open() slot, we show a file dialog to the user. The + easiest way to create a QFileDialog is to use the static + convenience functions. QFileDialog::getOpenFileName() returns an + existing file selected by the user. If the user presses \uicontrol + Cancel, QFileDialog returns an empty string. + + Unless the file name is a empty string, we check if the file's + format is an image format by constructing a QImage which tries to + load the image from the file. If the constructor returns a null + image, we use a QMessageBox to alert the user. + + The QMessageBox class provides a modal dialog with a short + message, an icon, and some buttons. As with QFileDialog the + easiest way to create a QMessageBox is to use its static + convenience functions. QMessageBox provides a range of different + messages arranged along two axes: severity (question, + information, warning and critical) and complexity (the number of + necessary response buttons). In this particular example an + information message with an \uicontrol OK button (the default) is + sufficient, since the message is part of a normal operation. + + \snippet widgets/imageviewer/imageviewer.cpp 3 + \snippet widgets/imageviewer/imageviewer.cpp 4 + + If the format is supported, we display the image in \c imageLabel + by setting the label's \l {QLabel::pixmap}{pixmap}. Then we enable + the \uicontrol Print and \uicontrol {Fit to Window} menu entries and update + the rest of the view menu entries. The \uicontrol Open and \uicontrol Exit + entries are enabled by default. + + If the \uicontrol {Fit to Window} option is turned off, the + QScrollArea::widgetResizable property is \c false and it is + our responsibility (not QScrollArea's) to give the QLabel a + reasonable size based on its contents. We call + \{QWidget::adjustSize()}{adjustSize()} to achieve this, which is + essentially the same as + + \code + imageLabel->resize(imageLabel->pixmap()->size()); + \endcode + + In the \c print() slot, we first make sure that an image has been + loaded into the application: + + \snippet widgets/imageviewer/imageviewer.cpp 5 + \snippet widgets/imageviewer/imageviewer.cpp 6 + + If the application is built in debug mode, the \c Q_ASSERT() macro + will expand to + + \code + if (!imageLabel->pixmap()) + qFatal("ASSERT: "imageLabel->pixmap()" in file ..."); + \endcode + + In release mode, the macro simply disappear. The mode can be set + in the application's \c .pro file. One way to do so is to add an + option to \uicontrol qmake when building the application: + + \code + qmake "CONFIG += debug" foo.pro + \endcode + + or + + \code + qmake "CONFIG += release" foo.pro + \endcode + + Another approach is to add this line directly to the \c .pro + file. + + \snippet widgets/imageviewer/imageviewer.cpp 7 + \snippet widgets/imageviewer/imageviewer.cpp 8 + + Then we present a print dialog allowing the user to choose a + printer and to set a few options. We construct a painter with a + QPrinter as the paint device. We set the painter's window + and viewport in such a way that the image is as large as possible + on the paper, but without altering its + \l{Qt::KeepAspectRatio}{aspect ratio}. + + In the end we draw the pixmap at position (0, 0). + + \snippet widgets/imageviewer/imageviewer.cpp 9 + \snippet widgets/imageviewer/imageviewer.cpp 10 + + We implement the zooming slots using the private \c scaleImage() + function. We set the scaling factors to 1.25 and 0.8, + respectively. These factor values ensure that a \uicontrol {Zoom In} + action and a \uicontrol {Zoom Out} action will cancel each other (since + 1.25 * 0.8 == 1), and in that way the normal image size can be + restored using the zooming features. + + The screenshots below show an image in its normal size, and the + same image after zooming in: + + \table + \row + \li \inlineimage imageviewer-original_size.png + \li \inlineimage imageviewer-zoom_in_1.png + \li \inlineimage imageviewer-zoom_in_2.png + \endtable + + \snippet widgets/imageviewer/imageviewer.cpp 11 + \snippet widgets/imageviewer/imageviewer.cpp 12 + + When zooming, we use the QLabel's ability to scale its contents. + Such scaling doesn't change the actual size hint of the contents. + And since the \l {QLabel::adjustSize()}{adjustSize()} function + use those size hint, the only thing we need to do to restore the + normal size of the currently displayed image is to call \c + adjustSize() and reset the scale factor to 1.0. + + \snippet widgets/imageviewer/imageviewer.cpp 13 + \snippet widgets/imageviewer/imageviewer.cpp 14 + + The \c fitToWindow() slot is called each time the user toggled + the \uicontrol {Fit to Window} option. If the slot is called to turn on + the option, we tell the scroll area to resize its child widget + with the QScrollArea::setWidgetResizable() function. Then we + disable the \uicontrol {Zoom In}, \uicontrol {Zoom Out} and \uicontrol {Normal + Size} menu entries using the private \c updateActions() function. + + If the \l {QScrollArea::widgetResizable} property is set to \c + false (the default), the scroll area honors the size of its child + widget. If this property is set to \c true, the scroll area will + automatically resize the widget in order to avoid scroll bars + where they can be avoided, or to take advantage of extra space. + But the scroll area will honor the minimum size hint of its child + widget independent of the widget resizable property. So in this + example we set \c {imageLabel}'s size policy to \l + {QSizePolicy::Ignored}{ignored} in the constructor, to avoid that + scroll bars appear when the scroll area becomes smaller than the + label's minimum size hint. + + The screenshots below shows an image in its normal size, and the + same image with the \uicontrol {Fit to window} option turned on. + Enlarging the window will stretch the image further, as shown in + the third screenshot. + + \table + \row + \li \inlineimage imageviewer-original_size.png + \li \inlineimage imageviewer-fit_to_window_1.png + \li \inlineimage imageviewer-fit_to_window_2.png + \endtable + + If the slot is called to turn off the option, the + {QScrollArea::setWidgetResizable} property is set to \c false. We + also restore the image pixmap to its normal size by adjusting the + label's size to its content. And in the end we update the view + menu entries. + + \snippet widgets/imageviewer/imageviewer.cpp 15 + \snippet widgets/imageviewer/imageviewer.cpp 16 + + We implement the \c about() slot to create a message box + describing what the example is designed to show. + + \snippet widgets/imageviewer/imageviewer.cpp 17 + \snippet widgets/imageviewer/imageviewer.cpp 18 + + In the private \c createAction() function, we create the + actions providing the application features. + + We assign a short-cut key to each action and connect them to the + appropriate slots. We only enable the \c openAct and \c exitAct at + the time of creation, the others are updated once an image has + been loaded into the application. In addition we make the \c + fitToWindowAct \l {QAction::checkable}{checkable}. + + \snippet widgets/imageviewer/imageviewer.cpp 19 + \snippet widgets/imageviewer/imageviewer.cpp 20 + + In the private \c createMenu() function, we add the previously + created actions to the \uicontrol File, \uicontrol View and \uicontrol Help menus. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus. The QMenuBar class provides + a horizontal menu bar that consists of a list of pull-down menu + items. So at the end we put the menus in the \c {ImageViewer}'s + menu bar which we retrieve with the QMainWindow::menuBar() + function. + + \snippet widgets/imageviewer/imageviewer.cpp 21 + \snippet widgets/imageviewer/imageviewer.cpp 22 + + The private \c updateActions() function enables or disables the + \uicontrol {Zoom In}, \uicontrol {Zoom Out} and \uicontrol {Normal Size} menu + entries depending on whether the \uicontrol {Fit to Window} option is + turned on or off. + + \snippet widgets/imageviewer/imageviewer.cpp 23 + \snippet widgets/imageviewer/imageviewer.cpp 24 + + In \c scaleImage(), we use the \c factor parameter to calculate + the new scaling factor for the displayed image, and resize \c + imageLabel. Since we set the + \l{QLabel::scaledContents}{scaledContents} property to \c true in + the constructor, the call to QWidget::resize() will scale the + image displayed in the label. We also adjust the scroll bars to + preserve the focal point of the image. + + At the end, if the scale factor is less than 33.3% or greater + than 300%, we disable the respective menu entry to prevent the + image pixmap from becoming too large, consuming too much + resources in the window system. + + \snippet widgets/imageviewer/imageviewer.cpp 25 + \snippet widgets/imageviewer/imageviewer.cpp 26 + + Whenever we zoom in or out, we need to adjust the scroll bars in + consequence. It would have been tempting to simply call + + \code + scrollBar->setValue(int(factor * scrollBar->value())); + \endcode + + but this would make the top-left corner the focal point, not the + center. Therefore we need to take into account the scroll bar + handle's size (the \l{QScrollBar::pageStep}{page step}). +*/ diff --git a/examples/widgets/doc/src/interview.qdoc b/examples/widgets/doc/src/interview.qdoc new file mode 100644 index 0000000000..35721ccfae --- /dev/null +++ b/examples/widgets/doc/src/interview.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 itemviews/interview + \title Interview + + The Interview example explores the flexibility and scalability of the + model/view framework by presenting an infinitely deep data structure using a model + and three different types of view. + + \image interview-demo.png +*/ diff --git a/examples/widgets/doc/src/itemviewspuzzle.qdoc b/examples/widgets/doc/src/itemviewspuzzle.qdoc new file mode 100644 index 0000000000..ca8288cf1c --- /dev/null +++ b/examples/widgets/doc/src/itemviewspuzzle.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 itemviews/puzzle + \title Item Views Puzzle Example + + The Puzzle example shows how to enable drag and drop with a custom model + to allow items to be transferred between a view and another widget. + + \image itemviewspuzzle-example.png + + This example is an implementation of a simple jigsaw puzzle game using the + built-in support for drag and drop provided by Qt's model/view framework. + The \l{Drag and Drop Puzzle Example}{Drag and Drop Puzzle} example shows + many of the same features, but takes an alternative approach that uses Qt's + drag and drop API at the application level to handle drag and drop + operations. +*/ diff --git a/examples/widgets/doc/src/licensewizard.qdoc b/examples/widgets/doc/src/licensewizard.qdoc new file mode 100644 index 0000000000..125e0fec8f --- /dev/null +++ b/examples/widgets/doc/src/licensewizard.qdoc @@ -0,0 +1,218 @@ +/**************************************************************************** +** +** 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 dialogs/licensewizard + \title License Wizard Example + + The License Wizard example shows how to implement complex wizards in + Qt. + + \image licensewizard-example.png Screenshot of the License Wizard example + + Most wizards have a linear structure, with page 1 followed by + page 2 and so on until the last page. The + \l{dialogs/classwizard}{Class Wizard} example shows how to create + such wizards. + + Some wizards are more complex in that they allow different + traversal paths based on the information provided by the user. + The License Wizard example illustrates this. It provides five + wizard pages; depending on which options are selected, the user + can reach different pages. + + \image licensewizard-flow.png The License Wizard pages + + The example consists of the following classes: + + \list + \li \c LicenseWizard inherits QWizard and implements a non-linear + five-page wizard that leads the user through the process of + choosing a license agreement. + \li \c IntroPage, \c EvaluatePage, \c RegisterPage, \c + DetailsPage, and \c ConclusionPage are QWizardPage subclasses + that implement the wizard pages. + \endlist + + \section1 The LicenseWizard Class + + The \c LicenseWizard class derives from QWizard and provides a + five-page wizard that guides the user through the process of + registering their copy of a fictitious software product. Here's + the class definition: + + \snippet dialogs/licensewizard/licensewizard.h 1 + + The class's public API is limited to a constructor and an enum. + The enum defines the IDs associated with the various pages: + + \table + \header \li Class name \li Enum value \li Page ID + \row \li \c IntroPage \li \c Page_Intro \li 0 + \row \li \c EvaluatePage \li \c Page_Evaluate \li 1 + \row \li \c RegisterPage \li \c Page_Register \li 2 + \row \li \c DetailsPage \li \c Page_Details \li 3 + \row \li \c ConclusionPage \li \c Page_Conclusion \li 4 + \endtable + + For this example, the IDs are arbitrary. The only constraints are + that they must be unique and different from -1. IDs allow us to + refer to pages. + + \snippet dialogs/licensewizard/licensewizard.cpp 2 + + In the constructor, we create the five pages, insert them into + the wizard using QWizard::setPage(), and set \c Page_Intro to be + the first page. + + \snippet dialogs/licensewizard/licensewizard.cpp 3 + \snippet dialogs/licensewizard/licensewizard.cpp 4 + + We set the style to \l{QWizard::}{ModernStyle} on all platforms + except Mac OS X, + + \snippet dialogs/licensewizard/licensewizard.cpp 5 + \snippet dialogs/licensewizard/licensewizard.cpp 6 + + We configure the QWizard to show a \uicontrol Help button, which is + connected to our \c showHelp() slot. We also set the + \l{QWizard::}{LogoPixmap} for all pages that have a header (i.e., + \c EvaluatePage, \c RegisterPage, and \c DetailsPage). + + \snippet dialogs/licensewizard/licensewizard.cpp 9 + \snippet dialogs/licensewizard/licensewizard.cpp 11 + \dots + \snippet dialogs/licensewizard/licensewizard.cpp 13 + + In \c showHelp(), we display help texts that are appropriate for + the current page. If the user clicks \uicontrol Help twice for the same + page, we say, "Sorry, I already gave what help I could. Maybe you + should try asking a human?" + + \section1 The IntroPage Class + + The pages are defined in \c licensewizard.h and implemented in \c + licensewizard.cpp, together with \c LicenseWizard. + + Here's the definition and implementation of \c{IntroPage}: + + \snippet dialogs/licensewizard/licensewizard.h 4 + \codeline + \snippet dialogs/licensewizard/licensewizard.cpp 16 + + A page inherits from QWizardPage. We set a + \l{QWizardPage::}{title} and a + \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting + any \l{QWizardPage::}{subTitle}, we ensure that no header is + displayed for this page. (On Windows, it is customary for wizards + to display a watermark pixmap on the first and last pages, and to + have a header on the other pages.) + + \snippet dialogs/licensewizard/licensewizard.cpp 17 + \snippet dialogs/licensewizard/licensewizard.cpp 19 + + The \c nextId() function returns the ID for \c EvaluatePage if + the \uicontrol{Evaluate the product for 30 days} option is checked; + otherwise it returns the ID for \c RegisterPage. + + \section1 The EvaluatePage Class + + The \c EvaluatePage is slightly more involved: + + \snippet dialogs/licensewizard/licensewizard.h 5 + \codeline + \snippet dialogs/licensewizard/licensewizard.cpp 20 + \dots + \snippet dialogs/licensewizard/licensewizard.cpp 21 + \dots + \snippet dialogs/licensewizard/licensewizard.cpp 22 + + First, we set the page's \l{QWizardPage::}{title} + and \l{QWizardPage::}{subTitle}. + + Then we create the child widgets, create \l{Registering and Using + Fields}{wizard fields} associated with them, and put them into + layouts. The fields are created with an asterisk (\c + *) next to their name. This makes them \l{mandatory fields}, that + is, fields that must be filled before the user can press the + \uicontrol Next button (\uicontrol Continue on Mac OS X). The fields' values + can be accessed from any other page using QWizardPage::field(). + + Resetting the page amounts to clearing the two text fields. + + \snippet dialogs/licensewizard/licensewizard.cpp 23 + + The next page is always the \c ConclusionPage. + + \section1 The ConclusionPage Class + + The \c RegisterPage and \c DetailsPage are very similar to \c + EvaluatePage. Let's go directly to the \c ConclusionPage: + + \snippet dialogs/licensewizard/licensewizard.h 6 + + This time, we reimplement QWizardPage::initializePage() and + QWidget::setVisible(), in addition to + \l{QWizardPage::}{nextId()}. We also declare a private slot: + \c printButtonClicked(). + + \snippet dialogs/licensewizard/licensewizard.cpp 18 + + The default implementation of QWizardPage::nextId() returns + the page with the next ID, or -1 if the current page has the + highest ID. This behavior would work here, because \c + Page_Conclusion equals 5 and there is no page with a higher ID, + but to avoid relying on such subtle behavior, we reimplement + \l{QWizardPage::}{nextId()} to return -1. + + \snippet dialogs/licensewizard/licensewizard.cpp 27 + + We use QWizard::hasVisitedPage() to determine the type of + license agreement the user has chosen. If the user filled the \c + EvaluatePage, the license text refers to an Evaluation License + Agreement. If the user filled the \c DetailsPage, the license + text is a First-Time License Agreement. If the user provided an + upgrade key and skipped the \c DetailsPage, the license text is + an Update License Agreement. + + \snippet dialogs/licensewizard/licensewizard.cpp 28 + + We want to display a \uicontrol Print button in the wizard when the \c + ConclusionPage is up. One way to accomplish this is to reimplement + QWidget::setVisible(): + + \list + \li If the page is shown, we set the \l{QWizard::}{CustomButton1} button's + text to \uicontrol{\underline{P}rint}, we enable the \l{QWizard::}{HaveCustomButton1} + option, and we connect the QWizard's \l{QWizard::}{customButtonClicked()} + signal to our \c printButtonClicked() slot. + \li If the page is hidden, we disable the \l{QWizard::}{HaveCustomButton1} + option and disconnect the \c printButtonClicked() slot. + \endlist + + \sa QWizard, {Class Wizard Example}, {Trivial Wizard Example} +*/ diff --git a/examples/widgets/doc/src/lighting.qdoc b/examples/widgets/doc/src/lighting.qdoc new file mode 100644 index 0000000000..aafa70f38c --- /dev/null +++ b/examples/widgets/doc/src/lighting.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** 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 effects/lighting + \title Lighting Effect Example + + \image lightingeffect-example.png +*/ diff --git a/examples/widgets/doc/src/lineedits.qdoc b/examples/widgets/doc/src/lineedits.qdoc new file mode 100644 index 0000000000..c9cb7b5f43 --- /dev/null +++ b/examples/widgets/doc/src/lineedits.qdoc @@ -0,0 +1,161 @@ +/**************************************************************************** +** +** 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/lineedits + \title Line Edits Example + + The Line Edits example demonstrates the many ways that QLineEdit can be used, and + shows the effects of various properties and validators on the input and output + supplied by the user. + + \image lineedits-example.png + + The example consists of a single \c Window class, containing a selection of + line edits with different input constraints and display properties that can be + changed by selecting items from comboboxes. Presenting these together helps + developers choose suitable properties to use with line edits, and makes it easy + to compare the effects of each validator on user input. + + \section1 Window Class Definition + + The \c Window class inherits QWidget and contains a constructor and several + slots: + + \snippet widgets/lineedits/window.h 0 + + The slots are used to update the type of validator used for a given line edit when + a new validator has been selected in the associated combobox. The line edits + are stored in the window for use in these slots. + + \section1 Window Class Implementation + + The \c Window constructor is used to set up the line edits, validators, + and comboboxes, connect signals from the comboboxes to slots in the \c Window + class, and arrange the child widgets in layouts. + + We begin by constructing a \l{QGroupBox}{group box} to hold a label, combobox, + and line edit so that we can demonstrate the QLineEdit::echoMode property: + + \snippet widgets/lineedits/window.cpp 0 + + At this point, none of these widgets have been arranged in layouts. Eventually, + the \c echoLabel, \c echoComboBox, and \c echoLineEdit will be placed in a + vertical layout inside the \c echoGroup group box. + + Similarly, we construct group boxes and collections of widgets to show the + effects of QIntValidator and QDoubleValidator on a line edit's contents: + + \snippet widgets/lineedits/window.cpp 1 + + Text alignment is demonstrated by another group of widgets: + + \snippet widgets/lineedits/window.cpp 2 + + QLineEdit supports the use of \l{QLineEdit::inputMask}{input masks}. + These only allow the user to type characters into the line edit that + follow a simple specification. We construct a group of widgets to + demonstrate a selection of predefined masks: + + \snippet widgets/lineedits/window.cpp 3 + + Another useful feature of QLineEdit is its ability to make its contents + read-only. This property is used to control access to a line edit in the + following group of widgets: + + \snippet widgets/lineedits/window.cpp 4 + + Now that all the child widgets have been constructed, we connect signals + from the comboboxes to slots in the \c Window object: + + \snippet widgets/lineedits/window.cpp 5 + + Each of these connections use the QComboBox::activated() signal that + supplies an integer to the slot. This will be used to efficiently + make changes to the appropriate line edit in each slot. + + We place each combobox, line edit, and label in a layout for each group + box, beginning with the layout for the \c echoGroup group box: + + \snippet widgets/lineedits/window.cpp 6 + + The other layouts are constructed in the same way: + + \snippet widgets/lineedits/window.cpp 7 + + Finally, we place each group box in a grid layout for the \c Window object + and set the window title: + + \snippet widgets/lineedits/window.cpp 8 + + The slots respond to signals emitted when the comboboxes are changed by the + user. + + When the combobox for the \uicontrol{Echo} group box is changed, the \c echoChanged() + slot is called: + + \snippet widgets/lineedits/window.cpp 9 + + The slot updates the line edit in the same group box to use an echo mode that + corresponds to the entry described in the combobox. + + When the combobox for the \uicontrol{Validator} group box is changed, the + \c validatorChanged() slot is called: + + \snippet widgets/lineedits/window.cpp 10 + + The slot either creates a new validator for the line edit to use, or it removes + the validator in use by calling QLineEdit::setValidator() with a zero pointer. + We clear the line edit in this case to ensure that the new validator is + initially given valid input to work with. + + When the combobox for the \uicontrol{Alignment} group box is changed, the + \c alignmentChanged() slot is called: + + \snippet widgets/lineedits/window.cpp 11 + + This changes the way that text is displayed in the line edit to correspond with + the description selected in the combobox. + + The \c inputMaskChanged() slot handles changes to the combobox in the + \uicontrol{Input Mask} group box: + + \snippet widgets/lineedits/window.cpp 12 + + Each entry in the relevant combobox is associated with an input mask. We set + a new mask by calling the QLineEdit::setMask() function with a suitable string; + the mask is disabled if an empty string is used. + + The \c accessChanged() slot handles changes to the combobox in the + \uicontrol{Access} group box: + + \snippet widgets/lineedits/window.cpp 13 + + Here, we simply associate the \uicontrol{False} and \uicontrol{True} entries in the combobox + with \c false and \c true values to be passed to QLineEdit::setReadOnly(). This + allows the user to enable and disable input to the line edit. +*/ diff --git a/examples/widgets/doc/src/mainwindow.qdoc b/examples/widgets/doc/src/mainwindow.qdoc new file mode 100644 index 0000000000..b4f6aebed1 --- /dev/null +++ b/examples/widgets/doc/src/mainwindow.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 mainwindows/mainwindow + \title Main Window + + The Main Window example shows Qt's extensive support for tool bars, + dock windows, menus, and other standard application features. + + \image mainwindow-demo.png +*/ diff --git a/examples/widgets/doc/src/mdi.qdoc b/examples/widgets/doc/src/mdi.qdoc new file mode 100644 index 0000000000..e8b1b5c9ef --- /dev/null +++ b/examples/widgets/doc/src/mdi.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 mainwindows/mdi + \title MDI Example + + The MDI example shows how to implement a Multiple Document Interface using Qt's + QMdiArea class. + + \image mdi-example.png + +*/ diff --git a/examples/widgets/doc/src/menus.qdoc b/examples/widgets/doc/src/menus.qdoc new file mode 100644 index 0000000000..3531e439c1 --- /dev/null +++ b/examples/widgets/doc/src/menus.qdoc @@ -0,0 +1,218 @@ +/**************************************************************************** +** +** 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 mainwindows/menus + \title Menus Example + + The Menus example demonstrates how menus can be used in a main + window application. + + A menu widget can be either a pull-down menu in a menu bar or a + standalone context menu. Pull-down menus are shown by the menu bar + when the user clicks on the respective item or presses the + specified shortcut key. Context menus are usually invoked by some + special keyboard key or by right-clicking. + + \image menus-example.png + + A menu consists of a list of \e action items. In applications, + many common commands can be invoked via menus, toolbar buttons as + well as keyboard shortcuts. Since the user expects the commands to + be performed in the same way, regardless of the user interface + used, it is useful to represent each command as an action. + + The Menus example consists of one single class, \c MainWindow, derived + from the QMainWindow class. When choosing one of the + action items in our application, it will display the item's path + in its central widget. + + \section1 MainWindow Class Definition + + QMainWindow provides a main application window, with a menu bar, + tool bars, dock widgets and a status bar around a large central + widget. + + \snippet mainwindows/menus/mainwindow.h 0 + + In this example, we will see how to implement pull-down menus as + well as a context menu. In order to implement a custom context + menu we must reimplement QWidget's \l + {QWidget::}{contextMenuEvent()} function to receive the context + menu events for our main window. + + \snippet mainwindows/menus/mainwindow.h 1 + + We must also implement a collection of private slots to respond to + the user activating any of our menu entries. Note that these + slots are left out of this documentation since they are trivial, + i.e., most of them are only displaying the action's path in the + main window's central widget. + + \snippet mainwindows/menus/mainwindow.h 2 + + We have chosen to simplify the constructor by implementing two + private convenience functions to create the various actions, to + add them to menus and to insert the menus into our main window's + menu bar. + + \snippet mainwindows/menus/mainwindow.h 3 + + Finally, we declare the various menus and actions as well as a + simple information label in the application wide scope. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus while the QAction class + provides an abstract user interface action that can be inserted + into widgets. + + In some situations it is useful to group actions together, e.g., + we have a \uicontrol {Left Align} action, a \uicontrol {Right Align} action, a + \uicontrol {Justify} action, and a \uicontrol {Center} action, and we want + only one of these actions to be active at any one time. One simple + way of achieving this is to group the actions together in an + action group using the QActionGroup class. + + \section1 MainWindow Class Implementation + + In the constructor, we start off by creating a regular QWidget and + make it our main window's central widget. Note that the main + window takes ownership of the widget pointer and deletes it at the + appropriate time. + + \snippet mainwindows/menus/mainwindow.cpp 0 + \codeline + \snippet mainwindows/menus/mainwindow.cpp 1 + + Then we create the information label as well as a top and bottom + filler that we add to a layout which we install on the central + widget. QMainWindow objects come with their own customized layout + and setting a layout on a the actual main window, or creating a + layout with a main window as a parent, is considered an error. You + should always set your own layout on the central widget instead. + + \snippet mainwindows/menus/mainwindow.cpp 2 + + To create the actions and menus we call our two convenience + functions: \c createActions() and \c createMenus(). We will get + back to these shortly. + + QMainWindow's \l {QMainWindow::statusBar()}{statusBar()} function + returns the status bar for the main window (if the status bar does + not exist, this function will create and return an empty status + bar). We initialize the status bar and window title, resize the + window to an appropriate size as well as ensure that the main + window cannot be resized to a smaller size than the given + one. + + Now, let's take a closer look at the \c createActions() convenience + function that creates the various actions: + + \snippet mainwindows/menus/mainwindow.cpp 4 + \dots + + A QAction object may contain an icon, a text, a shortcut, a status + tip, a "What's This?" text, and a tooltip. Most of these can be + set in the constructor, but they can also be set independently + using the provided convenience functions. + + In the \c createActions() function, we first create a \c newAct + action. We make \uicontrol Ctrl+N its shortcut using the + QAction::setShortcut() function, and we set its status tip using the + QAction::setStatusTip() function (the status tip is displayed on all + status bars provided by the action's top-level parent widget). We + also connect its \l {QAction::}{triggered()} signal to the \c + newFile() slot. + + The rest of the actions are created in a similar manner. Please + see the source code for details. + + \snippet mainwindows/menus/mainwindow.cpp 7 + + + Once we have created the \uicontrol {Left Align}, \uicontrol {Right Align}, + \uicontrol {Justify}, and a \uicontrol {Center} actions, we can also create + the previously mentioned action group. + + Each action is added to the group using QActionGroup's \l + {QActionGroup::}{addAction()} function. Note that an action also + can be added to a group by creating it with the group as its + parent. Since an action group is exclusive by default, only one of + the actions in the group is checked at any one time (this can be + altered using the QActionGroup::setExclusive() function). + + When all the actions are created, we use the \c createMenus() + function to add the actions to the menus and to insert the menus + into the menu bar: + + \snippet mainwindows/menus/mainwindow.cpp 8 + + QMenuBar's \l {QMenuBar::addMenu()}{addMenu()} function appends a + new QMenu with the given title, to the menu bar (note that the + menu bar takes ownership of the menu). We use QWidget's \l + {QWidget::addAction()}{addAction()} function to add each action to + the corresponding menu. + + Alternatively, the QMenu class provides several \l + {QMenu::addAction()}{addAction()} convenience functions that create + and add new actions from given texts and/or icons. You can also + provide a member that will automatically connect to the new + action's \l {QAction::triggered()}{triggered()} signal, and a + shortcut represented by a QKeySequence instance. + + The QMenu::addSeparator() function creates and returns a new + separator action, i.e. an action for which QAction::isSeparator() + returns true, and adds the new action to the menu's list of + actions. + + \snippet mainwindows/menus/mainwindow.cpp 12 + + Note the \uicontrol Format menu. First of all, it is added as a submenu + to the \uicontrol Edit Menu using QMenu's \l + {QMenu::addMenu()}{addMenu()} function. Secondly, take a look at the + alignment actions: In the \c createActions() function we added the + \c leftAlignAct, \c rightAlignAct, \c justifyAct and \c centerAct + actions to an action group. Nevertheless, we must add each action + to the menu separately while the action group does its magic + behind the scene. + + \snippet mainwindows/menus/mainwindow.cpp 3 + + To provide a custom context menu, we must reimplement QWidget's \l + {QWidget::}{contextMenuEvent()} function to receive the widget's + context menu events (note that the default implementation simply + ignores these events). + + Whenever we receive such an event, we create a menu containing the + \uicontrol Cut, \uicontrol Copy and \uicontrol Paste actions. Context menus can be + executed either asynchronously using the \l {QMenu::}{popup()} + function or synchronously using the \l {QMenu::}{exec()} + function. In this example, we have chosen to show the menu using + its \l {QMenu::}{exec()} function. By passing the event's position + as argument we ensure that the context menu appears at the + expected position. +*/ diff --git a/examples/widgets/doc/src/moveblocks.qdoc b/examples/widgets/doc/src/moveblocks.qdoc new file mode 100644 index 0000000000..8c12280989 --- /dev/null +++ b/examples/widgets/doc/src/moveblocks.qdoc @@ -0,0 +1,214 @@ +/**************************************************************************** +** +** 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 animation/moveblocks + \title Move Blocks Example + + The Move Blocks example shows how to animate items in a + QGraphicsScene using a QStateMachine with a custom transition. + + \image moveblocks-example.png + + The example animates the blue blocks that you can see in the image + above. The animation moves the blocks between four preset positions. + + The example consists of the following classes: + + \list + \li \c StateSwitcher inherits QState and can add + \c {StateSwitchTransition}s to other states. + When entered, it will randomly transition to one of these + states. + \li \c StateSwitchTransition is a custom transition that + triggers on \c{StateSwitchEvent}s. + \li \c StateSwitchEvent is a QEvent that triggers \c{StateSwitchTransition}s. + \li \c QGraphicsRectWidget is a QGraphicsWidget that simply + paints its background in a solid \l{Qt::}{blue} color. + \endlist + + The blocks are instances of \c QGraphicsRectWidget and are + animated in a QGraphicsScene. We do this by building a state + graph, which we insert animations into. The graph is then executed + in a QStateMachine. All this is done in \c main(). + Let's look at the \c main() function first. + + \section1 The \c main() Function + + After QApplication has been initialized, we set up the + QGraphicsScene with its \c{QGraphicsRectWidget}s. + + \snippet animation/moveblocks/main.cpp 1 + + After adding the scene to a QGraphicsView, it is time to build the + state graph. Let's first look at a statechart of what we are + trying to build. + + \image move-blocks-chart.png + + Note that the \c group has seven sub states, but we have only + included three of them in the diagram. The code that builds this + graph will be examined line-by-line, and will show how the graph + works. First off, we construct the \c group state: + + \snippet animation/moveblocks/main.cpp 2 + + The timer is used to add a delay between each time the blocks are + moved. The timer is started when \c group is entered. As we will + see later, \c group has a transition back to the \c StateSwitcher + when the timer times out. \c group is the initial state in the + machine, so an animation will be scheduled when the example is + started. + + \snippet animation/moveblocks/main.cpp 3 + \dots + \snippet animation/moveblocks/main.cpp 4 + + \c createGeometryState() returns a QState that will set the + geometry of our items upon entry. It also assigns \c group as the + parent of this state. + + A QPropertyAnimation inserted into a transition will use the + values assigned to a QState (with QState::assignProperty()), i.e., + the animation will interpolate between the current values of the + properties and the values in the target state. We add animated + transitions to the state graph later. + + \snippet animation/moveblocks/main.cpp 5 + + We move the items in parallel. Each item is added to \c + animationGroup, which is the animation that is inserted into the + transitions. + + \snippet animation/moveblocks/main.cpp 6 + + The sequential animation group, \c subGroup, helps us insert a + delay between the animation of each item. + + \snippet animation/moveblocks/main.cpp 7 + \dots + \snippet animation/moveblocks/main.cpp 8 + + A StateSwitchTransition is added to the state switcher + in \c StateSwitcher::addState(). We also add the animation in this + function. Since QPropertyAnimation uses the values from the + states, we can insert the same QPropertyAnimation instance in all + \c {StateSwitchTransition}s. + + As mentioned previously, we add a transition to the state switcher + that triggers when the timer times out. + + \snippet animation/moveblocks/main.cpp 9 + + Finally, we can create the state machine, add our initial state, + and start execution of the state graph. + + \section2 The \c createGeometryState() Function + + In \c createGeometryState(), we set up the geometry for each + graphics item. + + \snippet animation/moveblocks/main.cpp 13 + + As mentioned before, QAbstractTransition will set up an animation + added with \l{QAbstractTransition::}{addAnimation()} using + property values set with \l{QState::}{assignProperty()}. + + \section1 The StateSwitcher Class + + \c StateSwitcher has state switch transitions to each \l{QState}s + we created with \c createGeometryState(). Its job is to transition + to one of these states at random when it is entered. + + All functions in \c StateSwitcher are inlined. We'll step through + its definition. + + \snippet animation/moveblocks/main.cpp 10 + + \c StateSwitcher is a state designed for a particular purpose and + will always be a top-level state. We use \c m_stateCount to keep + track of how many states we are managing, and \c m_lastIndex to + remember which state was the last state to which we transitioned. + + \snippet animation/moveblocks/main.cpp 11 + + We select the next state we are going to transition to, and post a + \c StateSwitchEvent, which we know will trigger the \c + StateSwitchTransition to the selected state. + + \snippet animation/moveblocks/main.cpp 12 + + This is where the magic happens. We assign a number to each state + added. This number is given to both a StateSwitchTransition and to + StateSwitchEvents. As we have seen, state switch events will + trigger a transition with the same number. + + \section1 The StateSwitchTransition Class + + \c StateSwitchTransition inherits QAbstractTransition and triggers + on \c{StateSwitchEvent}s. It contains only inline functions, so + let's take a look at its \l{QAbstractTransition::}{eventTest()} + function, which is the only function that we define.. + + \snippet animation/moveblocks/main.cpp 14 + + \c eventTest is called by QStateMachine when it checks whether a + transition should be triggered--a return value of true means that + it will. We simply check if our assigned number is equal to the + event's number (in which case we fire away). + + \section1 The StateSwitchEvent Class + + \c StateSwitchEvent inherits QEvent, and holds a number that has + been assigned to a state and state switch transition by + \c StateSwitcher. We have already seen how it is used to trigger + \c{StateSwitchTransition}s in \c StateSwitcher. + + \snippet animation/moveblocks/main.cpp 15 + + We only have inlined functions in this class, so a look at its + definition will do. + + \section1 The QGraphicsRectWidget Class + + QGraphicsRectWidget inherits QGraphicsWidget and simply paints its + \l{QWidget::}{rect()} blue. We inline \l{QWidget::}{paintEvent()}, + which is the only function we define. Here is the + QGraphicsRectWidget class definition: + + \snippet animation/moveblocks/main.cpp 16 + + \section1 Moving On + + The technique shown in this example works equally well for all + \l{QPropertyAnimation}s. As long as the value to be animated is a + Qt property, you can insert an animation of it into a state graph. + + QState::addAnimation() takes a QAbstractAnimation, so any type + of animation can be inserted into the graph. +*/ + diff --git a/examples/widgets/doc/src/movie.qdoc b/examples/widgets/doc/src/movie.qdoc new file mode 100644 index 0000000000..e636ce5902 --- /dev/null +++ b/examples/widgets/doc/src/movie.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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/movie + \title Movie Example + + The Movie example demonstrates how to use QMovie and QLabel to + display animations. QMovie is mostly useful if one wants to play + a simple animation without the added complexity of a multimedia + framework to install and deploy. + + \image movie-example.png +*/ diff --git a/examples/widgets/doc/src/orderform.qdoc b/examples/widgets/doc/src/orderform.qdoc new file mode 100644 index 0000000000..ed40c65093 --- /dev/null +++ b/examples/widgets/doc/src/orderform.qdoc @@ -0,0 +1,364 @@ +/**************************************************************************** +** +** 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 richtext/orderform + \title Order Form Example + + The Order Form example shows how to generate rich text documents by + combining a simple template with data input by the user in a dialog. Data + is extracted from a \c DetailsDialog object and displayed on a QTextEdit + with a QTextCursor, using various formats. Each form generated is added + to a QTabWidget for easy access. + + \image orderform-example.png + + \section1 DetailsDialog Definition + + The \c DetailsDialog class is a subclass of QDialog, implementing a slot + \c verify() to allow contents of the \c DetailsDialog to be verified later. + This is further explained in \c DetailsDialog Implementation. + + \snippet richtext/orderform/detailsdialog.h 0 + + The constructor of \c DetailsDialog accepts parameters \a title and + \a parent. The class defines four \e{getter} functions: \c orderItems(), + \c senderName(), \c senderAddress(), and \c sendOffers() to allow data + to be accessed externally. + + The class definition includes input widgets for the required + fields, \c nameEdit and \c addressEdit. Also, a QCheckBox and a + QDialogButtonBox are defined; the former to provide the user with the + option to receive information on products and offers, and the latter + to ensure that buttons used are arranged according to the user's native + platform. In addition, a QTableWidget, \c itemsTable, is used to hold + order details. + + The screenshot below shows the \c DetailsDialog we intend to create. + + \image orderform-example-detailsdialog.png + + \section1 DetailsDialog Implementation + + The constructor of \c DetailsDialog instantiates the earlier defined fields + and their respective labels. The label for \c offersCheckBox is set and the + \c setupItemsTable() function is invoked to setup and populate + \c itemsTable. The QDialogButtonBox object, \c buttonBox, is instantiated + with \uicontrol OK and \uicontrol Cancel buttons. This \c buttonBox's \c accepted() and + \c rejected() signals are connected to the \c verify() and \c reject() + slots in \c DetailsDialog. + + \snippet richtext/orderform/detailsdialog.cpp 0 + + A QGridLayout is used to place all the objects on the \c DetailsDialog. + + \snippet richtext/orderform/detailsdialog.cpp 1 + + The \c setupItemsTable() function instantiates the QTableWidget object, + \c itemsTable, and sets the number of rows based on the QStringList + object, \c items, which holds the type of items ordered. The number of + columns is set to 2, providing a "name" and "quantity" layout. A \c for + loop is used to populate the \c itemsTable and the \c name item's flag + is set to Qt::ItemIsEnabled or Qt::ItemIsSelectable. For demonstration + purposes, the \c quantity item is set to a 1 and all items in the + \c itemsTable have this value for quantity; but this can be modified by + editing the contents of the cells at run time. + + \snippet richtext/orderform/detailsdialog.cpp 2 + + The \c orderItems() function extracts data from the \c itemsTable and + returns it in the form of a QList> where each QPair + corresponds to an item and the quantity ordered. + + \snippet richtext/orderform/detailsdialog.cpp 3 + + The \c senderName() function is used to return the value of the QLineEdit + used to store the name field for the order form. + + \snippet richtext/orderform/detailsdialog.cpp 4 + + The \c senderAddress() function is used to return the value of the + QTextEdit containing the address for the order form. + + \snippet richtext/orderform/detailsdialog.cpp 5 + + The \c sendOffers() function is used to return a \c true or \c false + value that is used to determine if the customer in the order form + wishes to receive more information on the company's offers and promotions. + + \snippet richtext/orderform/detailsdialog.cpp 6 + + The \c verify() function is an additionally implemented slot used to + verify the details entered by the user into the \c DetailsDialog. If + the details entered are incomplete, a QMessageBox is displayed + providing the user the option to discard the \c DetailsDialog. Otherwise, + the details are accepted and the \c accept() function is invoked. + + \snippet richtext/orderform/detailsdialog.cpp 7 + + \section1 MainWindow Definition + + The \c MainWindow class is a subclass of QMainWindow, implementing two + slots - \c openDialog() and \c printFile(). It also contains a private + instance of QTabWidget, \c letters. + + \snippet richtext/orderform/mainwindow.h 0 + + \section1 MainWindow Implementation + + The \c MainWindow constructor sets up the \c fileMenu and the required + actions, \c newAction and \c printAction. These actions' \c triggered() + signals are connected to the additionally implemented openDialog() slot + and the default close() slot. The QTabWidget, \c letters, is + instantiated and set as the window's central widget. + + \snippet richtext/orderform/mainwindow.cpp 0 + + The \c createLetter() function creates a new QTabWidget with a QTextEdit, + \c editor, as the parent. This function accepts four parameters that + correspond to we obtained through \c DetailsDialog, in order to "fill" + the \c editor. + + \snippet richtext/orderform/mainwindow.cpp 1 + + We then obtain the cursor for the \c editor using QTextEdit::textCursor(). + The \c cursor is then moved to the start of the document using + QTextCursor::Start. + + \snippet richtext/orderform/mainwindow.cpp 2 + + Recall the structure of a \l{Rich Text Document Structure} + {Rich Text Document}, where sequences of frames and + tables are always separated by text blocks, some of which may contain no + information. + + In the case of the Order Form Example, the document structure for this portion + is described by the table below: + + \table + \row + \li {1, 8} frame with \e{referenceFrameFormat} + \row + \li block \li \c{A company} + \row + \li block + \row + \li block \li \c{321 City Street} + \row + \li block + \row + \li block \li \c{Industry Park} + \row + \li block + \row + \li block \li \c{Another country} + \endtable + + This is accomplished with the following code: + + \snippet richtext/orderform/mainwindow.cpp 3 + + Note that \c topFrame is the \c {editor}'s top-level frame and is not shown + in the document structure. + + We then set the \c{cursor}'s position back to its last position in + \c topFrame and fill in the customer's name (provided by the constructor) + and address - using a \c foreach loop to traverse the QString, \c address. + + \snippet richtext/orderform/mainwindow.cpp 4 + + The \c cursor is now back in \c topFrame and the document structure for + the above portion of code is: + + \table + \row + \li block \li \c{Donald} + \row + \li block \li \c{47338 Park Avenue} + \row + \li block \li \c{Big City} + \endtable + + For spacing purposes, we invoke \l{QTextCursor::insertBlock()} + {insertBlock()} twice. The \l{QDate::currentDate()}{currentDate()} is + obtained and displayed. We use \l{QTextFrameFormat::setWidth()} + {setWidth()} to increase the width of \c bodyFrameFormat and we insert + a new frame with that width. + + \snippet richtext/orderform/mainwindow.cpp 5 + + The following code inserts standard text into the order form. + + \snippet richtext/orderform/mainwindow.cpp 6 + \snippet richtext/orderform/mainwindow.cpp 7 + + This part of the document structure now contains the date, a frame with + \c bodyFrameFormat, as well as the standard text. + + \table + \row + \li block + \row + \li block + \row + \li block \li \c{Date: 25 May 2007} + \row + \li block + \row + \li {1, 4} frame with \e{bodyFrameFormat} + \row + \li block \li \c{I would like to place an order for the following items:} + \row + \li block + \row + \li block + \endtable + + A QTextTableFormat object, \c orderTableFormat, is used to hold the type + of item and the quantity ordered. + + \snippet richtext/orderform/mainwindow.cpp 8 + + We use \l{QTextTable::cellAt()}{cellAt()} to set the headers for the + \c orderTable. + + \snippet richtext/orderform/mainwindow.cpp 9 + + Then, we iterate through the QList of QPair objects to populate + \c orderTable. + + \snippet richtext/orderform/mainwindow.cpp 10 + + The resulting document structure for this section is: + + \table + \row + \li {1, 11} \c{orderTable} with \e{orderTableFormat} + \row + \li block \li \c{Product} + \row + \li block \li \c{Quantity} + \row + \li block \li \c{T-shirt} + \row + \li block \li \c{4} + \row + \li block \li \c{Badge} + \row + \li block \li \c{3} + \row + \li block \li \c{Reference book} + \row + \li block \li \c{2} + \row + \li block \li \c{Coffee cup} + \row + \li block \li \c{5} + \endtable + + The \c cursor is then moved back to \c{topFrame}'s + \l{QTextFrame::lastPosition()}{lastPosition()} and more standard text + is inserted. + + \snippet richtext/orderform/mainwindow.cpp 11 + \snippet richtext/orderform/mainwindow.cpp 12 + + Another QTextTable is inserted, to display the customer's + preference regarding offers. + + \snippet richtext/orderform/mainwindow.cpp 13 + + The document structure for this portion is: + + \table + \row + \li block + \row + \li block\li \c{Please update my...} + \row + \li {1, 5} block + \row + \li {1, 4} \c{offersTable} + \row + \li block \li \c{I want to receive...} + \row + \li block \li \c{I do not want to receive...} + \row + \li block \li \c{X} + \endtable + + The \c cursor is moved to insert "Sincerely" along with the customer's + name. More blocks are inserted for spacing purposes. The \c printAction + is enabled to indicate that an order form can now be printed. + + \snippet richtext/orderform/mainwindow.cpp 14 + + The bottom portion of the document structure is: + + \table + \row + \li block + \row + \li {1, 5} block\li \c{Sincerely,} + \row + \li block + \row + \li block + \row + \li block + \row + \li block \li \c{Donald} + \endtable + + The \c createSample() function is used for illustration purposes, to create + a sample order form. + + \snippet richtext/orderform/mainwindow.cpp 15 + + The \c openDialog() function opens a \c DetailsDialog object. If the + details in \c dialog are accepted, the \c createLetter() function is + invoked using the parameters extracted from \c dialog. + + \snippet richtext/orderform/mainwindow.cpp 16 + + In order to print out the order form, a \c printFile() function is + included, as shown below: + + \snippet richtext/orderform/mainwindow.cpp 17 + + This function also allows the user to print a selected area with + QTextCursor::hasSelection(), instead of printing the entire document. + + \section1 \c main() Function + + The \c main() function instantiates \c MainWindow and sets its size to + 640x480 pixels before invoking the \c show() function and + \c createSample() function. + + \snippet richtext/orderform/main.cpp 0 + +*/ diff --git a/examples/widgets/doc/src/padnavigator.qdoc b/examples/widgets/doc/src/padnavigator.qdoc new file mode 100644 index 0000000000..8b1da516b5 --- /dev/null +++ b/examples/widgets/doc/src/padnavigator.qdoc @@ -0,0 +1,583 @@ +/**************************************************************************** +** +** 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 graphicsview/padnavigator + \title Pad Navigator Example + + The Pad Navigator Example shows how you can use Graphics View together with + embedded widgets and Qt's \l{State Machine Framework} to create a simple + but useful, dynamic, animated user interface. + + \image padnavigator-example.png + + The interface consists of a flippable, rotating pad with icons that can be + selected using the arrow keys on your keyboard or keypad. Pressing enter + will flip the pad around and reveal its back side, which has a form + embedded into a QGraphicsProxyWidget. You can interact with the form, and + press the enter key to flip back to the front side of the pad at any time. + + Graphics View provides the QGraphicsScene class for managing and + interacting with a large number of custom-made 2D graphical items derived + from the QGraphicsItem class, and a QGraphicsView widget for visualizing + the items, with support for zooming and rotation. + + This example consists of a \c RoundRectItem class, a \c FlippablePad class, + a \c PadNavigator class, a \c SplashItem class, and a \c main() function. + + \section1 RoundRectItem Class Definition + + The \c RoundRectItem class is used by itself to display the icons on the + pad, and as a base class for \c FlippablePad, the class for the pad itself. + The role of the class is to paint a round rectangle of a specified size and + gradient color, and optionally to paint a pixmap icon on top. To support \c + FlippablePad it also allows filling its contents with a plain window + background color. + + Let's start by reviewing the \c RoundRectItem class declaration. + + \snippet graphicsview/padnavigator/roundrectitem.h 0 + + \c RoundRectItem inherits QGraphicsObject, which makes it easy to control + its properties using QPropertyAnimation. Its constructor takes a rectangle + to determine its bounds, and a color. + + Besides implementing the mandatory \l{QGraphicsItem::paint()}{paint()} and + \l{QGraphicsItem::boundingRect()}{boundingRect()} pure virtual functions, + it also provides the \c pixmap and \c fill properties. + + The \c pixmap property sets an optional pixmap that is drawn on top of the + round rectangle. The \c fill property will, when true, fill the round + rectangle contents with a fixed QPalette::Window background color. + Otherwise the contents are filled using a gradient based on the color + passed to \c RoundRectItem's constructor. + + \snippet graphicsview/padnavigator/roundrectitem.h 1 + + The private data members are: + + \list + \li \c pix: The optional pixmap that is drawn on top of the rectangle. + \li \c fillRect: Corresponds to the \c fill property. + \li \c color: The configurable gradient color fill of the rectangle. + \li \c bounds: The bounds of the rectangle. + \li \c gradient: A precalculated gradient used to fill the rectangle. + \endlist + + We will now review the \c RoundRectItem implementation. Let's start by + looking at its constructor: + + \snippet graphicsview/padnavigator/roundrectitem.cpp 0 + + The constructor initializes its member variables and forwards the \c parent + argument to QGraphicsObject's constructor. It then constructs the linear + gradient that is used in \l{QGraphicsItem::paint()}{paint()} to draw the + round rectangle's gradient background. The linear gradient's starting point + is at the top-left corner of the bounds, and the end is at the bottom-left + corner. The start color is identical to the color passed as an argument, + and a slightly darker color is chosen for the final stop. + + We store this gradient as a member variable to avoid having to recreate the + gradient every time the item is repainted. + + Finally we set the cache mode + \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache}. This mode + causes the item's rendering to be cached into an off-screen pixmap that + remains persistent as we move and transform the item. This mode is ideal + for this example, and works particularly well with OpenGL and OpenGL ES. + + \snippet graphicsview/padnavigator/roundrectitem.cpp 1 + + The \c pixmap property implementation simple returns the member pixmap, or + sets it and then calls \l{QGraphicsItem::update()}{update()}. + + \snippet graphicsview/padnavigator/roundrectitem.cpp 2 + + As the \l{QGraphicsItem::paint()}{paint()} implementation below draws a + simple drop shadow down and to the right of the item, we return a slightly + adjusted rectangle from \l{QGraphicsItem::boundingRect()}{boundingRect()}. + + \snippet graphicsview/padnavigator/roundrectitem.cpp 3 + + The \l{QGraphicsItem::paint()}{paint()} implementation starts by rendering + a semi transparent black round rectangle drop shadow, two units down and to + the right of the main item. + + \snippet graphicsview/padnavigator/roundrectitem.cpp 4 + + We then draw the "foreground" round rectangle itself. The fill depends on + the \c fill property; if true, we will with a plain QPalette::Window color. + We get the current brush from QApplication::palette(). We assign a single + unit wide pen for the stroke, assign the brush, and then draw the + rectangle. + + \snippet graphicsview/padnavigator/roundrectitem.cpp 5 + + If a pixmap has been assigned to the \e pixmap property, we draw this + pixmap in the center of the rectangle item. The pixmaps are scaled to match + the size of the icons; in arguably a better approach would have been to + store the icons with the right size in the first places. + + \snippet graphicsview/padnavigator/roundrectitem.cpp 6 + + Finally, for completeness we include the \c fill property implementation. + It returns the \c fill member variable's value, and when assigned to, it + calls \l{QGraphicsItem::update()}{update()}. + + As mentioned already, \c RoundRectItem is the base class for \c + FlippablePad, which is the class representing the tilting pad itself. We + will proceed to reviewing \c FlippablePad. + + \section1 FlippablePad Class Definition + + \c FlippablePad is, in addition to its inherited \c RoundRectItem + responsibilities, responsible for creating and managing a grid of icons. + + \snippet graphicsview/padnavigator/flippablepad.h 0 + + Its declaration is very simple: It inherits \c RoundRectItem and does not + need any special polymorphic behavior. It's suitable to declare its own + constructor, and a getter-function that allows \c PadNavigator to access + the icons in the grid by (row, column). + + The example has no "real" behavior or logic of any kind, and because of + that, the icons do not need to provide any \e behavior or special + interactions management. In a real application, however, it would be + natural for the \c FlippablePad and its icons to handle more of the + navigation logic. In this example, we have chosen to leave this to + the \c PadNavigator class, which we will get back to below. + + We will now review the \c FlippablePad implementation. This implementation + starts with two helper functions: \c boundsFromSize() and \c + posForLocation(): + + \snippet graphicsview/padnavigator/flippablepad.cpp 0 + + \c boundsForSize() takes a QSize argument, and returns the bounding + rectangle of the flippable pad item. The QSize determines how many rows and + columns the icon grid should have. Each icon is given 150x150 units of + space, and this determines the bounds. + + \snippet graphicsview/padnavigator/flippablepad.cpp 1 + + \c posForLocation() returns the position of an icon given its row and + column position. Like \c boundsForSize(), the function assumes each icon is + given 150x150 units of space, and that all icons are centered around the + flippable pad item's origin (0, 0). + + \snippet graphicsview/padnavigator/flippablepad.cpp 2 + + The \c FlippablePad constructor passes suitable bounds (using \c + boundsForSize()) and specific color to \c RoundRectItem's constructor. + + \snippet graphicsview/padnavigator/flippablepad.cpp 3 + + It then loads pixmaps from compiled-in resources to use for its icons. + QDirIterator is very useful in this context, as it allows us to fetch all + resource "*.png" files inside the \c :/images directory without explicitly + naming the files. + + We also make sure not to load more pixmaps than we need. + + \snippet graphicsview/padnavigator/flippablepad.cpp 4 + + Now that we have the pixmaps, we can create icons, position then and assign + pixmaps. We start by finding a suitable size and color for the icons, and + initializing a convenient grid structure for storing the icons. This \c + iconGrid is also used later to find the icon for a specific (column, row) + location. + + For each row and column in our grid, we proceed to constructing each icon + as an instance of \c RoundRectItem. The item is placed by using the \c + posForLocation() helper function. To make room for the slip-behind + selection item, we give each icon a \l{QGraphicsItem::zValue()}{Z-value} of + 1. The pixmaps are distributed to the icons in round-robin fasion. + + Again, this approach is only suitable for example purposes. In a real-life + application where each icon represents a specific action, it would be more + natural to assign the pixmaps directly, or that the icons themselves + provide suitable pixmaps. + + \snippet graphicsview/padnavigator/flippablepad.cpp 5 + + Finally, the \c iconAt() function returns a pointer to the icon at a + specific row and column. It makes a somewhat bold assumption that the input + is valid, which is fair because the \c PadNavigator class only calls this + function with correct input. + + We will now review the \c SplashItem class. + + \section1 SplashItem Class Definition + + The \c SplashItem class represents the "splash window", a semitransparent + white overlay with text that appears immediately after the application has + started, and disappears after pressing any key. The animation is controlled + by \c PadNavigator; this class is very simple by itself. + + \snippet graphicsview/padnavigator/splashitem.h 0 + + The class declaration shows that \c SplashItem inherits QGraphicsObject to + allow it to be controlled by QPropertyAnimation. It reimplements the + mandatory \l{QGraphicsItem::paint()}{paint()} and + \l{QGraphicsItem::boundingRect()}{boundingRect()} pure virtual functions, + and keeps a \c text member variable which will contain the information text + displayed on this splash item. + + Let's look at its implementation. + + \snippet graphicsview/padnavigator/splashitem.cpp 0 + + The constructor forwards to QGraphicsObject as expected, assigns a text + message to the \c text member variable, and enables + \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache}. This cache + mode is suitable because the splash item only moves and is never + transformed, and because it contains text, it's important that it has a + pixel perfect visual appearance (in constrast to + \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache}, where the + visual appearance is not as good). + + We use caching to avoid having to relayout and rerender the text for each + frame. An alterative approach would be to use the new QStaticText class. + + \snippet graphicsview/padnavigator/splashitem.cpp 1 + + \c SplashItem's bounding rectangle is fixed at (400x175). + + \snippet graphicsview/padnavigator/splashitem.cpp 2 + + The \l{QGraphicsItem::paint()}{paint()} implementation draws a clipped + round rectangle with a thick 2-unit border and a semi-transparent white + background. It proceeds to finding a suitable text area by adjusting the + splash item's bounding rectangle with 10 units in each side. The text is + rendered inside this rectangle, with top-left alignment, and with word + wrapping enabled. + + The main class now remains. We will proceed to reviewing \c PadNavigator. + + \section1 PadNavigator Class Definition + + \c PadNavigator represents the main window of our Pad Navigator Example + application. It creates and controls a somewhat complex state machine, and + several animations. Its class declaration is very simple: + + \snippet graphicsview/padnavigator/padnavigator.h 0 + + It inherits QGraphicsView and reimplements only one function: + \l{QGraphicsView::resizeEvent()}{resizeEvent()}, to ensure the scene is + scaled to fit inside the view when resizing the main window. + + The \c PadNavigator constructor takes a QSize argument that determines the + number or rows and columns in the grid. + + It also keeps a private member instance, \c form, which is the generated + code for the pad's back side item's QGraphicsProxyWidget-embedded form. + + \snippet graphicsview/padnavigator/padnavigator.cpp 0 + + \c PadNavigator's constructor is a bit long. In short, its job is to create + all items, including the \c FlippablePad, the \c SplashItem and the + QGraphicsProxyWidget \c backItem, and then to set up all animations, states + and transitions that control the behavior of the application. + + It starts out simple, by forwarding to QGraphicsView's constructor. + + \snippet graphicsview/padnavigator/padnavigator.cpp 1 + + The first item to be created is \c SplashItem. This is going to be a top-level + item in the scene, next to \c FlippablePad, and stacked on top of it, so we + assign it a \l{QGraphicsItem::zValue()}{Z-value} of 1. + + \snippet graphicsview/padnavigator/padnavigator.cpp 2 + + Now we construct the \c FlippablePad item, passing its column-row count to + its constructor. + + The pad is controlled by three transformations, and we create one + QGraphicsRotation object for each of these. + + \list + \li \c flipRotation: Rotates the grid around its Qt::YAxis. This rotation is + animated from 0 to 180, and eventually back, when enter is pressed on the + keyboard, flipping the pad around. + \li \c xRotation: Rotates the grid around its Qt::XAxis. This is used to + tilt the pad vertically corresponding to which item is currently selected. + This way, the selected item is always kept in front. + \li \c yRotation: Rotates the grid around its Qt::YAxis. This is used to + tilt the pad horizontally corresponding to which item is selected. This + way, the selected item is always kept in front. + \endlist + + The combination of all three rotations is assigned via + QGraphicsItem::setTransformations(). + + \snippet graphicsview/padnavigator/padnavigator.cpp 3 + + Now we construct the QGraphicsProxyWidget-embedded \c backItem. The proxy + widget is created as a child of the pad. We create a new QWidget and + populate it with the \c form member. To ensure the \c hostName line edit is + the first to receive input focus when this item is shown, we call + \l{QWidget::setFocus()}{setFocus()} immediately. This will not give the + widget focus right away; it will only prepare the item to automatically + receive focus once it is shown. + + The QWidget based form is embedded into the proxy widget. The proxy is + hidden initially; we only want to show it when the pad is rotated at least + 90 degrees, and we also rotate the proxy itself by 180 degrees. This way we + give the impression that the proxy widget is "behind" the flipped pad, when + in fact, it's actually \e{on top of it}. + + We enable \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache} to + ensure the flip animation can run smoothly. + + \snippet graphicsview/padnavigator/padnavigator.cpp 4 + + We now create the selection item. This is simply another instance of \c + RoundRectItem that is slightly larger than the icons on the pad. We create + it as an immediate child of the \c FlippablePad, so the selection item is a + sibling to all the icons. By giving it a + \l{QGraphicsItem::zValue()}{Z-value} of 0.5 we ensure it will slide between + the pad and its icons. + + What follows now is a series of animation initializations. + + \snippet graphicsview/padnavigator/padnavigator.cpp 5 + + We begin with the animations that apply to the splash item. The first + animation, \c smoothSplashMove, ensures that the "y" property of \c splash + will be animated with a 250-millisecond duration + \l{QEasingCurve::InQuad}{InQuad} easing function. \c smoothSplashOpacity + ensures the opacity of \c splash eases in and out in 250 milliseconds. + + The values are assigned by \c PadNavigator's state machine, which is + created later. + + \snippet graphicsview/padnavigator/padnavigator.cpp 6 + + These are the animations that control the selection item's movement and the + \c xRotation and \c yRotation QGraphicsRotation objects that tilt the pad. + All animations have a duration of 125 milliseconds, and they all use the + \l{QEasingCurve::InOutQuad}{InOutQuad} easing function. + + \snippet graphicsview/padnavigator/padnavigator.cpp 7 + + We now create the animations that control the flip-effect when you press + the enter key. The main goal is to rotate the pad by 180 degrees or back, + but we also need to make sure the selection item's tilt rotations are reset + back to 0 when the pad is flipped, and restored back to their original + values when flipped back: + + \list + \li \c smoothFlipRotation: Animates the main 180 degree rotation of the pad. + \li \c smoothFlipScale: Scales the pad out and then in again while the pad is rotating. + \li \c smoothFlipXRotation: Animates the selection item's X-tilt to 0 and back. + \li \c smoothFlipYRotation: Animates the selection item's Y-tilt to 0 and back. + \li \c flipAnimation: A parallel animation group that ensures all the above animations are run in parallel. + \endlist + + All animations are given a 500 millisecond duration and an + \l{QEasingCurve::InOutQuad}{InOutQuad} easing function. + + It's worth taking a close look at \c smoothFlipScale. This animation's + start and end values are both 1.0, but at animation step 0.5 the + animation's value is 0.7. This means that after 50% of the animation's + duration, or 250 milliseconds, the pad will be scaled down to 0.7x of its + original size, which gives a great visual effect while flipping. + + \snippet graphicsview/padnavigator/padnavigator.cpp 8 + + This section uses a trick to ensure that certain properties are assigned + precisely when the flip animation passes 50%, or 90 degrees, rotation. In + short, the pad's icons and selection item are all hidden, the pad's \c fill + property is enabled, and \c backItem is shown when flipping over. When + flipping back, the reverse properties are applied. + + The way this is achieved is by running a sequential animation in parallel + to the other animations. This sequence, dubbed \c setVariablesSequence, + starts with a 250 millisecond pause, and then executes several animations + with a duration of 0. Each animation will ensure that properties are set + immediate at this point. + + This approach can also be used to call functions or set any other + properties at a specific time while an animation is running. + + \snippet graphicsview/padnavigator/padnavigator.cpp 9 + + We will now create the state machine. The whole \c PadNavigator state + machinery is controlled by one single state machine that has a + straight-forward state structure. The state engine itself is created + as a child of the \c PadNavigator itself. We then create three top level + states: + + \list + \li \c splashState: The initial state where the splash item is visible. + \li \c frontState: The base state where the splash is gone and we can see + the front side of the pad, and navigate the selection item. + \li \c backState: The flipped state where the \c backItem is visible, and we + can interact with the QGraphicsProxyWidget-embedded form. + \endlist + + \snippet graphicsview/padnavigator/padnavigator.cpp 10 + + Each state assigns specific properties to objects on entry. Most + interesting perhaps is the assignment of the value 0.0 to the pad's \c + flipRotation angle property when in \c frontState, and 180.0 when in \c + backState. At the end of this section we register default animations with + the state engine; these animations will apply to their respective objects + and properties for any state transition. Otherwise it's common to assign + animations to specific transitions. + + The \c splashState state is set as the initial state. This is required + before we start the state engine. We proceed with creating some + transitions. + + \snippet graphicsview/padnavigator/padnavigator.cpp 11 + + QEventTransition defines a very flexible transition type. You can use this + class to trigger a transition based on an object receiving an event of a + specific type. In this case, we would like to transition from \c + splashState into \c frontState if \c PadNavigator receives any key press + event (QEvent::KeyPress). + + We register the \c splashItem's animations to this transition to ensure they + are used to animate the item's movement and opacity. + + \snippet graphicsview/padnavigator/padnavigator.cpp 12 + + We use QKeyEventTransition to capture specific key events. In this case, we + detect that the user presses Qt::Key_Return or Qt::Key_Enter, and use this + to trigger transitions between \c frontState and backState. We register \c + flipAnimation, our complex parallel animation group, with these + transitions. + + We continue by defining the states for each of the icons in the grid. + + \snippet graphicsview/padnavigator/padnavigator.cpp 13 + + We will use state groups to control transitions between icons. Each icon + represents a \e substate of \c frontState. We will then define transitions + between the states by detecting key presses, using QKeyEventTransition. + + We start by creating all the substates, and at the same time we create a + temporary grid structure for the states to make it easier to find which + states represents icons that are up, down, left and to the right each + other. + + Once the first substate is known, we set this up as the initial substate of + \c frontState. We will use the (0, 0), or top-left, icon for the initial + substate. We initialze the selection item's position to be exactly where + the top-left icon is. + + \snippet graphicsview/padnavigator/padnavigator.cpp 14 + + We can now create four transitions for each icon. Each transition ensures + that we move to the state corresponding to which arrow key has been + pressed. It's clear from this techinique that we could design any other + specific transitions to and from each of the sub states depending on these + and other keys. + + \snippet graphicsview/padnavigator/padnavigator.cpp 15 + + Also, for each of the icons, we assign suitable values to the \c xRotation + and \c yRotation objects' "angle"-properties. If you recall, these + properties "tilt" the pad corresponding to which item is currently + selected. We ensure each icon is invisible when the pad is flipped, and + visible when the pad is not flipped. To ensure the visible property is + assigned at the right time, we add property-controlling animations to the + \c setVariableSequence animation defined earlier. + + \snippet graphicsview/padnavigator/padnavigator.cpp 16 + + We are now finished with all states, transitions, and animations. We now + create the scene that will contain all our items. The scene gets a defined + background pixmap, and we disable item indexing (as most items in this + scene are animated). We add our \c pad item to the scene, and use its + bounding rectangle to fixate the scene rectangle. This rectangle is used by + the view to find a suitable size for the application window. + + Then the scene is assigned to the view, or in our case, \c PadNavigator + itself. + + \snippet graphicsview/padnavigator/padnavigator.cpp 17 + + Now that the scene has received its final size, we can position the splash + item at the very top, find its fade-out position, and add it to the scene. + + \snippet graphicsview/padnavigator/padnavigator.cpp 18 + + The view toggles a few necessary properties: + + \list + \li It disables its scroll bars - this application has no use for scroll bars. + \li It assigns a minimum size. This is necessary to avoid numerical errors + in our fit-in-view \c resizeEvent() implementation. + \li It sets \l{QGraphicsView::FullViewportUpdate}{FullViewportUpdate}, to + ensure QGraphicsView doesn't spend time figuring out precisely what needs + to be redrawn. This application is very simple - if anything changes, + everything is updated. + \li It enables background caching - this makes no performance difference + with OpenGL, but without OpenGL it avoids unnecessary re-scaling of the + background pixmap. + \li It sets render hints that increase rendering quality. + \li If OpenGL is supported, a QGLWidget viewport is assigned to the view. + \endlist + + Finally, we start the state engine. + + \snippet graphicsview/padnavigator/padnavigator.cpp 19 + + The \l{QGraphicsView::resizeEvent()}{resizeEvent()} implementation calls + the base implementation, and then calls QGraphicsView::fitInView() to scale + the scene so that it fits perfectly inside the view. + + By resizing the main application window, you can see this effect yourself. + The scene contents grow when you make the window larger, and shrink when + you make it smaller, while keeping the aspect ratio intact. + + \section1 The main() Function + + \snippet graphicsview/padnavigator/main.cpp 0 + + The \c main function creates the QApplication instance, uses + Q_INIT_RESOURCE to ensure our compiled-in resources aren't removed by the + linker, and then creates a 3x3 \c PadNavigator instance and shows it. + + Our flippable pad shows up with a suitable splash item once control returns + to the event loop. + + \section1 Performance Notes + + The example uses OpenGL if this is available, to achieve optimal + performance; otherwise perspective tranformations can be quite costly. + + Although this example does use QGraphicsProxyWidget to demonstrate + integration of Qt widget components integrated into Graphics View, using + QGraphicsProxyWidget comes with a performance penalty, and is therefore not + recommended for embedded development. + + This example uses extensive item caching to avoid rerendering of static + elements, at the expense of graphics memory. +*/ diff --git a/examples/widgets/doc/src/painterpaths.qdoc b/examples/widgets/doc/src/painterpaths.qdoc new file mode 100644 index 0000000000..45b0697cee --- /dev/null +++ b/examples/widgets/doc/src/painterpaths.qdoc @@ -0,0 +1,418 @@ +/**************************************************************************** +** +** 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 painting/painterpaths + \title Painter Paths Example + + The Painter Paths example shows how painter paths can be used to + build complex shapes for rendering. + + \image painterpaths-example.png + + The QPainterPath class provides a container for painting + operations, enabling graphical shapes to be constructed and + reused. + + A painter path is an object composed of a number of graphical + building blocks (such as rectangles, ellipses, lines, and curves), + and can be used for filling, outlining, and clipping. The main + advantage of painter paths over normal drawing operations is that + complex shapes only need to be created once, but they can be drawn + many times using only calls to QPainter::drawPath(). + + The example consists of two classes: + + \list + \li The \c RenderArea class which is a custom widget displaying + a single painter path. + \li The \c Window class which is the applications main window + displaying several \c RenderArea widgets, and allowing the user + to manipulate the painter paths' filling, pen, color + and rotation angle. + \endlist + + First we will review the \c Window class, then we will take a look + at the \c RenderArea class. + + \section1 Window Class Definition + + The \c Window class inherits QWidget, and is the applications main + window displaying several \c RenderArea widgets, and allowing the + user to manipulate the painter paths' filling, pen, color and + rotation angle. + + \snippet painting/painterpaths/window.h 0 + + We declare three private slots to respond to user input regarding + filling and color: \c fillRuleChanged(), \c fillGradientChanged() + and \c penColorChanged(). + + When the user changes the pen width and the rotation angle, the + new value is passed directly on to the \c RenderArea widgets using + the QSpinBox::valueChanged() signal. The reason why we must + implement slots to update the filling and color, is that QComboBox + doesn't provide a similar signal passing the new value as + argument; so we need to retrieve the new value, or values, before + we can update the \c RenderArea widgets. + + \snippet painting/painterpaths/window.h 1 + + We also declare a couple of private convenience functions: \c + populateWithColors() populates a given QComboBox with items + corresponding to the color names Qt knows about, and \c + currentItemData() returns the current item for a given QComboBox. + + \snippet painting/painterpaths/window.h 2 + + Then we declare the various components of the main window + widget. We also declare a convenience constant specifying the + number of \c RenderArea widgets. + + \section1 Window Class Implementation + + In the implementation of the \c Window class we first declare the + constant \c Pi with six significant figures: + + \snippet painting/painterpaths/window.cpp 0 + + In the constructor, we then define the various painter paths and + create corresponding \c RenderArea widgets which will render the + graphical shapes: + + \snippet painting/painterpaths/window.cpp 1 + + We construct a rectangle with sharp corners using the + QPainterPath::moveTo() and QPainterPath::lineTo() + functions. + + QPainterPath::moveTo() moves the current point to the point passed + as argument. A painter path is an object composed of a number of + graphical building blocks, i.e. subpaths. Moving the current point + will also start a new subpath (implicitly closing the previously + current path when the new one is started). The + QPainterPath::lineTo() function adds a straight line from the + current point to the given end point. After the line is drawn, the + current point is updated to be at the end point of the line. + + We first move the current point starting a new subpath, and we + draw three of the rectangle's sides. Then we call the + QPainterPath::closeSubpath() function which draws a line to the + beginning of the current subpath. A new subpath is automatically + begun when the current subpath is closed. The current point of the + new path is (0, 0). We could also have called + QPainterPath::lineTo() to draw the last line as well, and then + explicitly start a new subpath using the QPainterPath::moveTo() + function. + + QPainterPath also provide the QPainterPath::addRect() convenience + function, which adds a given rectangle to the path as a closed + subpath. The rectangle is added as a clockwise set of lines. The + painter path's current position after the rect has been added is + at the top-left corner of the rectangle. + + \snippet painting/painterpaths/window.cpp 2 + + Then we construct a rectangle with rounded corners. As before, we + use the QPainterPath::moveTo() and QPainterPath::lineTo() + functions to draw the rectangle's sides. To create the rounded + corners we use the QPainterPath::arcTo() function. + + QPainterPath::arcTo() creates an arc that occupies the given + rectangle (specified by a QRect or the rectangle's coordinates), + beginning at the given start angle and extending the given degrees + counter-clockwise. Angles are specified in degrees. Clockwise arcs + can be specified using negative angles. The function connects the + current point to the starting point of the arc if they are not + already connected. + + \snippet painting/painterpaths/window.cpp 3 + + We also use the QPainterPath::arcTo() function to construct the + ellipse path. First we move the current point starting a new + path. Then we call QPainterPath::arcTo() with starting angle 0.0 + and 360.0 degrees as the last argument, creating an ellipse. + + Again, QPainterPath provides a convenience function ( + QPainterPath::addEllipse()) which creates an ellipse within a + given bounding rectangle and adds it to the painter path. If the + current subpath is closed, a new subpath is started. The ellipse + is composed of a clockwise curve, starting and finishing at zero + degrees (the 3 o'clock position). + + \snippet painting/painterpaths/window.cpp 4 + + When constructing the pie chart path we continue to use a + combination of the mentioned functions: First we move the current + point, starting a new subpath. Then we create a line from the + center of the chart to the arc, and the arc itself. When we close + the subpath, we implicitly construct the last line back to the + center of the chart. + + \snippet painting/painterpaths/window.cpp 5 + + Constructing a polygon is equivalent to constructing a rectangle. + + QPainterPath also provide the QPainterPath::addPolygon() + convenience function which adds the given polygon to the path as a + new subpath. Current position after the polygon has been added is + the last point in polygon. + + \snippet painting/painterpaths/window.cpp 6 + + Then we create a path consisting of a group of subpaths: First we + move the current point, and create a circle using the + QPainterPath::arcTo() function with starting angle 0.0, and 360 + degrees as the last argument, as we did when we created the + ellipse path. Then we move the current point again, starting a + new subpath, and construct three sides of a square using the + QPainterPath::lineTo() function. + + Now, when we call the QPainterPath::closeSubpath() function the + last side is created. Remember that the + QPainterPath::closeSubpath() function draws a line to the + beginning of the \e current subpath, i.e the square. + + QPainterPath provide a convenience function, + QPainterPath::addPath() which adds a given path to the path that + calls the function. + + \snippet painting/painterpaths/window.cpp 7 + + When creating the text path, we first create the font. Then we set + the font's style strategy which tells the font matching algorithm + what type of fonts should be used to find an appropriate default + family. QFont::ForceOutline forces the use of outline fonts. + + To construct the text, we use the QPainterPath::addText() function + which adds the given text to the path as a set of closed subpaths + created from the supplied font. The subpaths are positioned so + that the left end of the text's baseline lies at the specified + point. + + \snippet painting/painterpaths/window.cpp 8 + + To create the Bezier path, we use the QPainterPath::cubicTo() + function which adds a Bezier curve between the current point and + the given end point with the given control point. After the curve + is added, the current point is updated to be at the end point of + the curve. + + In this case we omit to close the subpath so that we only have a + simple curve. But there is still a logical line from the curve's + endpoint back to the beginning of the subpath; it becomes visible + when filling the path as can be seen in the applications main + window. + + \snippet painting/painterpaths/window.cpp 9 + + The final path that we construct shows that you can use + QPainterPath to construct rather complex shapes using only the + previous mentioned QPainterPath::moveTo(), QPainterPath::lineTo() + and QPainterPath::closeSubpath() functions. + + \snippet painting/painterpaths/window.cpp 10 + + Now that we have created all the painter paths that we need, we + create a corresponding \c RenderArea widget for each. In the end, + we make sure that the number of render areas is correct using the + Q_ASSERT() macro. + + \snippet painting/painterpaths/window.cpp 11 + + Then we create the widgets associated with the painter paths' fill + rule. + + There are two available fill rules in Qt: The Qt::OddEvenFill rule + determine whether a point is inside the shape by drawing a + horizontal line from the point to a location outside the shape, + and count the number of intersections. If the number of + intersections is an odd number, the point is inside the + shape. This rule is the default. + + The Qt::WindingFill rule determine whether a point is inside the + shape by drawing a horizontal line from the point to a location + outside the shape. Then it determines whether the direction of the + line at each intersection point is up or down. The winding number + is determined by summing the direction of each intersection. If + the number is non zero, the point is inside the shape. + + The Qt::WindingFill rule can in most cases be considered as the + intersection of closed shapes. + + \snippet painting/painterpaths/window.cpp 12 + + We also create the other widgets associated with the filling, the + pen and the rotation angle. + + \snippet painting/painterpaths/window.cpp 16 + + We connect the comboboxes \l {QComboBox::activated()}{activated()} + signals to the associated slots in the \c Window class, while we + connect the spin boxes \l + {QSpinBox::valueChanged()}{valueChanged()} signal directly to the + \c RenderArea widget's respective slots. + + \snippet painting/painterpaths/window.cpp 17 + + We add the \c RenderArea widgets to a separate layout which we + then add to the main layout along with the rest of the widgets. + + \snippet painting/painterpaths/window.cpp 18 + + Finally, we initialize the \c RenderArea widgets by calling the \c + fillRuleChanged(), \c fillGradientChanged() and \c + penColorChanged() slots, and we set the initial pen width and + window title. + + \snippet painting/painterpaths/window.cpp 19 + \codeline + \snippet painting/painterpaths/window.cpp 20 + \codeline + \snippet painting/painterpaths/window.cpp 21 + + The private slots are implemented to retrieve the new value, or + values, from the associated comboboxes and update the RenderArea + widgets. + + First we determine the new value, or values, using the private \c + currentItemData() function and the qvariant_cast() template + function. Then we call the associated slot for each of the \c + RenderArea widgets to update the painter paths. + + \snippet painting/painterpaths/window.cpp 22 + + The \c populateWithColors() function populates the given combobox + with items corresponding to the color names Qt knows about + provided by the static QColor::colorNames() function. + + \snippet painting/painterpaths/window.cpp 23 + + The \c currentItemData() function simply return the current item + of the given combobox. + + \section1 RenderArea Class Definition + + The \c RenderArea class inherits QWidget, and is a custom widget + displaying a single painter path. + + \snippet painting/painterpaths/renderarea.h 0 + + We declare several public slots updating the \c RenderArea + widget's associated painter path. In addition we reimplement the + QWidget::minimumSizeHint() and QWidget::sizeHint() functions to + give the \c RenderArea widget a reasonable size within our + application, and we reimplement the QWidget::paintEvent() event + handler to draw its painter path. + + \snippet painting/painterpaths/renderarea.h 1 + + Each instance of the \c RenderArea class has a QPainterPath, a + couple of fill colors, a pen width, a pen color and a rotation + angle. + + \section1 RenderArea Class Implementation + + The constructor takes a QPainterPath as argument (in addition to + the optional QWidget parent): + + \snippet painting/painterpaths/renderarea.cpp 0 + + In the constructor we initialize the \c RenderArea widget with the + QPainterPath parameter as well as initializing the pen width and + rotation angle. We also set the widgets \l + {QWidget::backgroundRole()}{background role}; QPalette::Base is + typically white. + + \snippet painting/painterpaths/renderarea.cpp 1 + \codeline + \snippet painting/painterpaths/renderarea.cpp 2 + + Then we reimplement the QWidget::minimumSizeHint() and + QWidget::sizeHint() functions to give the \c RenderArea widget a + reasonable size within our application. + + \snippet painting/painterpaths/renderarea.cpp 3 + \codeline + \snippet painting/painterpaths/renderarea.cpp 4 + \codeline + \snippet painting/painterpaths/renderarea.cpp 5 + \codeline + \snippet painting/painterpaths/renderarea.cpp 6 + \codeline + \snippet painting/painterpaths/renderarea.cpp 7 + + The various public slots updates the \c RenderArea widget's + painter path by setting the associated property and make a call to + the QWidget::update() function, forcing a repaint of the widget + with the new rendering preferences. + + The QWidget::update() slot does not cause an immediate repaint; + instead it schedules a paint event for processing when Qt returns + to the main event loop. + + \snippet painting/painterpaths/renderarea.cpp 8 + + A paint event is a request to repaint all or parts of the + widget. The paintEvent() function is an event handler that can be + reimplemented to receive the widget's paint events. We reimplement + the event handler to render the \c RenderArea widget's painter + path. + + First, we create a QPainter for the \c RenderArea instance, and + set the painter's render hints. The QPainter::RenderHints are used + to specify flags to QPainter that may, or may not, be respected by + any given engine. QPainter::Antialiasing indicates that the engine + should anti-alias the edges of primitives if possible, i.e. put + additional pixels around the original ones to smooth the edges. + + \snippet painting/painterpaths/renderarea.cpp 9 + + Then we scale the QPainter's coordinate system to ensure that the + painter path is rendered in the right size, i.e that it grows with + the \c RenderArea widget when the application is resized. When we + constructed the various painter paths, they were all rnedered + within a square with a 100 pixel width which is equivalent to \c + RenderArea::sizeHint(). The QPainter::scale() function scales the + coordinate system by the \c RenderArea widget's \e current width + and height divided by 100. + + Now, when we are sure that the painter path has the right size, we + can translate the coordinate system to make the painter path + rotate around the \c RenderArea widget's center. After we have + performed the rotation, we must remember to translate the + coordinate system back again. + + \snippet painting/painterpaths/renderarea.cpp 10 + + Then we set the QPainter's pen with the instance's rendering + preferences. We create a QLinearGradient and set its colors + corresponding to the \c RenderArea widget's fill colors. Finally, + we set the QPainter's brush (the gradient is automatically + converted into a QBrush), and draw the \c RenderArea widget's + painter path using the QPainter::drawPath() function. +*/ diff --git a/examples/widgets/doc/src/pathstroke.qdoc b/examples/widgets/doc/src/pathstroke.qdoc new file mode 100644 index 0000000000..89a0182934 --- /dev/null +++ b/examples/widgets/doc/src/pathstroke.qdoc @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** 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 painting/pathstroke + \title Path Stroking + + In this example we show some of the various types of pens that can be + used in Qt. + + \image pathstroke-demo.png + + Qt defines cap styles for how the end points are treated and join + styles for how path segments are joined together. A standard set of + predefined dash patterns are also included that can be used with + QPen. + + In addition to the predefined patterns available in + QPen we also demonstrate direct use of the + QPainterPathStroker class which can be used to define + custom dash patterns. You can see this by enabling the + \e{Custom Pattern} option. +*/ diff --git a/examples/widgets/doc/src/pingpong.qdoc b/examples/widgets/doc/src/pingpong.qdoc new file mode 100644 index 0000000000..c56085d8cf --- /dev/null +++ b/examples/widgets/doc/src/pingpong.qdoc @@ -0,0 +1,93 @@ +/**************************************************************************** +** +** 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 statemachine/pingpong + \title Ping Pong States Example + + The Ping Pong States example shows how to use parallel states together + with custom events and transitions in \l{The State Machine Framework}. + + This example implements a statechart where two states communicate by + posting events to the state machine. The state chart looks as follows: + + \image pingpong-example.png + \omit + \caption This is a caption + \endomit + + The \c pinger and \c ponger states are parallel states, i.e. they are + entered simultaneously and will take transitions independently of + eachother. + + The \c pinger state will post the first \c ping event upon entry; the \c + ponger state will respond by posting a \c pong event; this will cause the + \c pinger state to post a new \c ping event; and so on. + + \snippet statemachine/pingpong/main.cpp 0 + + Two custom events are defined, \c PingEvent and \c PongEvent. + + \snippet statemachine/pingpong/main.cpp 1 + + The \c Pinger class defines a state that posts a \c PingEvent to the state + machine when the state is entered. + + \snippet statemachine/pingpong/main.cpp 2 + + The \c PingTransition class defines a transition that is triggered by + events of type \c PingEvent, and that posts a \c PongEvent (with a delay + of 500 milliseconds) to the state machine when the transition is + triggered. + + \snippet statemachine/pingpong/main.cpp 3 + + The \c PongTransition class defines a transition that is triggered by + events of type \c PongEvent, and that posts a \c PingEvent (with a delay + of 500 milliseconds) to the state machine when the transition is + triggered. + + \snippet statemachine/pingpong/main.cpp 4 + + The main() function begins by creating a state machine and a parallel + state group. + + \snippet statemachine/pingpong/main.cpp 5 + + Next, the \c pinger and \c ponger states are created, with the parallel + state group as their parent state. Note that the transitions are \e + targetless. When such a transition is triggered, the source state won't be + exited and re-entered; only the transition's onTransition() function will + be called, and the state machine's configuration will remain the same, + which is precisely what we want in this case. + + \snippet statemachine/pingpong/main.cpp 6 + + Finally, the group is added to the state machine, the machine is started, + and the application event loop is entered. + + */ diff --git a/examples/widgets/doc/src/pixelator.qdoc b/examples/widgets/doc/src/pixelator.qdoc new file mode 100644 index 0000000000..099c382c82 --- /dev/null +++ b/examples/widgets/doc/src/pixelator.qdoc @@ -0,0 +1,255 @@ +/**************************************************************************** +** +** 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 itemviews/pixelator + \title Pixelator Example + + The Pixelator example shows how delegates can be used to customize the way that + items are rendered in standard item views. + + \image pixelator-example.png + + By default, QTreeView, QTableView, and QListView use a standard item delegate + to display and edit a set of common data types that are sufficient for many + applications. However, an application may need to represent items of data in a + particular way, or provide support for rendering more specialized data types, + and this often requires the use of a custom delegate. + + In this example, we show how to use custom delegates to modify the appearance + of standard views. To do this, we implement the following components: + + \list + \li A model which represents each pixel in an image as an item of data, where each + item contains a value for the brightness of the corresponding pixel. + \li A custom delegate that uses the information supplied by the model to represent + each pixel as a black circle on a white background, where the radius of the + circle corresponds to the darkness of the pixel. + \endlist + + This example may be useful for developers who want to implement their own table + models or custom delegates. The process of creating custom delegates for editing + item data is covered in the \l{Spin Box Delegate Example}{Spin Box Delegate} + example. + + \section1 ImageModel Class Definition + + The \c ImageModel class is defined as follows: + + \snippet itemviews/pixelator/imagemodel.h 0 + + Since we only require a simple, read-only table model, we only need to implement + functions to indicate the dimensions of the image and supply data to other + components. + + \section1 ImageModel Class Implementation + + The constructor is trivial: + + \snippet itemviews/pixelator/imagemodel.cpp 0 + + The \c setImage() function sets the image that will be used by the model: + + \snippet itemviews/pixelator/imagemodel.cpp 1 + + The QAbstractItemModel::reset() call tells the view(s) that the model + has changed. + + The \c rowCount() and \c columnCount() functions return the height and width of + the image respectively: + + \snippet itemviews/pixelator/imagemodel.cpp 2 + \snippet itemviews/pixelator/imagemodel.cpp 3 + + Since the image is a simple two-dimensional structure, the \c parent arguments + to these functions are unused. They both simply return the relevant size from + the underlying image object. + + The \c data() function returns data for the item that corresponds to a given + model index in a format that is suitable for a particular role: + + \snippet itemviews/pixelator/imagemodel.cpp 4 + + In this implementation, we only check that the model index is valid, and that + the role requested is the \l{Qt::ItemDataRole}{DisplayRole}. If so, the function + returns the grayscale value of the relevant pixel in the image; otherwise, a null + model index is returned. + + This model can be used with QTableView to display the integer brightness values + for the pixels in the image. However, we will implement a custom delegate to + display this information in a more artistic way. + + The \c headerData() function is also reimplemented: + + \snippet itemviews/pixelator/imagemodel.cpp 5 + + We return (1, 1) as the size hint for a header item. If we + didn't, the headers would default to a larger size, preventing + us from displaying really small items (which can be specified + using the \uicontrol{Pixel size} combobox). + + \section1 PixelDelegate Class Definition + + The \c PixelDelegate class is defined as follows: + + \snippet itemviews/pixelator/pixeldelegate.h 0 + + This class provides only basic features for a delegate so, unlike the + \l{Spin Box Delegate Example}{Spin Box Delegate} example, we subclass + QAbstractItemDelegate instead of QItemDelegate. + + We only need to reimplement \l{QAbstractItemDelegate::paint()}{paint()} and + \l{QAbstractItemDelegate::sizeHint()}{sizeHint()} in this class. + However, we also provide a delegate-specific \c setPixelSize() function so + that we can change the delegate's behavior via the signals and slots mechanism. + + \section1 PixelDelegate Class Implementation + + The \c PixelDelegate constructor is used to set up a default value for + the size of each "pixel" that it renders. The base class constructor is + also called to ensure that the delegate is set up with a parent object, + if one is supplied: + + \snippet itemviews/pixelator/pixeldelegate.cpp 0 + + Each item is rendered by the delegate's + \l{QAbstractItemDelegate::paint()}{paint()} function. The view calls this + function with a ready-to-use QPainter object, style information that the + delegate should use to correctly draw the item, and an index to the item in + the model: + + \snippet itemviews/pixelator/pixeldelegate.cpp 1 + + The first task the delegate has to perform is to draw the item's background + correctly. Usually, selected items appear differently to non-selected items, + so we begin by testing the state passed in the style option and filling the + background if necessary. + + The radius of each circle is calculated in the following lines of code: + + \snippet itemviews/pixelator/pixeldelegate.cpp 3 + \snippet itemviews/pixelator/pixeldelegate.cpp 4 + + First, the largest possible radius of the circle is determined by taking the + smallest dimension of the style option's \c rect attribute. + Using the model index supplied, we obtain a value for the brightness of the + relevant pixel in the image. The radius of the circle is calculated by + scaling the brightness to fit within the item and subtracting it from the + largest possible radius. + + \snippet itemviews/pixelator/pixeldelegate.cpp 5 + \snippet itemviews/pixelator/pixeldelegate.cpp 6 + \snippet itemviews/pixelator/pixeldelegate.cpp 7 + + We save the painter's state, turn on antialiasing (to obtain smoother + curves), and turn off the pen. + + \snippet itemviews/pixelator/pixeldelegate.cpp 8 + \snippet itemviews/pixelator/pixeldelegate.cpp 9 + + The foreground of the item (the circle representing a pixel) must be + rendered using an appropriate brush. For unselected items, we will use a + solid black brush; selected items are drawn using a predefined brush from + the style option's palette. + + \snippet itemviews/pixelator/pixeldelegate.cpp 10 + + Finally, we paint the circle within the rectangle specified by the style + option and we call \l{QPainter::}{restore()} on the painter. + + The \c paint() function does not have to be particularly complicated; it is + only necessary to ensure that the state of the painter when the function + returns is the same as it was when it was called. This usually + means that any transformations applied to the painter must be preceded by + a call to QPainter::save() and followed by a call to QPainter::restore(). + + The delegate's \l{QAbstractItemDelegate::}{sizeHint()} function + returns a size for the item based on the predefined pixel size, initially set + up in the constructor: + + \snippet itemviews/pixelator/pixeldelegate.cpp 11 + + The delegate's size is updated whenever the pixel size is changed. + We provide a custom slot to do this: + + \snippet itemviews/pixelator/pixeldelegate.cpp 12 + + \section1 Using The Custom Delegate + + In this example, we use a main window to display a table of data, using the + custom delegate to render each cell in a particular way. Much of the + \c MainWindow class performs tasks that are not related to item views. Here, + we only quote the parts that are relevant. You can look at the rest of the + implementation by following the links to the code at the top of this + document. + + In the constructor, we set up a table view, turn off its grid, and hide its + headers: + + \snippet itemviews/pixelator/mainwindow.cpp 0 + \dots + \snippet itemviews/pixelator/mainwindow.cpp 1 + + This enables the items to be drawn without any gaps between them. Removing + the headers also prevents the user from adjusting the sizes of individual + rows and columns. + + We also set the minimum section size to 1 on the headers. If we + didn't, the headers would default to a larger size, preventing + us from displaying really small items (which can be specified + using the \uicontrol{Pixel size} combobox). + + The custom delegate is constructed with the main window as its parent, so + that it will be deleted correctly later, and we set it on the table view. + + \snippet itemviews/pixelator/mainwindow.cpp 2 + + Each item in the table view will be rendered by the \c PixelDelegate + instance. + + We construct a spin box to allow the user to change the size of each "pixel" + drawn by the delegate: + + \snippet itemviews/pixelator/mainwindow.cpp 3 + + This spin box is connected to the custom slot we implemented in the + \c PixelDelegate class. This ensures that the delegate always draws each + pixel at the currently specified size: + + \snippet itemviews/pixelator/mainwindow.cpp 4 + \dots + \snippet itemviews/pixelator/mainwindow.cpp 5 + + We also connect the spin box to a slot in the \c MainWindow class. This + forces the view to take into account the new size hints for each item; + these are provided by the delegate in its \c sizeHint() function. + + \snippet itemviews/pixelator/mainwindow.cpp 6 + + We explicitly resize the columns and rows to match the + \uicontrol{Pixel size} combobox. +*/ diff --git a/examples/widgets/doc/src/recentfiles.qdoc b/examples/widgets/doc/src/recentfiles.qdoc new file mode 100644 index 0000000000..e2e876b088 --- /dev/null +++ b/examples/widgets/doc/src/recentfiles.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 mainwindows/recentfiles + \title Recent Files Example + + The Recent Files example shows how a standard File menu can be extended to show + the most recent files loaded by a main window application. + + \image recentfiles-example.png +*/ diff --git a/examples/widgets/doc/src/rogue.qdoc b/examples/widgets/doc/src/rogue.qdoc new file mode 100644 index 0000000000..4c65dd2d6e --- /dev/null +++ b/examples/widgets/doc/src/rogue.qdoc @@ -0,0 +1,208 @@ +/**************************************************************************** +** +** 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 statemachine/rogue + \title Rogue Example + + The Rogue example shows how to use the Qt state machine for event + handling. + + \image rogue-example.png + + This example implements a simple text based game. Do you see the + \c{@} in the screenshot? That's you, the rogue. The \c{#} + characters are walls, and the dots represent floor. In a real + game, other ASCII characters would represent all kinds of objects + and creatures, for instance, ancient dragons (\c{D}s) or food + rations (\c{%}s). But let's not get carried away. In this game, + the rogue is simply running around in an empty room. + + The rogue is moved with the keypad (2, 4, 8, 6). That aside, we + have implemented a \c quit command that triggers if the player + types \c {q}. The player is then asked if he/she really wants to + quit. + + Most games have commands that need more than one key press (we + think of consecutive presses, i.e., not of several keys being + pressed at the same time). In this game, only the \c quit command + falls under this category, but for the sake of argument, let's + imagine a fully-fledged game with a rich set of commands. If we + were to implement these by catching key events in + \l{QWidget::}{keyPressEvent()}, we would have to keep a lot of + class member variables to track the sequence of keys already typed + (or find some other way of deducing the current state of a + command). This can easily lead to spaghetti, which is--as we all + well know, I'm sure--unpleasant. With a state machine, on the + other hand, separate states can wait for a single key press, and + that makes our lives a lot simpler. + + The example consists of two classes: + + \list + \li \c Window draws the text display of the game and sets + up the state machine. The window also has a status bar + above the area in which the rouge moves. + \li \c MovementTransition is a transition that carries out + a single move of the rogue. + \endlist + + Before we embark on a code walkthrough, it is necessary to take a + closer look at the design of the machine. Here is a state chart + that shows what we want to achieve: + + \image rogue-statechart.png + + The input state waits for a key press to start a new command. + When receiving a key it recognizes, it transitions to one of the + two commands of the game; though, as we will see, movement is + handled by the transition itself. The quit state waits for the + player to answer yes or no (by typing \c y or \c n) when asked + whether he/she really wants to quit the game. + + The chart demonstrates how we use one state to wait for a single + key press. The press received may trigger one of the transitions + connected to the state. + + \section1 Window Class Definition + + The \c Window class is a widget that draws the text display of the + game. It also sets up the state machine, i.e., creates and + connects the states in the machine. It is the key events from this + widget that are used by the machine. + + \snippet statemachine/rogue/window.h 0 + + \c Direction specifies the direction in which the rogue is to + move. We use this in \c movePlayer(), which moves the rogue and + repaints the window. The game has a status line above the area in + which the rogue moves. The \c status property contains the text of + this line. We use a property because the QState class allows + setting any Qt \l{Qt's Property System}{property} when entered. + More on this later. + + \snippet statemachine/rogue/window.h 1 + + The \c map is an array with the characters that are currently + displayed. We set up the array in \c setupMap(), and update it + when the rogue is moved. \c pX and \c pY is the current position + of the rogue. \c WIDTH and \c HEIGHT are macros specifying the + dimensions of the map. + + The \c paintEvent() function is left out of this walkthrough. We + also do not discuss other code that does not concern the state + machine (the \c setupMap(), \c status(), \c setStatus(), \c + movePlayer(), and \c sizeHint() functions). If you wish to take a + look at the code, click on the link for the \c window.cpp file at + the top of this page. + + \section1 Window Class Implementation + + Here is the constructor of \c Window: + + \snippet statemachine/rogue/window.cpp 0 + \dots + \snippet statemachine/rogue/window.cpp 1 + + The player starts off at position (5, 5). We then set up the map + and statemachine. Let's proceed with the \c buildMachine() + function: + + \snippet statemachine/rogue/window.cpp 2 + + We enter \c inputState when the machine is started and from the \c + quitState if the user wants to continue playing. We then set the + status to a helpful reminder of how to play the game. + + First, the \c Movement transition is added to the input state. + This will enable the rogue to be moved with the keypad. Notice + that we don't set a target state for the movement transition. This + will cause the transition to be triggered (and the + \l{QAbstractTransition::}{onTransition()} function to be invoked), + but the machine will not leave the \c inputState. If we had set \c + inputState as the target state, we would first have left and then + entered the \c inputState again. + + \snippet statemachine/rogue/window.cpp 3 + + When we enter \c quitState, we update the status bar of the + window. + + \c QKeyEventTransition is a utility class that removes the hassle + of implementing transitions for \l{QKeyEvent}s. We simply need to + specify the key on which the transition should trigger and the + target state of the transition. + + \snippet statemachine/rogue/window.cpp 4 + + The transition from \c inputState allows triggering the quit state + when the player types \c {q}. + + \snippet statemachine/rogue/window.cpp 5 + + The machine is set up, so it's time to start it. + + \section1 The MovementTransition Class + + \c MovementTransition is triggered when the player request the + rogue to be moved (by typing 2, 4, 6, or 8) when the machine is in + the \c inputState. + + \snippet statemachine/rogue/movementtransition.h 0 + + In the constructor, we tell QEventTransition to only send + \l{QEvent::}{KeyPress} events to the + \l{QAbstractTransition::}{eventTest()} function: + + \snippet statemachine/rogue/movementtransition.h 1 + + The KeyPress events come wrapped in \l{QStateMachine::WrappedEvent}s. \c event + must be confirmed to be a wrapped event because Qt uses other + events internally. After that, it is simply a matter of checking + which key has been pressed. + + Let's move on to the \c onTransition() function: + + \snippet statemachine/rogue/movementtransition.h 2 + + When \c onTransition() is invoked, we know that we have a + \l{QEvent::}{KeyPress} event with 2, 4, 6, or 8, and can ask \c + Window to move the player. + + \section1 The Roguelike Tradition + + You might have been wondering why the game features a rogue. Well, + these kinds of text based dungeon exploration games date back to a + game called, yes, "Rogue". Although outflanked by the technology + of modern 3D computer games, roguelikes have a solid community of + hard-core, devoted followers. + + Playing these games can be surprisingly addictive (despite the + lack of graphics). Angband, the perhaps most well-known rougelike, + is found here: \l{http://rephial.org/}. +*/ + diff --git a/examples/widgets/doc/src/screenshot.qdoc b/examples/widgets/doc/src/screenshot.qdoc new file mode 100644 index 0000000000..2d41cf0d85 --- /dev/null +++ b/examples/widgets/doc/src/screenshot.qdoc @@ -0,0 +1,247 @@ +/**************************************************************************** +** +** 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 desktop/screenshot + \title Screenshot Example + + The Screenshot example shows how to take a screenshot of the + desktop using QApplication and QDesktopWidget. It also shows how + to use QTimer to provide a single-shot timer, and how to + reimplement the QWidget::resizeEvent() event handler to make sure + that an application resizes smoothly and without data loss. + + \image screenshot-example.png + + With the application the users can take a screenshot of their + desktop. They are provided with a couple of options: + + \list + \li Delaying the screenshot, giving them time to rearrange + their desktop. + \li Hiding the application's window while the screenshot is taken. + \endlist + + In addition the application allows the users to save their + screenshot if they want to. + + \section1 Screenshot Class Definition + + \snippet desktop/screenshot/screenshot.h 0 + + The \c Screenshot class inherits QWidget and is the application's + main widget. It displays the application options and a preview of + the screenshot. + + We reimplement the QWidget::resizeEvent() function to make sure + that the preview of the screenshot scales properly when the user + resizes the application widget. We also need several private slots + to facilitate the options: + + \list + \li The \c newScreenshot() slot prepares a new screenshot. + \li The \c saveScreenshot() slot saves the last screenshot. + \li The \c shootScreen() slot takes the screenshot. + \li The \c updateCheckBox() slot enables or disables the + \uicontrol {Hide This Window} option. + \endlist + + We also declare some private functions: We use the \c + createOptionsGroupBox(), \c createButtonsLayout() and \c + createButton() functions when we construct the widget. And we call + the private \c updateScreenshotLabel() function whenever a new + screenshot is taken or when a resize event changes the size of the + screenshot preview label. + + In addition we need to store the screenshot's original pixmap. The + reason is that when we display the preview of the screenshot, we + need to scale its pixmap, storing the original we make sure that + no data are lost in that process. + + \section1 Screenshot Class Implementation + + \snippet desktop/screenshot/screenshot.cpp 0 + + In the constructor we first create the QLabel displaying the + screenshot preview. + + We set the QLabel's size policy to be QSizePolicy::Expanding both + horizontally and vertically. This means that the QLabel's size + hint is a sensible size, but the widget can be shrunk and still be + useful. Also, the widget can make use of extra space, so it should + get as much space as possible. Then we make sure the QLabel is + aligned in the center of the \c Screenshot widget, and set its + minimum size. + + We create the applications's buttons and the group box containing + the application's options, and put it all into a main + layout. Finally we take the initial screenshot, and set the initial + delay and the window title, before we resize the widget to a + suitable size. + + \snippet desktop/screenshot/screenshot.cpp 1 + + The \c resizeEvent() function is reimplemented to receive the + resize events dispatched to the widget. The purpose is to scale + the preview screenshot pixmap without deformation of its content, + and also make sure that the application can be resized smoothly. + + To achieve the first goal, we scale the screenshot pixmap using + Qt::KeepAspectRatio. We scale the pixmap to a rectangle as large + as possible inside the current size of the screenshot preview + label, preserving the aspect ratio. This means that if the user + resizes the application window in only one direction, the preview + screenshot keeps the same size. + + To reach our second goal, we make sure that the preview screenshot + only is repainted (using the private \c updateScreenshotLabel() + function) when it actually changes its size. + + \snippet desktop/screenshot/screenshot.cpp 2 + + The private \c newScreenshot() slot is called when the user + requests a new screenshot; but the slot only prepares a new + screenshot. + + First we see if the \uicontrol {Hide This Window} option is checked, if + it is we hide the \c Screenshot widget. Then we disable the \uicontrol + {New Screenshot} button, to make sure the user only can request + one screenshot at a time. + + We create a timer using the QTimer class which provides repetitive + and single-shot timers. We set the timer to time out only once, + using the static QTimer::singleShot() function. This function + calls the private \c shootScreen() slot after the time interval + specified by the \uicontrol {Screenshot Delay} option. It is \c + shootScreen() that actually performs the screenshot. + + \snippet desktop/screenshot/screenshot.cpp 3 + + The \c saveScreenshot() slot is called when the user push the \uicontrol + Save button, and it presents a file dialog using the QFileDialog + class. + + QFileDialog enables a user to traverse the file system in order to + select one or many files or a directory. The easiest way to create + a QFileDialog is to use the convenience static + functions. + + We define the default file format to be png, and we make the file + dialog's initial path the path the application is run from. We + create the file dialog using the static + QFileDialog::getSaveFileName() function which returns a file name + selected by the user. The file does not have to exist. If the file + name is valid, we use the QPixmap::save() function to save the + screenshot's original pixmap in that file. + + \snippet desktop/screenshot/screenshot.cpp 4 + + The \c shootScreen() slot is called to take the screenshot. If the + user has chosen to delay the screenshot, we make the application + beep when the screenshot is taken using the static + QApplication::beep() function. + + The QApplication class manages the GUI application's control flow + and main settings. It contains the main event loop, where all + events from the window system and other sources are processed and + dispatched. + + \snippet desktop/screenshot/screenshot.cpp 5 + + Using the static function QApplication::primaryScreen(), we + obtain the QScreen object for the application's main screen. + + We take the screenshot using the QScreen::grabWindow() + function. The function grabs the contents of the window passed as + an argument, makes a pixmap out of it and returns that pixmap. + The window id can be obtained with QWidget::winId() or QWindow::winId(). + Here, however, we just pass 0 as the window id, indicating that we + want to grab the entire screen. + + We update the screenshot preview label using the private \c + updateScreenshotLabel() function. Then we enable the \uicontrol {New + Screenshot} button, and finally we make the \c Screenshot widget + visible if it was hidden during the screenshot. + + \snippet desktop/screenshot/screenshot.cpp 6 + + The \uicontrol {Hide This Window} option is enabled or disabled + depending on the delay of the screenshot. If there is no delay, + the application window cannot be hidden and the option's checkbox + is disabled. + + The \c updateCheckBox() slot is called whenever the user changes + the delay using the \uicontrol {Screenshot Delay} option. + + \snippet desktop/screenshot/screenshot.cpp 7 + + The private \c createOptionsGroupBox() function is called from the + constructor. + + First we create a group box that will contain all of the options' + widgets. Then we create a QSpinBox and a QLabel for the \uicontrol + {Screenshot Delay} option, and connect the spinbox to the \c + updateCheckBox() slot. Finally, we create a QCheckBox for the \uicontrol + {Hide This Window} option, add all the options' widgets to a + QGridLayout and install the layout on the group box. + + Note that we don't have to specify any parents for the widgets + when we create them. The reason is that when we add a widget to a + layout and install the layout on another widget, the layout's + widgets are automatically reparented to the widget the layout is + installed on. + + \snippet desktop/screenshot/screenshot.cpp 8 + + The private \c createButtonsLayout() function is called from the + constructor. We create the application's buttons using the private + \c createButton() function, and add them to a QHBoxLayout. + + \snippet desktop/screenshot/screenshot.cpp 9 + + The private \c createButton() function is called from the \c + createButtonsLayout() function. It simply creates a QPushButton + with the provided text, connects it to the provided receiver and + slot, and returns a pointer to the button. + + \snippet desktop/screenshot/screenshot.cpp 10 + + The private \c updateScreenshotLabel() function is called whenever + the screenshot changes, or when a resize event changes the size of + the screenshot preview label. It updates the screenshot preview's + label using the QLabel::setPixmap() and QPixmap::scaled() + functions. + + QPixmap::scaled() returns a copy of the given pixmap scaled to a + rectangle of the given size according to the given + Qt::AspectRatioMode and Qt::TransformationMode. + + We scale the original pixmap to fit the current screenshot label's + size, preserving the aspect ratio and giving the resulting pixmap + smoothed edges. +*/ + diff --git a/examples/widgets/doc/src/scribble.qdoc b/examples/widgets/doc/src/scribble.qdoc new file mode 100644 index 0000000000..5749b9ed07 --- /dev/null +++ b/examples/widgets/doc/src/scribble.qdoc @@ -0,0 +1,417 @@ +/**************************************************************************** +** +** 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/scribble + \title Scribble Example + + The Scribble example shows how to reimplement some of QWidget's + event handlers to receive the events generated for the + application's widgets. + + We reimplement the mouse event handlers to implement drawing, the + paint event handler to update the application and the resize event + handler to optimize the application's appearance. In addition we + reimplement the close event handler to intercept the close events + before terminating the application. + + The example also demonstrates how to use QPainter to draw an image + in real time, as well as to repaint widgets. + + \image scribble-example.png Screenshot of the Scribble example + + With the Scribble application the users can draw an image. The + \uicontrol File menu gives the users the possibility to open and edit an + existing image file, save an image and exit the application. While + drawing, the \uicontrol Options menu allows the users to to choose the + pen color and pen width, as well as clear the screen. In addition + the \uicontrol Help menu provides the users with information about the + Scribble example in particular, and about Qt in general. + + The example consists of two classes: + + \list + \li \c ScribbleArea is a custom widget that displays a QImage and + allows to the user to draw on it. + \li \c MainWindow provides a menu above the \c ScribbleArea. + \endlist + + We will start by reviewing the \c ScribbleArea class. Then we will + review the \c MainWindow class, which uses \c ScribbleArea. + + \section1 ScribbleArea Class Definition + + \snippet widgets/scribble/scribblearea.h 0 + + The \c ScribbleArea class inherits from QWidget. We reimplement + the \c mousePressEvent(), \c mouseMoveEvent() and \c + mouseReleaseEvent() functions to implement the drawing. We + reimplement the \c paintEvent() function to update the scribble + area, and the \c resizeEvent() function to ensure that the QImage + on which we draw is at least as large as the widget at any time. + + We need several public functions: \c openImage() loads an image + from a file into the scribble area, allowing the user to edit the + image; \c save() writes the currently displayed image to file; \c + clearImage() slot clears the image displayed in the scribble + area. We need the private \c drawLineTo() function to actually do + the drawing, and \c resizeImage() to change the size of a + QImage. The \c print() slot handles printing. + + We also need the following private variables: + + \list + \li \c modified is \c true if there are unsaved + changes to the image displayed in the scribble area. + \li \c scribbling is \c true while the user is pressing + the left mouse button within the scribble area. + \li \c penWidth and \c penColor hold the currently + set width and color for the pen used in the application. + \li \c image stores the image drawn by the user. + \li \c lastPoint holds the position of the cursor at the last + mouse press or mouse move event. + \endlist + + \section1 ScribbleArea Class Implementation + + \snippet widgets/scribble/scribblearea.cpp 0 + + In the constructor, we set the Qt::WA_StaticContents + attribute for the widget, indicating that the widget contents are + rooted to the top-left corner and don't change when the widget is + resized. Qt uses this attribute to optimize paint events on + resizes. This is purely an optimization and should only be used + for widgets whose contents are static and rooted to the top-left + corner. + + \snippet widgets/scribble/scribblearea.cpp 1 + \snippet widgets/scribble/scribblearea.cpp 2 + + In the \c openImage() function, we load the given image. Then we + resize the loaded QImage to be at least as large as the widget in + both directions using the private \c resizeImage() function and + we set the \c image member variable to be the loaded image. At + the end, we call QWidget::update() to schedule a repaint. + + \snippet widgets/scribble/scribblearea.cpp 3 + \snippet widgets/scribble/scribblearea.cpp 4 + + The \c saveImage() function creates a QImage object that covers + only the visible section of the actual \c image and saves it using + QImage::save(). If the image is successfully saved, we set the + scribble area's \c modified variable to \c false, because there is + no unsaved data. + + \snippet widgets/scribble/scribblearea.cpp 5 + \snippet widgets/scribble/scribblearea.cpp 6 + \codeline + \snippet widgets/scribble/scribblearea.cpp 7 + \snippet widgets/scribble/scribblearea.cpp 8 + + The \c setPenColor() and \c setPenWidth() functions set the + current pen color and width. These values will be used for future + drawing operations. + + \snippet widgets/scribble/scribblearea.cpp 9 + \snippet widgets/scribble/scribblearea.cpp 10 + + The public \c clearImage() slot clears the image displayed in the + scribble area. We simply fill the entire image with white, which + corresponds to RGB value (255, 255, 255). As usual when we modify + the image, we set \c modified to \c true and schedule a repaint. + + \snippet widgets/scribble/scribblearea.cpp 11 + \snippet widgets/scribble/scribblearea.cpp 12 + + For mouse press and mouse release events, we use the + QMouseEvent::button() function to find out which button caused + the event. For mose move events, we use QMouseEvent::buttons() + to find which buttons are currently held down (as an OR-combination). + + If the users press the left mouse button, we store the position + of the mouse cursor in \c lastPoint. We also make a note that the + user is currently scribbling. (The \c scribbling variable is + necessary because we can't assume that a mouse move and mouse + release event is always preceded by a mouse press event on the + same widget.) + + If the user moves the mouse with the left button pressed down or + releases the button, we call the private \c drawLineTo() function + to draw. + + \snippet widgets/scribble/scribblearea.cpp 13 + \snippet widgets/scribble/scribblearea.cpp 14 + + In the reimplementation of the \l + {QWidget::paintEvent()}{paintEvent()} function, we simply create + a QPainter for the scribble area, and draw the image. + + At this point, you might wonder why we don't just draw directly + onto the widget instead of drawing in a QImage and copying the + QImage onto screen in \c paintEvent(). There are at least three + good reasons for this: + + \list + \li The window system requires us to be able to redraw the widget + \e{at any time}. For example, if the window is minimized and + restored, the window system might have forgotten the contents + of the widget and send us a paint event. In other words, we + can't rely on the window system to remember our image. + + \li Qt normally doesn't allow us to paint outside of \c + paintEvent(). In particular, we can't paint from the mouse + event handlers. (This behavior can be changed using the + Qt::WA_PaintOnScreen widget attribute, though.) + + \li If initialized properly, a QImage is guaranteed to use 8-bit + for each color channel (red, green, blue, and alpha), whereas + a QWidget might have a lower color depth, depending on the + monitor configuration. This means that if we load a 24-bit or + 32-bit image and paint it onto a QWidget, then copy the + QWidget into a QImage again, we might lose some information. + \endlist + + \snippet widgets/scribble/scribblearea.cpp 15 + \snippet widgets/scribble/scribblearea.cpp 16 + + When the user starts the Scribble application, a resize event is + generated and an image is created and displayed in the scribble + area. We make this initial image slightly larger than the + application's main window and scribble area, to avoid always + resizing the image when the user resizes the main window (which + would be very inefficient). But when the main window becomes + larger than this initial size, the image needs to be resized. + + \snippet widgets/scribble/scribblearea.cpp 17 + \snippet widgets/scribble/scribblearea.cpp 18 + + In \c drawLineTo(), we draw a line from the point where the mouse + was located when the last mouse press or mouse move occurred, we + set \c modified to true, we generate a repaint event, and we + update \c lastPoint so that next time \c drawLineTo() is called, + we continue drawing from where we left. + + We could call the \c update() function with no parameter, but as + an easy optimization we pass a QRect that specifies the rectangle + inside the scribble are needs updating, to avoid a complete + repaint of the widget. + + \snippet widgets/scribble/scribblearea.cpp 19 + \snippet widgets/scribble/scribblearea.cpp 20 + + QImage has no nice API for resizing an image. There's a + QImage::copy() function that could do the trick, but when used to + expand an image, it fills the new areas with black, whereas we + want white. + + So the trick is to create a brand new QImage with the right size, + to fill it with white, and to draw the old image onto it using + QPainter. The new image is given the QImage::Format_RGB32 + format, which means that each pixel is stored as 0xffRRGGBB + (where RR, GG, and BB are the red, green and blue + color channels, ff is the hexadecimal value 255). + + Printing is handled by the \c print() slot: + + \snippet widgets/scribble/scribblearea.cpp 21 + + We construct a high resolution QPrinter object for the required + output format, using a QPrintDialog to ask the user to specify a + page size and indicate how the output should be formatted on the page. + + If the dialog is accepted, we perform the task of printing to the paint + device: + + \snippet widgets/scribble/scribblearea.cpp 22 + + Printing an image to a file in this way is simply a matter of + painting onto the QPrinter. We scale the image to fit within the + available space on the page before painting it onto the paint + device. + + \section1 MainWindow Class Definition + + \snippet widgets/scribble/mainwindow.h 0 + + The \c MainWindow class inherits from QMainWindow. We reimplement + the \l{QWidget::closeEvent()}{closeEvent()} handler from QWidget. + The \c open(), \c save(), \c penColor() and \c penWidth() + slots correspond to menu entries. In addition we create four + private functions. + + We use the boolean \c maybeSave() function to check if there are + any unsaved changes. If there are unsaved changes, we give the + user the opportunity to save these changes. The function returns + \c false if the user clicks \uicontrol Cancel. We use the \c saveFile() + function to let the user save the image currently displayed in + the scribble area. + + \section1 MainWindow Class Implementation + + \snippet widgets/scribble/mainwindow.cpp 0 + + In the constructor, we create a scribble area which we make the + central widget of the \c MainWindow widget. Then we create the + associated actions and menus. + + \snippet widgets/scribble/mainwindow.cpp 1 + \snippet widgets/scribble/mainwindow.cpp 2 + + Close events are sent to widgets that the users want to close, + usually by clicking \uicontrol{File|Exit} or by clicking the \uicontrol X + title bar button. By reimplementing the event handler, we can + intercept attempts to close the application. + + In this example, we use the close event to ask the user to save + any unsaved changes. The logic for that is located in the \c + maybeSave() function. If \c maybeSave() returns true, there are + no modifications or the users successfully saved them, and we + accept the event. The application can then terminate normally. If + \c maybeSave() returns false, the user clicked \uicontrol Cancel, so we + "ignore" the event, leaving the application unaffected by it. + + \snippet widgets/scribble/mainwindow.cpp 3 + \snippet widgets/scribble/mainwindow.cpp 4 + + In the \c open() slot we first give the user the opportunity to + save any modifications to the currently displayed image, before a + new image is loaded into the scribble area. Then we ask the user + to choose a file and we load the file in the \c ScribbleArea. + + \snippet widgets/scribble/mainwindow.cpp 5 + \snippet widgets/scribble/mainwindow.cpp 6 + + The \c save() slot is called when the users choose the \uicontrol {Save + As} menu entry, and then choose an entry from the format menu. The + first thing we need to do is to find out which action sent the + signal using QObject::sender(). This function returns the sender + as a QObject pointer. Since we know that the sender is an action + object, we can safely cast the QObject. We could have used a + C-style cast or a C++ \c static_cast<>(), but as a defensive + programming technique we use a qobject_cast(). The advantage is + that if the object has the wrong type, a null pointer is + returned. Crashes due to null pointers are much easier to diagnose + than crashes due to unsafe casts. + + Once we have the action, we extract the chosen format using + QAction::data(). (When the actions are created, we use + QAction::setData() to set our own custom data attached to the + action, as a QVariant. More on this when we review \c + createActions().) + + Now that we know the format, we call the private \c saveFile() + function to save the currently displayed image. + + \snippet widgets/scribble/mainwindow.cpp 7 + \snippet widgets/scribble/mainwindow.cpp 8 + + We use the \c penColor() slot to retrieve a new color from the + user with a QColorDialog. If the user chooses a new color, we + make it the scribble area's color. + + \snippet widgets/scribble/mainwindow.cpp 9 + \snippet widgets/scribble/mainwindow.cpp 10 + + To retrieve a new pen width in the \c penWidth() slot, we use + QInputDialog. The QInputDialog class provides a simple + convenience dialog to get a single value from the user. We use + the static QInputDialog::getInt() function, which combines a + QLabel and a QSpinBox. The QSpinBox is initialized with the + scribble area's pen width, allows a range from 1 to 50, a step of + 1 (meaning that the up and down arrow increment or decrement the + value by 1). + + The boolean \c ok variable will be set to \c true if the user + clicked \uicontrol OK and to \c false if the user pressed \uicontrol Cancel. + + \snippet widgets/scribble/mainwindow.cpp 11 + \snippet widgets/scribble/mainwindow.cpp 12 + + We implement the \c about() slot to create a message box + describing what the example is designed to show. + + \snippet widgets/scribble/mainwindow.cpp 13 + \snippet widgets/scribble/mainwindow.cpp 14 + + In the \c createAction() function we create the actions + representing the menu entries and connect them to the appropriate + slots. In particular we create the actions found in the \uicontrol + {Save As} sub-menu. We use QImageWriter::supportedImageFormats() + to get a list of the supported formats (as a QList). + + Then we iterate through the list, creating an action for each + format. We call QAction::setData() with the file format, so we + can retrieve it later as QAction::data(). We could also have + deduced the file format from the action's text, by truncating the + "...", but that would have been inelegant. + + \snippet widgets/scribble/mainwindow.cpp 15 + \snippet widgets/scribble/mainwindow.cpp 16 + + In the \c createMenu() function, we add the previously created + format actions to the \c saveAsMenu. Then we add the rest of the + actions as well as the \c saveAsMenu sub-menu to the \uicontrol File, + \uicontrol Options and \uicontrol Help menus. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus. The QMenuBar class provides + a horizontal menu bar with a list of pull-down \l{QMenu}s. At the + end we put the \uicontrol File and \uicontrol Options menus in the \c + {MainWindow}'s menu bar, which we retrieve using the + QMainWindow::menuBar() function. + + \snippet widgets/scribble/mainwindow.cpp 17 + \snippet widgets/scribble/mainwindow.cpp 18 + + In \c mayBeSave(), we check if there are any unsaved changes. If + there are any, we use QMessageBox to give the user a warning that + the image has been modified and the opportunity to save the + modifications. + + As with QColorDialog and QFileDialog, the easiest way to create a + QMessageBox is to use its static functions. QMessageBox provides + a range of different messages arranged along two axes: severity + (question, information, warning and critical) and complexity (the + number of necessary response buttons). Here we use the \c + warning() function sice the message is rather important. + + If the user chooses to save, we call the private \c saveFile() + function. For simplicitly, we use PNG as the file format; the + user can always press \uicontrol Cancel and save the file using another + format. + + The \c maybeSave() function returns \c false if the user clicks + \uicontrol Cancel; otherwise it returns \c true. + + \snippet widgets/scribble/mainwindow.cpp 19 + \snippet widgets/scribble/mainwindow.cpp 20 + + In \c saveFile(), we pop up a file dialog with a file name + suggestion. The static QFileDialog::getSaveFileName() function + returns a file name selected by the user. The file does not have + to exist. +*/ diff --git a/examples/widgets/doc/src/sdi.qdoc b/examples/widgets/doc/src/sdi.qdoc new file mode 100644 index 0000000000..b686888797 --- /dev/null +++ b/examples/widgets/doc/src/sdi.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 mainwindows/sdi + \title SDI Example + + The SDI example shows how to create a Single Document Interface. It uses a number of + top-level windows to display the contents of different text files. + + \image sdi-example.png +*/ diff --git a/examples/widgets/doc/src/shapedclock.qdoc b/examples/widgets/doc/src/shapedclock.qdoc new file mode 100644 index 0000000000..8d7b856fd6 --- /dev/null +++ b/examples/widgets/doc/src/shapedclock.qdoc @@ -0,0 +1,131 @@ +/**************************************************************************** +** +** 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/shapedclock + \title Shaped Clock Example + + The Shaped Clock example shows how to apply a widget mask to a top-level + widget to produce a shaped window. + + \image shapedclock-example.png + + Widget masks are used to customize the shapes of top-level widgets by restricting + the available area for painting. On some window systems, setting certain window flags + will cause the window decoration (title bar, window frame, buttons) to be disabled, + allowing specially-shaped windows to be created. In this example, we use this feature + to create a circular window containing an analog clock. + + Since this example's window does not provide a \uicontrol File menu or a close + button, we provide a context menu with an \uicontrol Exit entry so that the example + can be closed. Click the right mouse button over the window to open this menu. + + \section1 ShapedClock Class Definition + + The \c ShapedClock class is based on the \c AnalogClock class defined in the + \l{Analog Clock Example}{Analog Clock} example. The whole class definition is + presented below: + + \snippet widgets/shapedclock/shapedclock.h 0 + + The \l{QWidget::paintEvent()}{paintEvent()} implementation is the same as that found + in the \c AnalogClock class. We implement \l{QWidget::sizeHint()}{sizeHint()} + so that we don't have to resize the widget explicitly. We also provide an event + handler for resize events. This allows us to update the mask if the clock is resized. + + Since the window containing the clock widget will have no title bar, we provide + implementations for \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} and + \l{QWidget::mousePressEvent()}{mousePressEvent()} to allow the clock to be dragged + around the screen. The \c dragPosition variable lets us keep track of where the user + last clicked on the widget. + + \section1 ShapedClock Class Implementation + + The \c ShapedClock constructor performs many of the same tasks as the \c AnalogClock + constructor. We set up a timer and connect it to the widget's update() slot: + + \snippet widgets/shapedclock/shapedclock.cpp 0 + + We inform the window manager that the widget is not to be decorated with a window + frame by setting the Qt::FramelessWindowHint flag on the widget. As a result, we need + to provide a way for the user to move the clock around the screen. + + Mouse button events are delivered to the \c mousePressEvent() handler: + + \snippet widgets/shapedclock/shapedclock.cpp 1 + + If the left mouse button is pressed over the widget, we record the displacement in + global (screen) coordinates between the top-left position of the widget's frame (even + when hidden) and the point where the mouse click occurred. This displacement will be + used if the user moves the mouse while holding down the left button. Since we acted + on the event, we accept it by calling its \l{QEvent::accept()}{accept()} function. + + \image shapedclock-dragging.png + + The \c mouseMoveEvent() handler is called if the mouse is moved over the widget. + + \snippet widgets/shapedclock/shapedclock.cpp 2 + + If the left button is held down while the mouse is moved, the top-left corner of the + widget is moved to the point given by subtracting the \c dragPosition from the current + cursor position in global coordinates. If we drag the widget, we also accept the event. + + The \c paintEvent() function is given for completeness. See the + \l{Analog Clock Example}{Analog Clock} example for a description of the process used + to render the clock. + + \snippet widgets/shapedclock/shapedclock.cpp 3 + + In the \c resizeEvent() handler, we re-use some of the code from the \c paintEvent() + to determine the region of the widget that is visible to the user: + + \snippet widgets/shapedclock/shapedclock.cpp 4 + + Since the clock face is a circle drawn in the center of the widget, this is the region + we use as the mask. + + Although the lack of a window frame may make it difficult for the user to resize the + widget on some platforms, it will not necessarily be impossible. The \c resizeEvent() + function ensures that the widget mask will always be updated if the widget's dimensions + change, and additionally ensures that it will be set up correctly when the widget is + first displayed. + + Finally, we implement the \c sizeHint() for the widget so that it is given a reasonable + default size when it is first shown: + + \snippet widgets/shapedclock/shapedclock.cpp 5 + + \section1 Notes on Widget Masks + + Since QRegion allows arbitrarily complex regions to be created, widget masks can be + made to suit the most unconventionally-shaped windows, and even allow widgets to be + displayed with holes in them. + + Widget masks can also be constructed by using the contents of pixmap to define the + opaque part of the widget. For a pixmap with an alpha channel, a suitable mask can be + obtained with QPixmap::mask(). +*/ diff --git a/examples/widgets/doc/src/simpledommodel.qdoc b/examples/widgets/doc/src/simpledommodel.qdoc new file mode 100644 index 0000000000..2564c654fa --- /dev/null +++ b/examples/widgets/doc/src/simpledommodel.qdoc @@ -0,0 +1,280 @@ +/**************************************************************************** +** +** 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 itemviews/simpledommodel + \title Simple DOM Model Example + + The Simple DOM Model example shows how an existing class can be adapted for use with + the model/view framework. + + \image simpledommodel-example.png + + Qt provides two complementary sets of classes for reading XML files: The classes based + around QXmlReader provide a SAX-style API for incremental reading of large files, and + the classes based around QDomDocument enable developers to access the contents of XML + files using a Document Object Model (DOM) API. + + In this example, we create a model that uses the DOM API to expose the structure and + contents of XML documents to views via the standard QAbstractModel interface. + + \section1 Design and Concepts + + Reading an XML document with Qt's DOM classes is a straightforward process. Typically, + the contents of a file are supplied to QDomDocument, and nodes are accessed using the + functions provided by QDomNode and its subclasses. + + \omit + For example, the following code + snippet reads the contents of a file into a QDomDocument object and traverses the + document, reading all the plain text that can be found: + + \snippet doc/src/snippets/code/doc_src_examples_simpledommodel.cpp 0 + + In principle, the functions provided by QDomNode can be used to navigate from any + given starting point in a document to the piece of data requested by another component. + Since QDomDocument maintains information about the structure of a document, we can + use this to implement the required virtual functions in a QAbstractItemModel subclass. + \endomit + + The aim is to use the structure provided by QDomDocument by wrapping QDomNode objects + in item objects similar to the \c TreeItem objects used in the + \l{Simple Tree Model Example}{Simple Tree Model} example. + + \section1 DomModel Class Definition + + Let us begin by examining the \c DomModel class: + + \snippet itemviews/simpledommodel/dommodel.h 0 + + The class definition contains all the basic functions that are needed for a + read-only model. Only the constructor and \c document() function are specific to + this model. The private \c domDocument variable is used to hold the document + that is exposed by the model; the \c rootItem variable contains a pointer to + the root item in the model. + + \section1 DomItem Class Definition + + The \c DomItem class is used to hold information about a specific QDomNode in + the document: + + \snippet itemviews/simpledommodel/domitem.h 0 + + Each \c DomItem provides a wrapper for a QDomNode obtained from the underlying + document which contains a reference to the node, it's location in the parent node's + list of child nodes, and a pointer to a parent wrapper item. + + The \c parent(), \c child(), and \c row() functions are convenience functions for + the \c DomModel to use that provide basic information about the item to be discovered + quickly. The node() function provides access to the underlying QDomNode object. + + As well as the information supplied in the constructor, the class maintains a cache + of information about any child items. This is used to provide a collection of + persistent item objects that the model can identify consistently and improve the + performance of the model when accessing child items. + + \section1 DomItem Class Implementation + + Since the \c DomItem class is only a thin wrapper around QDomNode objects, with a + few additional features to help improve performance and memory usage, we can provide + a brief outline of the class before discussing the model itself. + + The constructor simply records details of the QDomNode that needs to be wrapped: + + \snippet itemviews/simpledommodel/domitem.cpp 0 + \snippet itemviews/simpledommodel/domitem.cpp 1 + + As a result, functions to provide the parent wrapper, the row number occupied by + the item in its parent's list of children, and the underlying QDomNode for each item + are straightforward to write: + + \snippet itemviews/simpledommodel/domitem.cpp 4 + \codeline + \snippet itemviews/simpledommodel/domitem.cpp 6 + \codeline + \snippet itemviews/simpledommodel/domitem.cpp 3 + + It is necessary to maintain a collection of items which can be consistently identified + by the model. For that reason, we maintain a hash of child wrapper items that, to + minimize memory usage, is initially empty. The model uses the item's \c child() + function to help create model indexes, and this constructs wrappers for the children + of the item's QDomNode, relating the row number of each child to the newly-constructed + wrapper: + + \snippet itemviews/simpledommodel/domitem.cpp 5 + + If a QDomNode was previously wrapped, the cached wrapper is returned; otherwise, a + new wrapper is constructed and stored for valid children, and zero is returned for + invalid ones. + + The class's destructor deletes all the child items of the wrapper: + + \snippet itemviews/simpledommodel/domitem.cpp 2 + + These, in turn, will delete their children and free any QDomNode objects in use. + + \section1 DomModel Class Implementation + + The structure provided by the \c DomItem class makes the implementation of \c DomModel + similar to the \c TreeModel shown in the + \l{Simple Tree Model Example}{Simple Tree Model} example. + + The constructor accepts an existing document and a parent object for the model: + + \snippet itemviews/simpledommodel/dommodel.cpp 0 + + A shallow copy of the document is stored for future reference, and a root item is + created to provide a wrapper around the document. We assign the root item a row + number of zero only to be consistent since the root item will have no siblings. + + Since the model only contains information about the root item, the destructor only + needs to delete this one item: + + \snippet itemviews/simpledommodel/dommodel.cpp 1 + + All of the child items in the tree will be deleted by the \c DomItem destructor as + their parent items are deleted. + + \section2 Basic Properties of The Model + + Some aspects of the model do not depend on the structure of the underlying document, + and these are simple to implement. + + The number of columns exposed by the model is returned by the \c columnCount() + function: + + \snippet itemviews/simpledommodel/dommodel.cpp 2 + + This value is fixed, and does not depend on the location or type of the underlying + node in the document. We will use these three columns to display different kinds of + data from the underlying document. + + Since we only implement a read-only model, the \c flags() function is straightforward + to write: + + \snippet itemviews/simpledommodel/dommodel.cpp 5 + + Since the model is intended for use in a tree view, the \c headerData() function only + provides a horizontal header: + + \snippet itemviews/simpledommodel/dommodel.cpp 6 + + The model presents the names of nodes in the first column, element attributes in the + second, and any node values in the third. + + \section2 Navigating The Document + + The index() function creates a model index for the item with the given row, column, + and parent in the model: + + \snippet itemviews/simpledommodel/dommodel.cpp 7 + + The function first has to relate the parent index to an item that contains a node + from the underlying document. If the parent index is invalid, it refers to the root + node in the document, so we retrieve the root item that wraps it; otherwise, we + obtain a pointer to the relevant item using the QModelIndex::internalPointer() + function. We are able to extract a pointer in this way because any valid model index + will have been created by this function, and we store pointers to item objects in + any new indexes that we create with QAbstractItemModel::createIndex(): + + \snippet itemviews/simpledommodel/dommodel.cpp 8 + + A child item for the given row is provided by the parent item's \c child() function. + If a suitable child item was found then we call + \l{QAbstractItemModel::createIndex()}{createIndex()} to produce a model index for the + requested row and column, passing a pointer to the child item for it to store + internally. If no suitable child item is found, an invalid model index is returned. + + Note that the items themselves maintain ownership of their child items. This means + that the model does not need to keep track of the child items that have been created, + and can let the items themselves tidy up when they are deleted. + + The number of rows beneath a given item in the model is returned by the \c rowCount() + function, and is the number of child nodes contained by the node that corresponds to + the specified model index: + + \snippet itemviews/simpledommodel/dommodel.cpp 10 + + To obtain the relevant node in the underlying document, we access the item via the + internal pointer stored in the model index. If an invalid index is supplied, the + root item is used instead. We use the item's \c node() function to access the node + itself, and simply count the number of child nodes it contains. + + Since the model is used to represent a hierarchical data structure, it needs to + provide an implementation for the \c parent() function. This returns a model index + that corresponds to the parent of a child model index supplied as its argument: + + \snippet itemviews/simpledommodel/dommodel.cpp 9 + + For valid indexes other than the index corresponding to the root item, we obtain + a pointer to the relevant item using the method described in the \c index() function, + and use the item's \c parent() function to obtain a pointer to the parent item. + + If no valid parent item exists, or if the parent item is the root item, we can simply + follow convention and return an invalid model index. For all other parent items, we + create a model index containing the appropriate row and column numbers, and a pointer + to the parent item we just obtained. + + Data is provided by the \c data() function. For simplicity, we only provide data for + the \l{Qt::DisplayRole}{display role}, returning an invalid variant for all other + requests: + + \snippet itemviews/simpledommodel/dommodel.cpp 3 + + As before, we obtain an item pointer for the index supplied, and use it to obtain + the underlying document node. Depending on the column specified, the data we return + is obtained in different ways: + + \snippet itemviews/simpledommodel/dommodel.cpp 4 + + For the first column, we return the node's name. For the second column, we read any + attributes that the node may have, and return a string that contains a space-separated + list of attribute-value assignments. For the third column, we return any value that + the node may have; this allows the contents of text nodes to be displayed in a view. + + If data from any other column is requested, an invalid variant is returned. + + \section1 Implementation Notes + + Ideally, we would rely on the structure provided by QDomDocument to help us write + the \l{QAbstractItemModel::parent()}{parent()} and + \l{QAbstractItemModel::index()}{index()} functions that are required when subclassing + QAbstractItemModel. However, since Qt's DOM classes use their own system for + dynamically allocating memory for DOM nodes, we cannot guarantee that the QDomNode + objects returned for a given piece of information will be the same for subsequent + accesses to the document. + + We use item wrappers for each QDomNode to provide consistent pointers that the model + can use to navigate the document structure. + \omit + Since these items contain value references to the QDomNode objects themselves, this + has the side effect that the DOM nodes themselves can be used to reliably navigate + the document [not sure about this - QDom* may return different QDomNode objects for + the same piece of information]. However, this advantage is redundant since we need to + use wrapper items to obtain it. [Possible use of QDomNode cache in the model itself.] + \endomit +*/ diff --git a/examples/widgets/doc/src/simpletreemodel.qdoc b/examples/widgets/doc/src/simpletreemodel.qdoc new file mode 100644 index 0000000000..c054352cb8 --- /dev/null +++ b/examples/widgets/doc/src/simpletreemodel.qdoc @@ -0,0 +1,341 @@ +/**************************************************************************** +** +** 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 itemviews/simpletreemodel + \title Simple Tree Model Example + + The Simple Tree Model example shows how to create a basic, read-only + hierarchical model to use with Qt's standard view classes. For a + description of simple non-hierarchical list and table models, see the + \l{Model/View Programming} overview. + + \image simpletreemodel-example.png + + Qt's model/view architecture provides a standard way for views to + manipulate information in a data source, using an abstract model + of the data to simplify and standardize the way it is accessed. + Simple models represent data as a table of items, and allow views + to access this data via an + \l{Model/View Programming#Models}{index-based} system. More generally, + models can be used to represent data in the form of a tree structure + by allowing each item to act as a parent to a table of child items. + + Before attempting to implement a tree model, it is worth considering whether + the data is supplied by an external source, or whether it is going to be + maintained within the model itself. In this example, we will implement an + internal structure to hold data rather than discuss how to package data from + an external source. + + \section1 Design and Concepts + + The data structure that we use to represent the structure of the data takes + the form of a tree built from \c TreeItem objects. Each \c TreeItem + represents an item in a tree view, and contains several columns of data. + + \target SimpleTreeModelStructure + \table + \row \li \inlineimage treemodel-structure.png + \li \b{Simple Tree Model Structure} + + The data is stored internally in the model using \c TreeItem objects that + are linked together in a pointer-based tree structure. Generally, each + \c TreeItem has a parent item, and can have a number of child items. + However, the root item in the tree structure has no parent item and it + is never referenced outside the model. + + Each \c TreeItem contains information about its place in the tree + structure; it can return its parent item and its row number. Having + this information readily available makes implementing the model easier. + + Since each item in a tree view usually contains several columns of data + (a title and a summary in this example), it is natural to store this + information in each item. For simplicity, we will use a list of QVariant + objects to store the data for each column in the item. + \endtable + + The use of a pointer-based tree structure means that, when passing a + model index to a view, we can record the address of the corresponding + item in the index (see QAbstractItemModel::createIndex()) and retrieve + it later with QModelIndex::internalPointer(). This makes writing the + model easier and ensures that all model indexes that refer to the same + item have the same internal data pointer. + + With the appropriate data structure in place, we can create a tree model + with a minimal amount of extra code to supply model indexes and data to + other components. + + \section1 TreeItem Class Definition + + The \c TreeItem class is defined as follows: + + \snippet itemviews/simpletreemodel/treeitem.h 0 + + The class is a basic C++ class. It does not inherit from QObject or + provide signals and slots. It is used to hold a list of QVariants, + containing column data, and information about its position in the tree + structure. The functions provide the following features: + + \list + \li The \c appendChildItem() is used to add data when the model is first + constructed and is not used during normal use. + \li The \c child() and \c childCount() functions allow the model to obtain + information about any child items. + \li Information about the number of columns associated with the item is + provided by \c columnCount(), and the data in each column can be + obtained with the data() function. + \li The \c row() and \c parent() functions are used to obtain the item's + row number and parent item. + \endlist + + The parent item and column data are stored in the \c parentItem and + \c itemData private member variables. The \c childItems variable contains + a list of pointers to the item's own child items. + + \section1 TreeItem Class Implementation + + The constructor is only used to record the item's parent and the data + associated with each column. + + \snippet itemviews/simpletreemodel/treeitem.cpp 0 + + A pointer to each of the child items belonging to this item will be + stored in the \c childItems private member variable. When the class's + destructor is called, it must delete each of these to ensure that + their memory is reused: + + \snippet itemviews/simpletreemodel/treeitem.cpp 1 + + Since each of the child items are constructed when the model is initially + populated with data, the function to add child items is straightforward: + + \snippet itemviews/simpletreemodel/treeitem.cpp 2 + + Each item is able to return any of its child items when given a suitable + row number. For example, in the \l{#SimpleTreeModelStructure}{above diagram}, + the item marked with the letter "A" corresponds to the child of the root item + with \c{row = 0}, the "B" item is a child of the "A" item with \c{row = 1}, + and the "C" item is a child of the root item with \c{row = 1}. + + The \c child() function returns the child that corresponds to + the specified row number in the item's list of child items: + + \snippet itemviews/simpletreemodel/treeitem.cpp 3 + + The number of child items held can be found with \c childCount(): + + \snippet itemviews/simpletreemodel/treeitem.cpp 4 + + The \c TreeModel uses this function to determine the number of rows that + exist for a given parent item. + + The \c row() function reports the item's location within its parent's + list of items: + + \snippet itemviews/simpletreemodel/treeitem.cpp 8 + + Note that, although the root item (with no parent item) is automatically + assigned a row number of 0, this information is never used by the model. + + The number of columns of data in the item is trivially returned by the + \c columnCount() function. + + \snippet itemviews/simpletreemodel/treeitem.cpp 5 + + Column data is returned by the \c data() function, taking advantage of + QList's ability to provide sensible default values if the column number + is out of range: + + \snippet itemviews/simpletreemodel/treeitem.cpp 6 + + The item's parent is found with \c parent(): + + \snippet itemviews/simpletreemodel/treeitem.cpp 7 + + Note that, since the root item in the model will not have a parent, this + function will return zero in that case. We need to ensure that the model + handles this case correctly when we implement the \c TreeModel::parent() + function. + + \section1 TreeModel Class Definition + + The \c TreeModel class is defined as follows: + + \snippet itemviews/simpletreemodel/treemodel.h 0 + + This class is similar to most other subclasses of QAbstractItemModel that + provide read-only models. Only the form of the constructor and the + \c setupModelData() function are specific to this model. In addition, we + provide a destructor to clean up when the model is destroyed. + + \section1 TreeModel Class Implementation + + For simplicity, the model does not allow its data to be edited. As a + result, the constructor takes an argument containing the data that the + model will share with views and delegates: + + \snippet itemviews/simpletreemodel/treemodel.cpp 0 + + It is up to the constructor to create a root item for the model. This + item only contains vertical header data for convenience. We also use it + to reference the internal data structure that contains the model data, + and it is used to represent an imaginary parent of top-level items in + the model. + + The model's internal data structure is populated with items by the + \c setupModelData() function. We will examine this function separately + at the end of this document. + + The destructor ensures that the root item and all of its descendants + are deleted when the model is destroyed: + + \snippet itemviews/simpletreemodel/treemodel.cpp 1 + + Since we cannot add data to the model after it is constructed and set + up, this simplifies the way that the internal tree of items is managed. + + Models must implement an \c index() function to provide indexes for + views and delegates to use when accessing data. Indexes are created + for other components when they are referenced by their row and column + numbers, and their parent model index. If an invalid model + index is specified as the parent, it is up to the model to return an + index that corresponds to a top-level item in the model. + + When supplied with a model index, we first check whether it is valid. + If it is not, we assume that a top-level item is being referred to; + otherwise, we obtain the data pointer from the model index with its + \l{QModelIndex::internalPointer()}{internalPointer()} function and use + it to reference a \c TreeItem object. Note that all the model indexes + that we construct will contain a pointer to an existing \c TreeItem, + so we can guarantee that any valid model indexes that we receive will + contain a valid data pointer. + + \snippet itemviews/simpletreemodel/treemodel.cpp 6 + + Since the row and column arguments to this function refer to a + child item of the corresponding parent item, we obtain the item using + the \c TreeItem::child() function. The + \l{QAbstractItemModel::createIndex()}{createIndex()} function is used + to create a model index to be returned. We specify the row and column + numbers, and a pointer to the item itself. The model index can be used + later to obtain the item's data. + + The way that the \c TreeItem objects are defined makes writing the + \c parent() function easy: + + \snippet itemviews/simpletreemodel/treemodel.cpp 7 + + We only need to ensure that we never return a model index corresponding + to the root item. To be consistent with the way that the \c index() + function is implemented, we return an invalid model index for the + parent of any top-level items in the model. + + When creating a model index to return, we must specify the row and + column numbers of the parent item within its own parent. We can + easily discover the row number with the \c TreeItem::row() function, + but we follow a convention of specifying 0 as the column number of + the parent. The model index is created with + \l{QAbstractItemModel::createIndex()}{createIndex()} in the same way + as in the \c index() function. + + The \c rowCount() function simply returns the number of child items + for the \c TreeItem that corresponds to a given model index, or the + number of top-level items if an invalid index is specified: + + \snippet itemviews/simpletreemodel/treemodel.cpp 8 + + Since each item manages its own column data, the \c columnCount() + function has to call the item's own \c columnCount() function to + determine how many columns are present for a given model index. + As with the \c rowCount() function, if an invalid model index is + specified, the number of columns returned is determined from the + root item: + + \snippet itemviews/simpletreemodel/treemodel.cpp 2 + + Data is obtained from the model via \c data(). Since the item manages + its own columns, we need to use the column number to retrieve the data + with the \c TreeItem::data() function: + + \snippet itemviews/simpletreemodel/treemodel.cpp 3 + + Note that we only support the \l{Qt::ItemDataRole}{DisplayRole} + in this implementation, and we also return invalid QVariant objects for + invalid model indexes. + + We use the \c flags() function to ensure that views know that the + model is read-only: + + \snippet itemviews/simpletreemodel/treemodel.cpp 4 + + The \c headerData() function returns data that we conveniently stored + in the root item: + + \snippet itemviews/simpletreemodel/treemodel.cpp 5 + + This information could have been supplied in a different way: either + specified in the constructor, or hard coded into the \c headerData() + function. + + \section1 Setting Up the Data in the Model + + We use the \c setupModelData() function to set up the initial data in + the model. This function parses a text file, extracting strings of + text to use in the model, and creates item objects that record both + the data and the overall model structure. + Naturally, this function works in a way that is very specific to + this model. We provide the following description of its behavior, + and refer the reader to the example code itself for more information. + + We begin with a text file in the following format: + + \code + Getting Started How to familiarize yourself with Qt Designer + Launching Designer Running the Qt Designer application + The User Interface How to interact with Qt Designer + \endcode + \dots + \code + Connection Editing Mode Connecting widgets together with signals and slots + Connecting Objects Making connections in Qt Designer + Editing Connections Changing existing connections + \endcode + + We process the text file with the following two rules: + + \list + \li For each pair of strings on each line, create an item (or node) + in a tree structure, and place each string in a column of data + in the item. + \li When the first string on a line is indented with respect to the + first string on the previous line, make the item a child of the + previous item created. + \endlist + + To ensure that the model works correctly, it is only necessary to + create instances of \c TreeItem with the correct data and parent item. +*/ diff --git a/examples/widgets/doc/src/simplewidgetmapper.qdoc b/examples/widgets/doc/src/simplewidgetmapper.qdoc new file mode 100644 index 0000000000..2b7cd2d79a --- /dev/null +++ b/examples/widgets/doc/src/simplewidgetmapper.qdoc @@ -0,0 +1,125 @@ +/**************************************************************************** +** +** 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 itemviews/simplewidgetmapper + \title Simple Widget Mapper Example + + The Simple Widget Mapper example shows how to use a widget mapper to display + data from a model in a collection of widgets. + + \image simplewidgetmapper-example.png + + The QDataWidgetMapper class allows information obtained from a + \l{Model Classes}{model} to be viewed and edited in a collection of + widgets instead of in an \l{View Classes}{item view}. + Any model derived from QAbstractItemModel can be used as the source of + data and almost any input widget can be used to display it. + + The example itself is very simple: we create \c Window, a QWidget subclass + that we use to hold the widgets used to present the data, and show it. The + \c Window class will provide buttons that the user can click to show + different records from the model. + + \section1 Window Class Definition + + The class provides a constructor, a slot to keep the buttons up to date, + and a private function to set up the model: + + \snippet itemviews/simplewidgetmapper/window.h Window definition + + In addition to the QDataWidgetMapper object and the controls used to make + up the user interface, we use a QStandardItemModel to hold our data. + We could use a custom model, but this standard implementation is sufficient + for our purposes. + + \section1 Window Class Implementation + + The constructor of the \c Window class can be explained in three parts. + In the first part, we set up the widgets used for the user interface: + + \snippet itemviews/simplewidgetmapper/window.cpp Set up widgets + + We also set up the buddy relationships between various labels and the + corresponding input widgets. + + Next, we set up the widget mapper, relating each input widget to a column + in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}: + + \snippet itemviews/simplewidgetmapper/window.cpp Set up the mapper + + We also connect the mapper to the \uicontrol{Next} and \uicontrol{Previous} buttons + via its \l{QDataWidgetMapper::}{toNext()} and + \l{QDataWidgetMapper::}{toPrevious()} slots. The mapper's + \l{QDataWidgetMapper::}{currentIndexChanged()} signal is connected to the + \c{updateButtons()} slot in the window which we'll show later. + + In the final part of the constructor, we set up the layout, placing each + of the widgets in a grid (we could also use a QFormLayout for this): + + \snippet itemviews/simplewidgetmapper/window.cpp Set up the layout + + Lastly, we set the window title and initialize the mapper by setting it to + refer to the first row in the model. + + The model is initialized in the window's \c{setupModel()} function. Here, + we create a standard model with 5 rows and 3 columns, and we insert some + sample names, addresses and ages into each row: + + \snippet itemviews/simplewidgetmapper/window.cpp Set up the model + + As a result, each row can be treated like a record in a database, and the + widget mapper will read the data from each row, using the column numbers + specified earlier to access the correct data for each widget. This is + shown in the following diagram: + + \image widgetmapper-simple-mapping.png + + Since the user can navigate using the buttons in the user interface, the + example is fully-functional at this point, but to make it a bit more + user-friendly, we implement the \c{updateButtons()} slot to show when the + user is viewing the first or last records: + + \snippet itemviews/simplewidgetmapper/window.cpp Slot for updating the buttons + + If the mapper is referring to the first row in the model, the \uicontrol{Previous} + button is disabled. Similarly, the \uicontrol{Next} button is disabled if the + mapper reaches the last row in the model. + + \section1 More Complex Mappings + + The QDataWidgetMapper class makes it easy to relate information from a + model to widgets in a user interface. However, it is sometimes necessary + to use input widgets which offer choices to the user, such as QComboBox, + in conjunction with a widget mapper. + + In these situations, although the mapping to input widgets remains simple, + more work needs to be done to expose additional data to the widget mapper. + This is covered by the \l{Combo Widget Mapper Example}{Combo Widget Mapper} + and \l{SQL Widget Mapper Example}{SQL Widget Mapper} + examples. +*/ diff --git a/examples/widgets/doc/src/sipdialog.qdoc b/examples/widgets/doc/src/sipdialog.qdoc new file mode 100644 index 0000000000..b5f18cb4be --- /dev/null +++ b/examples/widgets/doc/src/sipdialog.qdoc @@ -0,0 +1,127 @@ +/**************************************************************************** +** +** 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 dialogs/sipdialog + \title SIP Dialog Example + \ingroup qtce + + The SIP Dialog example shows how to create a dialog that is aware of + the Windows Mobile SIP (Software Input Panel) and reacts to it. + + \table + \row \li \inlineimage sipdialog-closed.png + \li \inlineimage sipdialog-opened.png + \endtable + + Sometimes it is necessary for a dialog to take the SIP into account, + as the SIP may hide important input widgets. The SIP Dialog Example + shows how a \c Dialog object, \c dialog, can be resized accordingly + if the SIP is opened, by embedding the contents of \c dialog in a + QScrollArea. + + \section1 Dialog Class Definition + + The \c Dialog class is a subclass of QDialog that implements a public + slot, \c desktopResized(), and a public function, \c reactToSIP(). Also, + it holds a private instance of QRect, \c desktopGeometry. + + \snippet dialogs/sipdialog/dialog.h Dialog header + + \section1 Dialog Class Implementation + + In the constructor of \c Dialog, we start by obtaining the + available geometry of the screen with + \l{QDesktopWidget::availableGeometry()}{availableGeometry()}. The + parameter used is \c 0 to indicate that we require the primary screen. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part1 + + We set the window's title to "SIP Dialog Example" and declare a QScrollArea + object, \c scrollArea. Next we instantiate a QGroupBox, \c groupBox, with + \c scrollArea as its parent. The title of \c groupBox is also set to + "SIP Dialog Example". A QGridLayout object, \c gridLayout, is then used + as \c{groupBox}'s layout. + + We create a QLineEdit, a QLabel and a QPushButton and we set the + \l{QWidget::setMinimumWidth()}{minimumWidth} property to 220 pixels, + respectively. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part2 + + Also, all three widgets' text are set accordingly. The + \l{QGridLayout::setVerticalSpacing()}{verticalSpacing} property of + \c gridLayout is set based on the height of \c desktopGeometry. This + is to adapt to the different form factors of Windows Mobile. Then, we + add our widgets to the layout. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part3 + + The \c{scrollArea}'s widget is set to \c groupBox. We use a QHBoxLayout + object, \c layout, to contain \c scrollArea. The \c{Dialog}'s layout + is set to \c layout and the scroll area's horizontal scroll bar is turned + off. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part4 + + The following signals are connected to their respective slots: + \list + \li \c{button}'s \l{QPushButton::pressed()}{pressed()} signal to + \l{QApplication}'s \l{QApplication::closeAllWindows()} + {closeAllWindows()} slot, + \li \l{QDesktopWidget}'s \l{QDesktopWidget::workAreaResized()} + {workAreaResized()} signal to \c{dialog}'s \c desktopResized() slot. + \endlist + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part5 + + The \c desktopResized() function accepts an integer, \a screen, + corresponding to the screen's index. We only invoke \c reactToSIP() + if \a screen is the primary screen (e.g. index = 0). + + \snippet dialogs/sipdialog/dialog.cpp desktopResized() function + + The \c reactToSIP() function resizes \c dialog accordingly if the + desktop's available geometry changed vertically, as this change signifies + that the SIP may have been opened or closed. + + \snippet dialogs/sipdialog/dialog.cpp reactToSIP() function + + If the height has decreased, we unset the maximized window state. + Otherwise, we set the maximized window state. Lastly, we update + \c desktopGeometry to the desktop's available geometry. + + \section1 The \c main() function + + The \c main() function for the SIP Dialog example instantiates \c Dialog + and invokes its \l{QDialog::exec()}{exec()} function. + + \snippet dialogs/sipdialog/main.cpp main() function + + \note Although this example uses a dialog, the techniques used here apply to + all top-level widgets respectively. +*/ diff --git a/examples/widgets/doc/src/sliders.qdoc b/examples/widgets/doc/src/sliders.qdoc new file mode 100644 index 0000000000..209d81198d --- /dev/null +++ b/examples/widgets/doc/src/sliders.qdoc @@ -0,0 +1,255 @@ +/**************************************************************************** +** +** 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/sliders + \title Sliders Example + + Qt provides three types of slider-like widgets: QSlider, + QScrollBar and QDial. They all inherit most of their + functionality from QAbstractSlider, and can in theory replace + each other in an application since the differences only concern + their look and feel. This example shows what they look like, how + they work and how their behavior and appearance can be + manipulated through their properties. + + The example also demonstrates how signals and slots can be used to + synchronize the behavior of two or more widgets. + + \image sliders-example.png Screenshot of the Sliders example + + The Sliders example consists of two classes: + + \list + + \li \c SlidersGroup is a custom widget. It combines a QSlider, a + QScrollBar and a QDial. + + \li \c Window is the main widget combining a QGroupBox and a + QStackedWidget. In this example, the QStackedWidget provides a + stack of two \c SlidersGroup widgets. The QGroupBox contain + several widgets that control the behavior of the slider-like + widgets. + + \endlist + + First we will review the \c Window class, then we + will take a look at the \c SlidersGroup class. + + \section1 Window Class Definition + + \snippet widgets/sliders/window.h 0 + + The \c Window class inherits from QWidget. It displays the slider + widgets and allows the user to set their minimum, maximum and + current values and to customize their appearance, key bindings + and orientation. We use a private \c createControls() function to + create the widgets that provide these controlling mechanisms and + to connect them to the slider widgets. + + \section1 Window Class Implementation + + \snippet widgets/sliders/window.cpp 0 + + In the constructor we first create the two \c SlidersGroup + widgets that display the slider widgets horizontally and + vertically, and add them to the QStackedWidget. QStackedWidget + provides a stack of widgets where only the top widget is visible. + With \c createControls() we create a connection from a + controlling widget to the QStackedWidget, making the user able to + choose between horizontal and vertical orientation of the slider + widgets. The rest of the controlling mechanisms is implemented by + the same function call. + + \snippet widgets/sliders/window.cpp 1 + \snippet widgets/sliders/window.cpp 2 + + Then we connect the \c horizontalSliders, \c verticalSliders and + \c valueSpinBox to each other, so that the slider widgets and the + control widget will behave synchronized when the current value of + one of them changes. The \c valueChanged() signal is emitted with + the new value as argument. The \c setValue() slot sets the + current value of the widget to the new value, and emits \c + valueChanged() if the new value is different from the old one. + + We put the group of control widgets and the stacked widget in a + horizontal layout before we initialize the minimum, maximum and + current values. The initialization of the current value will + propagate to the slider widgets through the connection we made + between \c valueSpinBox and the \c SlidersGroup widgets. The + minimum and maximum values propagate through the connections we + created with \c createControls(). + + \snippet widgets/sliders/window.cpp 3 + \snippet widgets/sliders/window.cpp 4 + + In the private \c createControls() function, we let a QGroupBox + (\c controlsGroup) display the control widgets. A group box can + provide a frame, a title and a keyboard shortcut, and displays + various other widgets inside itself. The group of control widgets + is composed by two checkboxes, three spin boxes (with labels) and + one combobox. + + After creating the labels, we create the two checkboxes. + Checkboxes are typically used to represent features in an + application that can be enabled or disabled. When \c + invertedAppearance is enabled, the slider values are inverted. + The table below shows the appearance for the different + slider-like widgets: + + \table + \header \li \li{2,1} QSlider \li{2,1} QScrollBar \li{2,1} QDial + \header \li \li Normal \li Inverted \li Normal \li Inverted \li Normal \li Inverted + \row \li Qt::Horizontal \li Left to right \li Right to left \li Left to right \li Right to left \li Clockwise \li Counterclockwise + \row \li Qt::Vertical \li Bottom to top \li Top to bottom \li Top to bottom \li Bottom to top \li Clockwise \li Counterclockwise + \endtable + + It is common to invert the appearance of a vertical QSlider. A + vertical slider that controls volume, for example, will typically + go from bottom to top (the non-inverted appearance), whereas a + vertical slider that controls the position of an object on screen + might go from top to bottom, because screen coordinates go from + top to bottom. + + When the \c invertedKeyBindings option is enabled (corresponding + to the QAbstractSlider::invertedControls property), the slider's + wheel and key events are inverted. The normal key bindings mean + that scrolling the mouse wheel "up" or using keys like page up + will increase the slider's current value towards its maximum. + Inverted, the same wheel and key events will move the value + toward the slider's minimum. This can be useful if the \e + appearance of a slider is inverted: Some users might expect the + keys to still work the same way on the value, whereas others + might expect \uicontrol PageUp to mean "up" on the screen. + + Note that for horizontal and vertical scroll bars, the key + bindings are inverted by default: \uicontrol PageDown increases the + current value, and \uicontrol PageUp decreases it. + + \snippet widgets/sliders/window.cpp 5 + \snippet widgets/sliders/window.cpp 6 + + Then we create the spin boxes. QSpinBox allows the user to choose + a value by clicking the up and down buttons or pressing the \uicontrol + Up and \uicontrol Down keys on the keyboard to modify the value + currently displayed. The user can also type in the value + manually. The spin boxes control the minimum, maximum and current + values for the QSlider, QScrollBar, and QDial widgets. + + We create a QComboBox that allows the user to choose the + orientation of the slider widgets. The QComboBox widget is a + combined button and popup list. It provides a means of presenting + a list of options to the user in a way that takes up the minimum + amount of screen space. + + \snippet widgets/sliders/window.cpp 7 + \snippet widgets/sliders/window.cpp 8 + + We synchronize the behavior of the control widgets and the slider + widgets through their signals and slots. We connect each control + widget to both the horizontal and vertical group of slider + widgets. We also connect \c orientationCombo to the + QStackedWidget, so that the correct "page" is shown. Finally, we + lay out the control widgets in a QGridLayout within the \c + controlsGroup group box. + + \section1 SlidersGroup Class Definition + + \snippet widgets/sliders/slidersgroup.h 0 + + The \c SlidersGroup class inherits from QGroupBox. It provides a + frame and a title, and contains a QSlider, a QScrollBar and a + QDial. + + We provide a \c valueChanged() signal and a public \c setValue() + slot with equivalent functionality to the ones in QAbstractSlider + and QSpinBox. In addition, we implement several other public + slots to set the minimum and maximum value, and invert the slider + widgets' appearance as well as key bindings. + + \section1 SlidersGroup Class Implementation + + \snippet widgets/sliders/slidersgroup.cpp 0 + + First we create the slider-like widgets with the appropriate + properties. In particular we set the focus policy for each + widget. Qt::FocusPolicy is an enum type that defines the various + policies a widget can have with respect to acquiring keyboard + focus. The Qt::StrongFocus policy means that the widget accepts + focus by both tabbing and clicking. + + Then we connect the widgets with each other, so that they will + stay synchronized when the current value of one of them changes. + + \snippet widgets/sliders/slidersgroup.cpp 1 + \snippet widgets/sliders/slidersgroup.cpp 2 + + We connect \c {dial}'s \c valueChanged() signal to the + \c{SlidersGroup}'s \c valueChanged() signal, to notify the other + widgets in the application (i.e., the control widgets) of the + changed value. + + \snippet widgets/sliders/slidersgroup.cpp 3 + \codeline + \snippet widgets/sliders/slidersgroup.cpp 4 + + Finally, depending on the \l {Qt::Orientation}{orientation} given + at the time of construction, we choose and create the layout for + the slider widgets within the group box. + + \snippet widgets/sliders/slidersgroup.cpp 5 + \snippet widgets/sliders/slidersgroup.cpp 6 + + The \c setValue() slot sets the value of the QSlider. We don't + need to explicitly call + \l{QAbstractSlider::setValue()}{setValue()} on the QScrollBar and + QDial widgets, since QSlider will emit the + \l{QAbstractSlider::valueChanged()}{valueChanged()} signal when + its value changes, triggering a domino effect. + + \snippet widgets/sliders/slidersgroup.cpp 7 + \snippet widgets/sliders/slidersgroup.cpp 8 + \codeline + \snippet widgets/sliders/slidersgroup.cpp 9 + \snippet widgets/sliders/slidersgroup.cpp 10 + + The \c setMinimum() and \c setMaximum() slots are used by the \c + Window class to set the range of the QSlider, QScrollBar, and + QDial widgets. + + \snippet widgets/sliders/slidersgroup.cpp 11 + \snippet widgets/sliders/slidersgroup.cpp 12 + \codeline + \snippet widgets/sliders/slidersgroup.cpp 13 + \snippet widgets/sliders/slidersgroup.cpp 14 + + The \c invertAppearance() and \c invertKeyBindings() slots + control the child widgets' + \l{QAbstractSlider::invertedAppearance}{invertedAppearance} and + \l{QAbstractSlider::invertedControls}{invertedControls} + properties. +*/ diff --git a/examples/widgets/doc/src/spinboxdelegate.qdoc b/examples/widgets/doc/src/spinboxdelegate.qdoc new file mode 100644 index 0000000000..258811cc4c --- /dev/null +++ b/examples/widgets/doc/src/spinboxdelegate.qdoc @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** 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 itemviews/spinboxdelegate + \title Spin Box Delegate Example + + The Spin Box Delegate example shows how to create an editor for a custom delegate in + the model/view framework by reusing a standard Qt editor widget. + + The model/view framework provides a standard delegate that is used by default + with the standard view classes. For most purposes, the selection of editor + widgets available through this delegate is sufficient for editing text, boolean + values, and other simple data types. However, for specific data types, it is + sometimes necessary to use a custom delegate to either display the data in a + specific way, or allow the user to edit it with a custom control. + + \image spinboxdelegate-example.png + + This concepts behind this example are covered in the + \l{Model/View Programming#Delegate Classes}{Delegate Classes} chapter + of the \l{Model/View Programming} overview. + + \section1 SpinBoxDelegate Class Definition + + The definition of the delegate is as follows: + + \snippet itemviews/spinboxdelegate/delegate.h 0 + + The delegate class declares only those functions that are needed to + create an editor widget, display it at the correct location in a view, + and communicate with a model. Custom delegates can also provide their + own painting code by reimplementing the \c paintEvent() function. + Furthermore it is also possible to reuse (and avoid deleting) the editor + widget by reimplementing the \a destroyEditor() function. A reused widget + could be a mutable member created in the constructor and deleted in + the destructor. + + \section1 SpinBoxDelegate Class Implementation + + Delegates are often stateless. The constructor only needs to + call the base class's constructor with the parent QObject as its + argument: + + \snippet itemviews/spinboxdelegate/delegate.cpp 0 + + Since the delegate is a subclass of QStyledItemDelegate, the data it retrieves + from the model is displayed in a default style, and we do not need to + provide a custom \c paintEvent(). + + The \c createEditor() function returns an editor widget, in this case a + spin box that restricts values from the model to integers from 0 to 100 + inclusive. + + \snippet itemviews/spinboxdelegate/delegate.cpp 1 + + We install an event filter on the spin box to ensure that it behaves in + a way that is consistent with other delegates. The implementation for + the event filter is provided by the base class. + + The \c setEditorData() function reads data from the model, converts it + to an integer value, and writes it to the editor widget. + + \snippet itemviews/spinboxdelegate/delegate.cpp 2 + + Since the view treats delegates as ordinary QWidget instances, we have + to use a static cast before we can set the value in the spin box. + + The \c setModelData() function reads the contents of the spin box, and + writes it to the model. + + \snippet itemviews/spinboxdelegate/delegate.cpp 3 + + We call \l{QSpinBox::interpretText()}{interpretText()} to make sure that + we obtain the most up-to-date value in the spin box. + + The \c updateEditorGeometry() function updates the editor widget's + geometry using the information supplied in the style option. This is the + minimum that the delegate must do in this case. + + \snippet itemviews/spinboxdelegate/delegate.cpp 4 + + More complex editor widgets may divide the rectangle available in + \c{option.rect} between different child widgets if required. + + \section1 The Main Function + + This example is written in a slightly different way to many of the + other examples supplied with Qt. To demonstrate the use of a custom + editor widget in a standard view, it is necessary to set up a model + containing some arbitrary data and a view to display it. + + We set up the application in the normal way, construct a standard item + model to hold some data, set up a table view to use the data in the + model, and construct a custom delegate to use for editing: + + \snippet itemviews/spinboxdelegate/main.cpp 0 + + The table view is informed about the delegate, and will use it to + display each of the items. Since the delegate is a subclass of + QStyledItemDelegate, each cell in the table will be rendered using standard + painting operations. + + We insert some arbitrary data into the model for demonstration purposes: + + \snippet itemviews/spinboxdelegate/main.cpp 1 + \snippet itemviews/spinboxdelegate/main.cpp 2 + + Finally, the table view is displayed with a window title, and we start + the application's event loop: + + \snippet itemviews/spinboxdelegate/main.cpp 3 + + Each of the cells in the table can now be edited in the usual way, but + the spin box ensures that the data returned to the model is always + constrained by the values allowed by the spin box delegate. +*/ diff --git a/examples/widgets/doc/src/spinboxes.qdoc b/examples/widgets/doc/src/spinboxes.qdoc new file mode 100644 index 0000000000..ed4eea6a60 --- /dev/null +++ b/examples/widgets/doc/src/spinboxes.qdoc @@ -0,0 +1,191 @@ +/**************************************************************************** +** +** 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/spinboxes + \title Spin Boxes Example + + The Spin Boxes example shows how to use the many different types of spin boxes + available in Qt, from a simple QSpinBox widget to more complex editors like + the QDateTimeEdit widget. + + \image spinboxes-example.png + + The example consists of a single \c Window class that is used to display the + different spin box-based widgets available with Qt. + + \section1 Window Class Definition + + The \c Window class inherits QWidget and contains two slots that are used + to provide interactive features: + + \snippet widgets/spinboxes/window.h 0 + + The private functions are used to set up each type of spin box in the window. + We use member variables to keep track of various widgets so that they can + be reconfigured when required. + + \section1 Window Class Implementation + + The constructor simply calls private functions to set up the different types + of spin box used in the example, and places each group in a layout: + + \snippet widgets/spinboxes/window.cpp 0 + + We use the layout to manage the arrangement of the window's child widgets, + and change the window title. + + The \c createSpinBoxes() function constructs a QGroupBox and places three + QSpinBox widgets inside it with descriptive labels to indicate the types of + input they expect. + + \snippet widgets/spinboxes/window.cpp 1 + + The first spin box shows the simplest way to use QSpinBox. It accepts values + from -20 to 20, the current value can be increased or decreased by 1 with + either the arrow buttons or \uicontrol{Up} and \uicontrol{Down} keys, and the default + value is 0. + + The second spin box uses a larger step size and displays a suffix to + provide more information about the type of data the number represents: + + \snippet widgets/spinboxes/window.cpp 2 + + This spin box also displays a + \l{QAbstractSpinBox::specialValueText}{special value} instead of the minimum + value defined for it. This means that it will never show \uicontrol{0%}, but will + display \uicontrol{Automatic} when the minimum value is selected. + + The third spin box shows how a prefix can be used: + + \snippet widgets/spinboxes/window.cpp 4 + + For simplicity, we show a spin box with a prefix and no suffix. It is also + possible to use both at the same time. + + \snippet widgets/spinboxes/window.cpp 5 + + The rest of the function sets up a layout for the group box and places each + of the widgets inside it. + + The \c createDateTimeEdits() function constructs another group box with a + selection of spin boxes used for editing dates and times. + + \snippet widgets/spinboxes/window.cpp 6 + + The first spin box is a QDateEdit widget that is able to accept dates + within a given range specified using QDate values. The arrow buttons and + \uicontrol{Up} and \uicontrol{Down} keys can be used to increase and decrease the + values for year, month, and day when the cursor is in the relevant section. + + The second spin box is a QTimeEdit widget: + + \snippet widgets/spinboxes/window.cpp 7 + + Acceptable values for the time are defined using QTime values. + + The third spin box is a QDateTimeEdit widget that can display both date and + time values, and we place a label above it to indicate the range of allowed + times for a meeting. These widgets will be updated when the user changes a + format string. + + \snippet widgets/spinboxes/window.cpp 8 + + The format string used for the date time editor, which is also shown in the + string displayed by the label, is chosen from a set of strings in a combobox: + + \snippet widgets/spinboxes/window.cpp 9 + \codeline + \snippet widgets/spinboxes/window.cpp 10 + + A signal from this combobox is connected to a slot in the \c Window class + (shown later). + + \snippet widgets/spinboxes/window.cpp 11 + + Each child widget of the group box in placed in a layout. + + The \c setFormatString() slot is called whenever the user selects a new + format string in the combobox. The display format for the QDateTimeEdit + widget is set using the raw string passed by the signal: + + \snippet widgets/spinboxes/window.cpp 12 + + Depending on the visible sections in the widget, we set a new date or time + range, and update the associated label to provide relevant information for + the user: + + \snippet widgets/spinboxes/window.cpp 13 + + When the format string is changed, there will be an appropriate label and + entry widget for dates, times, or both types of input. + + The \c createDoubleSpinBoxes() function constructs three spin boxes that are + used to input double-precision floating point numbers: + + \snippet widgets/spinboxes/window.cpp 14 + + Before the QDoubleSpinBox widgets are constructed, we create a spin box to + control how many decimal places they show. By default, only two decimal places + are shown in the following spin boxes, each of which is the equivalent of a + spin box in the group created by the \c createSpinBoxes() function. + + The first double spin box shows a basic double-precision spin box with the + same range, step size, and default value as the first spin box in the + \c createSpinBoxes() function: + + \snippet widgets/spinboxes/window.cpp 15 + + However, this spin box also allows non-integer values to be entered. + + The second spin box displays a suffix and shows a special value instead + of the minimum value: + + \snippet widgets/spinboxes/window.cpp 16 + + The third spin box displays a prefix instead of a suffix: + + \snippet widgets/spinboxes/window.cpp 17 + + We connect the QSpinBox widget that specifies the precision to a slot in + the \c Window class. + + \snippet widgets/spinboxes/window.cpp 18 + + The rest of the function places each of the widgets into a layout for the + group box. + + The \c changePrecision() slot is called when the user changes the value in + the precision spin box: + + \snippet widgets/spinboxes/window.cpp 19 + + This function simply uses the integer supplied by the signal to specify the + number of decimal places in each of the QDoubleSpinBox widgets. Each one + of these will be updated automatically when their + \l{QDoubleSpinBox::decimals}{decimals} property is changed. +*/ diff --git a/examples/widgets/doc/src/spreadsheet.qdoc b/examples/widgets/doc/src/spreadsheet.qdoc new file mode 100644 index 0000000000..7364f022cb --- /dev/null +++ b/examples/widgets/doc/src/spreadsheet.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 itemviews/spreadsheet + \title Spreadsheet + + The Spreadsheet example shows how a table view can be used to create a + simple spreadsheet application. Custom delegates are used to render different + types of data in distinctive colors. + + \image spreadsheet-demo.png +*/ diff --git a/examples/widgets/doc/src/standarddialogs.qdoc b/examples/widgets/doc/src/standarddialogs.qdoc new file mode 100644 index 0000000000..b56642b6ec --- /dev/null +++ b/examples/widgets/doc/src/standarddialogs.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 dialogs/standarddialogs + \title Standard Dialogs Example + + The Standard Dialogs example shows the standard dialogs that are provided by Qt. + + \image standarddialogs-example.png +*/ diff --git a/examples/widgets/doc/src/stardelegate.qdoc b/examples/widgets/doc/src/stardelegate.qdoc new file mode 100644 index 0000000000..aba8864c2b --- /dev/null +++ b/examples/widgets/doc/src/stardelegate.qdoc @@ -0,0 +1,296 @@ +/**************************************************************************** +** +** 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 itemviews/stardelegate + \title Star Delegate Example + + The Star Delegate example shows how to create a delegate that + can paint itself and that supports editing. + + \image stardelegate.png The Star Delegate Example + + When displaying data in a QListView, QTableView, or QTreeView, + the individual items are drawn by a + \l{Delegate Classes}{delegate}. Also, when the user starts + editing an item (e.g., by double-clicking the item), the delegate + provides an editor widget that is placed on top of the item while + editing takes place. + + Delegates are subclasses of QAbstractItemDelegate. Qt provides + QItemDelegate, which inherits QAbstractItemDelegate and handles + the most common data types (notably \c int and QString). If we + need to support custom data types, or want to customize the + rendering or the editing for existing data types, we can subclass + QAbstractItemDelegate or QItemDelegate. See \l{Delegate Classes} + for more information about delegates, and \l{Model/View + Programming} if you need a high-level introduction to Qt's + model/view architecture (including delegates). + + In this example, we will see how to implement a custom delegate + to render and edit a "star rating" data type, which can store + values such as "1 out of 5 stars". + + The example consists of the following classes: + + \list + \li \c StarRating is the custom data type. It stores a rating + expressed as stars, such as "2 out of 5 stars" or "5 out of + 6 stars". + + \li \c StarDelegate inherits QItemDelegate and provides support + for \c StarRating (in addition to the data types already + handled by QItemDelegate). + + \li \c StarEditor inherits QWidget and is used by \c StarDelegate + to let the user edit a star rating using the mouse. + \endlist + + To show the \c StarDelegate in action, we will fill a + QTableWidget with some data and install the delegate on it. + + \section1 StarDelegate Class Definition + + Here's the definition of the \c StarDelegate class: + + \snippet itemviews/stardelegate/stardelegate.h 0 + + All public functions are reimplemented virtual functions from + QItemDelegate to provide custom rendering and editing. + + \section1 StarDelegate Class Implementation + + The \l{QAbstractItemDelegate::}{paint()} function is + reimplemented from QItemDelegate and is called whenever the view + needs to repaint an item: + + \snippet itemviews/stardelegate/stardelegate.cpp 0 + + The function is invoked once for each item, represented by a + QModelIndex object from the model. If the data stored in the item + is a \c StarRating, we paint it ourselves; otherwise, we let + QItemDelegate paint it for us. This ensures that the \c + StarDelegate can handle the most common data types. + + In the case where the item is a \c StarRating, we draw the + background if the item is selected, and we draw the item using \c + StarRating::paint(), which we will review later. + + \c{StartRating}s can be stored in a QVariant thanks to the + Q_DECLARE_METATYPE() macro appearing in \c starrating.h. More on + this later. + + The \l{QAbstractItemDelegate::}{createEditor()} function is + called when the user starts editing an item: + + \snippet itemviews/stardelegate/stardelegate.cpp 2 + + If the item is a \c StarRating, we create a \c StarEditor and + connect its \c editingFinished() signal to our \c + commitAndCloseEditor() slot, so we can update the model when the + editor closes. + + Here's the implementation of \c commitAndCloseEditor(): + + \snippet itemviews/stardelegate/stardelegate.cpp 5 + + When the user is done editing, we emit + \l{QAbstractItemDelegate::}{commitData()} and + \l{QAbstractItemDelegate::}{closeEditor()} (both declared in + QAbstractItemDelegate), to tell the model that there is edited + data and to inform the view that the editor is no longer needed. + + The \l{QAbstractItemDelegate::}{setEditorData()} function is + called when an editor is created to initialize it with data + from the model: + + \snippet itemviews/stardelegate/stardelegate.cpp 3 + + We simply call \c setStarRating() on the editor. + + The \l{QAbstractItemDelegate::}{setModelData()} function is + called when editing is finished, to commit data from the editor + to the model: + + \snippet itemviews/stardelegate/stardelegate.cpp 4 + + The \c sizeHint() function returns an item's preferred size: + + \snippet itemviews/stardelegate/stardelegate.cpp 1 + + We simply forward the call to \c StarRating. + + \section1 StarEditor Class Definition + + The \c StarEditor class was used when implementing \c + StarDelegate. Here's the class definition: + + \snippet itemviews/stardelegate/stareditor.h 0 + + The class lets the user edit a \c StarRating by moving the mouse + over the editor. It emits the \c editingFinished() signal when + the user clicks on the editor. + + The protected functions are reimplemented from QWidget to handle + mouse and paint events. The private function \c starAtPosition() + is a helper function that returns the number of the star under + the mouse pointer. + + \section1 StarEditor Class Implementation + + Let's start with the constructor: + + \snippet itemviews/stardelegate/stareditor.cpp 0 + + We enable \l{QWidget::setMouseTracking()}{mouse tracking} on the + widget so we can follow the cursor even when the user doesn't + hold down any mouse button. We also turn on QWidget's + \l{QWidget::autoFillBackground}{auto-fill background} feature to + obtain an opaque background. (Without the call, the view's + background would shine through the editor.) + + The \l{QWidget::}{paintEvent()} function is reimplemented from + QWidget: + + \snippet itemviews/stardelegate/stareditor.cpp 1 + + We simply call \c StarRating::paint() to draw the stars, just + like we did when implementing \c StarDelegate. + + \snippet itemviews/stardelegate/stareditor.cpp 2 + + In the mouse event handler, we call \c setStarCount() on the + private data member \c myStarRating to reflect the current cursor + position, and we call QWidget::update() to force a repaint. + + \snippet itemviews/stardelegate/stareditor.cpp 3 + + When the user releases a mouse button, we simply emit the \c + editingFinished() signal. + + \snippet itemviews/stardelegate/stareditor.cpp 4 + + The \c starAtPosition() function uses basic linear algebra to + find out which star is under the cursor. + + \section1 StarRating Class Definition + + \snippet itemviews/stardelegate/starrating.h 0 + \codeline + \snippet itemviews/stardelegate/starrating.h 1 + + The \c StarRating class represents a rating as a number of stars. + In addition to holding the data, it is also capable of painting + the stars on a QPaintDevice, which in this example is either a + view or an editor. The \c myStarCount member variable stores the + current rating, and \c myMaxStarCount stores the highest possible + rating (typically 5). + + The Q_DECLARE_METATYPE() macro makes the type \c StarRating known + to QVariant, making it possible to store \c StarRating values in + QVariant. + + \section1 StarRating Class Implementation + + The constructor initializes \c myStarCount and \c myMaxStarCount, + and sets up the polygons used to draw stars and diamonds: + + \snippet itemviews/stardelegate/starrating.cpp 0 + + The \c paint() function paints the stars in this \c StarRating + object on a paint device: + + \snippet itemviews/stardelegate/starrating.cpp 2 + + We first set the pen and brush we will use for painting. The \c + mode parameter can be either \c Editable or \c ReadOnly. If \c + mode is editable, we use the \l{QPalette::}{Highlight} color + instead of the \l{QPalette::}{Foreground} color to draw the + stars. + + Then we draw the stars. If we are in \c Edit mode, we paint + diamonds in place of stars if the rating is less than the highest + rating. + + The \c sizeHint() function returns the preferred size for an area + to paint the stars on: + + \snippet itemviews/stardelegate/starrating.cpp 1 + + The preferred size is just enough to paint the maximum number of + stars. The function is called by both \c StarDelegate::sizeHint() + and \c StarEditor::sizeHint(). + + \section1 The \c main() Function + + Here's the program's \c main() function: + + \snippet itemviews/stardelegate/main.cpp 5 + + The \c main() function creates a QTableWidget and sets a \c + StarDelegate on it. \l{QAbstractItemView::}{DoubleClicked} and + \l{QAbstractItemView::}{SelectedClicked} are set as + \l{QAbstractItemView::editTriggers()}{edit triggers}, so that the + editor is opened with a single click when the star rating item is + selected. + + The \c populateTableWidget() function fills the QTableWidget with + data: + + \snippet itemviews/stardelegate/main.cpp 0 + \snippet itemviews/stardelegate/main.cpp 1 + \dots + \snippet itemviews/stardelegate/main.cpp 2 + \snippet itemviews/stardelegate/main.cpp 3 + \codeline + \snippet itemviews/stardelegate/main.cpp 4 + + Notice the call to qVariantFromValue to convert a \c + StarRating to a QVariant. + + \section1 Possible Extensions and Suggestions + + There are many ways to customize Qt's \l{Model/View + Programming}{model/view framework}. The approach used in this + example is appropriate for most custom delegates and editors. + Examples of possibilities not used by the star delegate and star + editor are: + + \list + \li It is possible to open editors programmatically by calling + QAbstractItemView::edit(), instead of relying on edit + triggers. This could be use to support other edit triggers + than those offered by the QAbstractItemView::EditTrigger enum. + For example, in the Star Delegate example, hovering over an + item with the mouse might make sense as a way to pop up an + editor. + + \li By reimplementing QAbstractItemDelegate::editorEvent(), it is + possible to implement the editor directly in the delegate, + instead of creating a separate QWidget subclass. + \endlist +*/ diff --git a/examples/widgets/doc/src/states.qdoc b/examples/widgets/doc/src/states.qdoc new file mode 100644 index 0000000000..52eda087f1 --- /dev/null +++ b/examples/widgets/doc/src/states.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 animation/states + \title States Example + + The States example shows how to use the Qt state machine to play + animations. + + \image states-example.png +*/ diff --git a/examples/widgets/doc/src/stickman.qdoc b/examples/widgets/doc/src/stickman.qdoc new file mode 100644 index 0000000000..cffdb64822 --- /dev/null +++ b/examples/widgets/doc/src/stickman.qdoc @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** 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 animation/stickman + \title Stickman Example + + The Stickman example shows how to animate transitions in a state machine to implement key frame + animations. + + \image stickman-example.png + + In this example, we will write a small application which animates the joints in a skeleton and + projects a stickman figure on top. The stickman can be either "alive" or "dead", and when in the + "alive" state, he can be performing different actions defined by key frame animations. + + Animations are implemented as composite states. Each child state of the animation state + represents a frame in the animation by setting the position of each joint in the stickman's + skeleton to the positions defined for the particular frame. The frames are then bound together + with animated transitions that trigger on the source state's propertiesAssigned() signal. Thus, + the machine will enter the state representing the next frame in the animation immediately after + it has finished animating into the previous frame. + + \image stickman-example1.png + + The states for an animation is constructed by reading a custom animation file format and + creating states that assign values to the the "position" properties of each of the nodes in the + skeleton graph. + + \snippet animation/stickman/lifecycle.cpp 1 + + The states are then bound together with signal transitions that listen to the + propertiesAssigned() signal. + + \snippet animation/stickman/lifecycle.cpp 2 + + The last frame state is given a transition to the first one, so that the animation will loop + until it is interrupted when a transition out from the animation state is taken. To get smooth + animations between the different key frames, we set a default animation on the state machine. + This is a parallel animation group which contains animations for all the "position" properties + and will be selected by default when taking any transition that leads into a state that assigns + values to these properties. + + \snippet animation/stickman/lifecycle.cpp 3 + + Several such animation states are constructed, and are placed together as children of a top + level "alive" state which represents the stickman life cycle. Transitions go from the parent + state to the child state to ensure that each of the child states inherit them. + + \image stickman-example2.png + + This saves us the effort of connect every state to every state with identical transitions. The + state machine makes sure that transitions between the key frame animations are also smooth by + applying the default animation when interrupting one and starting another. + + Finally, there is a transition out from the "alive" state and into the "dead" state. This is + a custom transition type called LightningSrikesTransition which samples every second and + triggers at random (one out of fifty times on average.) + + \snippet animation/stickman/lifecycle.cpp 4 + + When it triggers, the machine will first enter a "lightningBlink" state which uses a timer to + pause for a brief period of time while the background color of the scene is white. This gives us + a flash effect when the lightning strikes. + + \snippet animation/stickman/lifecycle.cpp 5 + + We start and stop a QTimer object when entering and exiting the state. Then we transition into + the "dead" state when the timer times out. + + \snippet animation/stickman/lifecycle.cpp 0 + + When the machine is in the "dead" state, it will be unresponsive. This is because the "dead" + state has no transitions leading out. + + \image stickman-example3.png + +*/ diff --git a/examples/widgets/doc/src/styles.qdoc b/examples/widgets/doc/src/styles.qdoc new file mode 100644 index 0000000000..f8be98d2da --- /dev/null +++ b/examples/widgets/doc/src/styles.qdoc @@ -0,0 +1,472 @@ +/**************************************************************************** +** +** 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/styles + \title Styles Example + + The Styles example illustrates how to create custom widget + drawing styles using Qt, and demonstrates Qt's predefined styles. + + \image styles-enabledwood.png Screenshot of the Styles example + + A style in Qt is a subclass of QStyle or of one of its + subclasses. Styles perform drawing on behalf of widgets. Qt + provides a whole range of predefined styles, either built into + the \l QtGui library or found in plugins. Custom styles are + usually created by subclassing one of Qt's existing style and + reimplementing a few virtual functions. + + In this example, the custom style is called \c NorwegianWoodStyle + and derives from QMotifStyle. Its main features are the wooden + textures used for filling most of the widgets and its round + buttons and comboboxes. + + To implement the style, we use some advanced features provided by + QPainter, such as \l{QPainter::Antialiasing}{antialiasing} (to + obtain smoother button edges), \l{QColor::alpha()}{alpha blending} + (to make the buttons appeared raised or sunken), and + \l{QPainterPath}{painter paths} (to fill the buttons and draw the + outline). We also use many features of QBrush and QPalette. + + The example consists of the following classes: + + \list + \li \c NorwegianWoodStyle inherits from QMotifStyle and implements + the Norwegian Wood style. + \li \c WidgetGallery is a \c QDialog subclass that shows the most + common widgets and allows the user to switch style + dynamically. + \endlist + + \section1 NorwegianWoodStyle Class Definition + + Here's the definition of the \c NorwegianWoodStyle class: + + \snippet widgets/styles/norwegianwoodstyle.h 0 + + The public functions are all declared in QStyle (QMotifStyle's + grandparent class) and reimplemented here to override the Motif + look and feel. The private functions are helper functions. + + \section1 NorwegianWoodStyle Class Implementation + + We will now review the implementation of the \c + NorwegianWoodStyle class. + + \snippet widgets/styles/norwegianwoodstyle.cpp 0 + + The \c polish() function is reimplemented from QStyle. It takes a + QPalette as a reference and adapts the palette to fit the style. + Most styles don't need to reimplement that function. The + Norwegian Wood style reimplements it to set a "wooden" palette. + + We start by defining a few \l{QColor}s that we'll need. Then we + load two PNG images. The \c : prefix in the file path indicates + that the PNG files are \l{The Qt Resource System}{embedded + resources}. + + \table + \row \li \inlineimage widgets/styles/images/woodbackground.png + + \li \b{woodbackground.png} + + This texture is used as the background of most widgets. + The wood pattern is horizontal. + + \row \li \inlineimage widgets/styles/images/woodbutton.png + + \li \b{woodbutton.png} + + This texture is used for filling push buttons and + comboboxes. The wood pattern is vertical and more reddish + than the texture used for the background. + \endtable + + The \c midImage variable is initialized to be the same as \c + buttonImage, but then we use a QPainter and fill it with a 25% + opaque black color (a black with an \l{QColor::alpha()}{alpha + channel} of 63). The result is a somewhat darker image than \c + buttonImage. This image will be used for filling buttons that the + user is holding down. + + \snippet widgets/styles/norwegianwoodstyle.cpp 1 + + We initialize the palette. Palettes have various + \l{QPalette::ColorRole}{color roles}, such as QPalette::Base + (used for filling text editors, item views, etc.), QPalette::Text + (used for foreground text), and QPalette::Background (used for + the background of most widgets). Each role has its own QBrush, + which usually is a plain color but can also be a brush pattern or + even a texture (a QPixmap). + + In addition to the roles, palettes have several + \l{QPalette::ColorGroup}{color groups}: active, disabled, and + inactive. The active color group is used for painting widgets in + the active window. The disabled group is used for disabled + widgets. The inactive group is used for all other widgets. Most + palettes have identical active and inactive groups, while the + disabled group uses darker shades. + + We initialize the QPalette object with a brown color. Qt + automatically derivates all color roles for all color groups from + that single color. We then override some of the default values. For + example, we use Qt::darkGreen instead of the default + (Qt::darkBlue) for the QPalette::Highlight role. The + QPalette::setBrush() overload that we use here sets the same + color or brush for all three color groups. + + The \c setTexture() function is a private function that sets the + texture for a certain color role, while preserving the existing + color in the QBrush. A QBrush can hold both a solid color and a + texture at the same time. The solid color is used for drawing + text and other graphical elements where textures don't look good. + + At the end, we set the brush for the disabled color group of the + palette. We use \c woodbackground.png as the texture for all + disabled widgets, including buttons, and use a darker color to + accompany the texture. + + \image styles-disabledwood.png The Norwegian Wood style with disabled widgets + + Let's move on to the other functions reimplemented from + QMotifStyle: + + \snippet widgets/styles/norwegianwoodstyle.cpp 3 + \snippet widgets/styles/norwegianwoodstyle.cpp 4 + + This QStyle::polish() overload is called once on every widget + drawn using the style. We reimplement it to set the Qt::WA_Hover + attribute on \l{QPushButton}s and \l{QComboBox}es. When this + attribute is set, Qt generates paint events when the mouse + pointer enters or leaves the widget. This makes it possible to + render push buttons and comboboxes differently when the mouse + pointer is over them. + + \snippet widgets/styles/norwegianwoodstyle.cpp 5 + \snippet widgets/styles/norwegianwoodstyle.cpp 6 + + This QStyle::unpolish() overload is called to undo any + modification done to the widget in \c polish(). For simplicity, + we assume that the flag wasn't set before \c polish() was called. + In an ideal world, we would remember the original state for each + widgets (e.g., using a QMap) and restore it in + \c unpolish(). + + \snippet widgets/styles/norwegianwoodstyle.cpp 7 + \snippet widgets/styles/norwegianwoodstyle.cpp 8 + + The \l{QStyle::pixelMetric()}{pixelMetric()} function returns the + size in pixels for a certain user interface element. By + reimplementing this function, we can affect the way certain + widgets are drawn and their size hint. Here, we return 8 as the + width around a shown in a QComboBox, ensuring that there is + enough place around the text and the arrow for the Norwegian Wood + round corners. The default value for this setting in the Motif + style is 2. + + We also change the extent of \l{QScrollBar}s, i.e., the height + for a horizontal scroll bar and the width for a vertical scroll + bar, to be 4 pixels more than in the Motif style. This makes the + style a bit more distinctive. + + For all other QStyle::PixelMetric elements, we use the Motif + settings. + + \snippet widgets/styles/norwegianwoodstyle.cpp 9 + \snippet widgets/styles/norwegianwoodstyle.cpp 10 + + The \l{QStyle::styleHint()}{styleHint()} function returns some + hints to widgets or to the base style (in our case QMotifStyle) + about how to draw the widgets. The Motif style returns \c true + for the QStyle::SH_DitherDisabledText hint, resulting in a most + unpleasing visual effect. We override this behavior and return \c + false instead. We also return \c true for the + QStyle::SH_EtchDisabledText hint, meaning that disabled text is + rendered with an embossed look (as QWindowsStyle does). + + \snippet widgets/styles/norwegianwoodstyle.cpp 11 + \snippet widgets/styles/norwegianwoodstyle.cpp 12 + + The \l{QStyle::drawPrimitive()}{drawPrimitive()} function is + called by Qt widgets to draw various fundamental graphical + elements. Here we reimplement it to draw QPushButton and + QComboBox with round corners. The button part of these widgets is + drawn using the QStyle::PE_PanelButtonCommand primitive element. + + The \c option parameter, of type QStyleOption, contains + everything we need to know about the widget we want to draw on. + In particular, \c option->rect gives the rectangle within which + to draw the primitive element. The \c painter parameter is a + QPainter object that we can use to draw on the widget. + + The \c widget parameter is the widget itself. Normally, all the + information we need is available in \c option and \c painter, so + we don't need \c widget. We can use it to perform special + effects; for example, QMacStyle uses it to animate default + buttons. If you use it, be aware that the caller is allowed to + pass a null pointer. + + We start by defining three \l{QColor}s that we'll need later on. + We also put the x, y, width, and height components of the + widget's rectangle in local variables. The value used for the \c + semiTransparentWhite and for the \c semiTransparentBlack color's + alpha channel depends on whether the mouse cursor is over the + widget or not. Since we set the Qt::WA_Hover attribute on + \l{QPushButton}s and \l{QComboBox}es, we can rely on the + QStyle::State_MouseOver flag to be set when the mouse is over the + widget. + + \snippet widgets/styles/norwegianwoodstyle.cpp 13 + \snippet widgets/styles/norwegianwoodstyle.cpp 14 + + The \c roundRect variable is a QPainterPath. A QPainterPath is is + a vectorial specification of a shape. Any shape (rectangle, + ellipse, spline, etc.) or combination of shapes can be expressed + as a path. We will use \c roundRect both for filling the button + background with a wooden texture and for drawing the outline. The + \c roundRectPath() function is a private function; we will come + back to it later. + + \snippet widgets/styles/norwegianwoodstyle.cpp 15 + \snippet widgets/styles/norwegianwoodstyle.cpp 16 + \snippet widgets/styles/norwegianwoodstyle.cpp 17 + \snippet widgets/styles/norwegianwoodstyle.cpp 18 + + We define two variables, \c brush and \c darker, and initialize + them based on the state of the button: + + \list + \li If the button is a \l{QPushButton::flat}{flat button}, we use + the \l{QPalette::Background}{Background} brush. We set \c + darker to \c true if the button is + \l{QAbstractButton::down}{down} or + \l{QAbstractButton::checked}{checked}. + \li If the button is currently held down by the user or in the + \l{QAbstractButton::checked}{checked} state, we use the + \l{QPalette::Mid}{Mid} component of the palette. We set + \c darker to \c true if the button is + \l{QAbstractButton::checked}{checked}. + \li Otherwise, we use the \l{QPalette::Button}{Button} component + of the palette. + \endlist + + The screenshot below illustrates how \l{QPushButton}s are + rendered based on their state: + + \image styles-woodbuttons.png Norwegian Wood buttons in different states + + To discover whether the button is flat or not, we need to cast + the \c option parameter to QStyleOptionButton and check if the + \l{QStyleOptionButton::features}{features} member specifies the + QStyleOptionButton::Flat flag. The qstyleoption_cast() function + performs a dynamic cast; if \c option is not a + QStyleOptionButton, qstyleoption_cast() returns a null pointer. + + \snippet widgets/styles/norwegianwoodstyle.cpp 19 + \snippet widgets/styles/norwegianwoodstyle.cpp 20 + \snippet widgets/styles/norwegianwoodstyle.cpp 21 + \snippet widgets/styles/norwegianwoodstyle.cpp 22 + \snippet widgets/styles/norwegianwoodstyle.cpp 23 + + We turn on antialiasing on QPainter. Antialiasing is a technique + that reduces the visual distortion that occurs when the edges of + a shape are converted into pixels. For the Norwegian Wood style, + we use it to obtain smoother edges for the round buttons. + + \image styles-aliasing.png Norwegian wood buttons with and without antialiasing + + The first call to QPainter::fillPath() draws the background of + the button with a wooden texture. The second call to + \l{QPainter::fillPath()}{fillPath()} paints the same area with a + semi-transparent black color (a black color with an alpha channel + of 63) to make the area darker if \c darker is true. + + \snippet widgets/styles/norwegianwoodstyle.cpp 24 + \snippet widgets/styles/norwegianwoodstyle.cpp 25 + + Next, we draw the outline. The top-left half of the outline and + the bottom-right half of the outline are drawn using different + \l{QPen}s to produce a 3D effect. Normally, the top-left half of + the outline is drawn lighter whereas the bottom-right half is + drawn darker, but if the button is + \l{QAbstractButton::down}{down} or + \l{QAbstractButton::checked}{checked}, we invert the two + \l{QPen}s to give a sunken look to the button. + + \snippet widgets/styles/norwegianwoodstyle.cpp 26 + + We draw the top-left part of the outline by calling + QPainter::drawPath() with an appropriate + \l{QPainter::setClipRegion()}{clip region}. If the + \l{QStyleOption::direction}{layout direction} is right-to-left + instead of left-to-right, we swap the \c x1, \c x2, \c x3, and \c + x4 variables to obtain correct results. On right-to-left desktop, + the "light" comes from the top-right corner of the screen instead + of the top-left corner; raised and sunken widgets must be drawn + accordingly. + + The diagram below illustrates how 3D effects are drawn according + to the layout direction. The area in red on the diagram + corresponds to the \c topHalf polygon: + + \image styles-3d.png + + An easy way to test how a style looks in right-to-left mode is to + pass the \c -reverse command-line option to the application. This + option is recognized by the QApplication constructor. + + \snippet widgets/styles/norwegianwoodstyle.cpp 32 + \snippet widgets/styles/norwegianwoodstyle.cpp 33 + \snippet widgets/styles/norwegianwoodstyle.cpp 34 + + The bottom-right part of the outline is drawn in a similar + fashion. Then we draw a one-pixel wide outline around the entire + button, using the \l{QPalette::Foreground}{Foreground} component + of the QPalette. + + This completes the QStyle::PE_PanelButtonCommand case of the \c + switch statement. Other primitive elements are handled by the + base style. Let's now turn to the other \c NorwegianWoodStyle + member functions: + + \snippet widgets/styles/norwegianwoodstyle.cpp 35 + \snippet widgets/styles/norwegianwoodstyle.cpp 36 + + We reimplement QStyle::drawControl() to draw the text on a + QPushButton in a bright color when the button is + \l{QAbstractButton::down}{down} or + \l{QAbstractButton::checked}{checked}. + + If the \c option parameter points to a QStyleOptionButton object + (it normally should), we take a copy of the object and modify its + \l{QStyleOption::palette}{palette} member to make the + QPalette::ButtonText be the same as the QPalette::BrightText + component (unless the widget is disabled). + + \snippet widgets/styles/norwegianwoodstyle.cpp 37 + \snippet widgets/styles/norwegianwoodstyle.cpp 38 + + The \c setTexture() function is a private function that sets the + \l{QBrush::texture()}{texture} component of the \l{QBrush}es for + a certain \l{QPalette::ColorRole}{color role}, for all three + \l{QPalette::ColorGroup}{color groups} (active, disabled, + inactive). We used it to initialize the Norwegian Wood palette in + \c polish(QPalette &). + + \snippet widgets/styles/norwegianwoodstyle.cpp 39 + \snippet widgets/styles/norwegianwoodstyle.cpp 40 + + The \c roundRectPath() function is a private function that + constructs a QPainterPath object for round buttons. The path + consists of eight segments: four arc segments for the corners and + four lines for the sides. + + With around 250 lines of code, we have a fully functional custom + style based on one of the predefined styles. Custom styles can be + used to provide a distinct look to an application or family of + applications. + + \section1 WidgetGallery Class + + For completeness, we will quickly review the \c WidgetGallery + class, which contains the most common Qt widgets and allows the + user to change style dynamically. Here's the class definition: + + \snippet widgets/styles/widgetgallery.h 0 + \dots + \snippet widgets/styles/widgetgallery.h 1 + + Here's the \c WidgetGallery constructor: + + \snippet widgets/styles/widgetgallery.cpp 0 + + We start by creating child widgets. The \uicontrol Style combobox is + initialized with all the styles known to QStyleFactory, in + addition to \c NorwegianWood. The \c create...() functions are + private functions that set up the various parts of the \c + WidgetGallery. + + \snippet widgets/styles/widgetgallery.cpp 1 + \snippet widgets/styles/widgetgallery.cpp 2 + + We connect the \uicontrol Style combobox to the \c changeStyle() + private slot, the \uicontrol{Use style's standard palette} check box to + the \c changePalette() slot, and the \uicontrol{Disable widgets} check + box to the child widgets' + \l{QWidget::setDisabled()}{setDisabled()} slot. + + \snippet widgets/styles/widgetgallery.cpp 3 + \snippet widgets/styles/widgetgallery.cpp 4 + + Finally, we put the child widgets in layouts. + + \snippet widgets/styles/widgetgallery.cpp 5 + \snippet widgets/styles/widgetgallery.cpp 6 + + When the user changes the style in the combobox, we call + QApplication::setStyle() to dynamically change the style of the + application. + + \snippet widgets/styles/widgetgallery.cpp 7 + \snippet widgets/styles/widgetgallery.cpp 8 + + If the user turns the \uicontrol{Use style's standard palette} on, the + current style's \l{QStyle::standardPalette()}{standard palette} + is used; otherwise, the system's default palette is honored. + + For the Norwegian Wood style, this makes no difference because we + always override the palette with our own palette in \c + NorwegianWoodStyle::polish(). + + \snippet widgets/styles/widgetgallery.cpp 9 + \snippet widgets/styles/widgetgallery.cpp 10 + + The \c advanceProgressBar() slot is called at regular intervals + to advance the progress bar. Since we don't know how long the + user will keep the Styles application running, we use a + logarithmic formula: The closer the progress bar gets to 100%, + the slower it advances. + + We will review \c createProgressBar() in a moment. + + \snippet widgets/styles/widgetgallery.cpp 11 + \snippet widgets/styles/widgetgallery.cpp 12 + + The \c createTopLeftGroupBox() function creates the QGroupBox + that occupies the top-left corner of the \c WidgetGallery. We + skip the \c createTopRightGroupBox(), \c + createBottomLeftTabWidget(), and \c createBottomRightGroupBox() + functions, which are very similar. + + \snippet widgets/styles/widgetgallery.cpp 13 + + In \c createProgressBar(), we create a QProgressBar at the bottom + of the \c WidgetGallery and connect its + \l{QTimer::timeout()}{timeout()} signal to the \c + advanceProgressBar() slot. +*/ diff --git a/examples/widgets/doc/src/stylesheet.qdoc b/examples/widgets/doc/src/stylesheet.qdoc new file mode 100644 index 0000000000..af45411f8c --- /dev/null +++ b/examples/widgets/doc/src/stylesheet.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 widgets/stylesheet + \title Style Sheet Example + + The Style Sheet Example shows how to use style sheets. + + \image stylesheet-pagefold.png Screen Shot of the Pagefold style sheet +*/ + diff --git a/examples/widgets/doc/src/sub-attaq.qdoc b/examples/widgets/doc/src/sub-attaq.qdoc new file mode 100644 index 0000000000..ae00eb0926 --- /dev/null +++ b/examples/widgets/doc/src/sub-attaq.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 animation/sub-attaq + \title Sub-Attaq + + This example shows Qt's ability to combine \l{The Animation Framework}{the animation framework} + and \l{The State Machine Framework}{the state machine framework} to create a game. + + \image sub-attaq-demo.png + + The purpose of the game is to destroy all submarines to win the current level. + The boat can be controlled using left and right keys. To fire a bomb you can press + up and down keys. +*/ diff --git a/examples/widgets/doc/src/syntaxhighlighter.qdoc b/examples/widgets/doc/src/syntaxhighlighter.qdoc new file mode 100644 index 0000000000..66727c0030 --- /dev/null +++ b/examples/widgets/doc/src/syntaxhighlighter.qdoc @@ -0,0 +1,252 @@ +/**************************************************************************** +** +** 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 richtext/syntaxhighlighter + \title Syntax Highlighter Example + + The Syntax Highlighter example shows how to perform simple syntax + highlighting by subclassing the QSyntaxHighlighter class. + + \image syntaxhighlighter-example.png + + The Syntax Highlighter application displays C++ files with custom + syntax highlighting. + + The example consists of two classes: + + \list + \li The \c Highlighter class defines and applies the + highlighting rules. + \li The \c MainWindow widget is the application's main window. + \endlist + + We will first review the \c Highlighter class to see how you can + customize the QSyntaxHighlighter class to fit your preferences, + then we will take a look at the relevant parts of the \c + MainWindow class to see how you can use your custom highlighter + class in an application. + + \section1 Highlighter Class Definition + + \snippet richtext/syntaxhighlighter/highlighter.h 0 + + To provide your own syntax highlighting, you must subclass + QSyntaxHighlighter, reimplement the \l + {QSyntaxHighlighter::highlightBlock()}{highlightBlock()} function, + and define your own highlighting rules. + + We have chosen to store our highlighting rules using a private + struct: A rule consists of a QRegExp pattern and a QTextCharFormat + instance. The various rules are then stored using a QVector. + + The QTextCharFormat class provides formatting information for + characters in a QTextDocument specifying the visual properties of + the text, as well as information about its role in a hypertext + document. In this example, we will only define the font weight and + color using the QTextCharFormat::setFontWeight() and + QTextCharFormat::setForeground() functions. + + \section1 Highlighter Class Implementation + + When subclassing the QSyntaxHighlighter class you must pass the + parent parameter to the base class constructor. The parent is the + text document upon which the syntax highligning will be + applied. In this example, we have also chosen to define our + highlighting rules in the constructor: + + \snippet richtext/syntaxhighlighter/highlighter.cpp 0 + \snippet richtext/syntaxhighlighter/highlighter.cpp 1 + + First we define a keyword rule which recognizes the most common + C++ keywords. We give the \c keywordFormat a bold, dark blue + font. For each keyword, we assign the keyword and the specified + format to a HighlightingRule object and append the object to our + list of rules. + + \snippet richtext/syntaxhighlighter/highlighter.cpp 2 + \codeline + \snippet richtext/syntaxhighlighter/highlighter.cpp 4 + \codeline + \snippet richtext/syntaxhighlighter/highlighter.cpp 5 + + Then we create a format that we will apply to Qt class names. The + class names will be rendered with a dark magenta color and a bold + style. We specify a string pattern that is actually a regular + expression capturing all Qt class names. Then we assign the + regular expression and the specified format to a HighlightingRule + object and append the object to our list of rules. + + We also define highlighting rules for quotations and functions + using the same approach: The patterns have the form of regular + expressions and are stored in HighlightingRule objects with the + associated format. + + \snippet richtext/syntaxhighlighter/highlighter.cpp 3 + \codeline + \snippet richtext/syntaxhighlighter/highlighter.cpp 6 + + The C++ language has two variations of comments: The single line + comment (\c //) and the multiline comment (\c{/*...*}\c{/}). The single + line comment can easily be defined through a highlighting rule + similar to the previous ones. But the multiline comment needs + special care due to the design of the QSyntaxHighlighter class. + + After a QSyntaxHighlighter object is created, its \l + {QSyntaxHighlighter::highlightBlock()}{highlightBlock()} function + will be called automatically whenever it is necessary by the rich + text engine, highlighting the given text block. The problem + appears when a comment spans several text blocks. We will take a + closer look at how this problem can be solved when reviewing the + implementation of the \c Highlighter::highlightBlock() + function. At this point we only specify the multiline comment's + color. + + \snippet richtext/syntaxhighlighter/highlighter.cpp 7 + + The highlightBlock() function is called automatically whenever it + is necessary by the rich text engine, i.e. when there are text + blocks that have changed. + + First we apply the syntax highlighting rules that we stored in the + \c highlightingRules vector. For each rule (i.e. for each + HighlightingRule object) we search for the pattern in the given + textblock using the QString::indexOf() function. When the first + occurrence of the pattern is found, we use the + QRegExp::matchedLength() function to determine the string that + will be formatted. QRegExp::matchedLength() returns the length of + the last matched string, or -1 if there was no match. + + To perform the actual formatting the QSyntaxHighlighter class + provides the \l {QSyntaxHighlighter::setFormat()}{setFormat()} + function. This function operates on the text block that is passed + as argument to the \c highlightBlock() function. The specified + format is applied to the text from the given start position for + the given length. The formatting properties set in the given + format are merged at display time with the formatting information + stored directly in the document. Note that the document itself + remains unmodified by the format set through this function. + + This process is repeated until the last occurrence of the pattern + in the current text block is found. + + \snippet richtext/syntaxhighlighter/highlighter.cpp 8 + + To deal with constructs that can span several text blocks (like + the C++ multiline comment), it is necessary to know the end state + of the previous text block (e.g. "in comment"). Inside your \c + highlightBlock() implementation you can query the end state of the + previous text block using the + QSyntaxHighlighter::previousBlockState() function. After parsing + the block you can save the last state using + QSyntaxHighlighter::setCurrentBlockState(). + + The \l + {QSyntaxHighlighter::previousBlockState()}{previousBlockState()} + function return an int value. If no state is set, the returned + value is -1. You can designate any other value to identify any + given state using the \l + {QSyntaxHighlighter::setCurrentBlockState()}{setCurrentBlockState()} + function. Once the state is set, the QTextBlock keeps that value + until it is set again or until the corresponding paragraph of text + is deleted. + + In this example we have chosen to use 0 to represent the "not in + comment" state, and 1 for the "in comment" state. When the stored + syntax highlighting rules are applied we initialize the current + block state to 0. + + \snippet richtext/syntaxhighlighter/highlighter.cpp 9 + + If the previous block state was "in comment" (\c + {previousBlockState() == 1}), we start the search for an end + expression at the beginning of the text block. If the + previousBlockState() returns 0, we start the search at the + location of the first occurrence of a start expression. + + \snippet richtext/syntaxhighlighter/highlighter.cpp 10 + \snippet richtext/syntaxhighlighter/highlighter.cpp 11 + + When an end expression is found, we calculate the length of the + comment and apply the multiline comment format. Then we search for + the next occurrence of the start expression and repeat the + process. If no end expression can be found in the current text + block we set the current block state to 1, i.e. "in comment". + + This completes the \c Highlighter class implementation; it is now + ready for use. + + \section1 MainWindow Class Definition + + Using a QSyntaxHighlighter subclass is simple; just provide your + application with an instance of the class and pass it the document + upon which you want the highlighting to be applied. + + \snippet richtext/syntaxhighlighter/mainwindow.h 0 + + In this example we declare a pointer to a \c Highlighter instance + which we later will initialize in the private \c setupEditor() + function. + + \section1 MainWindow Class Implementation + + The constructor of the main window is straight forward. We first + set up the menus, then we initialize the editor and make it the + central widget of the application. Finally we set the main + window's title. + + \snippet richtext/syntaxhighlighter/mainwindow.cpp 0 + + We initialize and install the \c Highlighter object in the private + setupEditor() convenience function: + + \snippet richtext/syntaxhighlighter/mainwindow.cpp 1 + + First we create the font we want to use in the editor, then we + create the editor itself which is an instance of the QTextEdit + class. Before we initialize the editor with the \c MainWindow + class definition file, we create a \c Highlighter instance passing + the editor's document as argument. This is the document that the + highlighting will be applied to. Then we are done. + + A QSyntaxHighlighter object can only be installed on one document + at the time, but you can easily reinstall the highlighter on + another document using the QSyntaxHighlighter::setDocument() + function. The QSyntaxHighlighter class also provides the \l + {QSyntaxHighlighter::document()}{document()} function which + returns the currently set document. + + \section1 Other Code Editor Features + + It is possible to implement parenthesis matching with + QSyntaxHighlighter. The "Matching Parentheses with + QSyntaxHighlighter" article in Qt Quarterly 31 + (\l{http://doc.qt.nokia.com/qq/}) implements this. We also have + the \l{Code Editor Example}, which shows how to implement line + numbers and how to highlight the current line. + +*/ diff --git a/examples/widgets/doc/src/tabdialog.qdoc b/examples/widgets/doc/src/tabdialog.qdoc new file mode 100644 index 0000000000..98983d124b --- /dev/null +++ b/examples/widgets/doc/src/tabdialog.qdoc @@ -0,0 +1,134 @@ +/**************************************************************************** +** +** 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 dialogs/tabdialog + \title Tab Dialog Example + + The Tab Dialog example shows how to construct a tab dialog using the + QTabWidget class. + + Dialogs provide an efficient way for the application to communicate + with the user, but complex dialogs suffer from the problem that they + often take up too much screen area. By using a number of tabs in a + dialog, information can be split into different categories, while + remaining accessible. + + \image tabdialog-example.png + + The Tab Dialog example consists of a single \c TabDialog class that + provides three tabs, each containing information about a particular + file, and two standard push buttons that are used to accept or reject + the contents of the dialog. + + \section1 TabDialog Class Definition + + The \c TabDialog class is a subclass of QDialog that displays a + QTabWidget and two standard dialog buttons. The class definition + only contain the class constructor and a private data member for + the QTabWidget: + + \snippet dialogs/tabdialog/tabdialog.h 3 + + In the example, the widget will be used as a top-level window, but + we define the constructor so that it can take a parent widget. This + allows the dialog to be centered on top of an application's main + window. + + \section1 TabDialog Class Implementation + + The constructor calls the QDialog constructor and creates a QFileInfo + object for the specified filename. + + \snippet dialogs/tabdialog/tabdialog.cpp 0 + + The tab widget is populated with three custom widgets that each + contain information about the file. We construct each of these + without a parent widget because the tab widget will reparent + them as they are added to it. + + We create two standard push buttons, and connect each of them to + the appropriate slots in the dialog: + + \snippet dialogs/tabdialog/tabdialog.cpp 1 + \snippet dialogs/tabdialog/tabdialog.cpp 3 + + We arrange the tab widget above the buttons in the dialog: + + \snippet dialogs/tabdialog/tabdialog.cpp 4 + + Finally, we set the dialog's title: + + \snippet dialogs/tabdialog/tabdialog.cpp 5 + + Each of the tabs are subclassed from QWidget, and only provide + constructors. + + \section1 GeneralTab Class Definition + + The GeneralTab widget definition is simple because we are only interested + in displaying the contents of a widget within a tab: + + \snippet dialogs/tabdialog/tabdialog.h 0 + + \section1 GeneralTab Class Implementation + + The GeneralTab widget simply displays some information about the file + passed by the TabDialog. Various widgets for this purpose, and these + are arranged within a vertical layout: + + \snippet dialogs/tabdialog/tabdialog.cpp 6 + + \section1 PermissionsTab Class Definition + + Like the GeneralTab, the PermissionsTab is just used as a placeholder + widget for its children: + + \snippet dialogs/tabdialog/tabdialog.h 1 + + \section1 PermissionsTab Class Implementation + + The PermissionsTab shows information about the file's access information, + displaying details of the file permissions and owner in widgets that are + arranged in nested layouts: + + \snippet dialogs/tabdialog/tabdialog.cpp 7 + + \section1 ApplicationsTab Class Definition + + The ApplicationsTab is another placeholder widget that is mostly + cosmetic: + + \snippet dialogs/tabdialog/tabdialog.h 2 + + \section1 ApplicationsTab Class Implementation + + The ApplicationsTab does not show any useful information, but could be + used as a template for a more complicated example: + + \snippet dialogs/tabdialog/tabdialog.cpp 8 +*/ diff --git a/examples/widgets/doc/src/tablet.qdoc b/examples/widgets/doc/src/tablet.qdoc new file mode 100644 index 0000000000..846a9a357b --- /dev/null +++ b/examples/widgets/doc/src/tablet.qdoc @@ -0,0 +1,369 @@ +/**************************************************************************** +** +** 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/tablet + \title Tablet Example + + This example shows how to use a Wacom tablet in Qt applications. + + \image tabletexample.png + + When you use a tablet with Qt applications, \l{QTabletEvent}s are + generated. You need to reimplement the + \l{QWidget::}{tabletEvent()} event handler if you want to handle + tablet events. Events are generated when the device used for + drawing enters and leaves the proximity of the tablet (i.e., when + it is close but not pressed down on it), when a device is pushed + down and released from it, and when a device is moved on the + tablet. + + The information available in QTabletEvent depends on the device + used. The tablet in this example has two different devices for + drawing: a stylus and an airbrush. For both devices the event + contains the position of the device, pressure on the tablet, + vertical tilt, and horizontal tilt (i.e, the angle between the + device and the perpendicular of the tablet). The airbrush has a + finger wheel; the position of this is also available in the tablet + event. + + In this example we implement a drawing program. You can use the + stylus to draw on the tablet as you use a pencil on paper. When + you draw with the airbrush you get a spray of paint; the finger + wheel is used to change the density of the spray. The pressure and + tilt can change the alpha and saturation values of the QColor and the + width of the QPen used for drawing. + + The example consists of the following: + + \list + \li The \c MainWindow class inherits QMainWindow and creates + the examples menus and connect their slots and signals. + \li The \c TabletCanvas class inherits QWidget and + receives tablet events. It uses the events to paint on a + offscreen pixmap, which it draws onto itself. + \li The \c TabletApplication class inherits QApplication. This + class handles tablet events that are not sent to \c tabletEvent(). + We will look at this later. + \li The \c main() function creates a \c MainWindow and shows it + as a top level window. + \endlist + + + \section1 MainWindow Class Definition + + The \c MainWindow creates a \c TabletCanvas and sets it as its + center widget. + + \snippet widgets/tablet/mainwindow.h 0 + + The QActions let the user select if the tablets pressure and + tilt should change the pen width, color alpha component and color + saturation. \c createActions() creates all actions, and \c + createMenus() sets up the menus with the actions. We have one + QActionGroup for the actions that alter the alpha channel, color + saturation and line width respectively. The action groups are + connected to the \c alphaActionTriggered(), \c + colorSaturationActiontriggered(), and \c + lineWidthActionTriggered() slots, which calls functions in \c + myCanvas. + + + \section1 MainWindow Class Implementation + + We start width a look at the constructor \c MainWindow(): + + \snippet widgets/tablet/mainwindow.cpp 0 + + In the constructor we create the canvas, actions, and menus. + We set the canvas as the center widget. We also initialize the + canvas to match the state of our menus and start drawing with a + red color. + + Here is the implementation of \c brushColorAct(): + + \snippet widgets/tablet/mainwindow.cpp 1 + + We let the user pick a color with a QColorDialog. If it is valid, + we set a new drawing color with \c setColor(). + + Here is the implementation of \c alphaActionTriggered(): + + \snippet widgets/tablet/mainwindow.cpp 2 + + The \c TabletCanvas class supports two ways by which the alpha + channel of the drawing color can be changed: tablet pressure and + tilt. We have one action for each and an action if the alpha + channel should not be changed. + + Here is the implementation of \c lineWidthActionTriggered(): + + \snippet widgets/tablet/mainwindow.cpp 3 + + We check which action is selected in \c lineWidthGroup, and set + how the canvas should change the drawing line width. + + Here is the implementation of \c saturationActionTriggered(): + + \snippet widgets/tablet/mainwindow.cpp 4 + + We check which action is selected in \c colorSaturationGroup, and + set how the canvas should change the color saturation of the + drawing color. + + Here is the implementation of \c saveAct(): + + \snippet widgets/tablet/mainwindow.cpp 5 + + We use the QFileDialog to let the user select a file to save the + drawing in. It is the \c TabletCanvas that save the drawing, so we + call its \c saveImage() function. + + Here is the implementation of \c loadAct(): + + \snippet widgets/tablet/mainwindow.cpp 6 + + We let the user select the image file to be opened with + a QFileDialog; we then ask the canvas to load the image with \c + loadImage(). + + Here is the implementation of \c aboutAct(): + + \snippet widgets/tablet/mainwindow.cpp 7 + + We show a message box with a short description of the example. + + \c createActions() creates all actions and action groups of + the example. We look at the creation of one action group and its + actions. See the \l{Application Example}{application example} if + you want a high-level introduction to QActions. + + Here is the implementation of \c createActions: + + \snippet widgets/tablet/mainwindow.cpp 8 + \dots + \snippet widgets/tablet/mainwindow.cpp 9 + + We want the user to be able to choose if the drawing color's + alpha component should be changed by the tablet pressure or tilt. + We have one action for each choice and an action if the alpha + channel is not to be changed, i.e, the color is opaque. We make + the actions checkable; the \c alphaChannelGroup will then ensure + that only one of the actions are checked at any time. The \c + triggered() signal is emitted when an action is checked. + + \dots + \snippet widgets/tablet/mainwindow.cpp 10 + + Here is the implementation of \c createMenus(): + + \snippet widgets/tablet/mainwindow.cpp 11 + + We create the menus of the example and add the actions to them. + + + \section1 TabletCanvas Class Definition + + The \c TabletCanvas class provides a surface on which the + user can draw with a tablet. + + \snippet widgets/tablet/tabletcanvas.h 0 + + The canvas can change the alpha channel, color saturation, + and line width of the drawing. We have one enum for each of + these; their values decide if it is the tablet pressure or tilt + that will alter them. We keep a private variable for each, the \c + alphaChannelType, \c colorSturationType, and \c penWidthType, + which we provide access functions for. + + We draw on a QPixmap with \c myPen and \c myBrush using \c + myColor. The \c saveImage() and \c loadImage() saves and loads + the QPixmap to disk. The pixmap is drawn on the widget in \c + paintEvent(). The \c pointerType and \c deviceType keeps the type + of pointer, which is either a pen or an eraser, and device + currently used on the tablet, which is either a stylus or an + airbrush. + + The interpretation of events from the tablet is done in \c + tabletEvent(); \c paintPixmap(), \c updateBrush(), and \c + brushPattern() are helper functions used by \c tabletEvent(). + + + \section1 TabletCanvas Class Implementation + + We start with a look at the constructor: + + \snippet widgets/tablet/tabletcanvas.cpp 0 + + In the constructor we initialize our class variables. We need + to draw the background of our pixmap, as the default is gray. + + Here is the implementation of \c saveImage(): + + \snippet widgets/tablet/tabletcanvas.cpp 1 + + QPixmap implements functionality to save itself to disk, so we + simply call \l{QPixmap::}{save()}. + + Here is the implementation of \c loadImage(): + + \snippet widgets/tablet/tabletcanvas.cpp 2 + + We simply call \l{QPixmap::}{load()}, which loads the image in \a + file. + + Here is the implementation of \c tabletEvent(): + + \snippet widgets/tablet/tabletcanvas.cpp 3 + + We get three kind of events to this function: TabletPress, + TabletRelease, and TabletMove, which is generated when a device + is pressed down on, leaves, or moves on the tablet. We set the \c + deviceDown to true when a device is pressed down on the tablet; + we then know when we should draw when we receive move events. We + have implemented the \c updateBrush() and \c paintPixmap() helper + functions to update \c myBrush and \c myPen after the state of \c + alphaChannelType, \c colorSaturationType, and \c lineWidthType. + + Here is the implementation of \c paintEvent(): + + \snippet widgets/tablet/tabletcanvas.cpp 4 + + We simply draw the pixmap to the top left of the widget. + + Here is the implementation of \c paintPixmap(): + + \snippet widgets/tablet/tabletcanvas.cpp 5 + + In this function we draw on the pixmap based on the movement of the + device. If the device used on the tablet is a stylus we want to draw a + line between the positions of the stylus recorded in \c polyLine. We + also assume that this is a reasonable handling of any unknown device, + but update the statusbar with a warning so that the user can see that + for his tablet he might have to implement special handling. + If it is an airbrush we want to draw a circle of points with a + point density based on the tangential pressure, which is the position + of the finger wheel on the airbrush. We use the Qt::BrushStyle to + draw the points as it has styles that draw points with different + density; we select the style based on the tangential pressure in + \c brushPattern(). + + \snippet widgets/tablet/tabletcanvas.cpp 6 + + We return a brush style with a point density that increases with + the tangential pressure. + + In \c updateBrush() we set the pen and brush used for drawing + to match \c alphaChannelType, \c lineWidthType, \c + colorSaturationType, and \c myColor. We will examine the code to + set up \c myBrush and \c myPen for each of these variables: + + \snippet widgets/tablet/tabletcanvas.cpp 7 + + We fetch the current drawingcolor's hue, saturation, value, + and alpha values. \c hValue and \c vValue are set to the + horizontal and vertical tilt as a number from 0 to 255. The + original values are in degrees from -60 to 60, i.e., 0 equals + -60, 127 equals 0, and 255 equals 60 degrees. The angle measured + is between the device and the perpendicular of the tablet (see + QTabletEvent for an illustration). + + \snippet widgets/tablet/tabletcanvas.cpp 8 + + The alpha channel of QColor is given as a number between 0 + and 255 where 0 is transparent and 255 is opaque. + \l{QTabletEvent::}{pressure()} returns the pressure as a qreal + between 0.0 and 1.0. By subtracting 127 from the tilt values and + taking the absolute value we get the smallest alpha values (i.e., + the color is most transparent) when the pen is perpendicular to + the tablet. We select the largest of the vertical and horizontal + tilt value. + + \snippet widgets/tablet/tabletcanvas.cpp 9 + + The colorsaturation is given as a number between 0 and 255. It is + set with \l{QColor::}{setHsv()}. We can set the tilt values + directly, but must multiply the pressure to a number between 0 and + 255. + + \snippet widgets/tablet/tabletcanvas.cpp 10 + + The width of the pen increases with the pressure. When the pen + width is controlled with the tilt we let the width increse with + the angle between the device and the perpendicular of the tablet. + + \snippet widgets/tablet/tabletcanvas.cpp 11 + + We finally check whether the pointer is the stylus or the eraser. + If it is the eraser, we set the color to the background color of + the pixmap an let the pressure decide the pen width, else we set + the colors we have set up previously in the function. + + + \section1 TabletApplication Class Definition + + We inherit QApplication in this class because we want to + reimplement the \l{QApplication::}{event()} function. + + \snippet widgets/tablet/tabletapplication.h 0 + + We keep a \c TabletCanvas we send the device type of the events we + handle in the \c event() function to. The TabletEnterProximity + and TabletLeaveProximity events are not sendt to the QApplication + object, while other tablet events are sendt to the QWidget's + \c event(), which sends them on to \l{QWidget::}{tabletEvent()}. + Since we want to handle these events we have implemented \c + TabletApplication. + + + \section1 TabletApplication Class Implementation + + Here is the implementation of \c event(): + + \snippet widgets/tablet/tabletapplication.cpp 0 + + We use this function to handle the TabletEnterProximity and + TabletLeaveProximity events, which is generated when a device + enters and leaves the proximity of the tablet. The intended use of these + events is to do work that is dependent on what kind of device is + used on the tablet. This way, you don't have to do this work + when other events are generated, which is more frequently than the + leave and enter proximity events. We call \c setTabletDevice() in + \c TabletCanvas. + + \section1 The \c main() function + + Here is the examples \c main() function: + + \snippet widgets/tablet/main.cpp 0 + + In the \c main() function we create a \c MainWinow and display it + as a top level window. We use the \c TabletApplication class. We + need to set the canvas after the application is created. We cannot + use classes that implement event handling before an QApplication + object is instantiated. +*/ diff --git a/examples/widgets/doc/src/tetrix.qdoc b/examples/widgets/doc/src/tetrix.qdoc new file mode 100644 index 0000000000..1a30845024 --- /dev/null +++ b/examples/widgets/doc/src/tetrix.qdoc @@ -0,0 +1,431 @@ +/**************************************************************************** +** +** 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/tetrix + \title Tetrix Example + + The Tetrix example is a Qt version of the classic Tetrix game. + + \image tetrix-example.png + + The object of the game is to stack pieces dropped from the top of the + playing area so that they fill entire rows at the bottom of the playing area. + + When a row is filled, all the blocks on that row are removed, the player earns + a number of points, and the pieces above are moved down to occupy that row. + If more than one row is filled, the blocks on each row are removed, and the + player earns extra points. + + The \uicontrol{Left} cursor key moves the current piece one space to the left, the + \uicontrol{Right} cursor key moves it one space to the right, the \uicontrol{Up} cursor + key rotates the piece counter-clockwise by 90 degrees, and the \uicontrol{Down} + cursor key rotates the piece clockwise by 90 degrees. + + To avoid waiting for a piece to fall to the bottom of the board, press \uicontrol{D} + to immediately move the piece down by one row, or press the \uicontrol{Space} key to + drop it as close to the bottom of the board as possible. + + This example shows how a simple game can be created using only three classes: + + \list + \li The \c TetrixWindow class is used to display the player's score, number of + lives, and information about the next piece to appear. + \li The \c TetrixBoard class contains the game logic, handles keyboard input, and + displays the pieces on the playing area. + \li The \c TetrixPiece class contains information about each piece. + \endlist + + In this approach, the \c TetrixBoard class is the most complex class, since it + handles the game logic and rendering. One benefit of this is that the + \c TetrixWindow and \c TetrixPiece classes are very simple and contain only a + minimum of code. + + \section1 TetrixWindow Class Definition + + The \c TetrixWindow class is used to display the game information and contains + the playing area: + + \snippet widgets/tetrix/tetrixwindow.h 0 + + We use private member variables for the board, various display widgets, and + buttons to allow the user to start a new game, pause the current game, and quit. + + Although the window inherits QWidget, the constructor does not provide an + argument to allow a parent widget to be specified. This is because the window + will always be used as a top-level widget. + + \section1 TetrixWindow Class Implementation + + The constructor sets up the user interface elements for the game: + + \snippet widgets/tetrix/tetrixwindow.cpp 0 + + We begin by constructing a \c TetrixBoard instance for the playing area and a + label that shows the next piece to be dropped into the playing area; the label + is initially empty. + + Three QLCDNumber objects are used to display the score, number of lives, and + lines removed. These initially show default values, and will be filled in + when a game begins: + + \snippet widgets/tetrix/tetrixwindow.cpp 1 + + Three buttons with shortcuts are constructed so that the user can start a + new game, pause the current game, and quit the application: + + \snippet widgets/tetrix/tetrixwindow.cpp 2 + \snippet widgets/tetrix/tetrixwindow.cpp 3 + + These buttons are configured so that they never receive the keyboard focus; + we want the keyboard focus to remain with the \c TetrixBoard instance so that + it receives all the keyboard events. Nonetheless, the buttons will still respond + to \uicontrol{Alt} key shortcuts. + + We connect \l{QAbstractButton::}{clicked()} signals from the \uicontrol{Start} + and \uicontrol{Pause} buttons to the board, and from the \uicontrol{Quit} button to the + application's \l{QApplication::}{quit()} slot. + + \snippet widgets/tetrix/tetrixwindow.cpp 4 + \snippet widgets/tetrix/tetrixwindow.cpp 5 + + Signals from the board are also connected to the LCD widgets for the purpose of + updating the score, number of lives, and lines removed from the playing area. + + We place the label, LCD widgets, and the board into a QGridLayout + along with some labels that we create with the \c createLabel() convenience + function: + + \snippet widgets/tetrix/tetrixwindow.cpp 6 + + Finally, we set the grid layout on the widget, give the window a title, and + resize it to an appropriate size. + + The \c createLabel() convenience function simply creates a new label on the + heap, gives it an appropriate alignment, and returns it to the caller: + + \snippet widgets/tetrix/tetrixwindow.cpp 7 + + Since each label will be used in the widget's layout, it will become a child + of the \c TetrixWindow widget and, as a result, it will be deleted when the + window is deleted. + + \section1 TetrixPiece Class Definition + + The \c TetrixPiece class holds information about a piece in the game's + playing area, including its shape, position, and the range of positions it can + occupy on the board: + + \snippet widgets/tetrix/tetrixpiece.h 0 + + Each shape contains four blocks, and these are defined by the \c coords private + member variable. Additionally, each piece has a high-level description that is + stored internally in the \c pieceShape variable. + + The constructor is written inline in the definition, and simply ensures that + each piece is initially created with no shape. The \c shape() function simply + returns the contents of the \c pieceShape variable, and the \c x() and \c y() + functions return the x and y-coordinates of any given block in the shape. + + \section1 TetrixPiece Class Implementation + + The \c setRandomShape() function is used to select a random shape for a piece: + + \snippet widgets/tetrix/tetrixpiece.cpp 0 + + For convenience, it simply chooses a random shape from the \c TetrixShape enum + and calls the \c setShape() function to perform the task of positioning the + blocks. + + The \c setShape() function uses a look-up table of pieces to associate each + shape with an array of block positions: + + \snippet widgets/tetrix/tetrixpiece.cpp 1 + \snippet widgets/tetrix/tetrixpiece.cpp 2 + + These positions are read from the table into the piece's own array of positions, + and the piece's internal shape information is updated to use the new shape. + + The \c x() and \c y() functions are implemented inline in the class definition, + returning positions defined on a grid that extends horizontally and vertically + with coordinates from -2 to 2. Although the predefined coordinates for each + piece only vary horizontally from -1 to 1 and vertically from -1 to 2, each + piece can be rotated by 90, 180, and 270 degrees. + + The \c minX() and \c maxX() functions return the minimum and maximum horizontal + coordinates occupied by the blocks that make up the piece: + + \snippet widgets/tetrix/tetrixpiece.cpp 3 + \snippet widgets/tetrix/tetrixpiece.cpp 4 + + Similarly, the \c minY() and \c maxY() functions return the minimum and maximum + vertical coordinates occupied by the blocks: + + \snippet widgets/tetrix/tetrixpiece.cpp 5 + \snippet widgets/tetrix/tetrixpiece.cpp 6 + + The \c rotatedLeft() function returns a new piece with the same shape as an + existing piece, but rotated counter-clockwise by 90 degrees: + + \snippet widgets/tetrix/tetrixpiece.cpp 7 + + Similarly, the \c rotatedRight() function returns a new piece with the same + shape as an existing piece, but rotated clockwise by 90 degrees: + + \snippet widgets/tetrix/tetrixpiece.cpp 9 + + These last two functions enable each piece to create rotated copies of itself. + + \section1 TetrixBoard Class Definition + + The \c TetrixBoard class inherits from QFrame and contains the game logic and display features: + + \snippet widgets/tetrix/tetrixboard.h 0 + + Apart from the \c setNextPieceLabel() function and the \c start() and \c pause() + public slots, we only provide public functions to reimplement QWidget::sizeHint() + and QWidget::minimumSizeHint(). The signals are used to communicate changes to + the player's information to the \c TetrixWindow instance. + + The rest of the functionality is provided by reimplementations of protected event + handlers and private functions: + + \snippet widgets/tetrix/tetrixboard.h 1 + + The board is composed of a fixed-size array whose elements correspond to + spaces for individual blocks. Each element in the array contains a \c TetrixShape + value corresponding to the type of shape that occupies that element. + + Each shape on the board will occupy four elements in the array, and these will + all contain the enum value that corresponds to the type of the shape. + + We use a QBasicTimer to control the rate at which pieces fall toward the bottom + of the playing area. This allows us to provide an implementation of + \l{QObject::}{timerEvent()} that we can use to update the widget. + + \section1 TetrixBoard Class Implementation + + In the constructor, we customize the frame style of the widget, ensure that + keyboard input will be received by the widget by using Qt::StrongFocus for the + focus policy, and initialize the game state: + + \snippet widgets/tetrix/tetrixboard.cpp 0 + + The first (next) piece is also set up with a random shape. + + The \c setNextPieceLabel() function is used to pass in an externally-constructed + label to the board, so that it can be shown alongside the playing area: + + \snippet widgets/tetrix/tetrixboard.cpp 1 + + We provide a reasonable size hint and minimum size hint for the board, based on + the size of the space for each block in the playing area: + + \snippet widgets/tetrix/tetrixboard.cpp 2 + \snippet widgets/tetrix/tetrixboard.cpp 3 + + By using a minimum size hint, we indicate to the layout in the parent widget + that the board should not shrink below a minimum size. + + A new game is started when the \c start() slot is called. This resets the + game's state, the player's score and level, and the contents of the board: + + \snippet widgets/tetrix/tetrixboard.cpp 4 + + We also emit signals to inform other components of these changes before creating + a new piece that is ready to be dropped into the playing area. We start the + timer that determines how often the piece drops down one row on the board. + + The \c pause() slot is used to temporarily stop the current game by stopping the + internal timer: + + \snippet widgets/tetrix/tetrixboard.cpp 5 + \snippet widgets/tetrix/tetrixboard.cpp 6 + + We perform checks to ensure that the game can only be paused if it is already + running and not already paused. + + The \c paintEvent() function is straightforward to implement. We begin by + calling the base class's implementation of \l{QWidget::}{paintEvent()} before + constructing a QPainter for use on the board: + + \snippet widgets/tetrix/tetrixboard.cpp 7 + + Since the board is a subclass of QFrame, we obtain a QRect that covers the area + \e inside the frame decoration before drawing our own content. + + If the game is paused, we want to hide the existing state of the board and + show some text. We achieve this by painting text onto the widget and returning + early from the function. The rest of the painting is performed after this point. + + The position of the top of the board is found by subtracting the total height + of each space on the board from the bottom of the frame's internal rectangle. + For each space on the board that is occupied by a piece, we call the + \c drawSquare() function to draw a block at that position. + + \snippet widgets/tetrix/tetrixboard.cpp 8 + \snippet widgets/tetrix/tetrixboard.cpp 9 + + Spaces that are not occupied by blocks are left blank. + + Unlike the existing pieces on the board, the current piece is drawn + block-by-block at its current position: + + \snippet widgets/tetrix/tetrixboard.cpp 10 + \snippet widgets/tetrix/tetrixboard.cpp 11 + \snippet widgets/tetrix/tetrixboard.cpp 12 + + The \c keyPressEvent() handler is called whenever the player presses a key while + the \c TetrixBoard widget has the keyboard focus. + + \snippet widgets/tetrix/tetrixboard.cpp 13 + + If there is no current game, the game is running but paused, or if there is no + current shape to control, we simply pass on the event to the base class. + + We check whether the event is about any of the keys that the player uses to + control the current piece and, if so, we call the relevant function to handle + the input: + + \snippet widgets/tetrix/tetrixboard.cpp 14 + + In the case where the player presses a key that we are not interested in, we + again pass on the event to the base class's implementation of + \l{QWidget::}{keyPressEvent()}. + + The \c timerEvent() handler is called every time the class's QBasicTimer + instance times out. We need to check that the event we receive corresponds to + our timer. If it does, we can update the board: + + \snippet widgets/tetrix/tetrixboard.cpp 15 + \snippet widgets/tetrix/tetrixboard.cpp 16 + \snippet widgets/tetrix/tetrixboard.cpp 17 + + If a row (or line) has just been filled, we create a new piece and reset the + timer; otherwise we move the current piece down by one row. We let the base + class handle other timer events that we receive. + + The \c clearBoard() function simply fills the board with the + \c TetrixShape::NoShape value: + + \snippet widgets/tetrix/tetrixboard.cpp 18 + + The \c dropDown() function moves the current piece down as far as possible on + the board, either until it is touching the bottom of the playing area or it is + stacked on top of another piece: + + \snippet widgets/tetrix/tetrixboard.cpp 19 + \snippet widgets/tetrix/tetrixboard.cpp 20 + + The number of rows the piece has dropped is recorded and passed to the + \c pieceDropped() function so that the player's score can be updated. + + The \c oneLineDown() function is used to move the current piece down by one row + (line), either when the user presses the \uicontrol{D} key or when the piece is + scheduled to move: + + \snippet widgets/tetrix/tetrixboard.cpp 21 + + If the piece cannot drop down by one line, we call the \c pieceDropped() function + with zero as the argument to indicate that it cannot fall any further, and that + the player should receive no extra points for the fall. + + The \c pieceDropped() function itself is responsible for awarding points to the + player for positioning the current piece, checking for full rows on the board + and, if no lines have been removed, creating a new piece to replace the current + one: + + \snippet widgets/tetrix/tetrixboard.cpp 22 + \snippet widgets/tetrix/tetrixboard.cpp 23 + + We call \c removeFullLines() each time a piece has been dropped. This scans + the board from bottom to top, looking for blank spaces on each row. + + \snippet widgets/tetrix/tetrixboard.cpp 24 + \snippet widgets/tetrix/tetrixboard.cpp 25 + \snippet widgets/tetrix/tetrixboard.cpp 26 + \snippet widgets/tetrix/tetrixboard.cpp 27 + + If a row contains no blank spaces, the rows above it are copied down by one row + to compress the stack of pieces, the top row on the board is cleared, and the + number of full lines found is incremented. + + \snippet widgets/tetrix/tetrixboard.cpp 28 + \snippet widgets/tetrix/tetrixboard.cpp 29 + + If some lines have been removed, the player's score and the total number of lines + removed are updated. The \c linesRemoved() and \c scoreChanged() signals are + emitted to send these new values to other widgets in the window. + + Additionally, we set the timer to elapse after half a second, set the + \c isWaitingAfterLine flag to indicate that lines have been removed, unset + the piece's shape to ensure that it is not drawn, and update the widget. + The next time that the \c timerEvent() handler is called, a new piece will be + created and the game will continue. + + The \c newPiece() function places the next available piece at the top of the + board, and creates a new piece with a random shape: + + \snippet widgets/tetrix/tetrixboard.cpp 30 + \snippet widgets/tetrix/tetrixboard.cpp 31 + + We place a new piece in the middle of the board at the top. The game is over if + the piece can't move, so we unset its shape to prevent it from being drawn, stop + the timer, and unset the \c isStarted flag. + + The \c showNextPiece() function updates the label that shows the next piece to + be dropped: + + \snippet widgets/tetrix/tetrixboard.cpp 32 + \snippet widgets/tetrix/tetrixboard.cpp 33 + + We draw the piece's component blocks onto a pixmap that is then set on the label. + + The \c tryMove() function is used to determine whether a piece can be positioned + at the specified coordinates: + + \snippet widgets/tetrix/tetrixboard.cpp 34 + + We examine the spaces on the board that the piece needs to occupy and, if they + are already occupied by other pieces, we return \c false to indicate that the + move has failed. + + \snippet widgets/tetrix/tetrixboard.cpp 35 + + If the piece could be placed on the board at the desired location, we update the + current piece and its position, update the widget, and return \c true to indicate + success. + + The \c drawSquare() function draws the blocks (normally squares) that make up + each piece using different colors for pieces with different shapes: + + \snippet widgets/tetrix/tetrixboard.cpp 36 + + We obtain the color to use from a look-up table that relates each shape to an + RGB value, and use the painter provided to draw the block at the specified + coordinates. +*/ diff --git a/examples/widgets/doc/src/textedit.qdoc b/examples/widgets/doc/src/textedit.qdoc new file mode 100644 index 0000000000..1bb596eb6e --- /dev/null +++ b/examples/widgets/doc/src/textedit.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 richtext/textedit + \title Text Edit + + The Text Edit example shows Qt's rich text editing facilities in action, + providing an example document for you to experiment with. + + \image textedit-demo.png +*/ diff --git a/examples/widgets/doc/src/tooltips.qdoc b/examples/widgets/doc/src/tooltips.qdoc new file mode 100644 index 0000000000..e06f080a93 --- /dev/null +++ b/examples/widgets/doc/src/tooltips.qdoc @@ -0,0 +1,394 @@ +/**************************************************************************** +** +** 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/tooltips + \title Tool Tips Example + + The Tool Tips example shows how to provide static and dynamic tool + tips for an application's widgets. + + The simplest and most common way to set a widget's tool tip is by + calling its QWidget::setToolTip() function (static tool + tips). Then the tool tip is shown whenever the cursor points at + the widget. We show how to do this with our application's tool + buttons. But it is also possible to show different tool tips + depending on the cursor's position (dynamic tooltips). This + approach uses mouse tracking and event handling to determine what + widgets are located under the cursor at any point in time, and + displays their tool tips. The tool tips for the shape items in our + application are implemented using the latter approach. + + \image tooltips-example.png + + With the \c Tooltips application the user can create new shape + items with the provided tool buttons, and move the items around + using the mouse. Tooltips are provided whenever the cursor is + pointing to a shape item or one of the buttons. + + The Tooltips example consists of two classes: + + \list + \li \c ShapeItem is a custom widget representing one single shape item. + \li \c SortingBox inherits from QWidget and is the application's main + widget. + \endlist + + First we will review the \c SortingBox class, then we will take a + look at the \c ShapeItem class. + + \section1 SortingBox Class Definition + + \snippet widgets/tooltips/sortingbox.h 0 + + The \c SortingBox class inherits QWidget, and it is the Tooltips + application's main widget. We reimplement several of the event + handlers. + + The \c event() function provides tooltips, the \c resize() + function makes sure the application appears consistently when the + user resizes the main widget, and the \c paintEvent() function + displays the shape items within the \c SortingBox widget. The + mouse event handlers are reimplemented to make the user able to + move the items around. + + In addition we need three private slots to make the user able to + create new shape items. + + \snippet widgets/tooltips/sortingbox.h 1 + + We also create several private functions: We use the \c + initialItemPosition(), \c initialItemColor() and \c + createToolButton() functions when we are constructing the widget, + and we use the \c updateButtonGeometry() function whenever the + user is resizing the application's main widget. + + The \c itemAt() function determines if there is a shape item at a + particular position, and the \c moveItemTo() function moves an + item to a new position. We use the \c createShapeItem(), \c + randomItemPosition() and \c randomItemColor() functions to create + new shape items. + + \snippet widgets/tooltips/sortingbox.h 2 + + We keep all the shape items in a QList, and we keep three + QPainterPath objects holding the shapes of a circle, a square and + a triangle. We also need to have a pointer to an item when it is + moving, and we need to know its previous position. + + \section1 SortingBox Class Implementation + + \snippet widgets/tooltips/sortingbox.cpp 0 + + In the constructor, we first set the Qt::WA_StaticContents + attribute on the widget. This attribute indicates that the widget + contents are north-west aligned and static. On resize, such a + widget will receive paint events only for the newly visible part + of itself. + + \snippet widgets/tooltips/sortingbox.cpp 1 + + To be able to show the appropriate tooltips while the user is + moving the cursor around, we need to enable mouse tracking for the + widget. + + If mouse tracking is disabled (the default), the widget only + receives mouse move events when at least one mouse button is + pressed while the mouse is being moved. If mouse tracking is + enabled, the widget receives mouse move events even if no buttons + are pressed. + + \snippet widgets/tooltips/sortingbox.cpp 2 + + A widget's background role defines the brush from the widget's + palette that is used to render the background, and QPalette::Base + is typically white. + + \snippet widgets/tooltips/sortingbox.cpp 3 + + After creating the application's tool buttons using the private \c + createToolButton() function, we construct the shapes of a circle, + a square and a triangle using QPainterPath. + + The QPainterPath class provides a container for painting + operations, enabling graphical shapes to be constructed and + reused. The main advantage of painter paths over normal drawing + operations is that complex shapes only need to be created once, + but they can be drawn many times using only calls to + QPainter::drawPath(). + + \snippet widgets/tooltips/sortingbox.cpp 4 + + Then we set the window title, resize the widget to a suitable + size, and finally create three initial shape items using the + private \c createShapeItem(), \c initialItemPosition() and \c + initialItemColor() functions. + + \snippet widgets/tooltips/sortingbox.cpp 5 + + QWidget::event() is the main event handler and receives all the + widget's events. Normally, we recommend reimplementing one of the + specialized event handlers instead of this function. But here we + want to catch the QEvent::ToolTip events, and since these are + rather rare, there exists no specific event handler. For that + reason we reimplement the main event handler, and the first thing + we need to do is to determine the event's type: + + \snippet widgets/tooltips/sortingbox.cpp 6 + + If the type is QEvent::ToolTip, we cast the event to a QHelpEvent, + otherwise we propagate the event using the QWidget::event() + function. + + The QHelpEvent class provides an event that is used to request + helpful information about a particular point in a widget. + + For example, the QHelpEvent::pos() function returns the event's + position relative to the widget to which the event is dispatched. + Here we use this information to determine if the position of the + event is contained within the area of any of the shape items. If + it is, we display the shape item's tooltip at the position of the + event. If not, we hide the tooltip and explicitly ignore the event. + This makes sure that the calling code does not start any tooltip + specific modes as a result of the event. Note that the + QToolTip::showText() function needs the event's position in global + coordinates provided by QHelpEvent::globalPos(). + + \snippet widgets/tooltips/sortingbox.cpp 7 + + The \c resizeEvent() function is reimplemented to receive the + resize events dispatched to the widget. It makes sure that the + tool buttons keep their position relative to the main widget when + the widget is resized. We want the buttons to always be vertically + aligned in the application's bottom right corner, so each time the + main widget is resized we update the buttons geometry. + + \snippet widgets/tooltips/sortingbox.cpp 8 + + The \c paintEvent() function is reimplemented to receive paint + events for the widget. We create a QPainter for the \c SortingBox + widget, and run through the list of created shape items, drawing + each item at its defined position. + + \snippet widgets/tooltips/sortingbox.cpp 9 + + The painter will by default draw all the shape items at position + (0,0) in the \c SortingBox widget. The QPainter::translate() + function translates the coordinate system by the given offset, + making each shape item appear at its defined position. But + remember to translate the coordinate system back when the item is + drawn, otherwise the next shape item will appear at a position + relative to the item we drawed last. + + \snippet widgets/tooltips/sortingbox.cpp 10 + + The QPainter::setBrush() function sets the current brush used by + the painter. When the provided argument is a QColor, the function + calls the appropriate QBrush constructor which creates a brush with + the specified color and Qt::SolidPattern style. The + QPainter::drawPath() function draws the given path using the + current pen for outline and the current brush for filling. + + \snippet widgets/tooltips/sortingbox.cpp 11 + + The \c mousePressEvent() function is reimplemented to receive the + mouse press events dispatched to the widget. It determines if an + event's position is contained within the area of any of the shape + items, using the private \c itemAt() function. + + If an item covers the position, we store a pointer to that item + and the event's position. If several of the shape items cover the + position, we store the pointer to the uppermost item. Finally, we + move the shape item to the end of the list, and make a call to the + QWidget::update() function to make the item appear on top. + + The QWidget::update() function does not cause an immediate + repaint; instead it schedules a paint event for processing when Qt + returns to the main event loop. + + \snippet widgets/tooltips/sortingbox.cpp 12 + + The \c mouseMoveEvent() function is reimplemented to receive mouse + move events for the widget. If the left mouse button is pressed + and there exists a shape item in motion, we use the private \c + moveItemTo() function to move the item with an offset + corresponding to the offset between the positions of the current + mouse event and the previous one. + + \snippet widgets/tooltips/sortingbox.cpp 13 + + The \c mouseReleaseEvent() function is reimplemented to receive + the mouse release events dispatched to the widget. If the left + mouse button is pressed and there exists a shape item in motion, + we use the private \c moveItemTo() function to move the item like + we did in \c mouseMoveEvent(). But then we remove the pointer to + the item in motion, making the shape item's position final for + now. To move the item further, the user will need to press the + left mouse button again. + + \snippet widgets/tooltips/sortingbox.cpp 14 + \codeline + \snippet widgets/tooltips/sortingbox.cpp 15 + \codeline + \snippet widgets/tooltips/sortingbox.cpp 16 + + The \c createNewCircle(), \c createNewSquare() and \c + createNewTriangle() slots simply create new shape items, using the + private \c createShapeItem(), \c randomItemPosition() and \c + randomItemColor() functions. + + \snippet widgets/tooltips/sortingbox.cpp 17 + + In the \c itemAt() function, we run through the list of created + shape items to check if the given position is contained within the + area of any of the shape items. + + For each shape item we use the QPainterPath::contains() function + to find out if the item's painter path contains the position. If + it does we return the index of the item, otherwise we return + -1. We run through the list backwards to get the index of the + uppermost shape item in case several items cover the position. + + \snippet widgets/tooltips/sortingbox.cpp 18 + + The \c moveItemTo() function moves the shape item in motion, and + the parameter \c pos is the position of a mouse event. First we + calculate the offset between the parameter \c pos and the previous + mouse event position. Then we add the offset to the current + position of the item in motion. + + It is tempting to simply set the position of the item to be the + parameter \c pos. But an item's position defines the top left + corner of the item's bounding rectangle, and the parameter \c pos + can be any point; The suggested shortcut would cause the item to + jump to a position where the cursor is pointing to the bounding + rectangle's top left corner, regardless of the item's previous + position. + + \snippet widgets/tooltips/sortingbox.cpp 19 + + Finally, we update the previous mouse event position, and make a + call to the QWidget::update() function to make the item appear at + its new position. + + \snippet widgets/tooltips/sortingbox.cpp 20 + + In the \c updateButtonGeometry() function we set the geometry for + the given button. The parameter coordinates define the bottom + right corner of the button. We use these coordinates and the + button's size hint to determine the position of the upper left + corner. This position, and the button's width and height, are the + arguments required by the QWidget::setGeometry() function. + + In the end, we calculate and return the y-coordinate of the bottom + right corner of the next button. We use the QWidget::style() + function to retrieve the widget's GUI style, and then + QStyle::pixelMetric() to determine the widget's preferred default + spacing between its child widgets. + + \snippet widgets/tooltips/sortingbox.cpp 21 + + The \c createShapeItem() function creates a single shape item. It + sets the path, tooltip, position and color, using the item's own + functions. In the end, the function appends the new item to the + list of shape items, and calls the QWidget::update() function to + make it appear with the other items within the \c SortingBox + widget. + + \snippet widgets/tooltips/sortingbox.cpp 22 + + The \c createToolButton() function is called from the \c + SortingBox constructor. We create a tool button with the given + tooltip and icon. The button's parent is the \c SortingBox widget, + and its size is 32 x 32 pixels. Before we return the button, we + connect it to the given slot. + + \snippet widgets/tooltips/sortingbox.cpp 23 + + The \c initialItemPosition() function is also called from the + constructor. We want the three first items to initially be + centered in the middle of the \c SortingBox widget, and we use + this function to calculate their positions. + + \snippet widgets/tooltips/sortingbox.cpp 24 + + Whenever the user creates a new shape item, we want the new item + to appear at a random position, and we use the \c + randomItemPosition() function to calculate such a position. We + make sure that the item appears within the visible area of the + \c SortingBox widget, using the widget's current width and height + when calculating the random coordinates. + + \snippet widgets/tooltips/sortingbox.cpp 25 + + As with \c initialItemPosition(), the \c initialItemColor() + function is called from the constructor. The purposes of both + functions are purely cosmetic: We want to control the initial + position and color of the three first items. + + \snippet widgets/tooltips/sortingbox.cpp 26 + + Finally the \c randomItemColor() function is implemented to give + the shape items the user creates, a random color. + + \section1 ShapeItem Class Definition + + \snippet widgets/tooltips/shapeitem.h 0 + + The \c ShapeItem class is a custom widget representing one single + shape item. The widget has a path, a position, a color and a + tooltip. We need functions to set or modify these objects, as well + as functions that return them. We make the latter functions \c + const to prohibit any modifications of the objects, + i.e. prohibiting unauthorized manipulation of the shape items + appearance. + + \section1 ShapeItem Class Implementation + + \snippet widgets/tooltips/shapeitem.cpp 0 + \codeline + \snippet widgets/tooltips/shapeitem.cpp 1 + \codeline + \snippet widgets/tooltips/shapeitem.cpp 2 + \codeline + \snippet widgets/tooltips/shapeitem.cpp 3 + + This first group of functions simply return the objects that are + requested. The objects are returned as constants, i.e. they cannot + be modified. + + \snippet widgets/tooltips/shapeitem.cpp 4 + \codeline + \snippet widgets/tooltips/shapeitem.cpp 5 + \codeline + \snippet widgets/tooltips/shapeitem.cpp 6 + \codeline + \snippet widgets/tooltips/shapeitem.cpp 7 + + The last group of functions set or modify the shape item's path, + position, color and tooltip, respectively. +*/ diff --git a/examples/widgets/doc/src/trafficlight.qdoc b/examples/widgets/doc/src/trafficlight.qdoc new file mode 100644 index 0000000000..ec3578abaa --- /dev/null +++ b/examples/widgets/doc/src/trafficlight.qdoc @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** 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 statemachine/trafficlight + \title Traffic Light Example + + The Traffic Light example shows how to use \l{The State Machine Framework} + to implement the control flow of a traffic light. + + \image trafficlight-example.png + + In this example we write a TrafficLightWidget class. The traffic light has + three lights: Red, yellow and green. The traffic light transitions from + one light to another (red to yellow to green to yellow to red again) at + certain intervals. + + \snippet statemachine/trafficlight/main.cpp 0 + + The LightWidget class represents a single light of the traffic light. It + provides an \c on property and two slots, turnOn() and turnOff(), to turn + the light on and off, respectively. The widget paints itself in the color + that's passed to the constructor. + + \snippet statemachine/trafficlight/main.cpp 1 + + The TrafficLightWidget class represents the visual part of the traffic + light; it's a widget that contains three lights arranged vertically, and + provides accessor functions for these. + + \snippet statemachine/trafficlight/main.cpp 2 + + The createLightState() function creates a state that turns a light on when + the state is entered, and off when the state is exited. The state uses a + timer, and as we shall see the timeout is used to transition from one + LightState to another. Here is the statechart for the light state: + + \image trafficlight-example1.png + \omit + \caption This is a caption + \endomit + + \snippet statemachine/trafficlight/main.cpp 3 + + The TrafficLight class combines the TrafficLightWidget with a state + machine. The state graph has four states: red-to-yellow, yellow-to-green, + green-to-yellow and yellow-to-red. The initial state is red-to-yellow; + when the state's timer times out, the state machine transitions to + yellow-to-green. The same process repeats through the other states. + This is what the statechart looks like: + + \image trafficlight-example2.png + \omit + \caption This is a caption + \endomit + + \snippet statemachine/trafficlight/main.cpp 4 + + The main() function constructs a TrafficLight and shows it. + +*/ diff --git a/examples/widgets/doc/src/transformations.qdoc b/examples/widgets/doc/src/transformations.qdoc new file mode 100644 index 0000000000..79681a2799 --- /dev/null +++ b/examples/widgets/doc/src/transformations.qdoc @@ -0,0 +1,371 @@ +/**************************************************************************** +** +** 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 painting/transformations + \title Transformations Example + + The Transformations example shows how transformations influence + the way that QPainter renders graphics primitives. In particular + it shows how the order of transformations affect the result. + + \image transformations-example.png + + The application allows the user to manipulate the rendering of a + shape by changing the translation, rotation and scale of + QPainter's coordinate system. + + The example consists of two classes and a global enum: + + \list + \li The \c RenderArea class controls the rendering of a given shape. + \li The \c Window class is the application's main window. + \li The \c Operation enum describes the various transformation + operations available in the application. + \endlist + + First we will take a quick look at the \c Operation enum, then we + will review the \c RenderArea class to see how a shape is + rendered. Finally, we will take a look at the Transformations + application's features implemented in the \c Window class. + + \section1 Transformation Operations + + Normally, the QPainter operates on the associated device's own + coordinate system, but it also has good support for coordinate + transformations. + + The default coordinate system of a paint device has its origin at + the top-left corner. The x values increase to the right and the y + values increase downwards. You can scale the coordinate system by + a given offset using the QPainter::scale() function, you can + rotate it clockwise using the QPainter::rotate() function and you + can translate it (i.e. adding a given offset to the points) using + the QPainter::translate() function. You can also twist the + coordinate system around the origin (called shearing) using the + QPainter::shear() function. + + All the tranformation operations operate on QPainter's + tranformation matrix that you can retrieve using the + QPainter::worldTransform() function. A matrix transforms a point in the + plane to another point. For more information about the + transformation matrix, see the \l {Coordinate System} and + QTransform documentation. + + \snippet painting/transformations/renderarea.h 0 + + The global \c Operation enum is declared in the \c renderarea.h + file and describes the various transformation operations available + in the Transformations application. + + \section1 RenderArea Class Definition + + The \c RenderArea class inherits QWidget, and controls the + rendering of a given shape. + + \snippet painting/transformations/renderarea.h 1 + + We declare two public functions, \c setOperations() and + \c setShape(), to be able to specify the \c RenderArea widget's shape + and to transform the coordinate system the shape is rendered + within. + + We reimplement the QWidget's \l + {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l + {QWidget::sizeHint()}{sizeHint()} functions to give the \c + RenderArea widget a reasonable size within our application, and we + reimplement the QWidget::paintEvent() event handler to draw the + render area's shape applying the user's transformation choices. + + \snippet painting/transformations/renderarea.h 2 + + We also declare several convenience functions to draw the shape, + the coordinate system's outline and the coordinates, and to + transform the painter according to the chosen transformations. + + In addition, the \c RenderArea widget keeps a list of the + currently applied transformation operations, a reference to its + shape, and a couple of convenience variables that we will use when + rendering the coordinates. + + \section1 RenderArea Class Implementation + + The \c RenderArea widget controls the rendering of a given shape, + including the transformations of the coordinate system, by + reimplementing the QWidget::paintEvent() event handler. But first + we will take a quick look at the constructor and at the functions + that provides access to the \c RenderArea widget: + + \snippet painting/transformations/renderarea.cpp 0 + + In the constructor we pass the parent parameter on to the base + class, and customize the font that we will use to render the + coordinates. The QWidget::font() function returns the font + currently set for the widget. As long as no special font has been + set, or after QWidget::setFont() is called, this is either a + special font for the widget class, the parent's font or (if this + widget is a top level widget) the default application font. + + After ensuring that the font's size is 12 points, we extract the + rectangles enclosing the coordinate letters, 'x' and 'y', using the + QFontMetrics class. + + QFontMetrics provides functions to access the individual metrics + of the font, its characters, and for strings rendered in the + font. The QFontMetrics::boundingRect() function returns the + bounding rectangle of the given character relative to the + left-most point on the base line. + + \snippet painting/transformations/renderarea.cpp 1 + \codeline + \snippet painting/transformations/renderarea.cpp 2 + + In the \c setShape() and \c setOperations() functions we update + the \c RenderArea widget by storing the new value or values + followed by a call to the QWidget::update() slot which schedules a + paint event for processing when Qt returns to the main event loop. + + \snippet painting/transformations/renderarea.cpp 3 + \codeline + \snippet painting/transformations/renderarea.cpp 4 + + We reimplement the QWidget's \l + {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l + {QWidget::sizeHint()}{sizeHint()} functions to give the \c + RenderArea widget a reasonable size within our application. The + default implementations of these functions returns an invalid size + if there is no layout for this widget, and returns the layout's + minimum size or preferred size, respectively, otherwise. + + \snippet painting/transformations/renderarea.cpp 5 + + The \c paintEvent() event handler receives the \c RenderArea + widget's paint events. A paint event is a request to repaint all + or part of the widget. It can happen as a result of + QWidget::repaint() or QWidget::update(), or because the widget was + obscured and has now been uncovered, or for many other reasons. + + First we create a QPainter for the \c RenderArea widget. The \l + {QPainter::RenderHint}{QPainter::Antialiasing} render hint + indicates that the engine should antialias edges of primitives if + possible. Then we erase the area that needs to be repainted using + the QPainter::fillRect() function. + + We also translate the coordinate system with an constant offset to + ensure that the original shape is renderend with a suitable + margin. + + \snippet painting/transformations/renderarea.cpp 6 + + Before we start to render the shape, we call the QPainter::save() + function. + + QPainter::save() saves the current painter state (i.e. pushes the + state onto a stack) including the current coordinate system. The + rationale for saving the painter state is that the following call + to the \c transformPainter() function will transform the + coordinate system depending on the currently chosen transformation + operations, and we need a way to get back to the original state to + draw the outline. + + After transforming the coordinate system, we draw the \c + RenderArea's shape, and then we restore the painter state using + the QPainter::restore() function (i.e. popping the saved state off + the stack). + + \snippet painting/transformations/renderarea.cpp 7 + + Then we draw the square outline. + + \snippet painting/transformations/renderarea.cpp 8 + + Since we want the coordinates to correspond with the coordinate + system the shape is rendered within, we must make another call to + the \c transformPainter() function. + + The order of the painting operations is essential with respect to + the shared pixels. The reason why we don't render the coordinates + when the coordinate system already is transformed to render the + shape, but instead defer their rendering to the end, is that we + want the coordinates to appear on top of the shape and its + outline. + + There is no need to save the QPainter state this time since + drawing the coordinates is the last painting operation. + + \snippet painting/transformations/renderarea.cpp 9 + \codeline + \snippet painting/transformations/renderarea.cpp 10 + \codeline + \snippet painting/transformations/renderarea.cpp 11 + + The \c drawCoordinates(), \c drawOutline() and \c drawShape() are + convenience functions called from the \c paintEvent() event + handler. For more information about QPainter's basic drawing + operations and how to display basic graphics primitives, see the + \l {painting/basicdrawing}{Basic Drawing} example. + + \snippet painting/transformations/renderarea.cpp 12 + + The \c transformPainter() convenience function is also called from + the \c paintEvent() event handler, and transforms the given + QPainter's coordinate system according to the user's + transformation choices. + + \section1 Window Class Definition + + The \c Window class is the Transformations application's main + window. + + The application displays four \c RenderArea widgets. The left-most + widget renders the shape in QPainter's default coordinate system, + the others render the shape with the chosen transformation in + addition to all the transformations applied to the \c RenderArea + widgets to their left. + + \snippet painting/transformations/window.h 0 + + We declare two public slots to make the application able to + respond to user interaction, updating the displayed \c RenderArea + widgets according to the user's transformation choices. + + The \c operationChanged() slot updates each of the \c RenderArea + widgets applying the currently chosen transformation operations, and + is called whenever the user changes the selected operations. The + \c shapeSelected() slot updates the \c RenderArea widgets' shapes + whenever the user changes the preferred shape. + + \snippet painting/transformations/window.h 1 + + We also declare a private convenience function, \c setupShapes(), + that is used when constructing the \c Window widget, and we + declare pointers to the various components of the widget. We + choose to keep the available shapes in a QList of \l + {QPainterPath}s. In addition we declare a private enum counting + the number of displayed \c RenderArea widgets except the widget + that renders the shape in QPainter's default coordinate system. + + \section1 Window Class Implementation + + In the constructor we create and initialize the application's + components: + + \snippet painting/transformations/window.cpp 0 + + First we create the \c RenderArea widget that will render the + shape in the default coordinate system. We also create the + associated QComboBox that allows the user to choose among four + different shapes: A clock, a house, a text and a truck. The shapes + themselves are created at the end of the constructor, using the + \c setupShapes() convenience function. + + \snippet painting/transformations/window.cpp 1 + + Then we create the \c RenderArea widgets that will render their + shapes with coordinate tranformations. By default the applied + operation is \uicontrol {No Transformation}, i.e. the shapes are + rendered within the default coordinate system. We create and + initialize the associated \l {QComboBox}es with items + corresponding to the various transformation operations decribed by + the global \c Operation enum. + + We also connect the \l {QComboBox}es' \l + {QComboBox::activated()}{activated()} signal to the \c + operationChanged() slot to update the application whenever the + user changes the selected transformation operations. + + \snippet painting/transformations/window.cpp 2 + + Finally, we set the layout for the application window using the + QWidget::setLayout() function, construct the available shapes + using the private \c setupShapes() convenience function, and make + the application show the clock shape on startup using the public + \c shapeSelected() slot before we set the window title. + + + \snippet painting/transformations/window.cpp 3 + \snippet painting/transformations/window.cpp 4 + \snippet painting/transformations/window.cpp 5 + \snippet painting/transformations/window.cpp 6 + \dots + + \snippet painting/transformations/window.cpp 7 + + The \c setupShapes() function is called from the constructor and + create the QPainterPath objects representing the shapes that are + used in the application. For construction details, see the \l + {painting/transformations/window.cpp}{window.cpp} example + file. The shapes are stored in a QList. The QList::append() + function inserts the given shape at the end of the list. + + We also connect the associated QComboBox's \l + {QComboBox::activated()}{activated()} signal to the \c + shapeSelected() slot to update the application when the user + changes the preferred shape. + + \snippet painting/transformations/window.cpp 8 + + The public \c operationChanged() slot is called whenever the user + changes the selected operations. + + We retrieve the chosen transformation operation for each of the + transformed \c RenderArea widgets by querying the associated \l + {QComboBox}{QComboBoxes}. The transformed \c RenderArea widgets + are supposed to render the shape with the transformation specified + by its associated combobox \e {in addition to} all the + transformations applied to the \c RenderArea widgets to its + left. For that reason, for each widget we query, we append the + associated operation to a QList of transformations which we apply + to the widget before proceeding to the next. + + \snippet painting/transformations/window.cpp 9 + + The \c shapeSelected() slot is called whenever the user changes + the preferred shape, updating the \c RenderArea widgets using + their public \c setShape() function. + + \section1 Summary + + The Transformations example shows how transformations influence + the way that QPainter renders graphics primitives. Normally, the + QPainter operates on the device's own coordinate system, but it + also has good support for coordinate transformations. With the + Transformations application you can scale, rotate and translate + QPainter's coordinate system. The order in which these + tranformations are applied is essential for the result. + + All the tranformation operations operate on QPainter's + tranformation matrix. For more information about the + transformation matrix, see the \l {Coordinate System} and + QTransform documentation. + + The Qt reference documentation provides several painting + examples. Among these is the \l {painting/affine}{Affine + Transformations} example that shows Qt's ability to perform + transformations on painting operations. The example also allows the + user to experiment with the various transformation operations. +*/ diff --git a/examples/widgets/doc/src/trivialwizard.qdoc b/examples/widgets/doc/src/trivialwizard.qdoc new file mode 100644 index 0000000000..e27f9cadc2 --- /dev/null +++ b/examples/widgets/doc/src/trivialwizard.qdoc @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** 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 dialogs/trivialwizard + \title Trivial Wizard Example + + The Trivial Wizard example illustrates how to create a linear three-page + registration wizard using three instances of QWizardPage and one instance + of QWizard. + + \image trivialwizard-example-flow.png + + \section1 Introduction Page + + \image trivialwizard-example-introduction.png + + The introduction page is created with the \c createIntroPage() + function where a QWizardPage is created and its title is set to + "Introduction". A QLabel is used to hold the description of \c page. + A QVBoxLayout is used to hold the \c label. This \c page is returned + when the \c createIntroPage() function is called. + + \snippet dialogs/trivialwizard/trivialwizard.cpp 0 + + \section1 Registration Page + + \image trivialwizard-example-registration.png + + The registration page is created with the \c createRegistrationPage() + function. QLineEdit objects are used to allow the user to input a name + and an e-mail address. A QGridLayout is used to hold the QLabel and + QLineEdit objects. + + \snippet dialogs/trivialwizard/trivialwizard.cpp 2 + + \section1 Conclusion Page + + \image trivialwizard-example-conclusion.png + + The conclusion page is created in the \c createConclusionPage() + function. This function's content is similar to \c createIntroPage(). A + QLabel is used to inform the user that the registration process has + completed successfully. + + \snippet dialogs/trivialwizard/trivialwizard.cpp 6 + + \section1 \c main() Function + + The \c main() function instantiates a QWizard object, \c wizard, and + adds all three QWizardPage objects to it. The \c wizard window title is + set to "Trivial Wizard" and its \c show() function is invoked to display + it. + + \snippet dialogs/trivialwizard/trivialwizard.cpp 10 + + \sa QWizard, {Class Wizard Example}, {License Wizard Example} +*/ diff --git a/examples/widgets/doc/src/twowaybutton.qdoc b/examples/widgets/doc/src/twowaybutton.qdoc new file mode 100644 index 0000000000..40f8c6f1f3 --- /dev/null +++ b/examples/widgets/doc/src/twowaybutton.qdoc @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** 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 statemachine/twowaybutton + \title Two-way Button Example + + The Two-way button example shows how to use \l{The State Machine + Framework} to implement a simple state machine that toggles the current + state when a button is clicked. + + \snippet statemachine/twowaybutton/main.cpp 0 + + The application's main() function begins by constructing the application + object, a button and a state machine. + + \snippet statemachine/twowaybutton/main.cpp 1 + + The state machine has two states; \c on and \c off. When either state is + entered, the text of the button will be set accordingly. + + \snippet statemachine/twowaybutton/main.cpp 2 + + When the state machine is in the \c off state and the button is clicked, + it will transition to the \c on state; when the state machine is in the \c + on state and the button is clicked, it will transition to the \c off + state. + + \snippet statemachine/twowaybutton/main.cpp 3 + + The states are added to the state machine; they become top-level (sibling) + states. + + \snippet statemachine/twowaybutton/main.cpp 4 + + The initial state is \c off; this is the state the state machine will + immediately transition to once the state machine is started. + + \snippet statemachine/twowaybutton/main.cpp 5 + + Finally, the button is resized and made visible, and the application event + loop is entered. + +*/ diff --git a/examples/widgets/doc/src/wiggly.qdoc b/examples/widgets/doc/src/wiggly.qdoc new file mode 100644 index 0000000000..e84ab00e61 --- /dev/null +++ b/examples/widgets/doc/src/wiggly.qdoc @@ -0,0 +1,167 @@ +/**************************************************************************** +** +** 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/wiggly + \title Wiggly Example + + The Wiggly example shows how to animate a widget using + QBasicTimer and \l{QObject::timerEvent()}{timerEvent()}. In + addition, the example demonstrates how to use QFontMetrics to + determine the size of text on screen. + + \image wiggly-example.png Screenshot of the Wiggly example + + QBasicTimer is a low-level class for timers. Unlike QTimer, + QBasicTimer doesn't inherit from QObject; instead of emitting a + \l{QTimer::timeout()}{timeout()} signal when a certain amount of + time has passed, it sends a QTimerEvent to a QObject of our + choice. This makes QBasicTimer a more lightweight alternative to + QTimer. Qt's built-in widgets use it internally, and it is + provided in Qt's API for highly-optimized applications (e.g., + \l{Qt for Embedded Linux} applications). + + The example consists of two classes: + + \list + \li \c WigglyWidget is the custom widget displaying the text + in a wiggly line. + + \li \c Dialog is the dialog widget allowing the user to enter a + text. It combines a \c WigglyWidget and a \c QLineEdit. + \endlist + + We will first take a quick look at the \c Dialog class, then we + will review the \c WigglyWidget class. + + \section1 Dialog Class Definition + + \snippet widgets/wiggly/dialog.h 0 + + The \c Dialog class provides a dialog widget that allows the user + to enter a text. The text is then rendered by \c WigglyWidget. + + \section1 Dialog Class Implementation + + \snippet widgets/wiggly/dialog.cpp 0 + + In the constructor we create a wiggly widget along with a + \l{QLineEdit}{line edit}, and we put the two widgets in a + vertical layout. We connect the line edit's \l + {QLineEdit::textChanged()}{textChanged()} signal to the wiggly + widget's \c setText() slot to obtain the real time interaction + with the wiggly widget. The widget's default text is "Hello + world!". + + \section1 WigglyWidget Class Definition + + \snippet widgets/wiggly/wigglywidget.h 0 + + The \c WigglyWidget class provides the wiggly line displaying the + text. We subclass QWidget and reimplement the standard \l + {QWidget::paintEvent()}{paintEvent()} and \l + {QObject::timerEvent()}{timerEvent()} functions to draw and update + the widget. In addition we implement a public \c setText() slot + that sets the widget's text. + + The \c timer variable, of type QBasicTimer, is used to update the + widget at regular intervals, making the widget move. The \c text + variable is used to store the currently displayed text, and \c + step to calculate position and color for each character on the + wiggly line. + + \section1 WigglyWidget Class Implementation + + \snippet widgets/wiggly/wigglywidget.cpp 0 + + In the constructor, we make the widget's background slightly + lighter than the usual background using the QPalette::Midlight + color role. The background role defines the brush from the + widget's palette that Qt uses to paint the background. Then we + enlarge the widget's font with 20 points. + + Finally we start the timer; the call to QBasicTimer::start() + makes sure that \e this particular wiggly widget will receive the + timer events generated when the timer times out (every 60 + milliseconds). + + \snippet widgets/wiggly/wigglywidget.cpp 1 + \snippet widgets/wiggly/wigglywidget.cpp 2 + + The \c paintEvent() function is called whenever a QPaintEvent is + sent to the widget. Paint events are sent to widgets that need to + update themselves, for instance when part of a widget is exposed + because a covering widget was moved. For the wiggly widget, a + paint event will also be generated every 60 milliseconds from + the \c timerEvent() slot. + + The \c sineTable represents y-values of the sine curve, + multiplied by 100. It is used to make the wiggly widget move + along the sine curve. + + The QFontMetrics object provides information about the widget's + font. The \c x variable is the horizontal position where we start + drawing the text. The \c y variable is the vertical position of + the text's base line. Both variables are computed so that the + text is horizontally and vertically centered. To compute the base + line, we take into account the font's ascent (the height of the + font above the base line) and font's descent (the height of the + font below the base line). If the descent equals the ascent, they + cancel out each other and the base line is at \c height() / 2. + + \snippet widgets/wiggly/wigglywidget.cpp 3 + \snippet widgets/wiggly/wigglywidget.cpp 4 + + Each time the \c paintEvent() function is called, we create a + QPainter object \c painter to draw the contents of the widget. + For each character in \c text, we determine the color and the + position on the wiggly line based on \c step. In addition, \c x + is incremented by the character's width. + + For simplicity, we assume that QFontMetrics::width(\c text) + returns the sum of the individual character widths + (QFontMetrics::width(\c text[i])). In practice, this is not + always the case because QFontMetrics::width(\c text) also takes + into account the kerning between certain letters (e.g., 'A' and + 'V'). The result is that the text isn't perfectly centered. You + can verify this by typing "AVAVAVAVAVAV" in the line edit. + + \snippet widgets/wiggly/wigglywidget.cpp 5 + \snippet widgets/wiggly/wigglywidget.cpp 6 + + The \c timerEvent() function receives all the timer events that + are generated for this widget. If a timer event is sent from the + widget's QBasicTimer, we increment \c step to make the text move, + and call QWidget::update() to refresh the display. Any other + timer event is passed on to the base class's implementation of + the \l{QWidget::timerEvent()}{timerEvent()} function. + + The QWidget::update() slot does not cause an immediate repaint; + instead the slot schedules a paint event for processing when Qt + returns to the main event loop. The paint events are then handled + by \c{WigglyWidget}'s \c paintEvent() function. +*/ diff --git a/examples/widgets/doc/src/windowflags.qdoc b/examples/widgets/doc/src/windowflags.qdoc new file mode 100644 index 0000000000..e85842b30a --- /dev/null +++ b/examples/widgets/doc/src/windowflags.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 widgets/windowflags + \title Window Flags Example + + The Window Flags example shows how to use the window flags + available in Qt. + + A window flag is either a type or a hint. A type is used to + specify various window-system properties for the widget. A widget + can only have one type, and the default is Qt::Widget. However, a + widget can have zero or more hints. The hints are used to + customize the appearance of top-level windows. + + A widget's flags are stored in a Qt::WindowFlags type which stores + an OR combination of the flags. + + \image windowflags-example.png Screenshot of the Window Flags example + + The example consists of two classes: + + \list + \li \c ControllerWindow is the main application widget that allows + the user to choose among the available window flags, and displays + the effect on a separate preview window. + \li \c PreviewWindow is a custom widget displaying the name of + its currently set window flags in a read-only text editor. + \endlist + + We will start by reviewing the \c ControllerWindow class, then we + will take a look at the \c PreviewWindow class. + + \section1 ControllerWindow Class Definition + + \snippet widgets/windowflags/controllerwindow.h 0 + + The \c ControllerWindow class inherits QWidget. The widget allows + the user to choose among the available window flags, and displays + the effect on a separate preview window. + + We declare a private \c updatePreview() slot to refresh the + preview window whenever the user changes the window flags. + + We also declare several private functions to simplify the + constructor: We call the \c createTypeGroupBox() function to + create a radio button for each available window type, using the + private \c createButton() function, and gather them within a group + box. In a similar way we use the \c createHintsGroupBox() function + to create a check box for each available hint, using the private + \c createCheckBox() function. + + In addition to the various radio buttons and checkboxes, we need + an associated \c PreviewWindow to show the effect of the currently + chosen window flags. + + \image windowflags_controllerwindow.png Screenshot of the Controller Window + + \section1 ControllerWindow Class Implementation + + \snippet widgets/windowflags/controllerwindow.cpp 0 + + In the constructor we first create the preview window. Then we + create the group boxes containing the available window flags using + the private \c createTypeGroupBox() and \c createHintsGroupBox() + functions. In addition we create a \uicontrol Quit button. We put the + button and a stretchable space in a separate layout to make the + button appear in the \c WindowFlag widget's right bottom corner. + + Finally, we add the button's layout and the two goup boxes to a + QVBoxLayout, set the window title and refresh the preview window + using the \c updatePreview() slot. + + \snippet widgets/windowflags/controllerwindow.cpp 1 + \snippet widgets/windowflags/controllerwindow.cpp 2 + + The \c updatePreview() slot is called whenever the user changes + any of the window flags. First we create an empty Qt::WindowFlags + \c flags, then we determine which one of the types that is checked + and add it to \c flags. + + \snippet widgets/windowflags/controllerwindow.cpp 3 + + We also determine which of the hints that are checked, and add + them to \c flags using an OR operator. We use \c flags to set the + window flags for the preview window. + + \snippet widgets/windowflags/controllerwindow.cpp 4 + + We adjust the position of the preview window. The reason we do + that, is that playing around with the window's frame may on some + platforms cause the window's position to be changed behind our + back. If a window is located in the upper left corner of the + screen, parts of the window may not be visible. So we adjust the + widget's position to make sure that, if this happens, the window + is moved within the screen's boundaries. Finally, we call + QWidget::show() to make sure the preview window is visible. + + \omit + \skipto pos + \printuntil /^\}/ + \endomit + + \snippet widgets/windowflags/controllerwindow.cpp 5 + + The private \c createTypeGroupBox() function is called from the + constructor. + + First we create a group box, and then we create a radio button + (using the private \c createRadioButton() function) for each of + the available types among the window flags. We make Qt::Window the + initially applied type. We put the radio buttons into a + QGridLayout and install the layout on the group box. + + We do not include the default Qt::Widget type. The reason is that + it behaves somewhat different than the other types. If the type is + not specified for a widget, and it has no parent, the widget is a + window. However, if it has a parent, it is a standard child + widget. The other types are all top-level windows, and since the + hints only affect top-level windows, we abandon the Qt::Widget + type. + + \snippet widgets/windowflags/controllerwindow.cpp 6 + + The private \c createHintsGroupBox() function is also called from + the constructor. + + Again, the first thing we do is to create a group box. Then we + create a checkbox, using the private \c createCheckBox() function, + for each of the available hints among the window flags. We put the + checkboxes into a QGridLayout and install the layout on the group + box. + + \snippet widgets/windowflags/controllerwindow.cpp 7 + + The private \c createCheckBox() function is called from \c + createHintsGroupBox(). + + We simply create a QCheckBox with the provided text, connect it to + the private \c updatePreview() slot, and return a pointer to the + checkbox. + + \snippet widgets/windowflags/controllerwindow.cpp 8 + + In the private \c createRadioButton() function it is a + QRadioButton we create with the provided text, and connect to the + private \c updatePreview() slot. The function is called from \c + createTypeGroupBox(), and returns a pointer to the button. + + \section1 PreviewWindow Class Definition + + \snippet widgets/windowflags/previewwindow.h 0 + + The \c PreviewWindow class inherits QWidget. It is a custom widget + that displays the names of its currently set window flags in a + read-only text editor. It is also provided with a QPushbutton that + closes the window. + + We reimplement the constructor to create the \uicontrol Close button and + the text editor, and the QWidget::setWindowFlags() function to + display the names of the window flags. + + \image windowflags_previewwindow.png Screenshot of the Preview Window + + \section1 PreviewWindow Class Implementation + + \snippet widgets/windowflags/previewwindow.cpp 0 + + In the constructor, we first create a QTextEdit and make sure that + it is read-only. + + We also prohibit any line wrapping in the text editor using the + QTextEdit::setLineWrapMode() function. The result is that a + horizontal scrollbar appears when a window flag's name exceeds the + width of the editor. This is a reasonable solution since we + construct the displayed text with built-in line breaks. If no line + breaks were guaranteed, using another QTextEdit::LineWrapMode + would perhaps make more sense. + + Then we create the \uicontrol Close button, and put both the widgets + into a QVBoxLayout before we set the window title. + + \snippet widgets/windowflags/previewwindow.cpp 1 + + In our reimplementation of the \c setWindowFlags() function, we + first set the widgets flags using the QWidget::setWindowFlags() + function. Then we run through the available window flags, creating + a text that contains the names of the flags that matches the \c + flags parameter. Finally, we display the text in the widgets text + editor. +*/ diff --git a/examples/widgets/doc/standarddialogs.qdoc b/examples/widgets/doc/standarddialogs.qdoc deleted file mode 100644 index b56642b6ec..0000000000 --- a/examples/widgets/doc/standarddialogs.qdoc +++ /dev/null @@ -1,35 +0,0 @@ -/**************************************************************************** -** -** 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 dialogs/standarddialogs - \title Standard Dialogs Example - - The Standard Dialogs example shows the standard dialogs that are provided by Qt. - - \image standarddialogs-example.png -*/ diff --git a/examples/widgets/doc/stardelegate.qdoc b/examples/widgets/doc/stardelegate.qdoc deleted file mode 100644 index aba8864c2b..0000000000 --- a/examples/widgets/doc/stardelegate.qdoc +++ /dev/null @@ -1,296 +0,0 @@ -/**************************************************************************** -** -** 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 itemviews/stardelegate - \title Star Delegate Example - - The Star Delegate example shows how to create a delegate that - can paint itself and that supports editing. - - \image stardelegate.png The Star Delegate Example - - When displaying data in a QListView, QTableView, or QTreeView, - the individual items are drawn by a - \l{Delegate Classes}{delegate}. Also, when the user starts - editing an item (e.g., by double-clicking the item), the delegate - provides an editor widget that is placed on top of the item while - editing takes place. - - Delegates are subclasses of QAbstractItemDelegate. Qt provides - QItemDelegate, which inherits QAbstractItemDelegate and handles - the most common data types (notably \c int and QString). If we - need to support custom data types, or want to customize the - rendering or the editing for existing data types, we can subclass - QAbstractItemDelegate or QItemDelegate. See \l{Delegate Classes} - for more information about delegates, and \l{Model/View - Programming} if you need a high-level introduction to Qt's - model/view architecture (including delegates). - - In this example, we will see how to implement a custom delegate - to render and edit a "star rating" data type, which can store - values such as "1 out of 5 stars". - - The example consists of the following classes: - - \list - \li \c StarRating is the custom data type. It stores a rating - expressed as stars, such as "2 out of 5 stars" or "5 out of - 6 stars". - - \li \c StarDelegate inherits QItemDelegate and provides support - for \c StarRating (in addition to the data types already - handled by QItemDelegate). - - \li \c StarEditor inherits QWidget and is used by \c StarDelegate - to let the user edit a star rating using the mouse. - \endlist - - To show the \c StarDelegate in action, we will fill a - QTableWidget with some data and install the delegate on it. - - \section1 StarDelegate Class Definition - - Here's the definition of the \c StarDelegate class: - - \snippet itemviews/stardelegate/stardelegate.h 0 - - All public functions are reimplemented virtual functions from - QItemDelegate to provide custom rendering and editing. - - \section1 StarDelegate Class Implementation - - The \l{QAbstractItemDelegate::}{paint()} function is - reimplemented from QItemDelegate and is called whenever the view - needs to repaint an item: - - \snippet itemviews/stardelegate/stardelegate.cpp 0 - - The function is invoked once for each item, represented by a - QModelIndex object from the model. If the data stored in the item - is a \c StarRating, we paint it ourselves; otherwise, we let - QItemDelegate paint it for us. This ensures that the \c - StarDelegate can handle the most common data types. - - In the case where the item is a \c StarRating, we draw the - background if the item is selected, and we draw the item using \c - StarRating::paint(), which we will review later. - - \c{StartRating}s can be stored in a QVariant thanks to the - Q_DECLARE_METATYPE() macro appearing in \c starrating.h. More on - this later. - - The \l{QAbstractItemDelegate::}{createEditor()} function is - called when the user starts editing an item: - - \snippet itemviews/stardelegate/stardelegate.cpp 2 - - If the item is a \c StarRating, we create a \c StarEditor and - connect its \c editingFinished() signal to our \c - commitAndCloseEditor() slot, so we can update the model when the - editor closes. - - Here's the implementation of \c commitAndCloseEditor(): - - \snippet itemviews/stardelegate/stardelegate.cpp 5 - - When the user is done editing, we emit - \l{QAbstractItemDelegate::}{commitData()} and - \l{QAbstractItemDelegate::}{closeEditor()} (both declared in - QAbstractItemDelegate), to tell the model that there is edited - data and to inform the view that the editor is no longer needed. - - The \l{QAbstractItemDelegate::}{setEditorData()} function is - called when an editor is created to initialize it with data - from the model: - - \snippet itemviews/stardelegate/stardelegate.cpp 3 - - We simply call \c setStarRating() on the editor. - - The \l{QAbstractItemDelegate::}{setModelData()} function is - called when editing is finished, to commit data from the editor - to the model: - - \snippet itemviews/stardelegate/stardelegate.cpp 4 - - The \c sizeHint() function returns an item's preferred size: - - \snippet itemviews/stardelegate/stardelegate.cpp 1 - - We simply forward the call to \c StarRating. - - \section1 StarEditor Class Definition - - The \c StarEditor class was used when implementing \c - StarDelegate. Here's the class definition: - - \snippet itemviews/stardelegate/stareditor.h 0 - - The class lets the user edit a \c StarRating by moving the mouse - over the editor. It emits the \c editingFinished() signal when - the user clicks on the editor. - - The protected functions are reimplemented from QWidget to handle - mouse and paint events. The private function \c starAtPosition() - is a helper function that returns the number of the star under - the mouse pointer. - - \section1 StarEditor Class Implementation - - Let's start with the constructor: - - \snippet itemviews/stardelegate/stareditor.cpp 0 - - We enable \l{QWidget::setMouseTracking()}{mouse tracking} on the - widget so we can follow the cursor even when the user doesn't - hold down any mouse button. We also turn on QWidget's - \l{QWidget::autoFillBackground}{auto-fill background} feature to - obtain an opaque background. (Without the call, the view's - background would shine through the editor.) - - The \l{QWidget::}{paintEvent()} function is reimplemented from - QWidget: - - \snippet itemviews/stardelegate/stareditor.cpp 1 - - We simply call \c StarRating::paint() to draw the stars, just - like we did when implementing \c StarDelegate. - - \snippet itemviews/stardelegate/stareditor.cpp 2 - - In the mouse event handler, we call \c setStarCount() on the - private data member \c myStarRating to reflect the current cursor - position, and we call QWidget::update() to force a repaint. - - \snippet itemviews/stardelegate/stareditor.cpp 3 - - When the user releases a mouse button, we simply emit the \c - editingFinished() signal. - - \snippet itemviews/stardelegate/stareditor.cpp 4 - - The \c starAtPosition() function uses basic linear algebra to - find out which star is under the cursor. - - \section1 StarRating Class Definition - - \snippet itemviews/stardelegate/starrating.h 0 - \codeline - \snippet itemviews/stardelegate/starrating.h 1 - - The \c StarRating class represents a rating as a number of stars. - In addition to holding the data, it is also capable of painting - the stars on a QPaintDevice, which in this example is either a - view or an editor. The \c myStarCount member variable stores the - current rating, and \c myMaxStarCount stores the highest possible - rating (typically 5). - - The Q_DECLARE_METATYPE() macro makes the type \c StarRating known - to QVariant, making it possible to store \c StarRating values in - QVariant. - - \section1 StarRating Class Implementation - - The constructor initializes \c myStarCount and \c myMaxStarCount, - and sets up the polygons used to draw stars and diamonds: - - \snippet itemviews/stardelegate/starrating.cpp 0 - - The \c paint() function paints the stars in this \c StarRating - object on a paint device: - - \snippet itemviews/stardelegate/starrating.cpp 2 - - We first set the pen and brush we will use for painting. The \c - mode parameter can be either \c Editable or \c ReadOnly. If \c - mode is editable, we use the \l{QPalette::}{Highlight} color - instead of the \l{QPalette::}{Foreground} color to draw the - stars. - - Then we draw the stars. If we are in \c Edit mode, we paint - diamonds in place of stars if the rating is less than the highest - rating. - - The \c sizeHint() function returns the preferred size for an area - to paint the stars on: - - \snippet itemviews/stardelegate/starrating.cpp 1 - - The preferred size is just enough to paint the maximum number of - stars. The function is called by both \c StarDelegate::sizeHint() - and \c StarEditor::sizeHint(). - - \section1 The \c main() Function - - Here's the program's \c main() function: - - \snippet itemviews/stardelegate/main.cpp 5 - - The \c main() function creates a QTableWidget and sets a \c - StarDelegate on it. \l{QAbstractItemView::}{DoubleClicked} and - \l{QAbstractItemView::}{SelectedClicked} are set as - \l{QAbstractItemView::editTriggers()}{edit triggers}, so that the - editor is opened with a single click when the star rating item is - selected. - - The \c populateTableWidget() function fills the QTableWidget with - data: - - \snippet itemviews/stardelegate/main.cpp 0 - \snippet itemviews/stardelegate/main.cpp 1 - \dots - \snippet itemviews/stardelegate/main.cpp 2 - \snippet itemviews/stardelegate/main.cpp 3 - \codeline - \snippet itemviews/stardelegate/main.cpp 4 - - Notice the call to qVariantFromValue to convert a \c - StarRating to a QVariant. - - \section1 Possible Extensions and Suggestions - - There are many ways to customize Qt's \l{Model/View - Programming}{model/view framework}. The approach used in this - example is appropriate for most custom delegates and editors. - Examples of possibilities not used by the star delegate and star - editor are: - - \list - \li It is possible to open editors programmatically by calling - QAbstractItemView::edit(), instead of relying on edit - triggers. This could be use to support other edit triggers - than those offered by the QAbstractItemView::EditTrigger enum. - For example, in the Star Delegate example, hovering over an - item with the mouse might make sense as a way to pop up an - editor. - - \li By reimplementing QAbstractItemDelegate::editorEvent(), it is - possible to implement the editor directly in the delegate, - instead of creating a separate QWidget subclass. - \endlist -*/ diff --git a/examples/widgets/doc/states.qdoc b/examples/widgets/doc/states.qdoc deleted file mode 100644 index 52eda087f1..0000000000 --- a/examples/widgets/doc/states.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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 animation/states - \title States Example - - The States example shows how to use the Qt state machine to play - animations. - - \image states-example.png -*/ diff --git a/examples/widgets/doc/stickman.qdoc b/examples/widgets/doc/stickman.qdoc deleted file mode 100644 index cffdb64822..0000000000 --- a/examples/widgets/doc/stickman.qdoc +++ /dev/null @@ -1,102 +0,0 @@ -/**************************************************************************** -** -** 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 animation/stickman - \title Stickman Example - - The Stickman example shows how to animate transitions in a state machine to implement key frame - animations. - - \image stickman-example.png - - In this example, we will write a small application which animates the joints in a skeleton and - projects a stickman figure on top. The stickman can be either "alive" or "dead", and when in the - "alive" state, he can be performing different actions defined by key frame animations. - - Animations are implemented as composite states. Each child state of the animation state - represents a frame in the animation by setting the position of each joint in the stickman's - skeleton to the positions defined for the particular frame. The frames are then bound together - with animated transitions that trigger on the source state's propertiesAssigned() signal. Thus, - the machine will enter the state representing the next frame in the animation immediately after - it has finished animating into the previous frame. - - \image stickman-example1.png - - The states for an animation is constructed by reading a custom animation file format and - creating states that assign values to the the "position" properties of each of the nodes in the - skeleton graph. - - \snippet animation/stickman/lifecycle.cpp 1 - - The states are then bound together with signal transitions that listen to the - propertiesAssigned() signal. - - \snippet animation/stickman/lifecycle.cpp 2 - - The last frame state is given a transition to the first one, so that the animation will loop - until it is interrupted when a transition out from the animation state is taken. To get smooth - animations between the different key frames, we set a default animation on the state machine. - This is a parallel animation group which contains animations for all the "position" properties - and will be selected by default when taking any transition that leads into a state that assigns - values to these properties. - - \snippet animation/stickman/lifecycle.cpp 3 - - Several such animation states are constructed, and are placed together as children of a top - level "alive" state which represents the stickman life cycle. Transitions go from the parent - state to the child state to ensure that each of the child states inherit them. - - \image stickman-example2.png - - This saves us the effort of connect every state to every state with identical transitions. The - state machine makes sure that transitions between the key frame animations are also smooth by - applying the default animation when interrupting one and starting another. - - Finally, there is a transition out from the "alive" state and into the "dead" state. This is - a custom transition type called LightningSrikesTransition which samples every second and - triggers at random (one out of fifty times on average.) - - \snippet animation/stickman/lifecycle.cpp 4 - - When it triggers, the machine will first enter a "lightningBlink" state which uses a timer to - pause for a brief period of time while the background color of the scene is white. This gives us - a flash effect when the lightning strikes. - - \snippet animation/stickman/lifecycle.cpp 5 - - We start and stop a QTimer object when entering and exiting the state. Then we transition into - the "dead" state when the timer times out. - - \snippet animation/stickman/lifecycle.cpp 0 - - When the machine is in the "dead" state, it will be unresponsive. This is because the "dead" - state has no transitions leading out. - - \image stickman-example3.png - -*/ diff --git a/examples/widgets/doc/styles.qdoc b/examples/widgets/doc/styles.qdoc deleted file mode 100644 index f8be98d2da..0000000000 --- a/examples/widgets/doc/styles.qdoc +++ /dev/null @@ -1,472 +0,0 @@ -/**************************************************************************** -** -** 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/styles - \title Styles Example - - The Styles example illustrates how to create custom widget - drawing styles using Qt, and demonstrates Qt's predefined styles. - - \image styles-enabledwood.png Screenshot of the Styles example - - A style in Qt is a subclass of QStyle or of one of its - subclasses. Styles perform drawing on behalf of widgets. Qt - provides a whole range of predefined styles, either built into - the \l QtGui library or found in plugins. Custom styles are - usually created by subclassing one of Qt's existing style and - reimplementing a few virtual functions. - - In this example, the custom style is called \c NorwegianWoodStyle - and derives from QMotifStyle. Its main features are the wooden - textures used for filling most of the widgets and its round - buttons and comboboxes. - - To implement the style, we use some advanced features provided by - QPainter, such as \l{QPainter::Antialiasing}{antialiasing} (to - obtain smoother button edges), \l{QColor::alpha()}{alpha blending} - (to make the buttons appeared raised or sunken), and - \l{QPainterPath}{painter paths} (to fill the buttons and draw the - outline). We also use many features of QBrush and QPalette. - - The example consists of the following classes: - - \list - \li \c NorwegianWoodStyle inherits from QMotifStyle and implements - the Norwegian Wood style. - \li \c WidgetGallery is a \c QDialog subclass that shows the most - common widgets and allows the user to switch style - dynamically. - \endlist - - \section1 NorwegianWoodStyle Class Definition - - Here's the definition of the \c NorwegianWoodStyle class: - - \snippet widgets/styles/norwegianwoodstyle.h 0 - - The public functions are all declared in QStyle (QMotifStyle's - grandparent class) and reimplemented here to override the Motif - look and feel. The private functions are helper functions. - - \section1 NorwegianWoodStyle Class Implementation - - We will now review the implementation of the \c - NorwegianWoodStyle class. - - \snippet widgets/styles/norwegianwoodstyle.cpp 0 - - The \c polish() function is reimplemented from QStyle. It takes a - QPalette as a reference and adapts the palette to fit the style. - Most styles don't need to reimplement that function. The - Norwegian Wood style reimplements it to set a "wooden" palette. - - We start by defining a few \l{QColor}s that we'll need. Then we - load two PNG images. The \c : prefix in the file path indicates - that the PNG files are \l{The Qt Resource System}{embedded - resources}. - - \table - \row \li \inlineimage widgets/styles/images/woodbackground.png - - \li \b{woodbackground.png} - - This texture is used as the background of most widgets. - The wood pattern is horizontal. - - \row \li \inlineimage widgets/styles/images/woodbutton.png - - \li \b{woodbutton.png} - - This texture is used for filling push buttons and - comboboxes. The wood pattern is vertical and more reddish - than the texture used for the background. - \endtable - - The \c midImage variable is initialized to be the same as \c - buttonImage, but then we use a QPainter and fill it with a 25% - opaque black color (a black with an \l{QColor::alpha()}{alpha - channel} of 63). The result is a somewhat darker image than \c - buttonImage. This image will be used for filling buttons that the - user is holding down. - - \snippet widgets/styles/norwegianwoodstyle.cpp 1 - - We initialize the palette. Palettes have various - \l{QPalette::ColorRole}{color roles}, such as QPalette::Base - (used for filling text editors, item views, etc.), QPalette::Text - (used for foreground text), and QPalette::Background (used for - the background of most widgets). Each role has its own QBrush, - which usually is a plain color but can also be a brush pattern or - even a texture (a QPixmap). - - In addition to the roles, palettes have several - \l{QPalette::ColorGroup}{color groups}: active, disabled, and - inactive. The active color group is used for painting widgets in - the active window. The disabled group is used for disabled - widgets. The inactive group is used for all other widgets. Most - palettes have identical active and inactive groups, while the - disabled group uses darker shades. - - We initialize the QPalette object with a brown color. Qt - automatically derivates all color roles for all color groups from - that single color. We then override some of the default values. For - example, we use Qt::darkGreen instead of the default - (Qt::darkBlue) for the QPalette::Highlight role. The - QPalette::setBrush() overload that we use here sets the same - color or brush for all three color groups. - - The \c setTexture() function is a private function that sets the - texture for a certain color role, while preserving the existing - color in the QBrush. A QBrush can hold both a solid color and a - texture at the same time. The solid color is used for drawing - text and other graphical elements where textures don't look good. - - At the end, we set the brush for the disabled color group of the - palette. We use \c woodbackground.png as the texture for all - disabled widgets, including buttons, and use a darker color to - accompany the texture. - - \image styles-disabledwood.png The Norwegian Wood style with disabled widgets - - Let's move on to the other functions reimplemented from - QMotifStyle: - - \snippet widgets/styles/norwegianwoodstyle.cpp 3 - \snippet widgets/styles/norwegianwoodstyle.cpp 4 - - This QStyle::polish() overload is called once on every widget - drawn using the style. We reimplement it to set the Qt::WA_Hover - attribute on \l{QPushButton}s and \l{QComboBox}es. When this - attribute is set, Qt generates paint events when the mouse - pointer enters or leaves the widget. This makes it possible to - render push buttons and comboboxes differently when the mouse - pointer is over them. - - \snippet widgets/styles/norwegianwoodstyle.cpp 5 - \snippet widgets/styles/norwegianwoodstyle.cpp 6 - - This QStyle::unpolish() overload is called to undo any - modification done to the widget in \c polish(). For simplicity, - we assume that the flag wasn't set before \c polish() was called. - In an ideal world, we would remember the original state for each - widgets (e.g., using a QMap) and restore it in - \c unpolish(). - - \snippet widgets/styles/norwegianwoodstyle.cpp 7 - \snippet widgets/styles/norwegianwoodstyle.cpp 8 - - The \l{QStyle::pixelMetric()}{pixelMetric()} function returns the - size in pixels for a certain user interface element. By - reimplementing this function, we can affect the way certain - widgets are drawn and their size hint. Here, we return 8 as the - width around a shown in a QComboBox, ensuring that there is - enough place around the text and the arrow for the Norwegian Wood - round corners. The default value for this setting in the Motif - style is 2. - - We also change the extent of \l{QScrollBar}s, i.e., the height - for a horizontal scroll bar and the width for a vertical scroll - bar, to be 4 pixels more than in the Motif style. This makes the - style a bit more distinctive. - - For all other QStyle::PixelMetric elements, we use the Motif - settings. - - \snippet widgets/styles/norwegianwoodstyle.cpp 9 - \snippet widgets/styles/norwegianwoodstyle.cpp 10 - - The \l{QStyle::styleHint()}{styleHint()} function returns some - hints to widgets or to the base style (in our case QMotifStyle) - about how to draw the widgets. The Motif style returns \c true - for the QStyle::SH_DitherDisabledText hint, resulting in a most - unpleasing visual effect. We override this behavior and return \c - false instead. We also return \c true for the - QStyle::SH_EtchDisabledText hint, meaning that disabled text is - rendered with an embossed look (as QWindowsStyle does). - - \snippet widgets/styles/norwegianwoodstyle.cpp 11 - \snippet widgets/styles/norwegianwoodstyle.cpp 12 - - The \l{QStyle::drawPrimitive()}{drawPrimitive()} function is - called by Qt widgets to draw various fundamental graphical - elements. Here we reimplement it to draw QPushButton and - QComboBox with round corners. The button part of these widgets is - drawn using the QStyle::PE_PanelButtonCommand primitive element. - - The \c option parameter, of type QStyleOption, contains - everything we need to know about the widget we want to draw on. - In particular, \c option->rect gives the rectangle within which - to draw the primitive element. The \c painter parameter is a - QPainter object that we can use to draw on the widget. - - The \c widget parameter is the widget itself. Normally, all the - information we need is available in \c option and \c painter, so - we don't need \c widget. We can use it to perform special - effects; for example, QMacStyle uses it to animate default - buttons. If you use it, be aware that the caller is allowed to - pass a null pointer. - - We start by defining three \l{QColor}s that we'll need later on. - We also put the x, y, width, and height components of the - widget's rectangle in local variables. The value used for the \c - semiTransparentWhite and for the \c semiTransparentBlack color's - alpha channel depends on whether the mouse cursor is over the - widget or not. Since we set the Qt::WA_Hover attribute on - \l{QPushButton}s and \l{QComboBox}es, we can rely on the - QStyle::State_MouseOver flag to be set when the mouse is over the - widget. - - \snippet widgets/styles/norwegianwoodstyle.cpp 13 - \snippet widgets/styles/norwegianwoodstyle.cpp 14 - - The \c roundRect variable is a QPainterPath. A QPainterPath is is - a vectorial specification of a shape. Any shape (rectangle, - ellipse, spline, etc.) or combination of shapes can be expressed - as a path. We will use \c roundRect both for filling the button - background with a wooden texture and for drawing the outline. The - \c roundRectPath() function is a private function; we will come - back to it later. - - \snippet widgets/styles/norwegianwoodstyle.cpp 15 - \snippet widgets/styles/norwegianwoodstyle.cpp 16 - \snippet widgets/styles/norwegianwoodstyle.cpp 17 - \snippet widgets/styles/norwegianwoodstyle.cpp 18 - - We define two variables, \c brush and \c darker, and initialize - them based on the state of the button: - - \list - \li If the button is a \l{QPushButton::flat}{flat button}, we use - the \l{QPalette::Background}{Background} brush. We set \c - darker to \c true if the button is - \l{QAbstractButton::down}{down} or - \l{QAbstractButton::checked}{checked}. - \li If the button is currently held down by the user or in the - \l{QAbstractButton::checked}{checked} state, we use the - \l{QPalette::Mid}{Mid} component of the palette. We set - \c darker to \c true if the button is - \l{QAbstractButton::checked}{checked}. - \li Otherwise, we use the \l{QPalette::Button}{Button} component - of the palette. - \endlist - - The screenshot below illustrates how \l{QPushButton}s are - rendered based on their state: - - \image styles-woodbuttons.png Norwegian Wood buttons in different states - - To discover whether the button is flat or not, we need to cast - the \c option parameter to QStyleOptionButton and check if the - \l{QStyleOptionButton::features}{features} member specifies the - QStyleOptionButton::Flat flag. The qstyleoption_cast() function - performs a dynamic cast; if \c option is not a - QStyleOptionButton, qstyleoption_cast() returns a null pointer. - - \snippet widgets/styles/norwegianwoodstyle.cpp 19 - \snippet widgets/styles/norwegianwoodstyle.cpp 20 - \snippet widgets/styles/norwegianwoodstyle.cpp 21 - \snippet widgets/styles/norwegianwoodstyle.cpp 22 - \snippet widgets/styles/norwegianwoodstyle.cpp 23 - - We turn on antialiasing on QPainter. Antialiasing is a technique - that reduces the visual distortion that occurs when the edges of - a shape are converted into pixels. For the Norwegian Wood style, - we use it to obtain smoother edges for the round buttons. - - \image styles-aliasing.png Norwegian wood buttons with and without antialiasing - - The first call to QPainter::fillPath() draws the background of - the button with a wooden texture. The second call to - \l{QPainter::fillPath()}{fillPath()} paints the same area with a - semi-transparent black color (a black color with an alpha channel - of 63) to make the area darker if \c darker is true. - - \snippet widgets/styles/norwegianwoodstyle.cpp 24 - \snippet widgets/styles/norwegianwoodstyle.cpp 25 - - Next, we draw the outline. The top-left half of the outline and - the bottom-right half of the outline are drawn using different - \l{QPen}s to produce a 3D effect. Normally, the top-left half of - the outline is drawn lighter whereas the bottom-right half is - drawn darker, but if the button is - \l{QAbstractButton::down}{down} or - \l{QAbstractButton::checked}{checked}, we invert the two - \l{QPen}s to give a sunken look to the button. - - \snippet widgets/styles/norwegianwoodstyle.cpp 26 - - We draw the top-left part of the outline by calling - QPainter::drawPath() with an appropriate - \l{QPainter::setClipRegion()}{clip region}. If the - \l{QStyleOption::direction}{layout direction} is right-to-left - instead of left-to-right, we swap the \c x1, \c x2, \c x3, and \c - x4 variables to obtain correct results. On right-to-left desktop, - the "light" comes from the top-right corner of the screen instead - of the top-left corner; raised and sunken widgets must be drawn - accordingly. - - The diagram below illustrates how 3D effects are drawn according - to the layout direction. The area in red on the diagram - corresponds to the \c topHalf polygon: - - \image styles-3d.png - - An easy way to test how a style looks in right-to-left mode is to - pass the \c -reverse command-line option to the application. This - option is recognized by the QApplication constructor. - - \snippet widgets/styles/norwegianwoodstyle.cpp 32 - \snippet widgets/styles/norwegianwoodstyle.cpp 33 - \snippet widgets/styles/norwegianwoodstyle.cpp 34 - - The bottom-right part of the outline is drawn in a similar - fashion. Then we draw a one-pixel wide outline around the entire - button, using the \l{QPalette::Foreground}{Foreground} component - of the QPalette. - - This completes the QStyle::PE_PanelButtonCommand case of the \c - switch statement. Other primitive elements are handled by the - base style. Let's now turn to the other \c NorwegianWoodStyle - member functions: - - \snippet widgets/styles/norwegianwoodstyle.cpp 35 - \snippet widgets/styles/norwegianwoodstyle.cpp 36 - - We reimplement QStyle::drawControl() to draw the text on a - QPushButton in a bright color when the button is - \l{QAbstractButton::down}{down} or - \l{QAbstractButton::checked}{checked}. - - If the \c option parameter points to a QStyleOptionButton object - (it normally should), we take a copy of the object and modify its - \l{QStyleOption::palette}{palette} member to make the - QPalette::ButtonText be the same as the QPalette::BrightText - component (unless the widget is disabled). - - \snippet widgets/styles/norwegianwoodstyle.cpp 37 - \snippet widgets/styles/norwegianwoodstyle.cpp 38 - - The \c setTexture() function is a private function that sets the - \l{QBrush::texture()}{texture} component of the \l{QBrush}es for - a certain \l{QPalette::ColorRole}{color role}, for all three - \l{QPalette::ColorGroup}{color groups} (active, disabled, - inactive). We used it to initialize the Norwegian Wood palette in - \c polish(QPalette &). - - \snippet widgets/styles/norwegianwoodstyle.cpp 39 - \snippet widgets/styles/norwegianwoodstyle.cpp 40 - - The \c roundRectPath() function is a private function that - constructs a QPainterPath object for round buttons. The path - consists of eight segments: four arc segments for the corners and - four lines for the sides. - - With around 250 lines of code, we have a fully functional custom - style based on one of the predefined styles. Custom styles can be - used to provide a distinct look to an application or family of - applications. - - \section1 WidgetGallery Class - - For completeness, we will quickly review the \c WidgetGallery - class, which contains the most common Qt widgets and allows the - user to change style dynamically. Here's the class definition: - - \snippet widgets/styles/widgetgallery.h 0 - \dots - \snippet widgets/styles/widgetgallery.h 1 - - Here's the \c WidgetGallery constructor: - - \snippet widgets/styles/widgetgallery.cpp 0 - - We start by creating child widgets. The \uicontrol Style combobox is - initialized with all the styles known to QStyleFactory, in - addition to \c NorwegianWood. The \c create...() functions are - private functions that set up the various parts of the \c - WidgetGallery. - - \snippet widgets/styles/widgetgallery.cpp 1 - \snippet widgets/styles/widgetgallery.cpp 2 - - We connect the \uicontrol Style combobox to the \c changeStyle() - private slot, the \uicontrol{Use style's standard palette} check box to - the \c changePalette() slot, and the \uicontrol{Disable widgets} check - box to the child widgets' - \l{QWidget::setDisabled()}{setDisabled()} slot. - - \snippet widgets/styles/widgetgallery.cpp 3 - \snippet widgets/styles/widgetgallery.cpp 4 - - Finally, we put the child widgets in layouts. - - \snippet widgets/styles/widgetgallery.cpp 5 - \snippet widgets/styles/widgetgallery.cpp 6 - - When the user changes the style in the combobox, we call - QApplication::setStyle() to dynamically change the style of the - application. - - \snippet widgets/styles/widgetgallery.cpp 7 - \snippet widgets/styles/widgetgallery.cpp 8 - - If the user turns the \uicontrol{Use style's standard palette} on, the - current style's \l{QStyle::standardPalette()}{standard palette} - is used; otherwise, the system's default palette is honored. - - For the Norwegian Wood style, this makes no difference because we - always override the palette with our own palette in \c - NorwegianWoodStyle::polish(). - - \snippet widgets/styles/widgetgallery.cpp 9 - \snippet widgets/styles/widgetgallery.cpp 10 - - The \c advanceProgressBar() slot is called at regular intervals - to advance the progress bar. Since we don't know how long the - user will keep the Styles application running, we use a - logarithmic formula: The closer the progress bar gets to 100%, - the slower it advances. - - We will review \c createProgressBar() in a moment. - - \snippet widgets/styles/widgetgallery.cpp 11 - \snippet widgets/styles/widgetgallery.cpp 12 - - The \c createTopLeftGroupBox() function creates the QGroupBox - that occupies the top-left corner of the \c WidgetGallery. We - skip the \c createTopRightGroupBox(), \c - createBottomLeftTabWidget(), and \c createBottomRightGroupBox() - functions, which are very similar. - - \snippet widgets/styles/widgetgallery.cpp 13 - - In \c createProgressBar(), we create a QProgressBar at the bottom - of the \c WidgetGallery and connect its - \l{QTimer::timeout()}{timeout()} signal to the \c - advanceProgressBar() slot. -*/ diff --git a/examples/widgets/doc/stylesheet.qdoc b/examples/widgets/doc/stylesheet.qdoc deleted file mode 100644 index af45411f8c..0000000000 --- a/examples/widgets/doc/stylesheet.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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/stylesheet - \title Style Sheet Example - - The Style Sheet Example shows how to use style sheets. - - \image stylesheet-pagefold.png Screen Shot of the Pagefold style sheet -*/ - diff --git a/examples/widgets/doc/sub-attaq.qdoc b/examples/widgets/doc/sub-attaq.qdoc deleted file mode 100644 index ae00eb0926..0000000000 --- a/examples/widgets/doc/sub-attaq.qdoc +++ /dev/null @@ -1,40 +0,0 @@ -/**************************************************************************** -** -** 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 animation/sub-attaq - \title Sub-Attaq - - This example shows Qt's ability to combine \l{The Animation Framework}{the animation framework} - and \l{The State Machine Framework}{the state machine framework} to create a game. - - \image sub-attaq-demo.png - - The purpose of the game is to destroy all submarines to win the current level. - The boat can be controlled using left and right keys. To fire a bomb you can press - up and down keys. -*/ diff --git a/examples/widgets/doc/syntaxhighlighter.qdoc b/examples/widgets/doc/syntaxhighlighter.qdoc deleted file mode 100644 index 66727c0030..0000000000 --- a/examples/widgets/doc/syntaxhighlighter.qdoc +++ /dev/null @@ -1,252 +0,0 @@ -/**************************************************************************** -** -** 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 richtext/syntaxhighlighter - \title Syntax Highlighter Example - - The Syntax Highlighter example shows how to perform simple syntax - highlighting by subclassing the QSyntaxHighlighter class. - - \image syntaxhighlighter-example.png - - The Syntax Highlighter application displays C++ files with custom - syntax highlighting. - - The example consists of two classes: - - \list - \li The \c Highlighter class defines and applies the - highlighting rules. - \li The \c MainWindow widget is the application's main window. - \endlist - - We will first review the \c Highlighter class to see how you can - customize the QSyntaxHighlighter class to fit your preferences, - then we will take a look at the relevant parts of the \c - MainWindow class to see how you can use your custom highlighter - class in an application. - - \section1 Highlighter Class Definition - - \snippet richtext/syntaxhighlighter/highlighter.h 0 - - To provide your own syntax highlighting, you must subclass - QSyntaxHighlighter, reimplement the \l - {QSyntaxHighlighter::highlightBlock()}{highlightBlock()} function, - and define your own highlighting rules. - - We have chosen to store our highlighting rules using a private - struct: A rule consists of a QRegExp pattern and a QTextCharFormat - instance. The various rules are then stored using a QVector. - - The QTextCharFormat class provides formatting information for - characters in a QTextDocument specifying the visual properties of - the text, as well as information about its role in a hypertext - document. In this example, we will only define the font weight and - color using the QTextCharFormat::setFontWeight() and - QTextCharFormat::setForeground() functions. - - \section1 Highlighter Class Implementation - - When subclassing the QSyntaxHighlighter class you must pass the - parent parameter to the base class constructor. The parent is the - text document upon which the syntax highligning will be - applied. In this example, we have also chosen to define our - highlighting rules in the constructor: - - \snippet richtext/syntaxhighlighter/highlighter.cpp 0 - \snippet richtext/syntaxhighlighter/highlighter.cpp 1 - - First we define a keyword rule which recognizes the most common - C++ keywords. We give the \c keywordFormat a bold, dark blue - font. For each keyword, we assign the keyword and the specified - format to a HighlightingRule object and append the object to our - list of rules. - - \snippet richtext/syntaxhighlighter/highlighter.cpp 2 - \codeline - \snippet richtext/syntaxhighlighter/highlighter.cpp 4 - \codeline - \snippet richtext/syntaxhighlighter/highlighter.cpp 5 - - Then we create a format that we will apply to Qt class names. The - class names will be rendered with a dark magenta color and a bold - style. We specify a string pattern that is actually a regular - expression capturing all Qt class names. Then we assign the - regular expression and the specified format to a HighlightingRule - object and append the object to our list of rules. - - We also define highlighting rules for quotations and functions - using the same approach: The patterns have the form of regular - expressions and are stored in HighlightingRule objects with the - associated format. - - \snippet richtext/syntaxhighlighter/highlighter.cpp 3 - \codeline - \snippet richtext/syntaxhighlighter/highlighter.cpp 6 - - The C++ language has two variations of comments: The single line - comment (\c //) and the multiline comment (\c{/*...*}\c{/}). The single - line comment can easily be defined through a highlighting rule - similar to the previous ones. But the multiline comment needs - special care due to the design of the QSyntaxHighlighter class. - - After a QSyntaxHighlighter object is created, its \l - {QSyntaxHighlighter::highlightBlock()}{highlightBlock()} function - will be called automatically whenever it is necessary by the rich - text engine, highlighting the given text block. The problem - appears when a comment spans several text blocks. We will take a - closer look at how this problem can be solved when reviewing the - implementation of the \c Highlighter::highlightBlock() - function. At this point we only specify the multiline comment's - color. - - \snippet richtext/syntaxhighlighter/highlighter.cpp 7 - - The highlightBlock() function is called automatically whenever it - is necessary by the rich text engine, i.e. when there are text - blocks that have changed. - - First we apply the syntax highlighting rules that we stored in the - \c highlightingRules vector. For each rule (i.e. for each - HighlightingRule object) we search for the pattern in the given - textblock using the QString::indexOf() function. When the first - occurrence of the pattern is found, we use the - QRegExp::matchedLength() function to determine the string that - will be formatted. QRegExp::matchedLength() returns the length of - the last matched string, or -1 if there was no match. - - To perform the actual formatting the QSyntaxHighlighter class - provides the \l {QSyntaxHighlighter::setFormat()}{setFormat()} - function. This function operates on the text block that is passed - as argument to the \c highlightBlock() function. The specified - format is applied to the text from the given start position for - the given length. The formatting properties set in the given - format are merged at display time with the formatting information - stored directly in the document. Note that the document itself - remains unmodified by the format set through this function. - - This process is repeated until the last occurrence of the pattern - in the current text block is found. - - \snippet richtext/syntaxhighlighter/highlighter.cpp 8 - - To deal with constructs that can span several text blocks (like - the C++ multiline comment), it is necessary to know the end state - of the previous text block (e.g. "in comment"). Inside your \c - highlightBlock() implementation you can query the end state of the - previous text block using the - QSyntaxHighlighter::previousBlockState() function. After parsing - the block you can save the last state using - QSyntaxHighlighter::setCurrentBlockState(). - - The \l - {QSyntaxHighlighter::previousBlockState()}{previousBlockState()} - function return an int value. If no state is set, the returned - value is -1. You can designate any other value to identify any - given state using the \l - {QSyntaxHighlighter::setCurrentBlockState()}{setCurrentBlockState()} - function. Once the state is set, the QTextBlock keeps that value - until it is set again or until the corresponding paragraph of text - is deleted. - - In this example we have chosen to use 0 to represent the "not in - comment" state, and 1 for the "in comment" state. When the stored - syntax highlighting rules are applied we initialize the current - block state to 0. - - \snippet richtext/syntaxhighlighter/highlighter.cpp 9 - - If the previous block state was "in comment" (\c - {previousBlockState() == 1}), we start the search for an end - expression at the beginning of the text block. If the - previousBlockState() returns 0, we start the search at the - location of the first occurrence of a start expression. - - \snippet richtext/syntaxhighlighter/highlighter.cpp 10 - \snippet richtext/syntaxhighlighter/highlighter.cpp 11 - - When an end expression is found, we calculate the length of the - comment and apply the multiline comment format. Then we search for - the next occurrence of the start expression and repeat the - process. If no end expression can be found in the current text - block we set the current block state to 1, i.e. "in comment". - - This completes the \c Highlighter class implementation; it is now - ready for use. - - \section1 MainWindow Class Definition - - Using a QSyntaxHighlighter subclass is simple; just provide your - application with an instance of the class and pass it the document - upon which you want the highlighting to be applied. - - \snippet richtext/syntaxhighlighter/mainwindow.h 0 - - In this example we declare a pointer to a \c Highlighter instance - which we later will initialize in the private \c setupEditor() - function. - - \section1 MainWindow Class Implementation - - The constructor of the main window is straight forward. We first - set up the menus, then we initialize the editor and make it the - central widget of the application. Finally we set the main - window's title. - - \snippet richtext/syntaxhighlighter/mainwindow.cpp 0 - - We initialize and install the \c Highlighter object in the private - setupEditor() convenience function: - - \snippet richtext/syntaxhighlighter/mainwindow.cpp 1 - - First we create the font we want to use in the editor, then we - create the editor itself which is an instance of the QTextEdit - class. Before we initialize the editor with the \c MainWindow - class definition file, we create a \c Highlighter instance passing - the editor's document as argument. This is the document that the - highlighting will be applied to. Then we are done. - - A QSyntaxHighlighter object can only be installed on one document - at the time, but you can easily reinstall the highlighter on - another document using the QSyntaxHighlighter::setDocument() - function. The QSyntaxHighlighter class also provides the \l - {QSyntaxHighlighter::document()}{document()} function which - returns the currently set document. - - \section1 Other Code Editor Features - - It is possible to implement parenthesis matching with - QSyntaxHighlighter. The "Matching Parentheses with - QSyntaxHighlighter" article in Qt Quarterly 31 - (\l{http://doc.qt.nokia.com/qq/}) implements this. We also have - the \l{Code Editor Example}, which shows how to implement line - numbers and how to highlight the current line. - -*/ diff --git a/examples/widgets/doc/tabdialog.qdoc b/examples/widgets/doc/tabdialog.qdoc deleted file mode 100644 index 98983d124b..0000000000 --- a/examples/widgets/doc/tabdialog.qdoc +++ /dev/null @@ -1,134 +0,0 @@ -/**************************************************************************** -** -** 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 dialogs/tabdialog - \title Tab Dialog Example - - The Tab Dialog example shows how to construct a tab dialog using the - QTabWidget class. - - Dialogs provide an efficient way for the application to communicate - with the user, but complex dialogs suffer from the problem that they - often take up too much screen area. By using a number of tabs in a - dialog, information can be split into different categories, while - remaining accessible. - - \image tabdialog-example.png - - The Tab Dialog example consists of a single \c TabDialog class that - provides three tabs, each containing information about a particular - file, and two standard push buttons that are used to accept or reject - the contents of the dialog. - - \section1 TabDialog Class Definition - - The \c TabDialog class is a subclass of QDialog that displays a - QTabWidget and two standard dialog buttons. The class definition - only contain the class constructor and a private data member for - the QTabWidget: - - \snippet dialogs/tabdialog/tabdialog.h 3 - - In the example, the widget will be used as a top-level window, but - we define the constructor so that it can take a parent widget. This - allows the dialog to be centered on top of an application's main - window. - - \section1 TabDialog Class Implementation - - The constructor calls the QDialog constructor and creates a QFileInfo - object for the specified filename. - - \snippet dialogs/tabdialog/tabdialog.cpp 0 - - The tab widget is populated with three custom widgets that each - contain information about the file. We construct each of these - without a parent widget because the tab widget will reparent - them as they are added to it. - - We create two standard push buttons, and connect each of them to - the appropriate slots in the dialog: - - \snippet dialogs/tabdialog/tabdialog.cpp 1 - \snippet dialogs/tabdialog/tabdialog.cpp 3 - - We arrange the tab widget above the buttons in the dialog: - - \snippet dialogs/tabdialog/tabdialog.cpp 4 - - Finally, we set the dialog's title: - - \snippet dialogs/tabdialog/tabdialog.cpp 5 - - Each of the tabs are subclassed from QWidget, and only provide - constructors. - - \section1 GeneralTab Class Definition - - The GeneralTab widget definition is simple because we are only interested - in displaying the contents of a widget within a tab: - - \snippet dialogs/tabdialog/tabdialog.h 0 - - \section1 GeneralTab Class Implementation - - The GeneralTab widget simply displays some information about the file - passed by the TabDialog. Various widgets for this purpose, and these - are arranged within a vertical layout: - - \snippet dialogs/tabdialog/tabdialog.cpp 6 - - \section1 PermissionsTab Class Definition - - Like the GeneralTab, the PermissionsTab is just used as a placeholder - widget for its children: - - \snippet dialogs/tabdialog/tabdialog.h 1 - - \section1 PermissionsTab Class Implementation - - The PermissionsTab shows information about the file's access information, - displaying details of the file permissions and owner in widgets that are - arranged in nested layouts: - - \snippet dialogs/tabdialog/tabdialog.cpp 7 - - \section1 ApplicationsTab Class Definition - - The ApplicationsTab is another placeholder widget that is mostly - cosmetic: - - \snippet dialogs/tabdialog/tabdialog.h 2 - - \section1 ApplicationsTab Class Implementation - - The ApplicationsTab does not show any useful information, but could be - used as a template for a more complicated example: - - \snippet dialogs/tabdialog/tabdialog.cpp 8 -*/ diff --git a/examples/widgets/doc/tablet.qdoc b/examples/widgets/doc/tablet.qdoc deleted file mode 100644 index 846a9a357b..0000000000 --- a/examples/widgets/doc/tablet.qdoc +++ /dev/null @@ -1,369 +0,0 @@ -/**************************************************************************** -** -** 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/tablet - \title Tablet Example - - This example shows how to use a Wacom tablet in Qt applications. - - \image tabletexample.png - - When you use a tablet with Qt applications, \l{QTabletEvent}s are - generated. You need to reimplement the - \l{QWidget::}{tabletEvent()} event handler if you want to handle - tablet events. Events are generated when the device used for - drawing enters and leaves the proximity of the tablet (i.e., when - it is close but not pressed down on it), when a device is pushed - down and released from it, and when a device is moved on the - tablet. - - The information available in QTabletEvent depends on the device - used. The tablet in this example has two different devices for - drawing: a stylus and an airbrush. For both devices the event - contains the position of the device, pressure on the tablet, - vertical tilt, and horizontal tilt (i.e, the angle between the - device and the perpendicular of the tablet). The airbrush has a - finger wheel; the position of this is also available in the tablet - event. - - In this example we implement a drawing program. You can use the - stylus to draw on the tablet as you use a pencil on paper. When - you draw with the airbrush you get a spray of paint; the finger - wheel is used to change the density of the spray. The pressure and - tilt can change the alpha and saturation values of the QColor and the - width of the QPen used for drawing. - - The example consists of the following: - - \list - \li The \c MainWindow class inherits QMainWindow and creates - the examples menus and connect their slots and signals. - \li The \c TabletCanvas class inherits QWidget and - receives tablet events. It uses the events to paint on a - offscreen pixmap, which it draws onto itself. - \li The \c TabletApplication class inherits QApplication. This - class handles tablet events that are not sent to \c tabletEvent(). - We will look at this later. - \li The \c main() function creates a \c MainWindow and shows it - as a top level window. - \endlist - - - \section1 MainWindow Class Definition - - The \c MainWindow creates a \c TabletCanvas and sets it as its - center widget. - - \snippet widgets/tablet/mainwindow.h 0 - - The QActions let the user select if the tablets pressure and - tilt should change the pen width, color alpha component and color - saturation. \c createActions() creates all actions, and \c - createMenus() sets up the menus with the actions. We have one - QActionGroup for the actions that alter the alpha channel, color - saturation and line width respectively. The action groups are - connected to the \c alphaActionTriggered(), \c - colorSaturationActiontriggered(), and \c - lineWidthActionTriggered() slots, which calls functions in \c - myCanvas. - - - \section1 MainWindow Class Implementation - - We start width a look at the constructor \c MainWindow(): - - \snippet widgets/tablet/mainwindow.cpp 0 - - In the constructor we create the canvas, actions, and menus. - We set the canvas as the center widget. We also initialize the - canvas to match the state of our menus and start drawing with a - red color. - - Here is the implementation of \c brushColorAct(): - - \snippet widgets/tablet/mainwindow.cpp 1 - - We let the user pick a color with a QColorDialog. If it is valid, - we set a new drawing color with \c setColor(). - - Here is the implementation of \c alphaActionTriggered(): - - \snippet widgets/tablet/mainwindow.cpp 2 - - The \c TabletCanvas class supports two ways by which the alpha - channel of the drawing color can be changed: tablet pressure and - tilt. We have one action for each and an action if the alpha - channel should not be changed. - - Here is the implementation of \c lineWidthActionTriggered(): - - \snippet widgets/tablet/mainwindow.cpp 3 - - We check which action is selected in \c lineWidthGroup, and set - how the canvas should change the drawing line width. - - Here is the implementation of \c saturationActionTriggered(): - - \snippet widgets/tablet/mainwindow.cpp 4 - - We check which action is selected in \c colorSaturationGroup, and - set how the canvas should change the color saturation of the - drawing color. - - Here is the implementation of \c saveAct(): - - \snippet widgets/tablet/mainwindow.cpp 5 - - We use the QFileDialog to let the user select a file to save the - drawing in. It is the \c TabletCanvas that save the drawing, so we - call its \c saveImage() function. - - Here is the implementation of \c loadAct(): - - \snippet widgets/tablet/mainwindow.cpp 6 - - We let the user select the image file to be opened with - a QFileDialog; we then ask the canvas to load the image with \c - loadImage(). - - Here is the implementation of \c aboutAct(): - - \snippet widgets/tablet/mainwindow.cpp 7 - - We show a message box with a short description of the example. - - \c createActions() creates all actions and action groups of - the example. We look at the creation of one action group and its - actions. See the \l{Application Example}{application example} if - you want a high-level introduction to QActions. - - Here is the implementation of \c createActions: - - \snippet widgets/tablet/mainwindow.cpp 8 - \dots - \snippet widgets/tablet/mainwindow.cpp 9 - - We want the user to be able to choose if the drawing color's - alpha component should be changed by the tablet pressure or tilt. - We have one action for each choice and an action if the alpha - channel is not to be changed, i.e, the color is opaque. We make - the actions checkable; the \c alphaChannelGroup will then ensure - that only one of the actions are checked at any time. The \c - triggered() signal is emitted when an action is checked. - - \dots - \snippet widgets/tablet/mainwindow.cpp 10 - - Here is the implementation of \c createMenus(): - - \snippet widgets/tablet/mainwindow.cpp 11 - - We create the menus of the example and add the actions to them. - - - \section1 TabletCanvas Class Definition - - The \c TabletCanvas class provides a surface on which the - user can draw with a tablet. - - \snippet widgets/tablet/tabletcanvas.h 0 - - The canvas can change the alpha channel, color saturation, - and line width of the drawing. We have one enum for each of - these; their values decide if it is the tablet pressure or tilt - that will alter them. We keep a private variable for each, the \c - alphaChannelType, \c colorSturationType, and \c penWidthType, - which we provide access functions for. - - We draw on a QPixmap with \c myPen and \c myBrush using \c - myColor. The \c saveImage() and \c loadImage() saves and loads - the QPixmap to disk. The pixmap is drawn on the widget in \c - paintEvent(). The \c pointerType and \c deviceType keeps the type - of pointer, which is either a pen or an eraser, and device - currently used on the tablet, which is either a stylus or an - airbrush. - - The interpretation of events from the tablet is done in \c - tabletEvent(); \c paintPixmap(), \c updateBrush(), and \c - brushPattern() are helper functions used by \c tabletEvent(). - - - \section1 TabletCanvas Class Implementation - - We start with a look at the constructor: - - \snippet widgets/tablet/tabletcanvas.cpp 0 - - In the constructor we initialize our class variables. We need - to draw the background of our pixmap, as the default is gray. - - Here is the implementation of \c saveImage(): - - \snippet widgets/tablet/tabletcanvas.cpp 1 - - QPixmap implements functionality to save itself to disk, so we - simply call \l{QPixmap::}{save()}. - - Here is the implementation of \c loadImage(): - - \snippet widgets/tablet/tabletcanvas.cpp 2 - - We simply call \l{QPixmap::}{load()}, which loads the image in \a - file. - - Here is the implementation of \c tabletEvent(): - - \snippet widgets/tablet/tabletcanvas.cpp 3 - - We get three kind of events to this function: TabletPress, - TabletRelease, and TabletMove, which is generated when a device - is pressed down on, leaves, or moves on the tablet. We set the \c - deviceDown to true when a device is pressed down on the tablet; - we then know when we should draw when we receive move events. We - have implemented the \c updateBrush() and \c paintPixmap() helper - functions to update \c myBrush and \c myPen after the state of \c - alphaChannelType, \c colorSaturationType, and \c lineWidthType. - - Here is the implementation of \c paintEvent(): - - \snippet widgets/tablet/tabletcanvas.cpp 4 - - We simply draw the pixmap to the top left of the widget. - - Here is the implementation of \c paintPixmap(): - - \snippet widgets/tablet/tabletcanvas.cpp 5 - - In this function we draw on the pixmap based on the movement of the - device. If the device used on the tablet is a stylus we want to draw a - line between the positions of the stylus recorded in \c polyLine. We - also assume that this is a reasonable handling of any unknown device, - but update the statusbar with a warning so that the user can see that - for his tablet he might have to implement special handling. - If it is an airbrush we want to draw a circle of points with a - point density based on the tangential pressure, which is the position - of the finger wheel on the airbrush. We use the Qt::BrushStyle to - draw the points as it has styles that draw points with different - density; we select the style based on the tangential pressure in - \c brushPattern(). - - \snippet widgets/tablet/tabletcanvas.cpp 6 - - We return a brush style with a point density that increases with - the tangential pressure. - - In \c updateBrush() we set the pen and brush used for drawing - to match \c alphaChannelType, \c lineWidthType, \c - colorSaturationType, and \c myColor. We will examine the code to - set up \c myBrush and \c myPen for each of these variables: - - \snippet widgets/tablet/tabletcanvas.cpp 7 - - We fetch the current drawingcolor's hue, saturation, value, - and alpha values. \c hValue and \c vValue are set to the - horizontal and vertical tilt as a number from 0 to 255. The - original values are in degrees from -60 to 60, i.e., 0 equals - -60, 127 equals 0, and 255 equals 60 degrees. The angle measured - is between the device and the perpendicular of the tablet (see - QTabletEvent for an illustration). - - \snippet widgets/tablet/tabletcanvas.cpp 8 - - The alpha channel of QColor is given as a number between 0 - and 255 where 0 is transparent and 255 is opaque. - \l{QTabletEvent::}{pressure()} returns the pressure as a qreal - between 0.0 and 1.0. By subtracting 127 from the tilt values and - taking the absolute value we get the smallest alpha values (i.e., - the color is most transparent) when the pen is perpendicular to - the tablet. We select the largest of the vertical and horizontal - tilt value. - - \snippet widgets/tablet/tabletcanvas.cpp 9 - - The colorsaturation is given as a number between 0 and 255. It is - set with \l{QColor::}{setHsv()}. We can set the tilt values - directly, but must multiply the pressure to a number between 0 and - 255. - - \snippet widgets/tablet/tabletcanvas.cpp 10 - - The width of the pen increases with the pressure. When the pen - width is controlled with the tilt we let the width increse with - the angle between the device and the perpendicular of the tablet. - - \snippet widgets/tablet/tabletcanvas.cpp 11 - - We finally check whether the pointer is the stylus or the eraser. - If it is the eraser, we set the color to the background color of - the pixmap an let the pressure decide the pen width, else we set - the colors we have set up previously in the function. - - - \section1 TabletApplication Class Definition - - We inherit QApplication in this class because we want to - reimplement the \l{QApplication::}{event()} function. - - \snippet widgets/tablet/tabletapplication.h 0 - - We keep a \c TabletCanvas we send the device type of the events we - handle in the \c event() function to. The TabletEnterProximity - and TabletLeaveProximity events are not sendt to the QApplication - object, while other tablet events are sendt to the QWidget's - \c event(), which sends them on to \l{QWidget::}{tabletEvent()}. - Since we want to handle these events we have implemented \c - TabletApplication. - - - \section1 TabletApplication Class Implementation - - Here is the implementation of \c event(): - - \snippet widgets/tablet/tabletapplication.cpp 0 - - We use this function to handle the TabletEnterProximity and - TabletLeaveProximity events, which is generated when a device - enters and leaves the proximity of the tablet. The intended use of these - events is to do work that is dependent on what kind of device is - used on the tablet. This way, you don't have to do this work - when other events are generated, which is more frequently than the - leave and enter proximity events. We call \c setTabletDevice() in - \c TabletCanvas. - - \section1 The \c main() function - - Here is the examples \c main() function: - - \snippet widgets/tablet/main.cpp 0 - - In the \c main() function we create a \c MainWinow and display it - as a top level window. We use the \c TabletApplication class. We - need to set the canvas after the application is created. We cannot - use classes that implement event handling before an QApplication - object is instantiated. -*/ diff --git a/examples/widgets/doc/tetrix.qdoc b/examples/widgets/doc/tetrix.qdoc deleted file mode 100644 index 1a30845024..0000000000 --- a/examples/widgets/doc/tetrix.qdoc +++ /dev/null @@ -1,431 +0,0 @@ -/**************************************************************************** -** -** 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/tetrix - \title Tetrix Example - - The Tetrix example is a Qt version of the classic Tetrix game. - - \image tetrix-example.png - - The object of the game is to stack pieces dropped from the top of the - playing area so that they fill entire rows at the bottom of the playing area. - - When a row is filled, all the blocks on that row are removed, the player earns - a number of points, and the pieces above are moved down to occupy that row. - If more than one row is filled, the blocks on each row are removed, and the - player earns extra points. - - The \uicontrol{Left} cursor key moves the current piece one space to the left, the - \uicontrol{Right} cursor key moves it one space to the right, the \uicontrol{Up} cursor - key rotates the piece counter-clockwise by 90 degrees, and the \uicontrol{Down} - cursor key rotates the piece clockwise by 90 degrees. - - To avoid waiting for a piece to fall to the bottom of the board, press \uicontrol{D} - to immediately move the piece down by one row, or press the \uicontrol{Space} key to - drop it as close to the bottom of the board as possible. - - This example shows how a simple game can be created using only three classes: - - \list - \li The \c TetrixWindow class is used to display the player's score, number of - lives, and information about the next piece to appear. - \li The \c TetrixBoard class contains the game logic, handles keyboard input, and - displays the pieces on the playing area. - \li The \c TetrixPiece class contains information about each piece. - \endlist - - In this approach, the \c TetrixBoard class is the most complex class, since it - handles the game logic and rendering. One benefit of this is that the - \c TetrixWindow and \c TetrixPiece classes are very simple and contain only a - minimum of code. - - \section1 TetrixWindow Class Definition - - The \c TetrixWindow class is used to display the game information and contains - the playing area: - - \snippet widgets/tetrix/tetrixwindow.h 0 - - We use private member variables for the board, various display widgets, and - buttons to allow the user to start a new game, pause the current game, and quit. - - Although the window inherits QWidget, the constructor does not provide an - argument to allow a parent widget to be specified. This is because the window - will always be used as a top-level widget. - - \section1 TetrixWindow Class Implementation - - The constructor sets up the user interface elements for the game: - - \snippet widgets/tetrix/tetrixwindow.cpp 0 - - We begin by constructing a \c TetrixBoard instance for the playing area and a - label that shows the next piece to be dropped into the playing area; the label - is initially empty. - - Three QLCDNumber objects are used to display the score, number of lives, and - lines removed. These initially show default values, and will be filled in - when a game begins: - - \snippet widgets/tetrix/tetrixwindow.cpp 1 - - Three buttons with shortcuts are constructed so that the user can start a - new game, pause the current game, and quit the application: - - \snippet widgets/tetrix/tetrixwindow.cpp 2 - \snippet widgets/tetrix/tetrixwindow.cpp 3 - - These buttons are configured so that they never receive the keyboard focus; - we want the keyboard focus to remain with the \c TetrixBoard instance so that - it receives all the keyboard events. Nonetheless, the buttons will still respond - to \uicontrol{Alt} key shortcuts. - - We connect \l{QAbstractButton::}{clicked()} signals from the \uicontrol{Start} - and \uicontrol{Pause} buttons to the board, and from the \uicontrol{Quit} button to the - application's \l{QApplication::}{quit()} slot. - - \snippet widgets/tetrix/tetrixwindow.cpp 4 - \snippet widgets/tetrix/tetrixwindow.cpp 5 - - Signals from the board are also connected to the LCD widgets for the purpose of - updating the score, number of lives, and lines removed from the playing area. - - We place the label, LCD widgets, and the board into a QGridLayout - along with some labels that we create with the \c createLabel() convenience - function: - - \snippet widgets/tetrix/tetrixwindow.cpp 6 - - Finally, we set the grid layout on the widget, give the window a title, and - resize it to an appropriate size. - - The \c createLabel() convenience function simply creates a new label on the - heap, gives it an appropriate alignment, and returns it to the caller: - - \snippet widgets/tetrix/tetrixwindow.cpp 7 - - Since each label will be used in the widget's layout, it will become a child - of the \c TetrixWindow widget and, as a result, it will be deleted when the - window is deleted. - - \section1 TetrixPiece Class Definition - - The \c TetrixPiece class holds information about a piece in the game's - playing area, including its shape, position, and the range of positions it can - occupy on the board: - - \snippet widgets/tetrix/tetrixpiece.h 0 - - Each shape contains four blocks, and these are defined by the \c coords private - member variable. Additionally, each piece has a high-level description that is - stored internally in the \c pieceShape variable. - - The constructor is written inline in the definition, and simply ensures that - each piece is initially created with no shape. The \c shape() function simply - returns the contents of the \c pieceShape variable, and the \c x() and \c y() - functions return the x and y-coordinates of any given block in the shape. - - \section1 TetrixPiece Class Implementation - - The \c setRandomShape() function is used to select a random shape for a piece: - - \snippet widgets/tetrix/tetrixpiece.cpp 0 - - For convenience, it simply chooses a random shape from the \c TetrixShape enum - and calls the \c setShape() function to perform the task of positioning the - blocks. - - The \c setShape() function uses a look-up table of pieces to associate each - shape with an array of block positions: - - \snippet widgets/tetrix/tetrixpiece.cpp 1 - \snippet widgets/tetrix/tetrixpiece.cpp 2 - - These positions are read from the table into the piece's own array of positions, - and the piece's internal shape information is updated to use the new shape. - - The \c x() and \c y() functions are implemented inline in the class definition, - returning positions defined on a grid that extends horizontally and vertically - with coordinates from -2 to 2. Although the predefined coordinates for each - piece only vary horizontally from -1 to 1 and vertically from -1 to 2, each - piece can be rotated by 90, 180, and 270 degrees. - - The \c minX() and \c maxX() functions return the minimum and maximum horizontal - coordinates occupied by the blocks that make up the piece: - - \snippet widgets/tetrix/tetrixpiece.cpp 3 - \snippet widgets/tetrix/tetrixpiece.cpp 4 - - Similarly, the \c minY() and \c maxY() functions return the minimum and maximum - vertical coordinates occupied by the blocks: - - \snippet widgets/tetrix/tetrixpiece.cpp 5 - \snippet widgets/tetrix/tetrixpiece.cpp 6 - - The \c rotatedLeft() function returns a new piece with the same shape as an - existing piece, but rotated counter-clockwise by 90 degrees: - - \snippet widgets/tetrix/tetrixpiece.cpp 7 - - Similarly, the \c rotatedRight() function returns a new piece with the same - shape as an existing piece, but rotated clockwise by 90 degrees: - - \snippet widgets/tetrix/tetrixpiece.cpp 9 - - These last two functions enable each piece to create rotated copies of itself. - - \section1 TetrixBoard Class Definition - - The \c TetrixBoard class inherits from QFrame and contains the game logic and display features: - - \snippet widgets/tetrix/tetrixboard.h 0 - - Apart from the \c setNextPieceLabel() function and the \c start() and \c pause() - public slots, we only provide public functions to reimplement QWidget::sizeHint() - and QWidget::minimumSizeHint(). The signals are used to communicate changes to - the player's information to the \c TetrixWindow instance. - - The rest of the functionality is provided by reimplementations of protected event - handlers and private functions: - - \snippet widgets/tetrix/tetrixboard.h 1 - - The board is composed of a fixed-size array whose elements correspond to - spaces for individual blocks. Each element in the array contains a \c TetrixShape - value corresponding to the type of shape that occupies that element. - - Each shape on the board will occupy four elements in the array, and these will - all contain the enum value that corresponds to the type of the shape. - - We use a QBasicTimer to control the rate at which pieces fall toward the bottom - of the playing area. This allows us to provide an implementation of - \l{QObject::}{timerEvent()} that we can use to update the widget. - - \section1 TetrixBoard Class Implementation - - In the constructor, we customize the frame style of the widget, ensure that - keyboard input will be received by the widget by using Qt::StrongFocus for the - focus policy, and initialize the game state: - - \snippet widgets/tetrix/tetrixboard.cpp 0 - - The first (next) piece is also set up with a random shape. - - The \c setNextPieceLabel() function is used to pass in an externally-constructed - label to the board, so that it can be shown alongside the playing area: - - \snippet widgets/tetrix/tetrixboard.cpp 1 - - We provide a reasonable size hint and minimum size hint for the board, based on - the size of the space for each block in the playing area: - - \snippet widgets/tetrix/tetrixboard.cpp 2 - \snippet widgets/tetrix/tetrixboard.cpp 3 - - By using a minimum size hint, we indicate to the layout in the parent widget - that the board should not shrink below a minimum size. - - A new game is started when the \c start() slot is called. This resets the - game's state, the player's score and level, and the contents of the board: - - \snippet widgets/tetrix/tetrixboard.cpp 4 - - We also emit signals to inform other components of these changes before creating - a new piece that is ready to be dropped into the playing area. We start the - timer that determines how often the piece drops down one row on the board. - - The \c pause() slot is used to temporarily stop the current game by stopping the - internal timer: - - \snippet widgets/tetrix/tetrixboard.cpp 5 - \snippet widgets/tetrix/tetrixboard.cpp 6 - - We perform checks to ensure that the game can only be paused if it is already - running and not already paused. - - The \c paintEvent() function is straightforward to implement. We begin by - calling the base class's implementation of \l{QWidget::}{paintEvent()} before - constructing a QPainter for use on the board: - - \snippet widgets/tetrix/tetrixboard.cpp 7 - - Since the board is a subclass of QFrame, we obtain a QRect that covers the area - \e inside the frame decoration before drawing our own content. - - If the game is paused, we want to hide the existing state of the board and - show some text. We achieve this by painting text onto the widget and returning - early from the function. The rest of the painting is performed after this point. - - The position of the top of the board is found by subtracting the total height - of each space on the board from the bottom of the frame's internal rectangle. - For each space on the board that is occupied by a piece, we call the - \c drawSquare() function to draw a block at that position. - - \snippet widgets/tetrix/tetrixboard.cpp 8 - \snippet widgets/tetrix/tetrixboard.cpp 9 - - Spaces that are not occupied by blocks are left blank. - - Unlike the existing pieces on the board, the current piece is drawn - block-by-block at its current position: - - \snippet widgets/tetrix/tetrixboard.cpp 10 - \snippet widgets/tetrix/tetrixboard.cpp 11 - \snippet widgets/tetrix/tetrixboard.cpp 12 - - The \c keyPressEvent() handler is called whenever the player presses a key while - the \c TetrixBoard widget has the keyboard focus. - - \snippet widgets/tetrix/tetrixboard.cpp 13 - - If there is no current game, the game is running but paused, or if there is no - current shape to control, we simply pass on the event to the base class. - - We check whether the event is about any of the keys that the player uses to - control the current piece and, if so, we call the relevant function to handle - the input: - - \snippet widgets/tetrix/tetrixboard.cpp 14 - - In the case where the player presses a key that we are not interested in, we - again pass on the event to the base class's implementation of - \l{QWidget::}{keyPressEvent()}. - - The \c timerEvent() handler is called every time the class's QBasicTimer - instance times out. We need to check that the event we receive corresponds to - our timer. If it does, we can update the board: - - \snippet widgets/tetrix/tetrixboard.cpp 15 - \snippet widgets/tetrix/tetrixboard.cpp 16 - \snippet widgets/tetrix/tetrixboard.cpp 17 - - If a row (or line) has just been filled, we create a new piece and reset the - timer; otherwise we move the current piece down by one row. We let the base - class handle other timer events that we receive. - - The \c clearBoard() function simply fills the board with the - \c TetrixShape::NoShape value: - - \snippet widgets/tetrix/tetrixboard.cpp 18 - - The \c dropDown() function moves the current piece down as far as possible on - the board, either until it is touching the bottom of the playing area or it is - stacked on top of another piece: - - \snippet widgets/tetrix/tetrixboard.cpp 19 - \snippet widgets/tetrix/tetrixboard.cpp 20 - - The number of rows the piece has dropped is recorded and passed to the - \c pieceDropped() function so that the player's score can be updated. - - The \c oneLineDown() function is used to move the current piece down by one row - (line), either when the user presses the \uicontrol{D} key or when the piece is - scheduled to move: - - \snippet widgets/tetrix/tetrixboard.cpp 21 - - If the piece cannot drop down by one line, we call the \c pieceDropped() function - with zero as the argument to indicate that it cannot fall any further, and that - the player should receive no extra points for the fall. - - The \c pieceDropped() function itself is responsible for awarding points to the - player for positioning the current piece, checking for full rows on the board - and, if no lines have been removed, creating a new piece to replace the current - one: - - \snippet widgets/tetrix/tetrixboard.cpp 22 - \snippet widgets/tetrix/tetrixboard.cpp 23 - - We call \c removeFullLines() each time a piece has been dropped. This scans - the board from bottom to top, looking for blank spaces on each row. - - \snippet widgets/tetrix/tetrixboard.cpp 24 - \snippet widgets/tetrix/tetrixboard.cpp 25 - \snippet widgets/tetrix/tetrixboard.cpp 26 - \snippet widgets/tetrix/tetrixboard.cpp 27 - - If a row contains no blank spaces, the rows above it are copied down by one row - to compress the stack of pieces, the top row on the board is cleared, and the - number of full lines found is incremented. - - \snippet widgets/tetrix/tetrixboard.cpp 28 - \snippet widgets/tetrix/tetrixboard.cpp 29 - - If some lines have been removed, the player's score and the total number of lines - removed are updated. The \c linesRemoved() and \c scoreChanged() signals are - emitted to send these new values to other widgets in the window. - - Additionally, we set the timer to elapse after half a second, set the - \c isWaitingAfterLine flag to indicate that lines have been removed, unset - the piece's shape to ensure that it is not drawn, and update the widget. - The next time that the \c timerEvent() handler is called, a new piece will be - created and the game will continue. - - The \c newPiece() function places the next available piece at the top of the - board, and creates a new piece with a random shape: - - \snippet widgets/tetrix/tetrixboard.cpp 30 - \snippet widgets/tetrix/tetrixboard.cpp 31 - - We place a new piece in the middle of the board at the top. The game is over if - the piece can't move, so we unset its shape to prevent it from being drawn, stop - the timer, and unset the \c isStarted flag. - - The \c showNextPiece() function updates the label that shows the next piece to - be dropped: - - \snippet widgets/tetrix/tetrixboard.cpp 32 - \snippet widgets/tetrix/tetrixboard.cpp 33 - - We draw the piece's component blocks onto a pixmap that is then set on the label. - - The \c tryMove() function is used to determine whether a piece can be positioned - at the specified coordinates: - - \snippet widgets/tetrix/tetrixboard.cpp 34 - - We examine the spaces on the board that the piece needs to occupy and, if they - are already occupied by other pieces, we return \c false to indicate that the - move has failed. - - \snippet widgets/tetrix/tetrixboard.cpp 35 - - If the piece could be placed on the board at the desired location, we update the - current piece and its position, update the widget, and return \c true to indicate - success. - - The \c drawSquare() function draws the blocks (normally squares) that make up - each piece using different colors for pieces with different shapes: - - \snippet widgets/tetrix/tetrixboard.cpp 36 - - We obtain the color to use from a look-up table that relates each shape to an - RGB value, and use the painter provided to draw the block at the specified - coordinates. -*/ diff --git a/examples/widgets/doc/textedit.qdoc b/examples/widgets/doc/textedit.qdoc deleted file mode 100644 index 1bb596eb6e..0000000000 --- a/examples/widgets/doc/textedit.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** 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 richtext/textedit - \title Text Edit - - The Text Edit example shows Qt's rich text editing facilities in action, - providing an example document for you to experiment with. - - \image textedit-demo.png -*/ diff --git a/examples/widgets/doc/tooltips.qdoc b/examples/widgets/doc/tooltips.qdoc deleted file mode 100644 index e06f080a93..0000000000 --- a/examples/widgets/doc/tooltips.qdoc +++ /dev/null @@ -1,394 +0,0 @@ -/**************************************************************************** -** -** 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/tooltips - \title Tool Tips Example - - The Tool Tips example shows how to provide static and dynamic tool - tips for an application's widgets. - - The simplest and most common way to set a widget's tool tip is by - calling its QWidget::setToolTip() function (static tool - tips). Then the tool tip is shown whenever the cursor points at - the widget. We show how to do this with our application's tool - buttons. But it is also possible to show different tool tips - depending on the cursor's position (dynamic tooltips). This - approach uses mouse tracking and event handling to determine what - widgets are located under the cursor at any point in time, and - displays their tool tips. The tool tips for the shape items in our - application are implemented using the latter approach. - - \image tooltips-example.png - - With the \c Tooltips application the user can create new shape - items with the provided tool buttons, and move the items around - using the mouse. Tooltips are provided whenever the cursor is - pointing to a shape item or one of the buttons. - - The Tooltips example consists of two classes: - - \list - \li \c ShapeItem is a custom widget representing one single shape item. - \li \c SortingBox inherits from QWidget and is the application's main - widget. - \endlist - - First we will review the \c SortingBox class, then we will take a - look at the \c ShapeItem class. - - \section1 SortingBox Class Definition - - \snippet widgets/tooltips/sortingbox.h 0 - - The \c SortingBox class inherits QWidget, and it is the Tooltips - application's main widget. We reimplement several of the event - handlers. - - The \c event() function provides tooltips, the \c resize() - function makes sure the application appears consistently when the - user resizes the main widget, and the \c paintEvent() function - displays the shape items within the \c SortingBox widget. The - mouse event handlers are reimplemented to make the user able to - move the items around. - - In addition we need three private slots to make the user able to - create new shape items. - - \snippet widgets/tooltips/sortingbox.h 1 - - We also create several private functions: We use the \c - initialItemPosition(), \c initialItemColor() and \c - createToolButton() functions when we are constructing the widget, - and we use the \c updateButtonGeometry() function whenever the - user is resizing the application's main widget. - - The \c itemAt() function determines if there is a shape item at a - particular position, and the \c moveItemTo() function moves an - item to a new position. We use the \c createShapeItem(), \c - randomItemPosition() and \c randomItemColor() functions to create - new shape items. - - \snippet widgets/tooltips/sortingbox.h 2 - - We keep all the shape items in a QList, and we keep three - QPainterPath objects holding the shapes of a circle, a square and - a triangle. We also need to have a pointer to an item when it is - moving, and we need to know its previous position. - - \section1 SortingBox Class Implementation - - \snippet widgets/tooltips/sortingbox.cpp 0 - - In the constructor, we first set the Qt::WA_StaticContents - attribute on the widget. This attribute indicates that the widget - contents are north-west aligned and static. On resize, such a - widget will receive paint events only for the newly visible part - of itself. - - \snippet widgets/tooltips/sortingbox.cpp 1 - - To be able to show the appropriate tooltips while the user is - moving the cursor around, we need to enable mouse tracking for the - widget. - - If mouse tracking is disabled (the default), the widget only - receives mouse move events when at least one mouse button is - pressed while the mouse is being moved. If mouse tracking is - enabled, the widget receives mouse move events even if no buttons - are pressed. - - \snippet widgets/tooltips/sortingbox.cpp 2 - - A widget's background role defines the brush from the widget's - palette that is used to render the background, and QPalette::Base - is typically white. - - \snippet widgets/tooltips/sortingbox.cpp 3 - - After creating the application's tool buttons using the private \c - createToolButton() function, we construct the shapes of a circle, - a square and a triangle using QPainterPath. - - The QPainterPath class provides a container for painting - operations, enabling graphical shapes to be constructed and - reused. The main advantage of painter paths over normal drawing - operations is that complex shapes only need to be created once, - but they can be drawn many times using only calls to - QPainter::drawPath(). - - \snippet widgets/tooltips/sortingbox.cpp 4 - - Then we set the window title, resize the widget to a suitable - size, and finally create three initial shape items using the - private \c createShapeItem(), \c initialItemPosition() and \c - initialItemColor() functions. - - \snippet widgets/tooltips/sortingbox.cpp 5 - - QWidget::event() is the main event handler and receives all the - widget's events. Normally, we recommend reimplementing one of the - specialized event handlers instead of this function. But here we - want to catch the QEvent::ToolTip events, and since these are - rather rare, there exists no specific event handler. For that - reason we reimplement the main event handler, and the first thing - we need to do is to determine the event's type: - - \snippet widgets/tooltips/sortingbox.cpp 6 - - If the type is QEvent::ToolTip, we cast the event to a QHelpEvent, - otherwise we propagate the event using the QWidget::event() - function. - - The QHelpEvent class provides an event that is used to request - helpful information about a particular point in a widget. - - For example, the QHelpEvent::pos() function returns the event's - position relative to the widget to which the event is dispatched. - Here we use this information to determine if the position of the - event is contained within the area of any of the shape items. If - it is, we display the shape item's tooltip at the position of the - event. If not, we hide the tooltip and explicitly ignore the event. - This makes sure that the calling code does not start any tooltip - specific modes as a result of the event. Note that the - QToolTip::showText() function needs the event's position in global - coordinates provided by QHelpEvent::globalPos(). - - \snippet widgets/tooltips/sortingbox.cpp 7 - - The \c resizeEvent() function is reimplemented to receive the - resize events dispatched to the widget. It makes sure that the - tool buttons keep their position relative to the main widget when - the widget is resized. We want the buttons to always be vertically - aligned in the application's bottom right corner, so each time the - main widget is resized we update the buttons geometry. - - \snippet widgets/tooltips/sortingbox.cpp 8 - - The \c paintEvent() function is reimplemented to receive paint - events for the widget. We create a QPainter for the \c SortingBox - widget, and run through the list of created shape items, drawing - each item at its defined position. - - \snippet widgets/tooltips/sortingbox.cpp 9 - - The painter will by default draw all the shape items at position - (0,0) in the \c SortingBox widget. The QPainter::translate() - function translates the coordinate system by the given offset, - making each shape item appear at its defined position. But - remember to translate the coordinate system back when the item is - drawn, otherwise the next shape item will appear at a position - relative to the item we drawed last. - - \snippet widgets/tooltips/sortingbox.cpp 10 - - The QPainter::setBrush() function sets the current brush used by - the painter. When the provided argument is a QColor, the function - calls the appropriate QBrush constructor which creates a brush with - the specified color and Qt::SolidPattern style. The - QPainter::drawPath() function draws the given path using the - current pen for outline and the current brush for filling. - - \snippet widgets/tooltips/sortingbox.cpp 11 - - The \c mousePressEvent() function is reimplemented to receive the - mouse press events dispatched to the widget. It determines if an - event's position is contained within the area of any of the shape - items, using the private \c itemAt() function. - - If an item covers the position, we store a pointer to that item - and the event's position. If several of the shape items cover the - position, we store the pointer to the uppermost item. Finally, we - move the shape item to the end of the list, and make a call to the - QWidget::update() function to make the item appear on top. - - The QWidget::update() function does not cause an immediate - repaint; instead it schedules a paint event for processing when Qt - returns to the main event loop. - - \snippet widgets/tooltips/sortingbox.cpp 12 - - The \c mouseMoveEvent() function is reimplemented to receive mouse - move events for the widget. If the left mouse button is pressed - and there exists a shape item in motion, we use the private \c - moveItemTo() function to move the item with an offset - corresponding to the offset between the positions of the current - mouse event and the previous one. - - \snippet widgets/tooltips/sortingbox.cpp 13 - - The \c mouseReleaseEvent() function is reimplemented to receive - the mouse release events dispatched to the widget. If the left - mouse button is pressed and there exists a shape item in motion, - we use the private \c moveItemTo() function to move the item like - we did in \c mouseMoveEvent(). But then we remove the pointer to - the item in motion, making the shape item's position final for - now. To move the item further, the user will need to press the - left mouse button again. - - \snippet widgets/tooltips/sortingbox.cpp 14 - \codeline - \snippet widgets/tooltips/sortingbox.cpp 15 - \codeline - \snippet widgets/tooltips/sortingbox.cpp 16 - - The \c createNewCircle(), \c createNewSquare() and \c - createNewTriangle() slots simply create new shape items, using the - private \c createShapeItem(), \c randomItemPosition() and \c - randomItemColor() functions. - - \snippet widgets/tooltips/sortingbox.cpp 17 - - In the \c itemAt() function, we run through the list of created - shape items to check if the given position is contained within the - area of any of the shape items. - - For each shape item we use the QPainterPath::contains() function - to find out if the item's painter path contains the position. If - it does we return the index of the item, otherwise we return - -1. We run through the list backwards to get the index of the - uppermost shape item in case several items cover the position. - - \snippet widgets/tooltips/sortingbox.cpp 18 - - The \c moveItemTo() function moves the shape item in motion, and - the parameter \c pos is the position of a mouse event. First we - calculate the offset between the parameter \c pos and the previous - mouse event position. Then we add the offset to the current - position of the item in motion. - - It is tempting to simply set the position of the item to be the - parameter \c pos. But an item's position defines the top left - corner of the item's bounding rectangle, and the parameter \c pos - can be any point; The suggested shortcut would cause the item to - jump to a position where the cursor is pointing to the bounding - rectangle's top left corner, regardless of the item's previous - position. - - \snippet widgets/tooltips/sortingbox.cpp 19 - - Finally, we update the previous mouse event position, and make a - call to the QWidget::update() function to make the item appear at - its new position. - - \snippet widgets/tooltips/sortingbox.cpp 20 - - In the \c updateButtonGeometry() function we set the geometry for - the given button. The parameter coordinates define the bottom - right corner of the button. We use these coordinates and the - button's size hint to determine the position of the upper left - corner. This position, and the button's width and height, are the - arguments required by the QWidget::setGeometry() function. - - In the end, we calculate and return the y-coordinate of the bottom - right corner of the next button. We use the QWidget::style() - function to retrieve the widget's GUI style, and then - QStyle::pixelMetric() to determine the widget's preferred default - spacing between its child widgets. - - \snippet widgets/tooltips/sortingbox.cpp 21 - - The \c createShapeItem() function creates a single shape item. It - sets the path, tooltip, position and color, using the item's own - functions. In the end, the function appends the new item to the - list of shape items, and calls the QWidget::update() function to - make it appear with the other items within the \c SortingBox - widget. - - \snippet widgets/tooltips/sortingbox.cpp 22 - - The \c createToolButton() function is called from the \c - SortingBox constructor. We create a tool button with the given - tooltip and icon. The button's parent is the \c SortingBox widget, - and its size is 32 x 32 pixels. Before we return the button, we - connect it to the given slot. - - \snippet widgets/tooltips/sortingbox.cpp 23 - - The \c initialItemPosition() function is also called from the - constructor. We want the three first items to initially be - centered in the middle of the \c SortingBox widget, and we use - this function to calculate their positions. - - \snippet widgets/tooltips/sortingbox.cpp 24 - - Whenever the user creates a new shape item, we want the new item - to appear at a random position, and we use the \c - randomItemPosition() function to calculate such a position. We - make sure that the item appears within the visible area of the - \c SortingBox widget, using the widget's current width and height - when calculating the random coordinates. - - \snippet widgets/tooltips/sortingbox.cpp 25 - - As with \c initialItemPosition(), the \c initialItemColor() - function is called from the constructor. The purposes of both - functions are purely cosmetic: We want to control the initial - position and color of the three first items. - - \snippet widgets/tooltips/sortingbox.cpp 26 - - Finally the \c randomItemColor() function is implemented to give - the shape items the user creates, a random color. - - \section1 ShapeItem Class Definition - - \snippet widgets/tooltips/shapeitem.h 0 - - The \c ShapeItem class is a custom widget representing one single - shape item. The widget has a path, a position, a color and a - tooltip. We need functions to set or modify these objects, as well - as functions that return them. We make the latter functions \c - const to prohibit any modifications of the objects, - i.e. prohibiting unauthorized manipulation of the shape items - appearance. - - \section1 ShapeItem Class Implementation - - \snippet widgets/tooltips/shapeitem.cpp 0 - \codeline - \snippet widgets/tooltips/shapeitem.cpp 1 - \codeline - \snippet widgets/tooltips/shapeitem.cpp 2 - \codeline - \snippet widgets/tooltips/shapeitem.cpp 3 - - This first group of functions simply return the objects that are - requested. The objects are returned as constants, i.e. they cannot - be modified. - - \snippet widgets/tooltips/shapeitem.cpp 4 - \codeline - \snippet widgets/tooltips/shapeitem.cpp 5 - \codeline - \snippet widgets/tooltips/shapeitem.cpp 6 - \codeline - \snippet widgets/tooltips/shapeitem.cpp 7 - - The last group of functions set or modify the shape item's path, - position, color and tooltip, respectively. -*/ diff --git a/examples/widgets/doc/trafficlight.qdoc b/examples/widgets/doc/trafficlight.qdoc deleted file mode 100644 index ec3578abaa..0000000000 --- a/examples/widgets/doc/trafficlight.qdoc +++ /dev/null @@ -1,85 +0,0 @@ -/**************************************************************************** -** -** 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 statemachine/trafficlight - \title Traffic Light Example - - The Traffic Light example shows how to use \l{The State Machine Framework} - to implement the control flow of a traffic light. - - \image trafficlight-example.png - - In this example we write a TrafficLightWidget class. The traffic light has - three lights: Red, yellow and green. The traffic light transitions from - one light to another (red to yellow to green to yellow to red again) at - certain intervals. - - \snippet statemachine/trafficlight/main.cpp 0 - - The LightWidget class represents a single light of the traffic light. It - provides an \c on property and two slots, turnOn() and turnOff(), to turn - the light on and off, respectively. The widget paints itself in the color - that's passed to the constructor. - - \snippet statemachine/trafficlight/main.cpp 1 - - The TrafficLightWidget class represents the visual part of the traffic - light; it's a widget that contains three lights arranged vertically, and - provides accessor functions for these. - - \snippet statemachine/trafficlight/main.cpp 2 - - The createLightState() function creates a state that turns a light on when - the state is entered, and off when the state is exited. The state uses a - timer, and as we shall see the timeout is used to transition from one - LightState to another. Here is the statechart for the light state: - - \image trafficlight-example1.png - \omit - \caption This is a caption - \endomit - - \snippet statemachine/trafficlight/main.cpp 3 - - The TrafficLight class combines the TrafficLightWidget with a state - machine. The state graph has four states: red-to-yellow, yellow-to-green, - green-to-yellow and yellow-to-red. The initial state is red-to-yellow; - when the state's timer times out, the state machine transitions to - yellow-to-green. The same process repeats through the other states. - This is what the statechart looks like: - - \image trafficlight-example2.png - \omit - \caption This is a caption - \endomit - - \snippet statemachine/trafficlight/main.cpp 4 - - The main() function constructs a TrafficLight and shows it. - -*/ diff --git a/examples/widgets/doc/transformations.qdoc b/examples/widgets/doc/transformations.qdoc deleted file mode 100644 index 79681a2799..0000000000 --- a/examples/widgets/doc/transformations.qdoc +++ /dev/null @@ -1,371 +0,0 @@ -/**************************************************************************** -** -** 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 painting/transformations - \title Transformations Example - - The Transformations example shows how transformations influence - the way that QPainter renders graphics primitives. In particular - it shows how the order of transformations affect the result. - - \image transformations-example.png - - The application allows the user to manipulate the rendering of a - shape by changing the translation, rotation and scale of - QPainter's coordinate system. - - The example consists of two classes and a global enum: - - \list - \li The \c RenderArea class controls the rendering of a given shape. - \li The \c Window class is the application's main window. - \li The \c Operation enum describes the various transformation - operations available in the application. - \endlist - - First we will take a quick look at the \c Operation enum, then we - will review the \c RenderArea class to see how a shape is - rendered. Finally, we will take a look at the Transformations - application's features implemented in the \c Window class. - - \section1 Transformation Operations - - Normally, the QPainter operates on the associated device's own - coordinate system, but it also has good support for coordinate - transformations. - - The default coordinate system of a paint device has its origin at - the top-left corner. The x values increase to the right and the y - values increase downwards. You can scale the coordinate system by - a given offset using the QPainter::scale() function, you can - rotate it clockwise using the QPainter::rotate() function and you - can translate it (i.e. adding a given offset to the points) using - the QPainter::translate() function. You can also twist the - coordinate system around the origin (called shearing) using the - QPainter::shear() function. - - All the tranformation operations operate on QPainter's - tranformation matrix that you can retrieve using the - QPainter::worldTransform() function. A matrix transforms a point in the - plane to another point. For more information about the - transformation matrix, see the \l {Coordinate System} and - QTransform documentation. - - \snippet painting/transformations/renderarea.h 0 - - The global \c Operation enum is declared in the \c renderarea.h - file and describes the various transformation operations available - in the Transformations application. - - \section1 RenderArea Class Definition - - The \c RenderArea class inherits QWidget, and controls the - rendering of a given shape. - - \snippet painting/transformations/renderarea.h 1 - - We declare two public functions, \c setOperations() and - \c setShape(), to be able to specify the \c RenderArea widget's shape - and to transform the coordinate system the shape is rendered - within. - - We reimplement the QWidget's \l - {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l - {QWidget::sizeHint()}{sizeHint()} functions to give the \c - RenderArea widget a reasonable size within our application, and we - reimplement the QWidget::paintEvent() event handler to draw the - render area's shape applying the user's transformation choices. - - \snippet painting/transformations/renderarea.h 2 - - We also declare several convenience functions to draw the shape, - the coordinate system's outline and the coordinates, and to - transform the painter according to the chosen transformations. - - In addition, the \c RenderArea widget keeps a list of the - currently applied transformation operations, a reference to its - shape, and a couple of convenience variables that we will use when - rendering the coordinates. - - \section1 RenderArea Class Implementation - - The \c RenderArea widget controls the rendering of a given shape, - including the transformations of the coordinate system, by - reimplementing the QWidget::paintEvent() event handler. But first - we will take a quick look at the constructor and at the functions - that provides access to the \c RenderArea widget: - - \snippet painting/transformations/renderarea.cpp 0 - - In the constructor we pass the parent parameter on to the base - class, and customize the font that we will use to render the - coordinates. The QWidget::font() function returns the font - currently set for the widget. As long as no special font has been - set, or after QWidget::setFont() is called, this is either a - special font for the widget class, the parent's font or (if this - widget is a top level widget) the default application font. - - After ensuring that the font's size is 12 points, we extract the - rectangles enclosing the coordinate letters, 'x' and 'y', using the - QFontMetrics class. - - QFontMetrics provides functions to access the individual metrics - of the font, its characters, and for strings rendered in the - font. The QFontMetrics::boundingRect() function returns the - bounding rectangle of the given character relative to the - left-most point on the base line. - - \snippet painting/transformations/renderarea.cpp 1 - \codeline - \snippet painting/transformations/renderarea.cpp 2 - - In the \c setShape() and \c setOperations() functions we update - the \c RenderArea widget by storing the new value or values - followed by a call to the QWidget::update() slot which schedules a - paint event for processing when Qt returns to the main event loop. - - \snippet painting/transformations/renderarea.cpp 3 - \codeline - \snippet painting/transformations/renderarea.cpp 4 - - We reimplement the QWidget's \l - {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l - {QWidget::sizeHint()}{sizeHint()} functions to give the \c - RenderArea widget a reasonable size within our application. The - default implementations of these functions returns an invalid size - if there is no layout for this widget, and returns the layout's - minimum size or preferred size, respectively, otherwise. - - \snippet painting/transformations/renderarea.cpp 5 - - The \c paintEvent() event handler receives the \c RenderArea - widget's paint events. A paint event is a request to repaint all - or part of the widget. It can happen as a result of - QWidget::repaint() or QWidget::update(), or because the widget was - obscured and has now been uncovered, or for many other reasons. - - First we create a QPainter for the \c RenderArea widget. The \l - {QPainter::RenderHint}{QPainter::Antialiasing} render hint - indicates that the engine should antialias edges of primitives if - possible. Then we erase the area that needs to be repainted using - the QPainter::fillRect() function. - - We also translate the coordinate system with an constant offset to - ensure that the original shape is renderend with a suitable - margin. - - \snippet painting/transformations/renderarea.cpp 6 - - Before we start to render the shape, we call the QPainter::save() - function. - - QPainter::save() saves the current painter state (i.e. pushes the - state onto a stack) including the current coordinate system. The - rationale for saving the painter state is that the following call - to the \c transformPainter() function will transform the - coordinate system depending on the currently chosen transformation - operations, and we need a way to get back to the original state to - draw the outline. - - After transforming the coordinate system, we draw the \c - RenderArea's shape, and then we restore the painter state using - the QPainter::restore() function (i.e. popping the saved state off - the stack). - - \snippet painting/transformations/renderarea.cpp 7 - - Then we draw the square outline. - - \snippet painting/transformations/renderarea.cpp 8 - - Since we want the coordinates to correspond with the coordinate - system the shape is rendered within, we must make another call to - the \c transformPainter() function. - - The order of the painting operations is essential with respect to - the shared pixels. The reason why we don't render the coordinates - when the coordinate system already is transformed to render the - shape, but instead defer their rendering to the end, is that we - want the coordinates to appear on top of the shape and its - outline. - - There is no need to save the QPainter state this time since - drawing the coordinates is the last painting operation. - - \snippet painting/transformations/renderarea.cpp 9 - \codeline - \snippet painting/transformations/renderarea.cpp 10 - \codeline - \snippet painting/transformations/renderarea.cpp 11 - - The \c drawCoordinates(), \c drawOutline() and \c drawShape() are - convenience functions called from the \c paintEvent() event - handler. For more information about QPainter's basic drawing - operations and how to display basic graphics primitives, see the - \l {painting/basicdrawing}{Basic Drawing} example. - - \snippet painting/transformations/renderarea.cpp 12 - - The \c transformPainter() convenience function is also called from - the \c paintEvent() event handler, and transforms the given - QPainter's coordinate system according to the user's - transformation choices. - - \section1 Window Class Definition - - The \c Window class is the Transformations application's main - window. - - The application displays four \c RenderArea widgets. The left-most - widget renders the shape in QPainter's default coordinate system, - the others render the shape with the chosen transformation in - addition to all the transformations applied to the \c RenderArea - widgets to their left. - - \snippet painting/transformations/window.h 0 - - We declare two public slots to make the application able to - respond to user interaction, updating the displayed \c RenderArea - widgets according to the user's transformation choices. - - The \c operationChanged() slot updates each of the \c RenderArea - widgets applying the currently chosen transformation operations, and - is called whenever the user changes the selected operations. The - \c shapeSelected() slot updates the \c RenderArea widgets' shapes - whenever the user changes the preferred shape. - - \snippet painting/transformations/window.h 1 - - We also declare a private convenience function, \c setupShapes(), - that is used when constructing the \c Window widget, and we - declare pointers to the various components of the widget. We - choose to keep the available shapes in a QList of \l - {QPainterPath}s. In addition we declare a private enum counting - the number of displayed \c RenderArea widgets except the widget - that renders the shape in QPainter's default coordinate system. - - \section1 Window Class Implementation - - In the constructor we create and initialize the application's - components: - - \snippet painting/transformations/window.cpp 0 - - First we create the \c RenderArea widget that will render the - shape in the default coordinate system. We also create the - associated QComboBox that allows the user to choose among four - different shapes: A clock, a house, a text and a truck. The shapes - themselves are created at the end of the constructor, using the - \c setupShapes() convenience function. - - \snippet painting/transformations/window.cpp 1 - - Then we create the \c RenderArea widgets that will render their - shapes with coordinate tranformations. By default the applied - operation is \uicontrol {No Transformation}, i.e. the shapes are - rendered within the default coordinate system. We create and - initialize the associated \l {QComboBox}es with items - corresponding to the various transformation operations decribed by - the global \c Operation enum. - - We also connect the \l {QComboBox}es' \l - {QComboBox::activated()}{activated()} signal to the \c - operationChanged() slot to update the application whenever the - user changes the selected transformation operations. - - \snippet painting/transformations/window.cpp 2 - - Finally, we set the layout for the application window using the - QWidget::setLayout() function, construct the available shapes - using the private \c setupShapes() convenience function, and make - the application show the clock shape on startup using the public - \c shapeSelected() slot before we set the window title. - - - \snippet painting/transformations/window.cpp 3 - \snippet painting/transformations/window.cpp 4 - \snippet painting/transformations/window.cpp 5 - \snippet painting/transformations/window.cpp 6 - \dots - - \snippet painting/transformations/window.cpp 7 - - The \c setupShapes() function is called from the constructor and - create the QPainterPath objects representing the shapes that are - used in the application. For construction details, see the \l - {painting/transformations/window.cpp}{window.cpp} example - file. The shapes are stored in a QList. The QList::append() - function inserts the given shape at the end of the list. - - We also connect the associated QComboBox's \l - {QComboBox::activated()}{activated()} signal to the \c - shapeSelected() slot to update the application when the user - changes the preferred shape. - - \snippet painting/transformations/window.cpp 8 - - The public \c operationChanged() slot is called whenever the user - changes the selected operations. - - We retrieve the chosen transformation operation for each of the - transformed \c RenderArea widgets by querying the associated \l - {QComboBox}{QComboBoxes}. The transformed \c RenderArea widgets - are supposed to render the shape with the transformation specified - by its associated combobox \e {in addition to} all the - transformations applied to the \c RenderArea widgets to its - left. For that reason, for each widget we query, we append the - associated operation to a QList of transformations which we apply - to the widget before proceeding to the next. - - \snippet painting/transformations/window.cpp 9 - - The \c shapeSelected() slot is called whenever the user changes - the preferred shape, updating the \c RenderArea widgets using - their public \c setShape() function. - - \section1 Summary - - The Transformations example shows how transformations influence - the way that QPainter renders graphics primitives. Normally, the - QPainter operates on the device's own coordinate system, but it - also has good support for coordinate transformations. With the - Transformations application you can scale, rotate and translate - QPainter's coordinate system. The order in which these - tranformations are applied is essential for the result. - - All the tranformation operations operate on QPainter's - tranformation matrix. For more information about the - transformation matrix, see the \l {Coordinate System} and - QTransform documentation. - - The Qt reference documentation provides several painting - examples. Among these is the \l {painting/affine}{Affine - Transformations} example that shows Qt's ability to perform - transformations on painting operations. The example also allows the - user to experiment with the various transformation operations. -*/ diff --git a/examples/widgets/doc/trivialwizard.qdoc b/examples/widgets/doc/trivialwizard.qdoc deleted file mode 100644 index e27f9cadc2..0000000000 --- a/examples/widgets/doc/trivialwizard.qdoc +++ /dev/null @@ -1,82 +0,0 @@ -/**************************************************************************** -** -** 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 dialogs/trivialwizard - \title Trivial Wizard Example - - The Trivial Wizard example illustrates how to create a linear three-page - registration wizard using three instances of QWizardPage and one instance - of QWizard. - - \image trivialwizard-example-flow.png - - \section1 Introduction Page - - \image trivialwizard-example-introduction.png - - The introduction page is created with the \c createIntroPage() - function where a QWizardPage is created and its title is set to - "Introduction". A QLabel is used to hold the description of \c page. - A QVBoxLayout is used to hold the \c label. This \c page is returned - when the \c createIntroPage() function is called. - - \snippet dialogs/trivialwizard/trivialwizard.cpp 0 - - \section1 Registration Page - - \image trivialwizard-example-registration.png - - The registration page is created with the \c createRegistrationPage() - function. QLineEdit objects are used to allow the user to input a name - and an e-mail address. A QGridLayout is used to hold the QLabel and - QLineEdit objects. - - \snippet dialogs/trivialwizard/trivialwizard.cpp 2 - - \section1 Conclusion Page - - \image trivialwizard-example-conclusion.png - - The conclusion page is created in the \c createConclusionPage() - function. This function's content is similar to \c createIntroPage(). A - QLabel is used to inform the user that the registration process has - completed successfully. - - \snippet dialogs/trivialwizard/trivialwizard.cpp 6 - - \section1 \c main() Function - - The \c main() function instantiates a QWizard object, \c wizard, and - adds all three QWizardPage objects to it. The \c wizard window title is - set to "Trivial Wizard" and its \c show() function is invoked to display - it. - - \snippet dialogs/trivialwizard/trivialwizard.cpp 10 - - \sa QWizard, {Class Wizard Example}, {License Wizard Example} -*/ diff --git a/examples/widgets/doc/twowaybutton.qdoc b/examples/widgets/doc/twowaybutton.qdoc deleted file mode 100644 index 40f8c6f1f3..0000000000 --- a/examples/widgets/doc/twowaybutton.qdoc +++ /dev/null @@ -1,68 +0,0 @@ -/**************************************************************************** -** -** 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 statemachine/twowaybutton - \title Two-way Button Example - - The Two-way button example shows how to use \l{The State Machine - Framework} to implement a simple state machine that toggles the current - state when a button is clicked. - - \snippet statemachine/twowaybutton/main.cpp 0 - - The application's main() function begins by constructing the application - object, a button and a state machine. - - \snippet statemachine/twowaybutton/main.cpp 1 - - The state machine has two states; \c on and \c off. When either state is - entered, the text of the button will be set accordingly. - - \snippet statemachine/twowaybutton/main.cpp 2 - - When the state machine is in the \c off state and the button is clicked, - it will transition to the \c on state; when the state machine is in the \c - on state and the button is clicked, it will transition to the \c off - state. - - \snippet statemachine/twowaybutton/main.cpp 3 - - The states are added to the state machine; they become top-level (sibling) - states. - - \snippet statemachine/twowaybutton/main.cpp 4 - - The initial state is \c off; this is the state the state machine will - immediately transition to once the state machine is started. - - \snippet statemachine/twowaybutton/main.cpp 5 - - Finally, the button is resized and made visible, and the application event - loop is entered. - -*/ diff --git a/examples/widgets/doc/wiggly.qdoc b/examples/widgets/doc/wiggly.qdoc deleted file mode 100644 index e84ab00e61..0000000000 --- a/examples/widgets/doc/wiggly.qdoc +++ /dev/null @@ -1,167 +0,0 @@ -/**************************************************************************** -** -** 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/wiggly - \title Wiggly Example - - The Wiggly example shows how to animate a widget using - QBasicTimer and \l{QObject::timerEvent()}{timerEvent()}. In - addition, the example demonstrates how to use QFontMetrics to - determine the size of text on screen. - - \image wiggly-example.png Screenshot of the Wiggly example - - QBasicTimer is a low-level class for timers. Unlike QTimer, - QBasicTimer doesn't inherit from QObject; instead of emitting a - \l{QTimer::timeout()}{timeout()} signal when a certain amount of - time has passed, it sends a QTimerEvent to a QObject of our - choice. This makes QBasicTimer a more lightweight alternative to - QTimer. Qt's built-in widgets use it internally, and it is - provided in Qt's API for highly-optimized applications (e.g., - \l{Qt for Embedded Linux} applications). - - The example consists of two classes: - - \list - \li \c WigglyWidget is the custom widget displaying the text - in a wiggly line. - - \li \c Dialog is the dialog widget allowing the user to enter a - text. It combines a \c WigglyWidget and a \c QLineEdit. - \endlist - - We will first take a quick look at the \c Dialog class, then we - will review the \c WigglyWidget class. - - \section1 Dialog Class Definition - - \snippet widgets/wiggly/dialog.h 0 - - The \c Dialog class provides a dialog widget that allows the user - to enter a text. The text is then rendered by \c WigglyWidget. - - \section1 Dialog Class Implementation - - \snippet widgets/wiggly/dialog.cpp 0 - - In the constructor we create a wiggly widget along with a - \l{QLineEdit}{line edit}, and we put the two widgets in a - vertical layout. We connect the line edit's \l - {QLineEdit::textChanged()}{textChanged()} signal to the wiggly - widget's \c setText() slot to obtain the real time interaction - with the wiggly widget. The widget's default text is "Hello - world!". - - \section1 WigglyWidget Class Definition - - \snippet widgets/wiggly/wigglywidget.h 0 - - The \c WigglyWidget class provides the wiggly line displaying the - text. We subclass QWidget and reimplement the standard \l - {QWidget::paintEvent()}{paintEvent()} and \l - {QObject::timerEvent()}{timerEvent()} functions to draw and update - the widget. In addition we implement a public \c setText() slot - that sets the widget's text. - - The \c timer variable, of type QBasicTimer, is used to update the - widget at regular intervals, making the widget move. The \c text - variable is used to store the currently displayed text, and \c - step to calculate position and color for each character on the - wiggly line. - - \section1 WigglyWidget Class Implementation - - \snippet widgets/wiggly/wigglywidget.cpp 0 - - In the constructor, we make the widget's background slightly - lighter than the usual background using the QPalette::Midlight - color role. The background role defines the brush from the - widget's palette that Qt uses to paint the background. Then we - enlarge the widget's font with 20 points. - - Finally we start the timer; the call to QBasicTimer::start() - makes sure that \e this particular wiggly widget will receive the - timer events generated when the timer times out (every 60 - milliseconds). - - \snippet widgets/wiggly/wigglywidget.cpp 1 - \snippet widgets/wiggly/wigglywidget.cpp 2 - - The \c paintEvent() function is called whenever a QPaintEvent is - sent to the widget. Paint events are sent to widgets that need to - update themselves, for instance when part of a widget is exposed - because a covering widget was moved. For the wiggly widget, a - paint event will also be generated every 60 milliseconds from - the \c timerEvent() slot. - - The \c sineTable represents y-values of the sine curve, - multiplied by 100. It is used to make the wiggly widget move - along the sine curve. - - The QFontMetrics object provides information about the widget's - font. The \c x variable is the horizontal position where we start - drawing the text. The \c y variable is the vertical position of - the text's base line. Both variables are computed so that the - text is horizontally and vertically centered. To compute the base - line, we take into account the font's ascent (the height of the - font above the base line) and font's descent (the height of the - font below the base line). If the descent equals the ascent, they - cancel out each other and the base line is at \c height() / 2. - - \snippet widgets/wiggly/wigglywidget.cpp 3 - \snippet widgets/wiggly/wigglywidget.cpp 4 - - Each time the \c paintEvent() function is called, we create a - QPainter object \c painter to draw the contents of the widget. - For each character in \c text, we determine the color and the - position on the wiggly line based on \c step. In addition, \c x - is incremented by the character's width. - - For simplicity, we assume that QFontMetrics::width(\c text) - returns the sum of the individual character widths - (QFontMetrics::width(\c text[i])). In practice, this is not - always the case because QFontMetrics::width(\c text) also takes - into account the kerning between certain letters (e.g., 'A' and - 'V'). The result is that the text isn't perfectly centered. You - can verify this by typing "AVAVAVAVAVAV" in the line edit. - - \snippet widgets/wiggly/wigglywidget.cpp 5 - \snippet widgets/wiggly/wigglywidget.cpp 6 - - The \c timerEvent() function receives all the timer events that - are generated for this widget. If a timer event is sent from the - widget's QBasicTimer, we increment \c step to make the text move, - and call QWidget::update() to refresh the display. Any other - timer event is passed on to the base class's implementation of - the \l{QWidget::timerEvent()}{timerEvent()} function. - - The QWidget::update() slot does not cause an immediate repaint; - instead the slot schedules a paint event for processing when Qt - returns to the main event loop. The paint events are then handled - by \c{WigglyWidget}'s \c paintEvent() function. -*/ diff --git a/examples/widgets/doc/windowflags.qdoc b/examples/widgets/doc/windowflags.qdoc deleted file mode 100644 index e85842b30a..0000000000 --- a/examples/widgets/doc/windowflags.qdoc +++ /dev/null @@ -1,216 +0,0 @@ -/**************************************************************************** -** -** 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/windowflags - \title Window Flags Example - - The Window Flags example shows how to use the window flags - available in Qt. - - A window flag is either a type or a hint. A type is used to - specify various window-system properties for the widget. A widget - can only have one type, and the default is Qt::Widget. However, a - widget can have zero or more hints. The hints are used to - customize the appearance of top-level windows. - - A widget's flags are stored in a Qt::WindowFlags type which stores - an OR combination of the flags. - - \image windowflags-example.png Screenshot of the Window Flags example - - The example consists of two classes: - - \list - \li \c ControllerWindow is the main application widget that allows - the user to choose among the available window flags, and displays - the effect on a separate preview window. - \li \c PreviewWindow is a custom widget displaying the name of - its currently set window flags in a read-only text editor. - \endlist - - We will start by reviewing the \c ControllerWindow class, then we - will take a look at the \c PreviewWindow class. - - \section1 ControllerWindow Class Definition - - \snippet widgets/windowflags/controllerwindow.h 0 - - The \c ControllerWindow class inherits QWidget. The widget allows - the user to choose among the available window flags, and displays - the effect on a separate preview window. - - We declare a private \c updatePreview() slot to refresh the - preview window whenever the user changes the window flags. - - We also declare several private functions to simplify the - constructor: We call the \c createTypeGroupBox() function to - create a radio button for each available window type, using the - private \c createButton() function, and gather them within a group - box. In a similar way we use the \c createHintsGroupBox() function - to create a check box for each available hint, using the private - \c createCheckBox() function. - - In addition to the various radio buttons and checkboxes, we need - an associated \c PreviewWindow to show the effect of the currently - chosen window flags. - - \image windowflags_controllerwindow.png Screenshot of the Controller Window - - \section1 ControllerWindow Class Implementation - - \snippet widgets/windowflags/controllerwindow.cpp 0 - - In the constructor we first create the preview window. Then we - create the group boxes containing the available window flags using - the private \c createTypeGroupBox() and \c createHintsGroupBox() - functions. In addition we create a \uicontrol Quit button. We put the - button and a stretchable space in a separate layout to make the - button appear in the \c WindowFlag widget's right bottom corner. - - Finally, we add the button's layout and the two goup boxes to a - QVBoxLayout, set the window title and refresh the preview window - using the \c updatePreview() slot. - - \snippet widgets/windowflags/controllerwindow.cpp 1 - \snippet widgets/windowflags/controllerwindow.cpp 2 - - The \c updatePreview() slot is called whenever the user changes - any of the window flags. First we create an empty Qt::WindowFlags - \c flags, then we determine which one of the types that is checked - and add it to \c flags. - - \snippet widgets/windowflags/controllerwindow.cpp 3 - - We also determine which of the hints that are checked, and add - them to \c flags using an OR operator. We use \c flags to set the - window flags for the preview window. - - \snippet widgets/windowflags/controllerwindow.cpp 4 - - We adjust the position of the preview window. The reason we do - that, is that playing around with the window's frame may on some - platforms cause the window's position to be changed behind our - back. If a window is located in the upper left corner of the - screen, parts of the window may not be visible. So we adjust the - widget's position to make sure that, if this happens, the window - is moved within the screen's boundaries. Finally, we call - QWidget::show() to make sure the preview window is visible. - - \omit - \skipto pos - \printuntil /^\}/ - \endomit - - \snippet widgets/windowflags/controllerwindow.cpp 5 - - The private \c createTypeGroupBox() function is called from the - constructor. - - First we create a group box, and then we create a radio button - (using the private \c createRadioButton() function) for each of - the available types among the window flags. We make Qt::Window the - initially applied type. We put the radio buttons into a - QGridLayout and install the layout on the group box. - - We do not include the default Qt::Widget type. The reason is that - it behaves somewhat different than the other types. If the type is - not specified for a widget, and it has no parent, the widget is a - window. However, if it has a parent, it is a standard child - widget. The other types are all top-level windows, and since the - hints only affect top-level windows, we abandon the Qt::Widget - type. - - \snippet widgets/windowflags/controllerwindow.cpp 6 - - The private \c createHintsGroupBox() function is also called from - the constructor. - - Again, the first thing we do is to create a group box. Then we - create a checkbox, using the private \c createCheckBox() function, - for each of the available hints among the window flags. We put the - checkboxes into a QGridLayout and install the layout on the group - box. - - \snippet widgets/windowflags/controllerwindow.cpp 7 - - The private \c createCheckBox() function is called from \c - createHintsGroupBox(). - - We simply create a QCheckBox with the provided text, connect it to - the private \c updatePreview() slot, and return a pointer to the - checkbox. - - \snippet widgets/windowflags/controllerwindow.cpp 8 - - In the private \c createRadioButton() function it is a - QRadioButton we create with the provided text, and connect to the - private \c updatePreview() slot. The function is called from \c - createTypeGroupBox(), and returns a pointer to the button. - - \section1 PreviewWindow Class Definition - - \snippet widgets/windowflags/previewwindow.h 0 - - The \c PreviewWindow class inherits QWidget. It is a custom widget - that displays the names of its currently set window flags in a - read-only text editor. It is also provided with a QPushbutton that - closes the window. - - We reimplement the constructor to create the \uicontrol Close button and - the text editor, and the QWidget::setWindowFlags() function to - display the names of the window flags. - - \image windowflags_previewwindow.png Screenshot of the Preview Window - - \section1 PreviewWindow Class Implementation - - \snippet widgets/windowflags/previewwindow.cpp 0 - - In the constructor, we first create a QTextEdit and make sure that - it is read-only. - - We also prohibit any line wrapping in the text editor using the - QTextEdit::setLineWrapMode() function. The result is that a - horizontal scrollbar appears when a window flag's name exceeds the - width of the editor. This is a reasonable solution since we - construct the displayed text with built-in line breaks. If no line - breaks were guaranteed, using another QTextEdit::LineWrapMode - would perhaps make more sense. - - Then we create the \uicontrol Close button, and put both the widgets - into a QVBoxLayout before we set the window title. - - \snippet widgets/windowflags/previewwindow.cpp 1 - - In our reimplementation of the \c setWindowFlags() function, we - first set the widgets flags using the QWidget::setWindowFlags() - function. Then we run through the available window flags, creating - a text that contains the names of the flags that matches the \c - flags parameter. Finally, we display the text in the widgets text - editor. -*/ -- cgit v1.2.3