[Development] New Qt example development guideline and revamping examples

[A. Pönitz]

On Wed, Jan 18, 2023 at 04:10:20PM +0000, Kai Köhne via Development wrote:
> > -----Original Message-----
> >[...]
> 
> > > MANDATORY
> > >
> > >     Do not use QT_BEGIN_NAMESPACE ... QT_END_NAMESPACE for example
> > types. This namespace is exclusively for types in the Qt libraries.
> > 
> > This is broken. How is one going to correctly forward declare Qt names
> > in a namespaced build of Qt without using those macros? 
> 
> Option 1: Do not forward declare the Qt type, but just include the right Qt header.
> Option 2: Use QT_BEGIN_NAMESPACE..QT_END_NAMESPACE, but only for Qt types, _not_ for all header content.

Option 3: Add a flag to uic to give the user control on the emission of
the macros. There's a patch on gerrit for that now.

Lacking that, I'd go for Option 1: The examples are small, #include'ing
a "unneeded" header is not deadly.

> The rule just says that wrapping all of your headers with QT_BEGIN_NAMESPACE,
> QT_END_NAMESPACE is a misfeature which shouldn't be cargo-culted.

Was this ever the rule for examples?

> > Is there perhaps a more comprehensive discussion regarding how to
> > write examples that cope with namespaced Qt builds?
> 
> Personally, I wouldn't even mind if Qt examples wouldn't compile with
> a namespaced Qt (-qtnamespace configure argument), because I feel it's
> a somewhat specialist feature.

> But alas, we have at least one CI  configuration that builds with
> -qtnamespace and Qt examples, so we might as well keep it working.

Yes, please.

> (A nasty feature of uic is btw that it also does generate C++ code
> inside QT_BEGIN_NAMESPACE, QT_END_NAMESPACE.  That is, if you have a
> .ui file for a Dialog, and you want to pre-declare the type generated
> by uic, you have to also put it in QT_BEGIN_NAMESPACE,
> QT_END_NAMESPACE, 

Not quite. This is only ever needed once (non-personally) you want to
use a namespaced Qt for your own code or at least for one configuration
of the code.  Anywhere else you can sprinkle in QT_BEGIN_NAMESPACE or
leave it out at will, it doesn't do anything.

As you (personally) correctly state, this is a somewhat specialist
feature, so in practice not many are affected at all, and these that are
affected have to sprinkle QT_BEGIN_NAMESPACE and QT_END_NAMESPACE around
forward-declarations of Qt classes anyway. 

As a data point, even at it's height of .ui usage, Qt Creator (which is
a "namespace aware" code base, see https://wiki.qt.io/Qt_In_Namespace)
needed the QT_*_NAMESPACE for about 30 of its >200 .ui classes, and
that in the presence of ~680 places where it was needed for other
reasons.

So basically, this "evil misfeature" adds < 5% to the overall problem
of having a Qt-namespace-aware (and 0% for a Qt-namespaced) codebase,
a ratio that was not exactly predicted, but very roughly expected and
accepted so at the time the feature was implemented.

If it had been considered a problem at the time, we'd probably had
the uic flag for 13 years or so...

> which is a bit surprising to me Anyhow, changing
> this is probably not worth the breakages anymore ...

I still think there is no Real Problem (with the solution for the 
examples being to #include the Q* headers), and - as fallback if that's
considered too pragmatic for 2023 - to have a uic flag.

In neither case anything would break. [Nor would I need to think about
what "not worth ... anymore" could possibly mean...]

Andre'