Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebindings@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
author: toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da> 2009-11-25 17:56:58 +0000
committer: toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da> 2009-11-25 17:56:58 +0000
commit: 90825e2392b2d70e43c7a25b8a3752299a933894 (patch)
tree: e33aa27f02b74604afbfd0ea4f1cfca8833d882a /python/pykde/doc/limits.html
download: tdebindings-90825e2392b2d70e43c7a25b8a3752299a933894.tar.gz
tdebindings-90825e2392b2d70e43c7a25b8a3752299a933894.zip
1 files changed, 427 insertions, 0 deletions
diff --git a/python/pykde/doc/limits.html b/python/pykde/doc/limits.html
new file mode 100644
index 00000000..3316c8c9
--- /dev/null
+++ b/python/pykde/doc/limits.html
@@ -0,0 +1,427 @@
+<HTML
+><HEAD
+><TITLE
+>General Limitations</TITLE
+><META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+REL="HOME"
+TITLE="Python Bindings for KDE (PyKDE-3.16.0)"
+HREF="index.html"><LINK
+REL="PREVIOUS"
+TITLE="Python Bindings for KDE (PyKDE-3.16.0)"
+HREF="index.html"><LINK
+REL="NEXT"
+TITLE="Signal and Slot Support"
+HREF="signal.html"></HEAD
+><BODY
+CLASS="SECT1"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+SUMMARY="Header navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>Python Bindings for KDE (PyKDE-3.3.16.0)</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="dcopext.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+></TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="signal.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECT1"
+><H1
+CLASS="SECT1"
+><A
+NAME="AEN28"
+></A
+>General Limitations</H1
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN30"
+></A
+>Python Strings, Qt Strings and Unicode</H2
+><P
+>Unicode support was added to Qt in v2.0 and to Python in v1.6.  In Qt, Unicode
+support is implemented using the <TT
+CLASS="LITERAL"
+>QString</TT
+> class.  It is
+important to understand that <TT
+CLASS="LITERAL"
+>QString</TT
+>s, Python string objects
+and Python Unicode objects are all different but conversions between them are
+automatic in many cases and easy to achieve manually when needed.</P
+><P
+>Whenever PyKDE expects a <TT
+CLASS="LITERAL"
+>QString</TT
+> as a function argument, a
+Python string object or a Python Unicode object can be provided instead, and
+PyKDE will do the necessary conversion automatically.</P
+><P
+>You may also manually convert Python string and Unicode objects to
+<TT
+CLASS="LITERAL"
+>QString</TT
+>s by using the <TT
+CLASS="LITERAL"
+>QString</TT
+> constructor
+as demonstrated in the following code fragment.</P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>qs1 = QString('Converted Python string object')
+qs2 = QString(u'Converted Python Unicode object')</PRE
+></TD
+></TR
+></TABLE
+><P
+>In order to convert a <TT
+CLASS="LITERAL"
+>QString</TT
+> to a Python string object use
+the Python <TT
+CLASS="LITERAL"
+>str()</TT
+> function.  Applying
+<TT
+CLASS="LITERAL"
+>str()</TT
+> to a null <TT
+CLASS="LITERAL"
+>QString</TT
+> and an empty
+<TT
+CLASS="LITERAL"
+>QString</TT
+> both result in an empty Python string object.</P
+><P
+>In order to convert a <TT
+CLASS="LITERAL"
+>QString</TT
+> to a Python Unicode object use
+the Python <TT
+CLASS="LITERAL"
+>unicode()</TT
+> function.  Applying
+<TT
+CLASS="LITERAL"
+>unicode()</TT
+> to a null <TT
+CLASS="LITERAL"
+>QString</TT
+> and an empty
+<TT
+CLASS="LITERAL"
+>QString</TT
+> both result in an empty Python Unicode object.</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN53"
+></A
+>Access to Protected Member Functions</H2
+><P
+>When an instance of a C++ class is not created from Python it is not possible
+to access the protected member functions, or emit the signals, of that
+instance.  Attempts to do so will raise a Python exception.  Also, any Python
+methods corresponding to the instance's virtual member functions will never be
+called.</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN56"
+></A
+>Garbage Collection</H2
+><P
+>C++ does not garbage collect unreferenced class instances, whereas Python does.
+In the following C++ fragment both colours exist even though the first can no
+longer be referenced from within the program:</P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>c = QColor();
+c = QColor();</PRE
+></TD
+></TR
+></TABLE
+><P
+>In the corresponding Python fragment, the first colour is destroyed when
+the second is assigned to <TT
+CLASS="LITERAL"
+>c</TT
+>:</P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>c = QColor()
+c = QColor()</PRE
+></TD
+></TR
+></TABLE
+><P
+>In Python, each colour must be assigned to different names.  Typically this
+is done within class definitions, so the code fragment would be something like:</P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>self.c1 = QColor()
+self.c2 = QColor()</PRE
+></TD
+></TR
+></TABLE
+><P
+>Sometimes a Qt class instance will maintain a pointer to another instance and
+will eventually call the destructor of that second instance. The most common
+example is that a <TT
+CLASS="LITERAL"
+>QObject</TT
+> (and any of its sub-classes) keeps
+pointers to its children and will automatically call their destructors. In
+these cases, the corresponding Python object will also keep a reference to the
+corresponding child objects.</P
+><P
+>So, in the following Python fragment, the first <TT
+CLASS="LITERAL"
+>QLabel</TT
+> is
+not destroyed when the second is assigned to <TT
+CLASS="LITERAL"
+>l</TT
+> because the
+parent <TT
+CLASS="LITERAL"
+>QWidget</TT
+> still has a reference to it.</P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>p = QWidget()
+l = QLabel('First label',p)
+l = QLabel('Second label',p)</PRE
+></TD
+></TR
+></TABLE
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN72"
+></A
+>C++ Variables</H2
+><P
+>Access to C++ variables is supported.  They are accessed as Python instance
+variables.  For example:</P
+><TABLE
+BORDER="0"
+BGCOLOR="#E0E0E0"
+WIDTH="100%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>tab = QTab()
+tab.label = "First Tab"
+tab.r = QRect(10,10,75,30)</PRE
+></TD
+></TR
+></TABLE
+><P
+>Global variables and static class variables are effectively read-only.  They
+can be assigned to, but the underlying C++ variable will not be changed.  This
+may change in the future.</P
+><P
+>Access to protected C++ class variables is not supported.  This may change in
+the future.</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN78"
+></A
+>Multiple Inheritance</H2
+><P
+>It is not possible to define a new Python class that sub-classes from more than
+one Qt class.</P
+></DIV
+></DIV>
+
+<H2 CLASS="SECT2">tr() methods</H2>
+<P>
+In a normal Qt installation, every descendant of QObject inherits two methods
+(tr (const char *) and tr (const char *, const char *) from QObject explicitly
+and also overloads these methods via the moc mechanism (by defining Q_OBJECT
+in the class declaration). KDE however is compiled with -DQT_NO_TRANSLATION,
+which prevents moc from creating the overloading tr() methods, and also produces
+side-effects with a normal Qt installation which was compiled without the
+-DQT_NO_TRANSLATION switch.
+</P>
+<P>
+PyKDE handles this situation by NOT providing tr() methods (either the inherited
+methods from QObject or the moc generated methods) for any KDE based QObject
+descendant. The tr() methods are static, so QObject::tr () methods are available
+via PyQt, as are tr() methods for any PyQt QObject descendant. PyKDE's handling
+of these methods has no effect on PyQt.
+</P>
+<P>Instead of the tr() methods, KDE uses corresponding i18n() methods for translating.
+These methods are available in the kdecore module of PyKDE. For compatibility with
+KDE, you should use the i18n methods.
+</P>
+<H2>Socket classes</H2>
+<P>
+The following classes (introduced in KDE2.2.0) are NOT yet implemented:
+</P>
+<TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%">
+<TR>
+<TD>
+<PRE CLASS="PROGRAMLISTING">
+KAddressInfo
+KExtendedSocket
+KInetSocketAddress
+KSocketAddress
+KUnixSocketAddress
+KSocks
+</PRE>
+</TD>
+</TR>
+</TABLE>
+<P>
+Most of their functionality already exists in the Python socket class or in the
+KSocket class (kdecore module). These classes may be implemented at a future date
+(they require support for C socket structures and careful handling to avoid buffer
+overflow problems/exploits)
+</P>
+
+<DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="dcopext.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="index.html"
+ACCESSKEY="H"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="signal.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>DCOP and Extensions</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+>&nbsp;</TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Signal and Slot Support</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
author	toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>	2009-11-25 17:56:58 +0000
committer	toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>	2009-11-25 17:56:58 +0000
commit	90825e2392b2d70e43c7a25b8a3752299a933894 (patch)
tree	e33aa27f02b74604afbfd0ea4f1cfca8833d882a /python/pykde/doc/limits.html
download	tdebindings-90825e2392b2d70e43c7a25b8a3752299a933894.tar.gz tdebindings-90825e2392b2d70e43c7a25b8a3752299a933894.zip