UiSide
======

Additional UI components for PySide_-based applications.

- Save File Dialog `uiside.dialogs.OpenFileDialog`
- Open File Dialog `uiside.dialogs.SaveFileDialog`
- Message Box `uiside.dialogs.MessageBox`

Components
----------

File Dialogs
^^^^^^^^^^^^

File Dialogs are fast and simple solution to let a user point to a file or files
(Open File Dialog) or enter name for a new file (Save File Dialog). They have
the same look and behaviour for all supported platforms. They are usually faster
than native dialogs as they are designed to do as little as possible when a dialog
pops up.

.. code-block:: python

    from uiside.dialogs import OpenFileDialog
    from uiside.dialogs import SaveFileDialog

    # multi=True means possibility to select several files
    dialog = OpenFileDialog(self, multi = True)

    # filters are array of tuples (name, list of masks)
    dialog.setFilters([('Text Files', ['*.txt', '*.cpp']), ('All Files', ['*.*'])])

    # this actually invokes dialog
    result = dialog.exec_()

    # result can be None when user selects Cancel button
    if result:
        fullName, directory, files = result
    else:
        print 'nothing was selected'

The result of `exec_()` method is either `None` when "Cancel" button has been pressed,
or tuple consisting of 3 parts:

- `string` full absolute path to the first selected file
- `string` full absolute path to directory containing selected file(s)
- `list` of selected file names, for example:

.. code-block:: python

    (u'/home/rita/test.txt', u'/home/rita', [u'1.txt', u'2.txt'])

Message Box
^^^^^^^^^^^

This is an extension of standard Message Box with a convenient constructor that
allows to specify title, message text and other parameters. It also has possibility
to show a check box. In this case result of `exec_()` is tuple consisting of

- result of standard QMessageBox_ `exec_()`
- either `True` or `False` representing state of check box

.. code-block:: python

    from uiside.dialogs import MessageBox

    # specify appearance of the dialog
    title = 'Message Box Example'  # window title
    text = '''
    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
    sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
    '''

    # which buttons are available
    buttons = QtGui.QMessageBox.Yes | QtGui.QMessageBox.No

    # default button
    default = QtGui.QMessageBox.No
    glyph = QtGui.QMessageBox.Question  # we can show a nice glyph in the dialog

    box = MessageBox(title, text, 'Do not ask next time', buttons, default, glyph, self)
    print box.exec_()  # tuple is returned
    # see QMessageBox for details on how to interpret the first part

Installation
------------

The `uiside` package requires PySide_ to be installed. The latter is not mentioned
in package dependencies because on most systems PySide is installed as system package.
Should your case not be the same, it is possible to install PySide from PyPI.

The `uiside` package can be installed from PyPI:

.. code-block:: bash

    pip install uiside

Alternatively you may clone the git repository and run demo application:

.. code-block:: bash

    git clone https://github.com/confluenity/uiside.git
    cd uiside
    python app.py

License
-------

License: MIT_.


.. _PySide: https://pypi.python.org/pypi/PySide
.. _QMessageBox: http://doc.qt.io/qt-4.8/qmessagebox.html
.. _MIT: http://opensource.org/licenses/MIT
