Tutorial
========


Introduction
------------

Qt is a highly complex and versatile toolkit, but this flexibility sometimes
makes it difficult to formulate workflows.  This short tutorial illustrates
a suitable workflow for developing desktop applications with PySide and qte.


Hello World
-----------

All tutorials start with a "Hello World" example::

    import qte
    label = qte.QLabel('Hello World!')
    qte.runApp(label, 'MyApp')

And here is an explanation of each line.

1.  `qte` is imported.  All of PySide's `!QtCore` and `!QtGui` classes,
    can be accessed directly from this namespace, as well as the extra
    objects provided by `qte`.

2.  A new `!QLabel` is created from the `qte` namespace.

3.  The application is launched with the label as the main window and
    the application name as 'MyApp'.

The most important part of this example is the `qte.runApp` function.  This
is essentially equivalent to::

    qte.Application().setApplicationName('MyApp')
    qte.Application().setMainWindow(label)
    win.setWindowTitle('MyApp')
    win.show()
    qte.Application().exec_()
    sys.exit()

Note that `qte.Application` is used instead of `!QApplication`.  The
`qte.Application` class provides a few extra features which make it more
suitable to desktop applications, such as settings management.  It is also
a singleton which on its first initialisation calls
``QApplication([sys.argv])``.


UIs and Resources
-----------------

Qt allows for two ways of designing user interfaces; they can either be hard
coded or created using Qt Designer.  In practice, it is common for a
combination of these methods to be used.  When coding Qt in C++, the normal
workflow consists of designing the UI and creating resources in Qt Designer,
then compiling them into binary files which can be inserted into the
executable.  In python, code is seldom compiled to an executable at all,
so compiling *ui* and *qrc* files becomes a rather annoying and tedious
exercise.  `qte` provides an alternative may of dealing with these.

Resources can be compiled at runtime using `qte.loadResource`.  The binary
data created by this is identical to the output of *rcc*, but the function
is implemented purely in python, with no dependency on *rcc* or *pyside-rcc*
at all.  If used with the *register* argument, it also registers the data
with the resource system so that resources can be used immediately.

PySide's `!QUiLoader` class can be used to create widgets at runtime from
*ui* files.  `qte` extends this with `qte.loadUi` and `qte.uiWrapper`.
`qte.loadUi` does the same job as `!QUiLoader.load`, but first registers
custom widgets and resources.  `qte.uiWrapper` wraps the widget in another
class and is especially useful for `!QMainWindows` which cannot be
promoted in Qt Designer.

The following example shows how to load and inherit from a `!QMainWindow`
interface created in Qt Designer.  The window has a single button called
``showDialog`` which, when clicked, loads and displays a dialog from another
*ui* file with itself as the parent.  The button icon is read from a resource
file::

    import qte

    class MainWindow(qte.UiWrapper('ui/mainwindow.ui'):

        def __init__(self):
            qte.loadResource('icons.qrc', register=True)
            self.showDialog.setIcon(':dialog.png')
            self.showDialog.clicked.connect(self.loadDialog)

        def loadDialog(self):
            dialog = qte.QUiLoader().load('ui/dialog.ui', self)
            dialog.show()


Model/View Programming
----------------------

One of the main problems with Qt's model/view framework in a python
environment is the assumption that data is stored, or only visible through
a `!QAbstractItemModel`.  In C++ this is an ideal structure for storing
structured data, but in python lists and dicts provide more flexibility.
`qte.DataModel` gives this flexibility by wrapping a `!QAbstractItemModel`
interface around generic python structures.  Currently it only supports
tabular data (i.e. which can be displayed in a `!QTableView`), but in the
future tree-like structures will be supported too.

An `qte.DataView` class is inherited from `!QTableView` and has a few extra
features and customised defaults.

There are also several new delegates, all based on `qte.TypedDelegate` which
supports more data types than the default `!QItemDelegate`.