From 87c67294301eb53c67e949ff50b991afe24d80c0 Mon Sep 17 00:00:00 2001 From: Luciano Wolf Date: Fri, 8 Oct 2010 18:13:17 -0300 Subject: Updating documentation to reflect adoption of wikipages. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reviewer: Renato Araújo --- doc/_templates/index.html | 24 +---- doc/_themes/pysidedocs/modindex.html | 40 +++++++ doc/contents.rst | 5 - doc/dbus.rst | 30 ------ doc/generatingdocs.rst | 42 -------- doc/howto-build/cmake-primer.rst | 72 ------------- doc/howto-build/index.rst | 19 ---- doc/howto-build/setup-apiextractor.rst | 52 --------- doc/howto-build/setup-bindings.rst | 82 --------------- doc/howto-build/setup-generator.rst | 50 --------- doc/howto-build/shiboken.rst | 54 ---------- doc/issuesdiff.rst | 14 --- doc/newsigslot.rst | 187 --------------------------------- doc/property.rst | 44 -------- 14 files changed, 41 insertions(+), 674 deletions(-) create mode 100644 doc/_themes/pysidedocs/modindex.html delete mode 100644 doc/dbus.rst delete mode 100644 doc/generatingdocs.rst delete mode 100644 doc/howto-build/cmake-primer.rst delete mode 100644 doc/howto-build/index.rst delete mode 100644 doc/howto-build/setup-apiextractor.rst delete mode 100644 doc/howto-build/setup-bindings.rst delete mode 100644 doc/howto-build/setup-generator.rst delete mode 100644 doc/howto-build/shiboken.rst delete mode 100644 doc/issuesdiff.rst delete mode 100644 doc/newsigslot.rst delete mode 100644 doc/property.rst diff --git a/doc/_templates/index.html b/doc/_templates/index.html index 8038bb1b7..c9d9c591f 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -2,7 +2,7 @@ {% set title = 'Overview' %} {% block body %}
-

PySide {{ version }}

+

PySide {{ version }} Reference

Qt is a cross-platform application framework from Qt Software (owned by Nokia). It features a large number of libraries providing services like network abstraction and XML handling, along with a very rich @@ -11,28 +11,6 @@

PySide is built using the Shiboken binding generator.

-

Documentation

- - - -
-

PyQt Incompatibilities
- PySide issues and specificities

-

DBus
- DBus integration

-

How to build
- building compiling and installing PySide

- 		-

Contents
- for a complete overview

- -

New-style signal/slot
- using the new-style signal/slot scheme

- -

Use of QProperty in PySide
- QProperty

-
-

Modules

diff --git a/doc/_themes/pysidedocs/modindex.html b/doc/_themes/pysidedocs/modindex.html new file mode 100644 index 000000000..b00a4401f --- /dev/null +++ b/doc/_themes/pysidedocs/modindex.html @@ -0,0 +1,40 @@ +{% extends "layout.html" %} +{% set title = _('Global Module Index') %} +{% block extrahead %} +{{ super() }} +{% if not embedded and collapse_modindex %} + +{% endif %} +{% endblock %} +{% block body %} +
+

{{ _('Global Module Index') }}

+ + {%- for letter in letters %} + {{ letter }} {% if not loop.last %}| {% endif %} + {%- endfor %} +
+ + + {%- for modname, collapse, cgroup, indent, fname, synops, pform, dep, stripped in modindexentries %} + {%- if not modname -%} + {%- else -%} + + + + {%- endif -%} + {% endfor %} +
{% if collapse -%} + + {%- endif %}{% if indent %}   {% endif %} + {% if fname %}{% endif -%} + {{ stripped|e }}{{ modname|e }} + {%- if fname %}{% endif %} + {%- if pform and pform[0] %} ({{ pform|join(', ') }}){% endif -%} + {% if dep %}{{ _('Deprecated')}}:{% endif %} + {{ synops|e }}
+ +{% endblock %} diff --git a/doc/contents.rst b/doc/contents.rst index aa2b645ec..9ff4fb3de 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -4,11 +4,6 @@ PySide Documentation contents .. toctree:: :maxdepth: 2 - howto-build/index.rst - generatingdocs.rst - issuesdiff.rst - dbus.rst - modules.rst Indices and tables diff --git a/doc/dbus.rst b/doc/dbus.rst deleted file mode 100644 index 0e57d0b87..000000000 --- a/doc/dbus.rst +++ /dev/null @@ -1,30 +0,0 @@ -DBUS integration -**************** - -To get PySide and DBus working toghether you can use the glib mainloop integration already done in pydbus. - -The example above show how to export Qt objects to python and emit an DBus signal when a Qt signal is emited. The code comments explains what you need to know about PySide and dbus, any doubts, see the python-dbus help. - -DBUS Client ------------ - -.. literalinclude:: codesnippets/examples/dbus/example-client.py - - -DBUS Server ------------ - -.. literalinclude:: codesnippets/examples/dbus/example-server.py - - -Running the example -------------------- - -Copy the client code to a file called ``example-client.py`` and the server to a file called ``example-server.py`` and type: - -:: - - $ python example-server.py & - $ python example-client.py - -A litle window should appear on screen. Click on the button to emit a Qt signal, this signal will be converted to a DBus signal that will be caught by our dbus client. That's all. diff --git a/doc/generatingdocs.rst b/doc/generatingdocs.rst deleted file mode 100644 index 666df8146..000000000 --- a/doc/generatingdocs.rst +++ /dev/null @@ -1,42 +0,0 @@ -How to generate this documentation -********************************** - -Pre-requisites --------------- - -You will need: - -1. Qt4 source code (for API documentation). -2. Generator runner with shiboken plugin -3. PySide source code -4. cmake -5. sphinx -6. graphviz - -Extracting documentation from Qt4 ---------------------------------- - -The API documentation is generated from source code comments (for now, just -``qdoc3`` tool is supported, ``doxygen`` support will be added soon). - -``qdoc3`` is the tool used to generate the oficial Qt4 documentation, you will -use it to generate a bunch of XML files that will be used by the generator -to create the documentation. - -You need to tell PySide where it can find the Qt source code, to do this, when running cmake add the following parameters: - -:: - - $ mkdir build - $ cmake -DQT_SRC_DIR=PATH_TO_QT_SOURCE_DIR .. - $ make apidoc - $ make apidocinstall - -Where: - * *PATH_TO_QT_SOURCE_DIR* is the path to the Qt sources. - -The documentation will be installed at ``/share/doc/pyside/index.html``, change -the *CMAKE_INSTALL_PREFIX* value if you want to install the documentation in another -directory. - -If you want to have inheritance graphs on the generated documentation, make sure you have the bindings installed before generate the documentation. diff --git a/doc/howto-build/cmake-primer.rst b/doc/howto-build/cmake-primer.rst deleted file mode 100644 index 6d9224cbd..000000000 --- a/doc/howto-build/cmake-primer.rst +++ /dev/null @@ -1,72 +0,0 @@ - -.. _cmake-primer: - -************ -CMake primer -************ - -This chapter is a basic introduction to CMake, the build system used by PySide -and the bindings generator. - -The practical steps will focus on how to use CMake on a Unix-like (GNU/Linux) -environment. - - -Configuring -=========== - -Project file - CMakeLists.txt ------------------------------ - -CMake parses the file CMakeLists.txt for information about the project, -like project name, dependencies, what should be compiled, what should be -shipped, and so on. - - -CMake variables ---------------- - -CMake can have its default behavior modified by providing some options in the command line: - -* ``CMAKE_INSTALL_PREFIX=`` sets the install prefix to - the specified path. -* ``CMAKE_MODULE_PATH=`` sets the extra directories - where CMake will try to find its modules. -* ``CMAKE_TOOLCHAIN_FILE=`` sets the path to the file that - describes the toolchain used to compile this project. It is very useful - when using CMake with `Icecream `_ to speed up compilation. - -You can define a variable using the ``-D`` switch like the example -below. - -* ``-DCMAKE_BUILD_TYPE=Release|Debug`` sets the building behavior. Default - value is Release. - -Invoking CMake --------------- - -After writing the CMakeLists.txt and deciding which flags will be used, -you can invoke CMake using:: - - cmake - -For example, if you use the ``build/`` folder to build the project and -want it to be installed into ``/opt/sandbox/``, use the following lines:: - - cd build/ - cmake -DCMAKE_INSTALL_PREFIX=/opt/sandbox .. - -CMake will process the project file and write the output files in the -current directory. - -Building -======== - -After the configuration process, the Makefiles are written and you can build -the project using :program:`make`. - -Installing -========== - -As in the building process, :program:`make install` will install the files into -the target directory. diff --git a/doc/howto-build/index.rst b/doc/howto-build/index.rst deleted file mode 100644 index e8d1cd100..000000000 --- a/doc/howto-build/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. PySide documentation master file, created by sphinx-quickstart on Fri Mar 6 11:45:08 2009. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Getting started with PySide -=========================== - -Contents: - -.. toctree:: - :maxdepth: 2 - - cmake-primer - setup-apiextractor - setup-generator - shiboken - setup-bindings - - diff --git a/doc/howto-build/setup-apiextractor.rst b/doc/howto-build/setup-apiextractor.rst deleted file mode 100644 index 18f5d4d31..000000000 --- a/doc/howto-build/setup-apiextractor.rst +++ /dev/null @@ -1,52 +0,0 @@ - -.. _api-extractor: - -************** -API Extractor -************** - -Overview -======== - -The **API Extractor** library is used by the bindings generator to -parse the header and typesystem files to create an internal -representation of the API. It is based on the -`QtScriptGenerator `_ -codebase. - -Getting the sources -=================== - -* Download URL: http://www.pyside.org/downloads/ - -Build requirements -================== - -+ CMake >= 2.6.0 -+ Qt4.5 libraries and development headers >= 4.5 -+ libxml2 libraries and development headers >= 2.6.32 -+ libxslt libraries and development headers >= 1.1.19 - -Building and installing -======================= - -To build and install just follow the generic CMake instructions in section -:ref:`cmake-primer`. - -Debian packaging -================ - -In order to compile this package in a Debian environment, make sure the -following packages are installed: - -* debhelper (>= 7) -* cmake (>= 2.6.0) -* libqt4-dev (>= 4.5) -* libxml2-dev -* libxslt1-dev -* pkg-config -* python-sphinx - -And then you can build the package using:: - - $ dpkg-buildpackage -rfakeroot diff --git a/doc/howto-build/setup-bindings.rst b/doc/howto-build/setup-bindings.rst deleted file mode 100644 index 87feec963..000000000 --- a/doc/howto-build/setup-bindings.rst +++ /dev/null @@ -1,82 +0,0 @@ -*************** -Qt 4.6 Bindings -*************** - -Overview -======== - -These bindings allow access of Qt 4.6 libraries as Python modules, -making them available just using the ``import`` command. - -The build process is comprised of two stages: in a first moment the -bindings source code are created from the Qt 4.6 headers by calling -the :ref:`generator-runner` with apropriate parameters; the -generated files are then compiled and linked together to form the -bindings libraries. - -The bindings available at the moment are listed below: - - + QtCore - + QtGui - + QtHelp - + QtMultimedia - + QtNetwork - + QtOpenGL - + QtScript - + QtScriptTools - + QtSql - + QtSvg - + QtUiTools - + QtWebKit - + QtXml - + QtXmlPatterns - + Phonon - -Getting the sources -=================== - -* Download URL: http://www.pyside.org/downloads/ - -Build requirements -================== - - + CMake (>= 2.6.0) - + Qt4.6 libraries and development headers - + Python dev libraries - + Shiboken libraries - + :ref:`generator-runner` - - -Building and installing -======================= - -To build and install just follow the generic cmake instructions in -section :ref:`cmake-primer`. - -Be advised that the build process can be rather lenghty because of the -number of source files that will be compiled. - -Debian packaging -================ - -.. note:: Qt 4.6 is available for Debian in the testing branch (squeeze), Ubuntu 10.04 (Lucid Lynx), and in Maemo 5 (Fremantle) in the upcoming PR 1.2 update. - -In order to compile this package in a Debian environment, make sure the -following packages are installed: - -* debhelper (>= 7) -* cmake (>= 2.6.0) -* python-all-dev -* python-all-dbg -* python-support (>= 0.3.9) -* libqt4-dev -* libphonon-dev -* libqt4-opengl-dev -* shiboken (>= 0.3.0) -* generatorrunner (>= 0.4.1) -* libshiboken-dev (>= 0.3.0) - - -And then you can build the package using:: - - $ dpkg-buildpackage -rfakeroot diff --git a/doc/howto-build/setup-generator.rst b/doc/howto-build/setup-generator.rst deleted file mode 100644 index 6c231ccb5..000000000 --- a/doc/howto-build/setup-generator.rst +++ /dev/null @@ -1,50 +0,0 @@ - -.. _generator-runner: - -**************** -Generator Runner -**************** - -Overview -========================================= - -The **Generator Runner** (A.K.A. :program:`generatorrunner`) is the -program that controls the bindings generation process according to the -rules given by the user through headers, typesystem files and generator -front-ends (such as :ref:`shiboken-generator`). It depends on -:ref:`api-extractor` library. - - -Getting the sources -=================== - -* Download URL: http://www.pyside.org/downloads/ - -Build requirements -================== - -+ CMake >= 2.6.0 -+ Qt4.5 libraries and development headers >= 4.5.0 -+ :ref:`api-extractor` + development headers - -Building and installing -======================= - -To build and install just follow the generic CMake instructions in -section :ref:`cmake-primer`. - -Debian packaging -================ - -In order to compile this package in a Debian environment, make sure the -following packages are installed: - -* debhelper (>= 7) -* cmake (>= 2.6.0) -* libqt4-dev (>= 4.5) -* libapiextractor-dev (>= 0.5.0) -* libxlst-dev - -And then you can build the package using:: - - $ dpkg-buildpackage -rfakeroot diff --git a/doc/howto-build/shiboken.rst b/doc/howto-build/shiboken.rst deleted file mode 100644 index d5c19de5b..000000000 --- a/doc/howto-build/shiboken.rst +++ /dev/null @@ -1,54 +0,0 @@ - -.. _shiboken-generator: - -****************** -Shiboken Generator -****************** - -Overview -========================================= - -The **Shiboken Generator** (A.K.A. :program:`shiboken`) is -the plugin that creates the PySide bindings source files from Qt headers -and auxiliary files (typesystems, ``global.h`` and glue files). It depends on -:ref:`generator-runner` and :ref:`api-extractor` library. - - -Getting the sources -=================== - -* Download URL: http://www.pyside.org/downloads/ - -Build requirements -================== - -+ CMake >= 2.6.0 -+ Qt libraries and development headers >= 4.5.0 -+ Python development headers >= 2.5 -+ :ref:`api-extractor` + development headers -+ :ref:`generator-runner` + development headers - -Building and installing -======================= - -To build and install just follow the generic CMake instructions in -section :ref:`cmake-primer`. - -Debian packaging -================ - -In order to compile this package in a debian environment, make sure the -following packages are installed: - -* debhelper (>= 7) -* cmake (>= 2.6.0) -* libqt4-dev (>= 4.5) -* libapiextractor-dev (>= 0.5.0) -* libgenrunner-dev (>= 0.4.1) -* generatorrunner (>= 0.4.1) -* python-all-dev -* python-all-dbg - -And then you can build the package using:: - - $ dpkg-buildpackage -rfakeroot diff --git a/doc/issuesdiff.rst b/doc/issuesdiff.rst deleted file mode 100644 index 4c472aea1..000000000 --- a/doc/issuesdiff.rst +++ /dev/null @@ -1,14 +0,0 @@ -PySide issues and specificities -******************************* - -This document shows some points not supported by PySide. - -Deprecated Methods ------------------- - -The deprecated methods before Qt 4.4 is not supported by PySide, -e.g.: `QColor.dark()` and `QColor.light()`. - -**How to solve:** update the methods with new ones like `QColor.darker()` -and `QColor.lighter()`. - diff --git a/doc/newsigslot.rst b/doc/newsigslot.rst deleted file mode 100644 index 99db7e0d6..000000000 --- a/doc/newsigslot.rst +++ /dev/null @@ -1,187 +0,0 @@ -New-style signal/slot -********************* -The new-style signal/slot was introduced by Riverbank on its PyQt v4.5. The main goal of this new-style is to provide a more pythonic syntax to the Python programmers. PySide uses `PSEP100 `_ as its implementation guideline. - -Old way: SIGNAL() and SLOT() ----------------------------- -Both QtCore.SIGNAL(...) and QtCore.SLOT(...) macros allow Python to interface with Qt mechanisms. This is the old way of using signals/slots. - -The example below uses the well known *clicked* signal from a *QPushButton*. The *connect* method has a non python-friendly syntax. It is necessary to inform the object, its signal (via macro) and a slot to be connected to. - -:: - - ... - - def someFunc(): - print "someFunc has been called!" - - ... - - button = QtGui.QPushButton("Call someFunc") - QtCore.QObject.connect(button, QtCore.SIGNAL('clicked()'), someFunc) - - ... - - -Next section shows how everything has changed to become more pythonic. - -New way: Signal() and Slot() ----------------------------- -The new-style uses a different syntax to create and to connect signals/slots. The previous example could be rewritten as: - -:: - - ... - - def someFunc(): - print "someFunc has been called!" - - button = QtGui.QPushButton("Call someFunc") - button.clicked.connect(someFunc) - - ... - - -Using QtCore.Signal() ---------------------- -Signals can be defined using the *QtCore.Signal()* class. Python types and C types can be passed as parameters to it. If you need to overload it just pass the types as tuples or lists. - -Besides that it can receive also a named argument *name* that defines the signal name. If nothing is passed as *name* then the new signal will have the same name as the variable that it is being assigned to. - -The section `Putting everything together`_ has a collection of examples that shows a bunch of situation using the *Signal()* class. - -**Note**: Signals should be defined only inside classes inheriting from QObject. This way the signal information is added to the class QMetaObject structure. - - -Using QtCore.Slot() -------------------- -Slots are assigned and overloaded using the decorator *QtCore.Slot()*. Again, to define a signature just pass the types like the *QtCore.Signal()* class. Unlike the *Signal()* class, to overload a function you don't pass every variation as tuple or list. Instead of that you have to define a new decorator for every different signature. The examples section below will make it clearer. - -Another difference is about its keywords. *Slot()* accepts a *name* and a *result*. The *result* keyword defines the type that will be returned and can be a C or Python type. The *name* behaves the same way as in *Signal()*. If nothing is passed as *name* then the new slot will have the same name as the function that is being decorated. - -Putting everything together ---------------------------- -Nothing better than examples to show how to use the new-style. Here you can find some code covering a good range of cases, from basic connections to more complex situations. - -- **Hello World example**: the basic example, showing how to connect a signal to a slot without any parameters. - -:: - - import sys - from PySide import QtCore, QtGui - - # define a function that will be used as a slot - def sayHello(): - print 'Hello world!' - - app = QtGui.QApplication(sys.argv) - - button = QtGui.QPushButton('Say hello!') - - # connect the clicked signal to the sayHello slot - button.clicked.connect(sayHello) - button.show() - - sys.exit(app.exec_()) - -- **Lets add some arguments**: this is a modified *Hello World* version. It adds some arguments to the slot and creates a new signal. - -:: - - import sys - from PySide import QtCore - - # define a new slot that receives a string and has - # 'saySomeWords' as its name - @QtCore.Slot(str) - def saySomeWords(words): - print words - - class Communicate(QtCore.QObject): - # create a new signal on the fly and name it 'speak' - speak = QtCore.Signal(str) - - someone = Communicate() - # connect signal and slot - someone.speak.connect(saySomeWords) - # emit 'speak' signal - someone.speak.emit("Hello everybody!") - -- **Lets add some overloads**: a little more modification on the previous example now including overloads. - -:: - - import sys - from PySide import QtCore - - # define a new slot that receives a C 'int' or a 'str' - # and has 'saySomething' as its name - @QtCore.Slot(int) - @QtCore.Slot(str) - def saySomething(stuff): - print stuff - - class Communicate(QtCore.QObject): - # create two new signals on the fly: one will handle - # int type, the other will handle strings - speakNumber = QtCore.Signal(int) - speakWord = QtCore.Signal(str) - - someone = Communicate() - # connect signal and slot properly - someone.speakNumber.connect(saySomething) - someone.speakWord.connect(saySomething) - # emit each 'speak' signal - someone.speakNumber.emit(10) - someone.speakWord.emit("Hello everybody!") - - -- **Lets complicate even more**: now with overloads and complicated connections and emissions. - -:: - - import sys - from PySide import QtCore - - # define a new slot that receives an C 'int' or a 'str' - # and has 'saySomething' as its name - @QtCore.Slot(int) - @QtCore.Slot(str) - def saySomething(stuff): - print stuff - - class Communicate(QtCore.QObject): - # create two new signals on the fly: one will handle - # int type, the other will handle strings - speak = QtCore.Signal((int,), (str,)) - - someone = Communicate() - # connect signal and slot. As 'int' is the default - # we have to specify the str when connecting the - # second signal - someone.speak.connect(saySomething) - someone.speak[str].connect(saySomething) - - # emit 'speak' signal with different arguments. - # we have to specify the str as int is the default - someone.speak.emit(10) - someone.speak[str].emit("Hello everybody!") - - -PyQt compatibility ------------------- -PyQt uses a different naming convention to its new signal/slot functions. In order to convert any PyQt script that uses this new-style to run with PySide just use one the proposed modifications below: - -:: - - from PySide.QtCore import Signal as pyqtSignal - from PySide.QtCore import Slot as pyqtSlot - -or - -:: - - QtCore.pyqtSignal = QtCore.Signal - QtCore.pyqtSlot = QtCore.Slot - -This way any call to *pyqtSignal* or *pyqtSlot* will be translated to a *Signal* or *Slot* call. diff --git a/doc/property.rst b/doc/property.rst deleted file mode 100644 index 88db8d68e..000000000 --- a/doc/property.rst +++ /dev/null @@ -1,44 +0,0 @@ -Use of QProperty in PySide -************************** - -PySide implements the function 'QProperty' which allows to declare properties compatible with QMetaProperties. - - -Using PySide.QProperty() ------------------------- - -The QProperty works like Q_PROPERTY macro, and uses the same arguments. - -QProperty(getFunction, [setFunction], [resetFunction], [Designable], [Scriptable], [Stored], [User]) - - -The example below uses QProperty function to export a property in QMetaObject data. - -:: - - ... - clas MyObject(QObject): - def getX(self): - ... - - def setX(self, value): - ... - - def resetX(self): - ... - - X = QProperty(getX, setX, resetX, True, True, True, True) - - ... - - -The exported property works like native python property on python side. See the example below. - -:: - - ... - o = MyObject() - o.X = 10 - print o.X - ... - -- cgit v1.2.3