From 5c6eb8b91309ab5449bc9d0fa77394d393be19b1 Mon Sep 17 00:00:00 2001
From: Luciano Wolf <luciano.wolf@openbossa.org>
Date: Mon, 14 Jun 2010 16:59:58 -0300
Subject: Documentation about new API2.

---
 doc/pysideapi2.rst | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 doc/pysideapi2.rst

(limited to 'doc')

diff --git a/doc/pysideapi2.rst b/doc/pysideapi2.rst
new file mode 100644
index 000000000..2c111bd23
--- /dev/null
+++ b/doc/pysideapi2.rst
@@ -0,0 +1,104 @@
+PySide API 2
+************
+
+Since the beginning one of the PySide goals was to be API compatible with PyQt4,
+but with some (documented) exceptions. For example, PySide will not export to
+Python components marked as deprecated on C++ Qt.
+
+The latest release of PyQt4 came with improvements on the pythonic front, being
+the extinction of QString a good example. PySide followed this change, except in
+one point: while PyQt4 has conserved the old behavior as optional, PySide
+bindings fully adopted the new API - completely removing QString. No turning
+back. Thus remember to update your source code to the new API, this will ensure
+your code will run on both bindings.
+
+
+Changes:
+
+- __hash__() function return value
+- QString
+- QTextStream
+- QVariant
+
+
+__hash__() function return value
+================================
+
+The hash value returned for the classes QDate, QDateTime, QTime, QUrl will be
+based on their string representations, thus objects with the same value will
+produce the same hash.
+
+
+QString
+=======
+
+Methods that change QString arguments
+-------------------------------------
+
+Methods and functions that change the contents of a QString argument were
+modified to receive an immutable Python unicode (or str) and return another
+Python unicode/str as the modified string.
+
+The following methods had their return types modified this way:
+
+**Classes:** QAbstractSpinBox, QDateTimeEdit, QDoubleSpinBox, QSpinBox, QValidator
+
+Method / Return type
+
+- *fixup(string)*: string
+- *validate(string, int)*: [QValidator.State, string, int]
+
+
+**Classes:** QDoubleValidator, QIntValidator, QRegExpValidator
+
+Method / Return type
+
+- *validate(string, int)*: [QValidator.State, string, int]
+
+**Class:** QClipboard
+
+Method / Return type
+
+- *text(string, QClipboard.Mode mode=QClipboard.Clipboard)*: [string, string]
+
+
+**Class:** QFileDialog
+
+Instead of *getOpenFileNameAndFilter()*, *getOpenFileNamesAndFilter()* and *getSaveFileNameAndFilter()* like PyQt4 does,
+PySide has modified the original methods to return a tuple.
+
+Method / Return type
+
+- *getOpenFileName(QWidget parent=None, str caption=None, str dir=None, str filter=None, QFileDialog.Options options=0)*: [string, filter]
+- *getOpenFileNames(QWidget parent=None, str caption=None, str dir=None, str filter=None, QFileDialog.Options options=0)*: [list(string), filter]
+- *getSaveFileName(QWidget parent=None, str caption=None, str dir=None, str filter=None, QFileDialog.Options options=0)*: [string, filter]
+
+**Class:** QWebPage
+
+Method / Return type
+
+- *javaScriptPrompt(QWebFrame, string, string)*: [bool, string]
+
+Other QString related changes
+-----------------------------
+
+**Classes:** QFontMetrics and QFontMetricsF
+
+They had two new methods added. Both take a string of one character and convert to a QChar (to call the C++ counterpart):
+
+- widthChar(string)
+- boundingRectChar(string)
+
+
+QTextStream
+===========
+
+Inside this class some renames were applied to avoid clashes with native Python functions. They are: *bin_()*, *hex_()* and *oct_()*.
+The only modification was the addition of '_' character.
+
+
+QVariant
+========
+
+As QVariant was removed, any function expecting it can receive any Python object (None is an invalid QVariant). The same rule is valid when returning something: the returned QVariant will be converted to the its original Python object type.
+
-- 
cgit v1.2.3