diff options
Diffstat (limited to 'doc/html/using.html')
| -rw-r--r-- | doc/html/using.html | 81 |
1 files changed, 41 insertions, 40 deletions
diff --git a/doc/html/using.html b/doc/html/using.html index 5ff6786..c3c0309 100644 --- a/doc/html/using.html +++ b/doc/html/using.html @@ -235,13 +235,13 @@ be used for this example without change.</p> <div class="section" id="a-more-complex-c-example"> <h2>A More Complex C++ Example<a class="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 <tt class="docutils literal"><span class="pre">Hello</span></tt> which is derived from -Qt’s <tt class="docutils literal"><span class="pre">QLabel</span></tt> class. It behaves just like <tt class="docutils literal"><span class="pre">QLabel</span></tt> except that the text +TQt’s <tt class="docutils literal"><span class="pre">TQLabel</span></tt> class. It behaves just like <tt class="docutils literal"><span class="pre">TQLabel</span></tt> except that the text in the label is hard coded to be <tt class="docutils literal"><span class="pre">Hello</span> <span class="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 <tt class="docutils literal"><span class="pre">setDefault()</span></tt> that is not implemented in the Windows version of the library.</p> <p>The <tt class="docutils literal"><span class="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> @@ -273,25 +274,25 @@ void setDefault(const QString &def); %Module hello 0 -%Import QtGui/QtGuimod.sip +%Import TQtGui/TQtGuimod.sip -%If (Qt_4_2_0 -) +%If (TQt_4_2_0 -) -class Hello : QLabel { +class Hello : TQLabel { %TypeHeaderCode #include <hello.h> %End public: - Hello(QWidget *parent /TransferThis/ = 0); + Hello(TQWidget *parent /TransferThis/ = 0); private: Hello(const Hello &); }; %If (!WS_WIN) -void setDefault(const QString &def); +void setDefault(const TQString &def); %End %End</pre> @@ -301,12 +302,12 @@ previous examples.</p> <blockquote> <ul class="simple"> <li>The <a class="reference external" href="directives.html#directive-%Import"><tt class="xref docutils literal"><span class="pre">%Import</span></tt></a> directive has been added to specify that we are -extending the class hierarchy defined in the file <tt class="docutils literal"><span class="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 <tt class="docutils literal"><span class="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 <a class="reference external" href="directives.html#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> directive has been added to specify that everything -<a class="footnote-reference" href="#id11" id="id8">[4]</a> up to the matching <a class="reference external" href="directives.html#directive-%End"><tt class="xref docutils literal"><span class="pre">%End</span></tt></a> directive only applies to Qt -v4.2 and later. <tt class="docutils literal"><span class="pre">Qt_4_2_0</span></tt> is a <em>tag</em> defined in <tt class="docutils literal"><span class="pre">QtCoremod.sip</span></tt> +<a class="footnote-reference" href="#id11" id="id8">[4]</a> up to the matching <a class="reference external" href="directives.html#directive-%End"><tt class="xref docutils literal"><span class="pre">%End</span></tt></a> directive only applies to TQt +v4.2 and later. <tt class="docutils literal"><span class="pre">TQt_4_2_0</span></tt> is a <em>tag</em> defined in <tt class="docutils literal"><span class="pre">TQtCoremod.sip</span></tt> <a class="footnote-reference" href="#id12" id="id9">[5]</a> using the <a class="reference external" href="directives.html#directive-%Timeline"><tt class="xref docutils literal"><span class="pre">%Timeline</span></tt></a> directive. <a class="reference external" href="directives.html#directive-%Timeline"><tt class="xref docutils literal"><span class="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 <a class="reference external" href="annotations.html#aanno-TransferThis"><tt class="xref docutils literal"><span class="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 <tt class="docutils literal"><span class="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 <tt class="docutils literal"><span class="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 <tt class="docutils literal"><span class="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 <a class="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 <a class="reference external" href="directives.html#directive-%If"><tt class="xref docutils literal"><span class="pre">%If</span></tt></a> directive has been added to specify that everything up to the matching <a class="reference external" href="directives.html#directive-%End"><tt class="xref docutils literal"><span class="pre">%End</span></tt></a> directive does not apply to Windows. -<tt class="docutils literal"><span class="pre">WS_WIN</span></tt> is another tag defined by PyQt, this time using the +<tt class="docutils literal"><span class="pre">WS_WIN</span></tt> is another tag defined by PyTQt, this time using the <a class="reference external" href="directives.html#directive-%Platforms"><tt class="xref docutils literal"><span class="pre">%Platforms</span></tt></a> directive. Tags defined by the <a class="reference external" href="directives.html#directive-%Platforms"><tt class="xref docutils literal"><span class="pre">%Platforms</span></tt></a> directive are mutually exclusive, i.e. only one may be valid at a time <a class="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 <tt class="docutils literal"><span class="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 <tt class="docutils literal"><span class="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 <tt class="docutils literal"><span class="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 <tt class="docutils literal"><span class="pre">helloconfig</span></tt>) for our @@ -354,16 +355,16 @@ life easier for them.</p> <p>Now we have two scripts. First the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script:</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">os</span> <span class="kn">import</span> <span class="nn">sipconfig</span> -<span class="kn">from</span> <span class="nn">PyQt4</span> <span class="kn">import</span> <span class="n">pyqtconfig</span> +<span class="kn">from</span> <span class="nn">PyTQt4</span> <span class="kn">import</span> <span class="n">pyqtconfig</span> <span class="c"># The name of the SIP build file generated by SIP and used by the build</span> <span class="c"># system.</span> <span class="n">build_file</span> <span class="o">=</span> <span class="s">"hello.sbf"</span> -<span class="c"># Get the PyQt configuration information.</span> +<span class="c"># Get the PyTQt configuration information.</span> <span class="n">config</span> <span class="o">=</span> <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">Configuration</span><span class="p">()</span> -<span class="c"># Get the extra SIP flags needed by the imported PyQt modules. Note that</span> +<span class="c"># Get the extra SIP flags needed by the imported PyTQt modules. Note that</span> <span class="c"># this normally only includes those flags (-x and -t) that relate to SIP's</span> <span class="c"># versioning system.</span> <span class="n">pyqt_sip_flags</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">pyqt_sip_flags</span> @@ -380,10 +381,10 @@ life easier for them.</p> <span class="n">installs</span><span class="o">.</span><span class="n">append</span><span class="p">([</span><span class="s">"helloconfig.py"</span><span class="p">,</span> <span class="n">config</span><span class="o">.</span><span class="n">default_mod_dir</span><span class="p">])</span> -<span class="c"># Create the Makefile. The QtGuiModuleMakefile class provided by the</span> +<span class="c"># Create the Makefile. The TQtGuiModuleMakefile class provided by the</span> <span class="c"># pyqtconfig module takes care of all the extra preprocessor, compiler and</span> -<span class="c"># linker flags needed by the Qt library.</span> -<span class="n">makefile</span> <span class="o">=</span> <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">QtGuiModuleMakefile</span><span class="p">(</span> +<span class="c"># linker flags needed by the TQt library.</span> +<span class="n">makefile</span> <span class="o">=</span> <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">TQtGuiModuleMakefile</span><span class="p">(</span> <span class="n">configuration</span><span class="o">=</span><span class="n">config</span><span class="p">,</span> <span class="n">build_file</span><span class="o">=</span><span class="n">build_file</span><span class="p">,</span> <span class="n">installs</span><span class="o">=</span><span class="n">installs</span> @@ -418,7 +419,7 @@ life easier for them.</p> </pre></div> </div> <p>Next we have the <tt class="docutils literal"><span class="pre">helloconfig.py.in</span></tt> template script:</p> -<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">PyQt4</span> <span class="kn">import</span> <span class="n">pyqtconfig</span> +<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">PyTQt4</span> <span class="kn">import</span> <span class="n">pyqtconfig</span> <span class="c"># These are installation specific values created when Hello was configured.</span> <span class="c"># The following line will be replaced when this template is used to create</span> @@ -445,7 +446,7 @@ life easier for them.</p> <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">Configuration</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cfg</span><span class="p">)</span> -<span class="k">class</span> <span class="nc">HelloModuleMakefile</span><span class="p">(</span><span class="n">pyqtconfig</span><span class="o">.</span><span class="n">QtGuiModuleMakefile</span><span class="p">):</span> +<span class="k">class</span> <span class="nc">HelloModuleMakefile</span><span class="p">(</span><span class="n">pyqtconfig</span><span class="o">.</span><span class="n">TQtGuiModuleMakefile</span><span class="p">):</span> <span class="sd">"""The Makefile class for modules that %Import hello.</span> <span class="sd"> """</span> <span class="k">def</span> <span class="nf">finalise</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> @@ -455,7 +456,7 @@ life easier for them.</p> <span class="bp">self</span><span class="o">.</span><span class="n">extra_libs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">"hello"</span><span class="p">)</span> <span class="c"># Let the super-class do what it needs to.</span> - <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">QtGuiModuleMakefile</span><span class="o">.</span><span class="n">finalise</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> + <span class="n">pyqtconfig</span><span class="o">.</span><span class="n">TQtGuiModuleMakefile</span><span class="o">.</span><span class="n">finalise</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> </pre></div> </div> <p>Again, we hope that the scripts are self documenting.</p> @@ -468,8 +469,8 @@ life easier for them.</p> <table class="docutils footnote" frame="void" id="id12" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id9">[5]</a></td><td>Actually in <tt class="docutils literal"><span class="pre">versions.sip</span></tt>. PyQt uses the <a class="reference external" href="directives.html#directive-%Include"><tt class="xref docutils literal"><span class="pre">%Include</span></tt></a> -directive to split the SIP specification for Qt across a large number of +<tr><td class="label"><a class="fn-backref" href="#id9">[5]</a></td><td>Actually in <tt class="docutils literal"><span class="pre">versions.sip</span></tt>. PyTQt uses the <a class="reference external" href="directives.html#directive-%Include"><tt class="xref docutils literal"><span class="pre">%Include</span></tt></a> +directive to split the SIP specification for TQt across a large number of separate <tt class="docutils literal"><span class="pre">.sip</span></tt> files.</td></tr> </tbody> </table> @@ -535,13 +536,13 @@ by importing modules.</p> sub-classed from one of the SIP provided types. Your types must be registered using <a title="sipRegisterPyType" class="reference external" href="c_api.html#sipRegisterPyType"><tt class="xref docutils literal"><span class="pre">sipRegisterPyType()</span></tt></a>. This is normally done in code specified using the <a class="reference external" href="directives.html#directive-%InitialisationCode"><tt class="xref docutils literal"><span class="pre">%InitialisationCode</span></tt></a> directive.</p> -<p>As an example, PyQt4 uses <a class="reference external" href="directives.html#directive-%DefaultMetatype"><tt class="xref docutils literal"><span class="pre">%DefaultMetatype</span></tt></a> to specify a new -meta-type that handles the interaction with Qt’s own meta-type system. It also +<p>As an example, PyTQt4 uses <a class="reference external" href="directives.html#directive-%DefaultMetatype"><tt class="xref docutils literal"><span class="pre">%DefaultMetatype</span></tt></a> to specify a new +meta-type that handles the interaction with TQt’s own meta-type system. It also uses <a class="reference external" href="directives.html#directive-%DefaultSupertype"><tt class="xref docutils literal"><span class="pre">%DefaultSupertype</span></tt></a> to specify that the smaller <tt class="xref docutils literal"><span class="pre">sip.simplewrapper</span></tt> super-type is normally used. Finally it uses -<a class="reference external" href="annotations.html#canno-Supertype"><tt class="xref docutils literal"><span class="pre">Supertype</span></tt></a> as an annotation of the <tt class="docutils literal"><span class="pre">QObject</span></tt> class to override the +<a class="reference external" href="annotations.html#canno-Supertype"><tt class="xref docutils literal"><span class="pre">Supertype</span></tt></a> as an annotation of the <tt class="docutils literal"><span class="pre">TQObject</span></tt> class to override the default and use <a title="sip.wrapper" class="reference external" href="python_api.html#sip.wrapper"><tt class="xref docutils literal"><span class="pre">sip.wrapper</span></tt></a> as the super-type so that the parent/child -relationships of <tt class="docutils literal"><span class="pre">QObject</span></tt> instances are properly maintained.</p> +relationships of <tt class="docutils literal"><span class="pre">TQObject</span></tt> instances are properly maintained.</p> </div> <div class="section" id="lazy-type-attributes"> <span id="ref-lazy-type-attributes"></span><h2>Lazy Type Attributes<a class="headerlink" href="#lazy-type-attributes" title="Permalink to this headline">¶</a></h2> @@ -566,8 +567,8 @@ ignored.</p> <div class="section" id="support-for-wide-characters"> <h2>Support for Wide Characters<a class="headerlink" href="#support-for-wide-characters" title="Permalink to this headline">¶</a></h2> <p>SIP v4.6 introduced support for wide characters (i.e. the <tt class="docutils literal"><span class="pre">wchar_t</span></tt> type). -Python’s C API includes support for converting between unicode objects and wide -character strings and arrays. When converting from a unicode object to wide +Python’s C API includes support for converting between tqunicode objects and wide +character strings and arrays. When converting from a tqunicode object to wide characters SIP creates the string or array on the heap (using memory allocated using <a title="sipMalloc" class="reference external" href="c_api.html#sipMalloc"><tt class="xref docutils literal"><span class="pre">sipMalloc()</span></tt></a>). This then raises the problem of how this memory is subsequently freed.</p> |