aui 0.1.1
An abstraction layer over UI libraries in Python
Requires Python: >=3

python-aui
==========

**aui** is an abstraction layer over user interfaces in Python. It aims to wrap popular ui libraries so that they have common API.

Write code once and import different backend to render the application using different UI library.

Available backends:

- `aui_tk <https://github.com/klausweiss/python-aui-tk>`_

Installation
=============
.. code-block:: bash

   pip install aui

Sample application
===================
.. code-block:: python

   import aui_tk
   from aui import App
   from aui.widgets import (
       Button,
       Input,
       Label,
       Horizontal as H,
       Vertical as V
   )

   user_output = Label('output')
   user_input = Input()

   def set_output(value):
       user_output.text = value

   ui = V( H( Button('submit', onclick=lambda _button: set_output(user_input.value))
            , user_input
            )
         , user_output
         )
   App(ui, title="Sample application").run()


How to use
==========

Import a backend, create an ``App`` with ``ui`` and ``run`` it! ``ui`` is just a widget (or nested widgets):

.. code-block:: python

   from aui import App
   from aui.widgets import Label
   import aui_tk

   App(Label('hi!')).run()


API
~~~

`aui.App(ui, title)`
^^^^^^^^^^^^^^^^^^^^

- **ui** ``Widget``
    a widget to be used as the user interface
- **title** ``str``
    an application title

methods:

- **run()** ``-> void``
    runs the application


Widgets:
========

All the widgets can be imported from ``aui.widgets``.


UI elements
~~~~~~~~~~~

`aui.widgets.Button(text, onclick)`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Represents button

- **text** ``str``
    button text
- **onclick** ``function: Button -> void`` (default: ``None``)
    function invoked after pressing the button

additional attributes:

- **wide**
    using once makes the button wide
                  

`aui.widgets.Checkbox(text, selected, onchange)`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Represents checkbox

- **text** ``str``
    checkbox text
- **selected** ``boolean`` (default: ``False``)
    whether the checkbox is selected on init
- **onchange** ``function: Checkbox -> void`` (default: ``None``)
    function invoked after toggling the checkbox


`aui.widgets.Input(value, onenter)`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Represents single line input field

- **value** ``str`` (default: ``""``)
    default value
- **onenter** ``function: Input -> void`` (default: ``None``)
    function called after the return key is pressed

additional attributes:

- **wide**
    using once makes the input wide


`aui.widgets.Label(text)`
^^^^^^^^^^^^^^^^^^^^^^^^^
Represents label

- **text** ``str``
    label text


`aui.widgets.Text(text)`
^^^^^^^^^^^^^^^^^^^^^^^^
Represents multiline input field

- **text** ``str`` (default: ``""``)
    widget text


Containers
~~~~~~~~~~


`aui.widgets.Horizontal(*children)`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Represents horizontal container

- **\*children** ``[Widget]``
    widgets to be displayed horizontally

methods:

- **append(Widget)** ``Widget -> void``
    appends given widget to the container

`aui.widgets.Vertical(*children)`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Represents vertical container

- **\*children** ``[Widget]``
    widgets to be displayed vertically

methods:

- **append(Widget)** ``Widget -> void``
    appends given widget to the container

Convention
==========

UI code (containers' content) should be indented as follows:

.. code-block:: python

   H( Button('button#1')
    , Label('label#1')
    , H( V( Checkbox('checkbox#1')
          , Button('button#2')
          )
       , Text()
       , Input()
       )
    )


How to contribute
=================

#. Implement more backends (``urwind``, ``ncurses``, ``qt``, ``wxwidgets``, ``gtk``, ``cocoa``)
#. Discuss the API
#. Spread the word! ;)