[Development] api changes

[Girish Ramakrishnan]

Hi Thiago,

2012/4/13 Thiago Macieira <thiago.macieira at intel.com>:
> On sexta-feira, 13 de abril de 2012 19.18.26, Samuel Rødal wrote:
>> On 04/13/2012 07:08 PM, ext Girish Ramakrishnan wrote:
>> > Hi,
>> > I am going through all the new apis. I have a couple of more changes
>> > to the public apis already. I am not submitting them to api_changes
>> > branch. I think Lars and co are having enough trouble as-is with
>> > getting api_changes to merge to master :-) All the commits will have
>> > the "api:" prefix in the commit message (so it's easy to see on my
>> > dashboard). I will stage them only after api_changes is merged.
>> >
>> > My current understanding of the "qpa" plan is this, correct me if I am
>> > wrong: 1. Files with _qpa in them are supposed to be used by plugins and
>> > plugins only. If you see, _qpa.h being used in application code, they
>> > are using a binary and source incompatible Qt. _qpa.h also lacks the
>> > 'we mean it' header which I will add.
>>
>> Mostly, though I guess an application might use QPlatformNativeInterface
>> to get access to a platform specific resource (such as the X display or
>> the wayland display or window handles etc). Maybe we'll need to make a
>> public API front-end for that down the line.
>
> 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?

>> > 2. No public Qt include files should have _qpa.h in them
>
> Without adding a new rule:
> No public Qt include files should have _p.h in them
>
>> > 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?

>> > 4. Also, I would like to see all the handle() functions in public api
>> > die. Or make them protected and make all the classes friends (as such
>> > they are all mostly friends anyway). handle() encourages writing
>> > binary incompatible code in userland. Note that handle() in qpa land
>> > is very different from handle() in the old qt4 land (where it just
>> > implied being binary compatible but platform specific).
>>
>> 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.

Girish