[PyKDE] Updated PyQt4 Documentation

[David Boddie]

On Mon, 5 Jun 2006 22:43:18 +0100, Phil Thompson wrote: 
> On Monday 05 June 2006 8:03 pm, David Boddie wrote:

> > The following classes are probably internal classes and aren't mentioned
> > in the Qt documentation. They may be exported from QtGui, but are
> > probably actually marked as internal:
> >
> >   QAbstractPageSetupDialog
> >   QDragResponseEvent
> >   QTextEngine
> >   QTextFrameLayoutData
> >   QTextItem
> >   QTextStreamManipulator
> >   QToolBarChangeEvent
>
> Unfortunately SIP doesn't parse the \internal markup in the header files.
> Also my system doesn't account for opaque classes - eg.
> QTextStreamManipulator.

I think the basic rule is: if there's no corresponding page in the Qt
documentation, the class is internal. (Unless there's been a mistake, of
course.)

> Sometimes it isn't clear what's intended. For example, QTextInlineObject
> has only one documented ctor - but it takes the internal QTextEngine as one
> of its arguments.

Yes, it could be that QTextInlineObject should be internal or, more likely,
that the constructor should be marked as such. I would be surprised if you
were supposed to construct your own QTextInlineObjects using QTextEngine
unless QTextEngine itself was a documented public class.

Certainly, something needs to be checked in the Qt documentation.

> With some handwritten code I could hide the internal classes but maintain
> the "official" functionality - for example, lie to SIP that printer() is a
> member of QPageSetupDialog and not QAbstractPageSetupDialog. With the
> approach I've taken then at least all the functionality is present, even if
> it means exposing more than is official.
>
> If you are willing to confirm exactly what is internal then I can make the
> necessary changes.

The only one that's both documented and marked as internal is this one:

  QAbstractPageSetupDialog

The others are not marked as internal but only because there is no class
documentation for them:

  QDragResponseEvent
  QTextEngine
  QTextFrameLayoutData
  QTextItem
  QTextStreamManipulator
  QToolBarChangeEvent

This could mean that they are just missing documentation. However, some of
them look like internal classes.

> > Note that some of these are for container classes and others are only
> > used by Qtopia Core (Qt for Embedded Linux).
>
> The PyQt documentation covers exactly what is wrapped, no more, no less.

Sure. I realise this. :-)

> > I've wrapped the Q*Extension* and QDesigner* classes for my own purposes,
> > so you can have the .sip files for those if you want them. I guess you
> > probably aren't interested in the extra work they would require right
> > now, since you don't appear to have wrapped various other plugin-related
> > classes.
>
> I will include your stuff - but I need to get 4.0 out asap.

Then I should probably wait until after that's happened to avoid giving you
extra work. These classes are all part of the QtDesigner module and could
always be shipped separately.

David