Qt wiki will be updated on October 12th 2023 starting at 11:30 AM (EEST) and the maintenance will last around 2-3 hours. During the maintenance the site will be unavailable.

Qt6/Example-Guideline: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
mNo edit summary
Line 69: Line 69:
For further details see: https://codereview.qt-project.org/c/qt/qttools/+/447246
For further details see: https://codereview.qt-project.org/c/qt/qttools/+/447246
*Example should belong to only one category. Consider what's the most essential feature that the example is teaching and pick the category accordingly.
*Example should belong to only one category. Consider what's the most essential feature that the example is teaching and pick the category accordingly.
**If there isn't appropriate category for the example, it can also be left out and the example will then be listed under 'Other' category.  
**If there isn't appropriate category for the example, it can be left out and the example will then be listed under 'Other' category.  
**In the description and tags you add more information to make finding the example easy.
**In the description and tags you add more information to make finding the example easy.



Revision as of 10:21, 25 January 2023

When creating or updating Qt examples, developer should consider the best practises and guidelines listed in this document.

Evaluate if the example is meaningful or should it be removed/merged

MANDATORY

  • Check if there are similar examples for the same topic and consider if both are really needed or should they be merged.
  • Check also documentation on the topic and if that includes inline code snippet that would be adequate instead of complete example.

No C++ or qml warnings

MANDATORY


RECOMMENDED
Consider also compiling with the more strict warning flags and fix possible issues they reveal especially if these are in the example code.

GCC
Use -Wall and consider -Wextra parameter: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html
Clang
Use -Weverything compiler parameter: https://clang.llvm.org/docs/UsersManual.html#diagnostics-enable-everything
Visual Studio
Use /Wall compiler parameter: https://docs.microsoft.com/en-us/cpp/build/reference/compiler-option-warning-level

Qt6 best practises and changes

MANDATORY

Leveraging C++17

MANDATORY


RECOMMENDED


Naming the example, categorisation and adding tags

MANDATORY

Naming

  • Don't add Qt module name or "Example" word to the example name. e.g. QtWidgets Application Example → Text editor application
    • Note: If the part of the module name really needs to be used due to clearly describing functionality, that can still be done (e.g. Simple CoAP Client Example from Qt CoAP module)

Categorisation

  • Add example application to correct category, for instance by adding '\meta category {Graphics}' below '\examples'
 \example My Example 
 \meta category {My Category}

Will end up as

 <categories> 
   <category>My Category</category> 
 </categories>

in the <example> section of the respective examples-manifest.xml file.
For further details see: https://codereview.qt-project.org/c/qt/qttools/+/447246

  • Example should belong to only one category. Consider what's the most essential feature that the example is teaching and pick the category accordingly.
    • If there isn't appropriate category for the example, it can be left out and the example will then be listed under 'Other' category.
    • In the description and tags you add more information to make finding the example easy.

Acceptable categories

  • Application Examples
  • Connectivity
  • Graphics
  • Input/Output
  • Networking
  • User Interfaces
  • Internationalization
  • Desktop
  • Mobile
  • Embedded


RECOMMENDED

  • Confirm that the example shows up in Qt Creator welcome screen.
  • Check that the example description text shown in Creator contains the right keywords for users to find it.
  • Add appropriate tags to the example, for instance by adding '\meta tags {tag1,tag2}' below '\examples'.

Tags

  • Tags are used to set additional keywords for the example which makes it easier to search in Qt Creator example view
  • Common tags are for the UI stack (widgets, quick), and the 'main' module of the example.
    • Note that qdoc automatically does add tags for the Qt module, if not already set manually.
  • Don't add redundant information as tags which is already part of the category, example name or description
  • Don't add platform information in the tags
  • Example: quick,network

Visual Style

MANDATORY

  • Screen shots taken with high dpi resolution, minimum image size 440x320.
    • Note: Images can be larger but should follow either 4:3 or 5:4 aspect ratio. Take meaningful image that gives an idea what the example is about.
  • Icons should be suitable for high dpi screen with minimum size of 64x64.


RECOMMENDED

  • Consider using Qt Quick over Qt Widgets but remember also dependency restrictions with module api examples.
  • Create example's qml part to be compatible with Qt Design Studio.
    • Define purely declarative qml files with .ui.qml file extension.
    • Test the project also in Qt Design Studio.
  • Layouts should be tested on multiple platforms (macOS, Linux, Windows, iOS, Android, Embedded Linux / EGLFS) with full HD target screen resolution.

Build System

MANDATORY

  • Our users should be able to build with both qmake and CMake. Both build systems should therefore work.
  • Check that the example runs without any issues when opened in Qt Creator welcome screen, on all platforms. If additional steps are necessary, or examples only run on some platforms, make sure that is is prominently stated in the example's documentation.
  • CMake
    • Do not use the 'find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core)' pattern that is created for instance in CMakeLists.txt files created by Qt Creator wizards. This pattern is for keeping compatibility with Qt 5, which we don't strive for with Qt 6 examples.
    • Use qt_standard_project_setup() instead enabling AUTOMOC, AUTOUIC manually
    • Use PRIVATE linkage


RECOMMENDED

  • Avoid including (re)sources from outside the example directory, as examples should be self-contained.

Enable automated release testing

RECOMMENDED
For enabling RTA testing add unique object names for all the UI objects

Misc

MANDATORY

  • Do not use QT_BEGIN_NAMESPACE ... QT_END_NAMESPACE for example types. This namespace is exclusively for types in the Qt libraries.