[Development] api changes

[Girish Ramakrishnan]

On Fri, Apr 13, 2012 at 12:48 PM,  <lars.knoll at nokia.com> wrote:
> On 4/13/12 7:18 PM, "ext Samuel Rødal" <samuel.rodal at nokia.com> 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.
>
> I've seen other questions about how to e.g. convert a QPixmap to and from
> a HBITMAP or get access to other native handles. IMO we should offer APIs
> for these kind of things in platform dependent add-ons.
>

Isn't this why we have QPlatformNativeInterface. Don't we just have to
make the api public through the appropriate classes?

> ie. we have a QtX11/QtMac/QtWinSupport add-ons. That's also a natural
> place to add feature gaps to Qt 4.x such as QX11Embed into.
>>

I think that add-ons is a good idea. I didn't even realize that
QX11Embed has disappeared :-)

>>> 2. No public Qt include files should have _qpa.h in them
>
> Correct.
>
>>> 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.
>
> We need to install them, as we want to allow platform plugins outside of
> qtbase. Ideally, we move them all into a separate directory though, but
> that would require a bit of build system magic.
>

I can try to move them to QtPlatform/ but no promises for 5.0 :)

>
>>> 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.
>
> Yes, do we still need it, or should we rename it to something that has the
> correct name (like platformWindow())? Explicit names would certainly be
> cleaner, but can break quite some thing currently, so I'd go for adding
> the new methods and deprecating+inlining the old ones.
>

They should be definitely removed. If they cannot be removed because
the changes are too many, I will at least rename them to
platformWindow().

Thanks,
Girish