[Development] api changes

[Thiago Macieira]

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>.

> > 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.

> > 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.

-- 
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: signature.asc
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.qt-project.org/pipermail/development/attachments/20120413/a0b83c49/attachment.sig>