[Development] New Qt example development guideline and revamping examples

[Tuukka Turunen]

Hi,

…and in case unsure what is shown in docs & Creator, it is the ones listed in the manifest file as described at https://doc.qt.io/qt-6/26-qdoc-configuration-example-manifest-files.html and https://wiki.qt.io/Qt_Examples_in_Qt_Creator

Mostly these are examples that have not been deemed relevant to show to the users in docs and Creator, often ones that would take quite an effort to update according to the guideline.

Rough listing of these:

activeqt/simpleqml
applicationmanager/application-features/imports/terminator2
applicationmanager/application-features/native/widgets
applicationmanager/startup-plugin
charts/chartinteractions
charts/qmlboxplot
charts/qmlcandlestick
charts/qmlpiechart
core5/widgets/tools/codecs
corelib/bindableproperties/bindablesubscription
corelib/bindableproperties/subscription
corelib/permissions
corelib/tools/customtypesending
dbus/remotecontrolledcar
embedded/digiflip
embedded/flickable
embedded/flightinfo
embedded/lightmaps
embedded/raycasting
embedded/styleexample
ifvehiclefunctions/window-qml
interfaceframework/qface-remote/demo
interfaceframework/qface-remote/frontend
interfaceframework/qface-remote/server_qtro
location/geojson_viewer
mqtt/consolepubsub
mqtt/quickpublication
multimedia/audiodecoder
multimedia/devices
network/dnslookup
network/multistreamclient
network/multistreamserver
oauth/redditclient
oauth/twittertimeline
opcua/waterpump/simulationserver
opengl/computegles31
opengl/contextinfo
opengl/hellowindow
opengl/paintedwindow
opengl/qopenglwidget
opengl/qopenglwindow
opengl/threadedqopenglwidget
pdf/pdfviewer
qml/qmldom
qml/shell
qmltest/qmltest
qpa/qrasterwindow
qpa/windows
qt3d/3d-text
qt3d/anaglyph-rendering
qt3d/compute-particles
qt3d/controls
qt3d/controlsunderlay
qt3d/instanced-arrays-qml
qt3d/lights
qt3d/phong-cubes
qt3d/qardboard
qt3d/qgltf
quick/customitems/maskedmousearea
quick/delegatechooser
quick/customitems/scrollbar/scrollbar.pro
quick/customitems/tabwidget/tabwidget.pro
quick/embeddedinwidgets
quick/multieffect/itemswitcher
quick/multieffect/testbed
quick/particles/itemparticle
quick/pointerhandlers
quick/scenegraph/threadedanimation
quick3d/helloqtquick3d
quick3d/offlineshaders
remoteobjects/ble/bleclient
remoteobjects/ble/bleserver
remoteobjects/clientapp
remoteobjects/cppclient
remoteobjects/plugins
remoteobjects/remoteobjects_server
remoteobjects/simpleswitch/directconnectclient
remoteobjects/simpleswitch/directconnectdynamicclient
remoteobjects/simpleswitch/directconnectserver
remoteobjects/simpleswitch/registryconnectedclient
remoteobjects/simpleswitch/registryconnectedserver
remoteobjects/ssl/sslcppclient
remoteobjects/ssl/sslserver
remoteobjects/websockets/wsclient
remoteobjects/websockets/wsserver
sensors/grue/console_app
sensors/grue/plugin
serialport/receiver
serialport/sender
spatialaudio/audiopanning
svg/draganddrop/delayedencoding
svg/embedded/desktopservices
svg/embedded/fluidlauncher
svg/embedded/weatherinfo
svg/embeddedsvgviewer
wayland/custom-extension
wayland/custom-extension/compositor
wayland/custom-extension/cpp-client
wayland/custom-extension/qml-client
wayland/custom-shell/client-plugin
wayland/custom-shell/compositor
wayland/hwlayer-compositor
wayland/minimal-cpp
wayland/server-buffer
wayland/server-buffer/compositor
wayland/server-buffer/cpp-client
widgets/itemviews/flattreeview
widgets/itemviews/storageview
widgets/scroller/graphicsview
widgets/tools/plugandpaint
widgets/windowcontainer
xml/htmlinfo
xml/rsslisting

As Kimmo mentioned, we should aim to check and move (or remove if not seen relevant as a manual test by the module maintainer) these during February.

Yours,

                Tuukka

From: Development <development-bounces at qt-project.org> on behalf of Kimmo Leppälä via Development <development at qt-project.org>
Date: Friday, 3. February 2023 at 9.03
To: development at qt-project.org <development at qt-project.org>
Subject: Re: [Development] New Qt example development guideline and revamping examples
Hi,

There has been slight modifications to the guideline document https://wiki.qt.io/Qt6/Example-Guideline


Most important change being that the examples that are not shown in Qt documentation should be moved under tests/manual/examples. This cleanup should be done preferably during February so that we have cleared away the examples we don’t want to revamp at this point.

Thanks!

-Kimmo

On 19.1.2023, 9.25, "Kimmo Leppälä" <kimmo.leppala at qt.io> wrote:

Hi,

Thank you for the proposals Giuseppe!

On 18.1.2023, 14.14, "Development" <development-bounces at qt-project.org> wrote:

On 18/01/2023 10:51, Kimmo Leppälä via Development wrote:
> Also, the guideline is a living document in wiki and we would be happy
> to hear feedback and proposals for it!
>

Here's a few considerations:


>  RECOMMENDED
> Consider also compiling with the more strict warning flags and fix any issues they reveal.

As history shows, this is not going to happen unless we enforce it. The
cmake-magic macros that are used to build examples should set those more
strict flags and enforce them (-Werror).


> Clang
>     Use -Weverything compiler parameter
> Visual Studio
>     Use /Wall compiler parameter

These aren't good recommendations. There's basically no code that
survives those flags, incl. libc++/MS-STL own headers.
Yes, if we enforce with (-Werror) these would be too strict but the warning flags were meant to be enabled without enforcing and then use human judgement if something needs to be fixed.
I changed wiki page to make it clear that consideration should be used and also that focus is on fixing the example codebase, not all the dependencies.

In addition we could define explicit set of warning flags that should be used when enforced with -werror.
Did you already have a list of flags in mind?



> RECOMMENDED
>
>     Prefer signal/slot connection with lambdas: https://doc.qt.io/qt-6/signalsandslots.html

All the contrary, do NOT do that, as it results in 200+ lines unnamed
lambdas. Strongly prefer named slots. Keep the lambdas short and to the
point. Do not use unnamed lambdas.
I changed the wiki page like so:
*Consider using signal/slot connection with lambdas: https://doc.qt.io/qt-6/signalsandslots.html
**Keep lambdas short and to the point
**Don't use unnamed lambdas




>     Check Qt Coding conventions: https://wiki.qt.io/Coding_Conventions

This shouldn't be "recommended" but mandatory. We must follow the same
style in examples as we do in the rest of our code.


>     Consider using clazy plugin (comes also with Qt Creator): https://www.qt.io/blog/porting-from-qt-5-to-qt-6-using-clazy-checks

This should also be mandatory and enforced by CI.
I moved these under mandatory.



> Add example application to correct category, for instance by adding '\meta category {Graphics & UI}' below '\examples'

Is there a list of categories to pick from?
This is still being worked on but should be available this week.
The list will then be linked or included in the guideline document.

-Kimmo
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20230203/e0461c05/attachment-0001.htm>