[Development] api changes
thiago.macieira at intel.com
Fri Apr 13 20:16:54 CEST 2012
On sexta-feira, 13 de abril de 2012 11.03.58, Girish Ramakrishnan wrote:
> Hi Thiago,
> > Let's please not invent a new rule.
> > If it's _p.h, it's private, otherwise it's public and subject to source-
> > and binary-compatibility guarantees. If there's API in some files that we
> > don't want to keep BC on, let's move them to a _p.h file.
> > Plugins can include those since we do install private headers in Qt 5.
> > Also, syncqt will not generate forwarding headers for classes in the _p.h
> > files. This helps us by not including one of them by accident by #include
> > <QtGui/QPlatformWhatever>.
> All platform plugins, unfortunately, do exactly this. Fixing them all
> though entirely possible though. There's also some inconsistency with
> some of the qpa files being named _qpa_p.h :-)
> How about we fix this properly for 5.1? And for the moment, also have
> the understanding that _qpa.h is internal?
Immediate action then:
1) make sure all such classes are documented \internal, so they don't show up
2) add #pragma qt_no_master_include so that they aren't included in <QtGui>
and people use them by accident because they happened to complete in QtCreator
or another IDE
3) no _qpa.h includes in public headers
4) no includes of _qpa.h forwarding headers in public headers either
5) add #pragma qt_sync_stop_processing so that the forwarding headers aren't
added, fixing the code that used them
6) rename _qpa.h to _p.h and update all includes to have private/xxx_p.h
(there's no need to have "qpa" in the name, since QPA is the only platform --
At any time:
7) create proper public API where needed
Personally, I'd invert the order of 4 and 5: if you do 5 before 4, 5's actions
will make it clear where 4 needs to be fixed. So, by doing 5, you do 4 more
> >> > 3. _qpa.h files are installed only so that we can allow development of
> >> > plugins outside of qt source. I would like to see them not getting
> >> > installed at all but I don't know if this is an oversight or
> >> > intentional.
> > All headers are installed. This rule is unnecessary.
> Right, but only if we change all _qpa.h to _qpa_p.h. Correct?
All headers are installed, whatever their names.
The difference is whether they are inside private/ or not. As an effect of step
6 above, they move into private/, which makes their accidental use impossible.
If we can't do that step before 5.0, then we need to tell people that they
shouldn't include those headers.
I really, really, REALLY recommend we do that step before 5.0. What will we
look like if we start adding 5.0 errata over 2 months before the release?
> >> The handle() that gets the QPlatformWindow etc? Yeah, I guess those
> >> serve no great purpose in the public API.
> > Just say that the type of the pointer returned by such functions is not
> > part of Qt's public API. Private Qt API and non-Qt API fall under that
> > definition.
> You are suggesting that this be a documentation fix instead of an API
> fix? I think I like that because I tried removing some of the handle()
> and found that plugin code uses it. Compile fails since the plugins
> are not friends. I will just mark them all as \internal.
Yes, it's a documentation fix.
Matched, of course, by the pointers being either opaque (Qt private) or defined
in a non-Qt header.
Thiago Macieira - thiago.macieira (AT) intel.com
Software Architect - Intel Open Source Technology Center
Intel Sweden AB - Registration Number: 556189-6027
Knarrarnäsgatan 15, 164 40 Kista, Stockholm, Sweden
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 190 bytes
Desc: This is a digitally signed message part.
Url : http://lists.qt-project.org/pipermail/development/attachments/20120413/1faf21b8/attachment-0001.bin
More information about the Development