<p>Note that the current version of SIP does not complain about unknown
annotations, or annotations used out of their correct context.</p>
@ -191,7 +191,7 @@ directive. If the directive is not specified then <tt class="xref docutils lite
<p>Python v3 will use the <ttclass="docutils literal"><spanclass="pre">bytes</span></tt> type to represent the argument if the
encoding is <ttclass="docutils literal"><spanclass="pre">"None"</span></tt> and the <ttclass="docutils literal"><spanclass="pre">str</span></tt> type otherwise.</p>
<p>Python v2 will use the <ttclass="docutils literal"><spanclass="pre">str</span></tt> type to represent the argument if the
encoding is <ttclass="docutils literal"><spanclass="pre">"None"</span></tt> and the <ttclass="docutils literal"><spanclass="pre">unicode</span></tt> type otherwise.</p>
encoding is <ttclass="docutils literal"><spanclass="pre">"None"</span></tt> and the <ttclass="docutils literal"><spanclass="pre">tqunicode</span></tt> type otherwise.</p>
<p>An important feature of SIP is the ability to generate bindings that are built
on top of existing bindings. For example, both
<aclass="reference external"href="http://www.riverbankcomputing.com/software/pykde/">PyKDE</a> and
<aclass="reference external"href="http://pyqwt.sourceforge.net/">PyQwt</a> are built on top of PyQt but all three
packages are maintained by different developers. To make this easier PyQt
<aclass="reference external"href="http://pyqwt.sourceforge.net/">PyQwt</a> are built on top of PyTQt but all three
packages are maintained by different developers. To make this easier PyTQt
includes its own configuration module, <ttclass="docutils literal"><spanclass="pre">pyqtconfig</span></tt>, that contains additional
classes intended to be used by the configuration scripts of bindings built on
top of PyQt. The SIP build system includes facilities that do a lot of the
top of PyTQt. The SIP build system includes facilities that do a lot of the
work of creating these additional configuration modules.</p>
<dlclass="function">
<dtid="sipconfig.create_config_module">
@ -551,12 +551,12 @@ and <tt class="docutils literal"><span class="pre">BMAKE</span></tt>.</dd></dl>
<atitle="sipconfig.Configuration"class="reference internal"href="#sipconfig.Configuration"><ttclass="xref docutils literal"><spanclass="pre">Configuration</span></tt></a> class or a sub-class.</li>
<li><em>console</em>– is set if the target is a console (rather than GUI) target. This
only affects Windows and is ignored on other platforms.</li>
<li><em>qt</em>– is set if the target uses Qt. For Qt v4 a list of Qt libraries may
be specified and a simple non-zero value implies QtCore and QtGui.</li>
<li><em>qt</em>– is set if the target uses TQt. For TQt v4 a list of TQt libraries may
be specified and a simple non-zero value implies TQtCore and TQtGui.</li>
<li><em>opengl</em>– is set if the target uses OpenGL.</li>
<li><em>python</em>– is set if the target uses Python.h.</li>
<li><em>threaded</em>– is set if the target requires thread support. It is set
automatically if the target uses Qt and Qt has thread support
automatically if the target uses TQt and TQt has thread support
enabled.</li>
<li><em>warnings</em>– is set if compiler warning messages should be enabled. The default
of <ttclass="xref docutils literal"><spanclass="pre">None</span></tt> means that warnings are enabled for SIP v4.x and
<dd>Convert a C/C++ <ttclass="docutils literal"><spanclass="pre">L'\0'</span></tt> terminated wide character string to a Python
v2 unicode object or a Python v3 string object. If the string pointer
v2 tqunicode object or a Python v3 string object. If the string pointer
is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> then the result is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt>.</dd>
<dd>Convert a Python string-like object of length 1 to a C/C++ <ttclass="docutils literal"><spanclass="pre">char</span></tt>
according to the encoding <ttclass="docutils literal"><spanclass="pre">e</span></tt>. <ttclass="docutils literal"><spanclass="pre">e</span></tt> can either be <ttclass="docutils literal"><spanclass="pre">A</span></tt> for ASCII,
<ttclass="docutils literal"><spanclass="pre">L</span></tt> for Latin-1, or <ttclass="docutils literal"><spanclass="pre">8</span></tt> for UTF-8. For Python v2 the object may be
either a string or a unicode object that can be encoded. For Python v3
either a string or a tqunicode object that can be encoded. For Python v3
the object may either be a bytes object or a string object that can be
encoded. An object that supports the buffer protocol may also be used.</dd>
<dd>Convert a Python v2 string or tqunicode object or a Python v3 string
object to a C/C++ <ttclass="docutils literal"><spanclass="pre">L'\0'</span></tt> terminated wide character string. If the
Python object is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then the string is <ttclass="docutils literal"><spanclass="pre">NULL</span></tt>.</dd>
<dd>Convert a Python v2 string or tqunicode object or a Python v3 string
object to a C/C++ wide character array and its length. If the Python
object is <ttclass="docutils literal"><spanclass="pre">Py_None</span></tt> then the array and length are <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> and zero
respectively.</dd>
@ -2080,7 +2080,7 @@ corresponding generated type structure (see <a class="reference internal" href="
name prefixed by <ttclass="docutils literal"><spanclass="pre">sip</span></tt>. For example, the derived class for class <ttclass="docutils literal"><spanclass="pre">Klass</span></tt>
is <ttclass="docutils literal"><spanclass="pre">sipKlass</span></tt>.</p>
<p>If a C++ class doesn’t have any virtual or protected methods in it or any of
it’s super-class hierarchy, or does not emit any Qt signals, then a derived
it’s super-class hierarchy, or does not emit any TQt signals, then a derived
class is not generated.</p>
<p>Most of the time handwritten code should ignore the derived classes. The only
exception is that handwritten constructor code specified using the
@ -70,8 +70,8 @@ is omitted then <tt class="docutils literal"><span class="pre">stdin</span></tt>
<dlclass="cmdoption">
<dtid="cmdoption-sip-a">
<ttclass="descname">-a</tt><ttclass="descclassname"><FILE></tt><aclass="headerlink"href="#cmdoption-sip-a"title="Permalink to this definition">ยถ</a></dt>
<dd>The name of the QScintilla API file to generate. This file contains a
description of the module API in a form that the QScintilla editor
<dd>The name of the TQScintilla API file to generate. This file contains a
description of the module API in a form that the TQScintilla editor
component can use for auto-completion and call tips. (The file may also be
used by the SciTE editor but must be sorted first.) By default the file is
<p>A consolidated module is not intended to be explicitly imported by an
application. Instead it is imported by its component modules when they
@ -380,8 +380,8 @@ made to each element of the list.</dd>
</dl>
<p>The handwritten code must explicitly return a <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt>. If there was an
error then a Python exception must be raised and <ttclass="docutils literal"><spanclass="pre">NULL</span></tt> returned.</p>
<p>The following example converts a <ttclass="docutils literal"><spanclass="pre">QList<QWidget</span><spanclass="pre">*></span></tt> instance to a Python
list of <ttclass="docutils literal"><spanclass="pre">QWidget</span></tt> instances:</p>
<p>The following example converts a <ttclass="docutils literal"><spanclass="pre">TQList<TQWidget</span><spanclass="pre">*></span></tt> instance to a Python
list of <ttclass="docutils literal"><spanclass="pre">TQWidget</span></tt> instances:</p>
// Include the library interface to the type being mapped.
@ -1272,7 +1272,7 @@ object.</p>
}
// Create the instance on the heap.
QList<Type *> *ql = new QList<Type *>;
TQList<Type *> *ql = new TQList<Type *>;
for (int i = 0; i < PyList_GET_SIZE(sipPy); ++i)
{
@ -1333,9 +1333,9 @@ object.</p>
%End
}</pre>
</div>
<p>Using this we can use, for example, <ttclass="docutils literal"><spanclass="pre">QList<QObject</span><spanclass="pre">*></span></tt> throughout the
<p>Using this we can use, for example, <ttclass="docutils literal"><spanclass="pre">TQList<TQObject</span><spanclass="pre">*></span></tt> throughout the
module’s specification files (and in any module that imports this one). The
generated code will automatically map this to and from a Python list of QObject
generated code will automatically map this to and from a Python list of TQObject
@ -467,28 +467,28 @@ Handwritten code must be provided to interpret the conversion correctly.</p>
<p>This is a <ttclass="docutils literal"><spanclass="pre">PyObject</span><spanclass="pre">*</span></tt> that is a Python type object.</p>
<dlclass="sip-type">
<dtid="stype-SIP_QOBJECT">
<ttclass="descname">SIP_QOBJECT</tt><aclass="headerlink"href="#stype-SIP_QOBJECT" title="Permalink to this definition">ยถ</a></dt>
<dtid="stype-SIP_TQOBJECT">
<ttclass="descname">SIP_TQOBJECT</tt><aclass="headerlink"href="#stype-SIP_TQOBJECT" title="Permalink to this definition">ยถ</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">QObject</span><spanclass="pre">*</span></tt> that is a C++ instance of a class derived from Qt’s
<p>This is a <ttclass="docutils literal"><spanclass="pre">TQObject</span><spanclass="pre">*</span></tt> that is a C++ instance of a class derived from TQt’s
<ttclass="descname">SIP_RXOBJ_CON</tt><aclass="headerlink"href="#stype-SIP_RXOBJ_CON"title="Permalink to this definition">ยถ</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">QObject</span><spanclass="pre">*</span></tt> that is a C++ instance of a class derived from Qt’s
<ttclass="docutils literal"><spanclass="pre">QObject</span></tt> class. It is used as the type of the receiver instead of <ttclass="docutils literal"><spanclass="pre">const</span>
<spanclass="pre">QObject</span><spanclass="pre">*</span></tt> in functions that implement a connection to a slot.</p>
<p>This is a <ttclass="docutils literal"><spanclass="pre">TQObject</span><spanclass="pre">*</span></tt> that is a C++ instance of a class derived from TQt’s
<ttclass="docutils literal"><spanclass="pre">TQObject</span></tt> class. It is used as the type of the receiver instead of <ttclass="docutils literal"><spanclass="pre">const</span>
<spanclass="pre">TQObject</span><spanclass="pre">*</span></tt> in functions that implement a connection to a slot.</p>
<dlclass="sip-type">
<dtid="stype-SIP_RXOBJ_DIS">
<ttclass="descname">SIP_RXOBJ_DIS</tt><aclass="headerlink"href="#stype-SIP_RXOBJ_DIS"title="Permalink to this definition">ยถ</a></dt>
<dd></dd></dl>
<p>This is a <ttclass="docutils literal"><spanclass="pre">QObject</span><spanclass="pre">*</span></tt> that is a C++ instance of a class derived from Qt’s
<ttclass="docutils literal"><spanclass="pre">QObject</span></tt> class. It is used as the type of the receiver instead of <ttclass="docutils literal"><spanclass="pre">const</span>
<spanclass="pre">QObject</span><spanclass="pre">*</span></tt> in functions that implement a disconnection from a slot.</p>
<p>This is a <ttclass="docutils literal"><spanclass="pre">TQObject</span><spanclass="pre">*</span></tt> that is a C++ instance of a class derived from TQt’s
<ttclass="docutils literal"><spanclass="pre">TQObject</span></tt> class. It is used as the type of the receiver instead of <ttclass="docutils literal"><spanclass="pre">const</span>
<spanclass="pre">TQObject</span><spanclass="pre">*</span></tt> in functions that implement a disconnection from a slot.</p>
<dlclass="sip-type">
<dtid="stype-SIP_SIGNAL">
<ttclass="descname">SIP_SIGNAL</tt><aclass="headerlink"href="#stype-SIP_SIGNAL"title="Permalink to this definition">ยถ</a></dt>
@ -514,11 +514,11 @@ of an explicitly generated signal to a slot.</p>
<ttclass="docutils literal"><spanclass="pre">const</span><spanclass="pre">char</span><spanclass="pre">*</span></tt> in functions that implement the connection of an internally
generated signal to a slot. The type includes a comma separated list of types
that is the C++ signature of of the signal.</p>
<p>To take an example, <ttclass="docutils literal"><spanclass="pre">QAccel::connectItem()</span></tt> connects an internally generated
<p>To take an example, <ttclass="docutils literal"><spanclass="pre">TQAccel::connectItem()</span></tt> connects an internally generated
signal to a slot. The signal is emitted when the keyboard accelerator is
activated and it has a single integer argument that is the ID of the
@ -235,13 +235,13 @@ be used for this example without change.</p>
<divclass="section"id="a-more-complex-c-example">
<h2>A More Complex C++ Example<aclass="headerlink"href="#a-more-complex-c-example"title="Permalink to this headline">ยถ</a></h2>
<p>In this last example we will wrap a fictional C++ library that contains a class
that is derived from a Qt class. This will demonstrate how SIP allows a class
that is derived from a TQt class. This will demonstrate how SIP allows a class
hierarchy to be split across multiple Python extension modules, and will
introduce SIP’s versioning system.</p>
<p>The library contains a single C++ class called <ttclass="docutils literal"><spanclass="pre">Hello</span></tt> which is derived from
Qt’s <ttclass="docutils literal"><spanclass="pre">QLabel</span></tt> class. It behaves just like <ttclass="docutils literal"><spanclass="pre">QLabel</span></tt> except that the text
TQt’s <ttclass="docutils literal"><spanclass="pre">TQLabel</span></tt> class. It behaves just like <ttclass="docutils literal"><spanclass="pre">TQLabel</span></tt> except that the text
in the label is hard coded to be <ttclass="docutils literal"><spanclass="pre">Hello</span><spanclass="pre">World</span></tt>. To make the example more
interesting we’ll also say that the library only supports Qt v4.2 and later,
interesting we’ll also say that the library only supports TQt v4.2 and later,
and also includes a function called <ttclass="docutils literal"><spanclass="pre">setDefault()</span></tt> that is not implemented
in the Windows version of the library.</p>
<p>The <ttclass="docutils literal"><spanclass="pre">hello.h</span></tt> header file looks something like this:</p>
@ -251,12 +251,13 @@ in the Windows version of the library.</p>
#include <qwidget.h>
#include <qstring.h>
class Hello : public QLabel {
// This is needed by the Qt Meta-Object Compiler.
class Hello : public TQLabel {
// This is needed by the TQt Meta-Object Compiler.
Q_OBJECT
TQ_OBJECT
public:
Hello(QWidget *parent = 0);
Hello(TQWidget *parent = 0);
private:
// Prevent instances from being copied.
@ -265,7 +266,7 @@ private:
};
#if !defined(Q_OS_WIN)
void setDefault(const QString &def);
void setDefault(const TQString &def);
#endif</pre>
</div>
<p>The corresponding SIP specification file would then look something like this:</p>
<li>The <aclass="reference external"href="directives.html#directive-%Import"><ttclass="xref docutils literal"><spanclass="pre">%Import</span></tt></a> directive has been added to specify that we are
extending the class hierarchy defined in the file <ttclass="docutils literal"><spanclass="pre">QtGui/QtGuimod.sip</span></tt>.
This file is part of PyQt. The build system will take care of finding
extending the class hierarchy defined in the file <ttclass="docutils literal"><spanclass="pre">TQtGui/TQtGuimod.sip</span></tt>.
This file is part of PyTQt. The build system will take care of finding
the file’s exact location.</li>
<li>The <aclass="reference external"href="directives.html#directive-%If"><ttclass="xref docutils literal"><spanclass="pre">%If</span></tt></a> directive has been added to specify that everything
<aclass="footnote-reference"href="#id11"id="id8">[4]</a> up to the matching <aclass="reference external"href="directives.html#directive-%End"><ttclass="xref docutils literal"><spanclass="pre">%End</span></tt></a> directive only applies to Qt
v4.2 and later. <ttclass="docutils literal"><spanclass="pre">Qt_4_2_0</span></tt> is a <em>tag</em> defined in <ttclass="docutils literal"><spanclass="pre">QtCoremod.sip</span></tt>
<aclass="footnote-reference"href="#id11"id="id8">[4]</a> up to the matching <aclass="reference external"href="directives.html#directive-%End"><ttclass="xref docutils literal"><spanclass="pre">%End</span></tt></a> directive only applies to TQt
v4.2 and later. <ttclass="docutils literal"><spanclass="pre">TQt_4_2_0</span></tt> is a <em>tag</em> defined in <ttclass="docutils literal"><spanclass="pre">TQtCoremod.sip</span></tt>
<aclass="footnote-reference"href="#id12"id="id9">[5]</a> using the <aclass="reference external"href="directives.html#directive-%Timeline"><ttclass="xref docutils literal"><spanclass="pre">%Timeline</span></tt></a> directive. <aclass="reference external"href="directives.html#directive-%Timeline"><ttclass="xref docutils literal"><spanclass="pre">%Timeline</span></tt></a>
is used to define a tag for each version of a library’s API you are
wrapping allowing you to maintain all the different versions in a single
@ -318,9 +319,9 @@ removed. This is not supported by SIP.</li>
<li>The <aclass="reference external"href="annotations.html#aanno-TransferThis"><ttclass="xref docutils literal"><spanclass="pre">TransferThis</span></tt></a> annotation has been added to the constructor’s
argument. It specifies that if the argument is not 0 (i.e. the <ttclass="docutils literal"><spanclass="pre">Hello</span></tt>
instance being constructed has a parent) then ownership of the instance
is transferred from Python to C++. It is needed because Qt maintains
objects (i.e. instances derived from the <ttclass="docutils literal"><spanclass="pre">QObject</span></tt> class) in a
hierachy. When an object is destroyed all of its children are also
is transferred from Python to C++. It is needed because TQt maintains
objects (i.e. instances derived from the <ttclass="docutils literal"><spanclass="pre">TQObject</span></tt> class) in a
hierachy. When an object is destroyed all of its tqchildren are also
automatically destroyed. It is important, therefore, that the Python
garbage collector doesn’t also try and destroy them. This is covered in
more detail in <aclass="reference internal"href="#ref-object-ownership"><em>Ownership of Objects</em></a>. SIP provides many other
@ -331,7 +332,7 @@ values.</li>
SIP.</li>
<li>The <aclass="reference external"href="directives.html#directive-%If"><ttclass="xref docutils literal"><spanclass="pre">%If</span></tt></a> directive has been added to specify that everything
up to the matching <aclass="reference external"href="directives.html#directive-%End"><ttclass="xref docutils literal"><spanclass="pre">%End</span></tt></a> directive does not apply to Windows.
<ttclass="docutils literal"><spanclass="pre">WS_WIN</span></tt> is another tag defined by PyQt, this time using the
<ttclass="docutils literal"><spanclass="pre">WS_WIN</span></tt> is another tag defined by PyTQt, this time using the
<aclass="reference external"href="directives.html#directive-%Platforms"><ttclass="xref docutils literal"><spanclass="pre">%Platforms</span></tt></a> directive. Tags defined by the
<aclass="reference external"href="directives.html#directive-%Platforms"><ttclass="xref docutils literal"><spanclass="pre">%Platforms</span></tt></a> directive are mutually exclusive, i.e. only one
may be valid at a time <aclass="footnote-reference"href="#id13"id="id10">[6]</a>.</li>
@ -342,9 +343,9 @@ copy constructor when it can never be called from Python? The answer is to
prevent the automatic generation of a public copy constructor.</p>
<p>We now look at the <ttclass="docutils literal"><spanclass="pre">configure.py</span></tt> script. This is a little different to the
script in the previous examples for two related reasons.</p>
<p>Firstly, PyQt includes a pure Python module called <ttclass="docutils literal"><spanclass="pre">pyqtconfig</span></tt> that extends
the SIP build system for modules, like our example, that build on top of PyQt.
It deals with the details of which version of Qt is being used (i.e. it
<p>Firstly, PyTQt includes a pure Python module called <ttclass="docutils literal"><spanclass="pre">pyqtconfig</span></tt> that extends
the SIP build system for modules, like our example, that build on top of PyTQt.
It deals with the details of which version of TQt is being used (i.e. it
determines what the correct tags are) and where it is installed. This is
called a module’s configuration module.</p>
<p>Secondly, we generate a configuration module (called <ttclass="docutils literal"><spanclass="pre">helloconfig</span></tt>) for our
@ -354,16 +355,16 @@ life easier for them.</p>
<p>Now we have two scripts. First the <ttclass="docutils literal"><spanclass="pre">configure.py</span></tt> script:</p>
Timothy Pearson
12 years ago