diff options
| -rw-r--r-- | doc/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | doc/conf.py.in | 4 | ||||
| -rw-r--r-- | doc/extras/PySide.QtCore.Signal.rst | 144 | ||||
| -rw-r--r-- | doc/extras/PySide.QtCore.Slot.rst | 95 |
4 files changed, 242 insertions, 2 deletions
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 7f72f4107..c46054372 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -28,6 +28,7 @@ add_custom_target("docrsts" --documentation-data-dir=${DOC_DATA_DIR} --output-directory=${CMAKE_CURRENT_BINARY_DIR}/rst --documentation-code-snippets-dir=${CMAKE_CURRENT_SOURCE_DIR}/codesnippets + --documentation-extra-sections-dir=${CMAKE_CURRENT_SOURCE_DIR}/extras ${CMAKE_CURRENT_BINARY_DIR}/typesystem_doc.xml WORKING_DIRECTORY ${${module}_SOURCE_DIR} COMMENT "Running generator to generate documentation..." diff --git a/doc/conf.py.in b/doc/conf.py.in index d2d7408b2..b98412650 100644 --- a/doc/conf.py.in +++ b/doc/conf.py.in @@ -42,7 +42,7 @@ master_doc = 'contents' # General information about the project. project = u'PySide' -copyright = u'2009-2010, Nokia Corporation' +copyright = u'2009-2011, Nokia Corporation' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -68,7 +68,7 @@ release = '@BINDING_API_VERSION_FULL@' # List of directories, relative to source directory, that shouldn't be searched # for source files. -exclude_trees = ['_build'] +exclude_trees = ['_build', 'extras'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None diff --git a/doc/extras/PySide.QtCore.Signal.rst b/doc/extras/PySide.QtCore.Signal.rst new file mode 100644 index 000000000..441473eca --- /dev/null +++ b/doc/extras/PySide.QtCore.Signal.rst @@ -0,0 +1,144 @@ +.. module:: PySide.QtCore +.. _Signal: + +Signal +****** + +Synopsis +-------- + +Functions +^^^^^^^^^ + ++---------------------------------------------------------------------------------------------+ +|def :meth:`connect<Signal.connect>` (receiver) | ++---------------------------------------------------------------------------------------------+ +|def :meth:`disconnect<Signal.disconnect>` (receiver) | ++---------------------------------------------------------------------------------------------+ +|def :meth:`emit<Signal.disconnect>` (\*args) | ++---------------------------------------------------------------------------------------------+ + +Detailed Description +-------------------- + + The :class:`~.Signal` class provides a way to declare and connect Qt signals in a pythonic way. + + PySide adopt PyQt's new signal and slot syntax as-is. The PySide implementation is functionally compatible with the PyQt 4.5 one, with the exceptions listed bellow. + + .. note:: Parts of the documentation bellow are from the `PyQt4 documentation <http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/pyqt4ref.html#new-style-signal-and-slot-support>`_ public available on the internet Copyright (c) 2010 Riverbank Computing Limited just modified to fit the PySide implementation. + + +Defining New Signals with QtCore.Signal() +----------------------------------------- + + PySide automatically defines signals for all Qt's built-in signals. New signals can be defined as class attributes using the QtCore.Signal() factory. + + QtCore.Signal() takes a number of type arguments that corresponds to the signature of the signal. Each type may be a Python type object or a string that is the name of a C++ type. Alternatively each argument could be a sequence of type arguments. In this case each sequence defines the signature of a different signal overload. The first overload will be the default. + + QtCore.Signal() takes an optional name keyword argument that is the name of the signal. If it is omitted then the name of the class attribute is used. + + The following example shows the definition of a number of new signals: + + :: + + from PySide import QtCore + + class Foo(QtCore.QObject): + + # This defines a signal called 'closed' that takes no arguments. + closed = QtCore.Signal() + + # This defines a signal called 'rangeChanged' that takes two + # integer arguments. + range_changed = QtCore.Signal(int, int, name='rangeChanged') + + # This defines a signal called 'valueChanged' that has two overloads, + # one that takes an integer argument and one that takes a QString + # argument. + valueChanged = QtCore.Signal((int, ), (unicode, )) + + # The following will create exactly the same overloaded signal as + # above and demonstrates the use of C++ type names instead of Python + # type objects, and lists instead of tuples. + valueChanged = QtCore.pyqtSignal(['int'], ['unicode']) + + New signals should only be defined in sub-classes of QObject. + + New signals defined in this way will be automatically added to the class's QMetaObject. This means that they will appear in Qt Designer and can be introspected using the QMetaObject API. + +Connecting, Disconnecting and Emitting Signals +---------------------------------------------- + + Signals are connected and disconnected to slots using the :meth:`Signal.connect` and :meth:`Signal.disconnect` methods of a bound signal and emitted using the :meth:`Signal.emit` method. + + The following code demonstrates the definition, connection and emit of a signal without arguments: + + :: + + from PySide import QtCore + + class Foo(QtCore.QObject): + # Define a new signal called 'trigger' that has no arguments. + trigger = QtCore.pyqtSignal() + + def connect_and_emit_trigger(self): + # Connect the trigger signal to a slot. + self.trigger.connect(self.handle_trigger) + + # Emit the signal. + self.trigger.emit() + + def handle_trigger(self): + # Show that the slot has been called. + print "trigger signal received" + + The following code demonstrates the connection of overloaded signals: + + :: + + from PySide import QtGui + + class Bar(QtGui.QComboBox): + + def connect_activated(self): + # The PyQt documentation will define what the default overload is. + # In this case it is the overload with the single integer argument. + self.activated.connect(self.handle_int) + + # For non-default overloads we have to specify which we want to + # connect. In this case the one with the single string argument. + # (Note that we could also explicitly specify the default if we + # wanted to.) + self.activated[str].connect(self.handle_string) + + def handle_int(self, index): + print "activated signal passed integer", index + + def handle_string(self, text): + print "activated signal passed string", text + +Connecting Signals Using Keyword Arguments +------------------------------------------ + + It is also possible to connect signals by passing a slot as a keyword argument corresponding to the name of the signal when creating an object. For example the following three fragments are equivalent: + + :: + + act = QtGui.QAction("Action", self) + act.triggered.connect(self.on_triggered) + + act = QtGui.QAction("Action", self, triggered=self.on_triggered) + + +.. method:: Signal.connect(receiver[, type=Qt.AutoConnection]) + + Create a connection between this signal and a `receiver`, the `receiver` can be a Python callable, a :class:`Slot` or a :class:`Signal`. + +.. method:: Signal.disconnect(receiver) + + Disconnect this signal from a `receiver`, the `receiver` can be a Python callable, a :class:`Slot` or a :class:`Signal`. + +.. method:: Signal.emit(*args) + + `args` is the optional sequence of arguments to pass to any connected slots. + diff --git a/doc/extras/PySide.QtCore.Slot.rst b/doc/extras/PySide.QtCore.Slot.rst new file mode 100644 index 000000000..27791d036 --- /dev/null +++ b/doc/extras/PySide.QtCore.Slot.rst @@ -0,0 +1,95 @@ +.. module:: PySide.QtCore +.. _Slot: + +Slot +**** + +Detailed Description +-------------------- + + PySide adopt PyQt's new signal and slot syntax as-is. The PySide implementation is functionally compatible with the PyQt 4.5 one, with the exceptions listed bellow. + + .. note:: Parts of the documentation bellow are from the `PyQt4 documentation <http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/pyqt4ref.html#new-style-signal-and-slot-support>`_ public available on the internet Copyright (c) 2010 Riverbank Computing Limited just modified to fit the PySide implementation. + + Although PySide allows any Python callable to be used as a slot when connecting signals, it is sometimes necessary to explicitly mark a Python method as being a Qt slot and to provide a C++ signature for it. PySide provides the QtCore.Slot() function decorator to do this. + + All of the non-keyword arguments to the decorator are interpreted as the types of the corresponding C++ arguments. A type is either a Python type object or a string that specifies a C++ type. The decorator also takes two optional keywords arguments: name and result. name is the name of the slot that will be seen by C++. If ommitted the name of the Python method being decorated will be used. result is the type of the result and may also be a Python type object or a string that specifies a C++ type. + + For example: + + :: + + @QtCore.Slot() + def foo(self): + """ C++: void foo() """ + + @QtCore.Slot(int, unicode) + def foo(self, arg1, arg2): + """ C++: void foo(int, QString) """ + + @QtCore.Slot(int, name='bar') + def foo(self, arg1): + """ C++: void bar(int) """ + + @QtCore.Slot(int, result=int) + def foo(self, arg1): + """ C++: int foo(int) """ + + @QtCore.Slot(int, QtGui.QWidget) + def foo(self, arg1): + """ C++: int foo(int, QWidget*) """ + + It is also possible to chain the decorators in order to define a Python method several times with different signatures. + + For example: + + :: + + @QtCore.Slot(int) + @QtCore.Slot('QString') + def valueChanged(self, value): + """ Two slots will be defined in the QMetaObject. """ + +Connecting Slots By Name +------------------------ + + PySide supports the QtCore.QMetaObject.connectSlotsByName() function that is most commonly used by pyside-uic generated Python code to automatically connect signals to slots that conform to a simple naming convention besides the QtCore.Slot decoration. + + For example the :class:`PySide.QtGui.QSpinBox` class has the following signals: + + :: + + void valueChanged(int i); + void valueChanged(const QString& text); + + For example, if you were interested in the integer variant of the signal then your slot definition would look like the following: + + :: + + @QtCore.Slot(int) + def on_spinbox_valueChanged(self, i): + # i will be an integer. + pass + + If you wanted to handle both variants of the signal, but with different Python methods, then your slot definitions might look like the following: + + :: + + @QtCore.Slot(int, name='on_spinbox_valueChanged') + def spinbox_int_value(self, i): + # i will be an integer. + pass + + @QtCore.Slot(unicode, name='on_spinbox_valueChanged') + def spinbox_qstring_value(self, s): + # s will be a Python unicode object. + pass + + The following shows an example using a button when you are not interested in the optional argument: + + :: + + @QtCore.Slot() + def on_button_clicked(self): + pass + |