[PyKDE] PyKDE and libkdegames

[Jim Bublitz]

> On 10-Jun-02 Bjorn Pettersen wrote:
>> From: Jim Bublitz <jbublitz at nwinternet.com>
 
>> Basically, there are only a few simple rules for generating sip
>> description files (.sip) from C++ headers:

> 0a. Delete all methods you don't want to expose to Python
> (although point 5 below still holds).

Very good point. In PyKDE the goal is to expose everything to
Python, but in cases where you just want Python access to parts of
an API, you can save a lot of work by hiding things. Another
example is that in writing an intermediate C++ wrapper and then
writing the bindings to that instead of the base package, you can
expose very little in the h files that are used in binding and
expose nearly everything (to gcc) in the .cpp files of your
wrapper or in h files that aren't visible in the bindings. In the
extreme you can make the bindings' h files and sip files almost
identical.

> 0b. Delete all operator overloads (you'll have to write
> %MemberCode to access those).

Yep -- not done in PyKDE.

>> 1. Delete any forward declarations
>> 2. Change 'class someClass : public QWidget' to 
>> 'class someClass : QWidget'

> But only if you have given a definition for QWidget in one of your
> sip files, i.e. there is no need to expose the inheritance
> relationship if it doesn't buy you anything. 

> This can be useful if you're inheriting from a templatized class.

Another very good point - I hadn't tried that explicitly, but it
could prove very useful (in fact there's a couple of places in
PyKDE where that might work).

> A simple example is in kcharsets.sip

kcharsets.sip has %MemberCode examples with lists and static methods
as well as returning an int& argument in a tuple - those cover the
majority of cases. intvaluelist.sip is probably a good example of
%MappedType usage (and then grep the PyKDE sip files to see how the
IntValueList type is used to replace a template type).

>> 7. Anything template based (eg QList <QString>) will require
>> either handwritten code or a %MappedType.

> A simple example is in the PyQt distribution in qpair.sip. Note
> that specific instantiations of a templatized class work fine as
> long as SIP doesn't see the template, e.g:

>  ivec.h:

>     #include <vector>
>     typedef std::vector<int> IntVector;

>  ivec.sip:

>     class IntVector {
>     %HeaderCode
>     #include "ivec.h"
>     %End
>     public:
>         void push_back(int);
>         int size();
>     };

It's sometimes helpful to keep in mind that sip doesn't look in the
h files at all - it only reads .sip files. You can also augment the
h files with code in the %HeaderCode block in the sip file (there
was an example below but I already snipped it).

>> 8. Eliminate duplicate typedefs if any
>> 9. Namespaces need some special handling, mostly in naming
>> objects in namespaces - see KParts stuff

> I.e. if subclassing from a class in the same namespace you need to
> prefix with the namespace, e.g:

>  namespace foo {

>  class A {...};
>  class B : foo::A {...};

>  };

'A' and 'B' will need the namespace prefix nearly everywhere, even
within the namespace itself:

B.h:

namespace foo
{
class B
{
public:
                B ();
                B (B&);

        B*      self () { return this; }
};
};


B.sip:

namespace foo
{
class B
{
%HeaderCode
#include <B.h>
%End

public:
                B ();
                B (foo::B&);

        foo::B* self ();
};
};

I also forgot to mention that any inline code is stripped out too.

Lastly, you can insert SGML docs in the sip files and sip will
produce a concatenated .sgml documentation file with the proper
switches (see either PyQt or PyKDE - kde.sip or kde.sip-in drive
the documentation construction, but the doc text is distributed
over all of the sip files)


Jim