cs20-easygui 0.9.5

"Inspired by EasyGUI, designed for PyQt"

===============================
EasyGUI_Qt
===============================

*Inspired by EasyGUI, designed for PyQt*

.. image:: https://raw.githubusercontent.com/aroberge/easygui_qt/master/images/contribute.png


EasyGUI_Qt is a module for simple and easy GUI programming in Python.

EasyGUI_Qt was inspired by EasyGUI created by Stephen Ferg and
is based on Tkinter. By contrast, EasyGUI_Qt is based on PyQt
which is not included in the standard Python distribution - but is
included in some other distributions like Continuum Analytics' Anaconda.


.. image:: https://badge.fury.io/py/easygui_qt.png
:target: http://badge.fury.io/py/easygui_qt

.. image:: https://pypip.in/d/easygui_qt/badge.png
:target: https://pypi.python.org/pypi/easygui_qt

.. image:: https://badge.waffle.io/aroberge/easygui_qt.png?label=ready&title=Ready
:target: https://waffle.io/aroberge/easygui_qt
:alt: 'Stories in Ready'


* Free software: BSD license
* Documentation: https://easygui_qt.readthedocs.org.

Python version
--------------

Officially, this is a project that targets only Python 3. However, I have
now decided to attempt to provide some support for Python 2. Other than
some unicode issues, all widgets should work with Python 2.

Design philosophy
-----------------

Like the original EasyGUI, EasyGUI_Qt seeks to provide simple GUI widgets
that can be called in a procedural program. EasyGUI_Qt is NOT event-driven: all GUI interactions are invoked
by simple function calls.

The archetype is ``get_string(message)``
which pops a box whose purpose is exactly the same as Python's ``input(prompt)``,
that is, present the user with a question/prompt, have the user enter an
answer, and return the provided answer as a string. Thus
``easygui_qt.get_string()`` can be used as a drop-in replacement for
``input()``.
Similarly, instead of using a ``print()`` function to display a message,
``show_message()`` is used which pops a message window; however, note that
unlike ``print``, ``show_message`` interrupts the flow of the program
and require some interaction from the user for the program to
continue.

Unlike the original EasyGUI, which sometimes used cryptic names like
``msgbox`` or ``ynbox``, EasyGUI_Qt attempts to use descriptive names
which follow PEP8 convention. Thus, instead of ``msgbox``, it uses
``show_message``; instead of ``ynbox``, it has ``get_yes_or_no``.
Most function names start with either ``get_``, ``show_`` or ``set_``.

EasyGUI_QT is based on PyQt; it leverages the available dialogs that
come with PyQt whenever possible. This makes it possible to have
automatic translation of some GUI elements (such as text on standard buttons)
provided the locale is set correctly and that the local distribution of
PyQt includes the appropriate translation: when EasyGUI_Qt runs, it scans
the standard PyQt location for translation files and note which ones are
present and can be used when the locale is set.

An attempt is made at avoiding duplication of essentially
identical functionality. Thus, multiple selections from a list of choices
is done only one way: by using a dialog where choices appear as labels
in text and not labels on buttons.

Roadmap
-------

See https://github.com/aroberge/easygui_qt/issues/13 and feel free
to add comments.

Similar projects
----------------

The following is an incomplete lists of a few cross-platform projects
that share some similarity with EasyGUI_Qt, but use back-ends other than PyQt

- `easygui <http://easygui.sourceforge.net/>`_: the original; tkinter back-end
- `anygui <http://anygui.sourceforge.net/>`_: multiple back-ends; well known
but no longer supported
- `psidialogs <https://github.com/ponty/psidialogs>`_: multiple back-ends supported -
possibly the most complete project from that point of view.
- `python-dialog <http://pythondialog.sourceforge.net/>`_: dialog/Xdialog/gdialog back-end

There are quite a few lesser known projects but none that seem to be
actively supported. If you are aware of other projects that should
be mentioned, do not hesitate to contact me and let me know.




History
=======

0.9.5
-----

Changes by Dan Schellenberg:
- added a get_file_name function, so students do not need to worry about
extracting the path from a list when choosing a single file

0.9.3
-----

Changes by Dan Schellenberg:
- set PyQt5 as a dependency so pip autoinstalls it
This means that a student using an IDE such as Thonny can install a single package


0.9.2
-----

(Some of the changes noted are addition or improvements submitted by David Hughes via email)

- TextWindow now shows input either from a file or from a supplied string.
- added show_code()
- added show_text()
- renamed show() to show_message() [reverting change from 0.9.1]
- started creation of custom "page format" for more complex dialogs
- changed get_date() so that it returns a datetime date instance

Note: the documentation has NOT been updated to reflect these changes.

0.9.1
-----

- removed verification from get_new_password
- added find_help
- created "back end" for wizard creator - will become show_story()
- documented and changed naming convention
- renamed select_language() : get_language()
- renamed show_message() : show()
- fixed a unicode bug for Python 2
- changed the way show_file works
- removed required_install PyQt4 from setup.py

0.9.0a
------

- Simplified the way change_password was implemented by reusing one of
the new modules and fixed an unreported bug in the process
- changed the formatting of this file so that it should not cause problems
with PyPI anymore.


0.9.0
-----

Major change in version number as almost all the desired widgets for
version 1.0 have been implemented.

Release notes:
--------------

Some unicode problems are likely present when using Python 2.7; the primary
target is Python 3.3+ ... but we try to support earlier version as well.

Some problems are present with Mac OSX and Python 2.7 (only?)


- added show_abort
- added get_many_strings
- added handle_exception
- added show_code
- added show_file
- added get_new_password
- adressed an issue where some dialogs would appear below some windows
(e.g. terminal) when launched from some platforms (e.g. Mac OSX):
the goal should be that the dialogs always appear on top of other windows.
- removed with_app decorator; this decorator had been introduced to reduce
the amount of repetitive code appearing in each function (and initially
inspected the function signature to add automatically some additional
keyword args) but it likely made it impossible to do unit testing with
QTest (still not done) and prevented ReadTheDocs from reading the correct
signatures for the decorated functions.
- tooltips added to demos launcher
- added get_username_password

0.4.0
-----

- added get_password
- added get_date
- added get_color_hex
- added get_color_rgb
- added get_continue_or_cancel
- added roadmap as a github issue https://github.com/aroberge/easygui_qt/issues/13
- removed CONFIG as a global dict; using the configuration file instead.
- remove set_default_font
- rename set_locale to set_language
- added configuration file to save locale and font size

0.3.0
-----

- Decided to support (with lower priority) Python 2 (2.7.9 more specifically)
- Should work reasonably well with Python 2.7.9 - other than potential
unicode related issues
- made get_list_of_choices(), get_choice(), get_string(), and get_directory_name()
work properly with Python 2.7.9

0.2.3a
------

- changed extension of some demos (from .pyw to .py) as they were not uploaded to pypi

0.2.3
-----

- added demos dir to setup.py so that it can be included on pypi

0.2.2a
------

- changing path on image in readme in attempt to help pypi display properly

0.2.2
-----

- changed the syntax for calls to super() to be compatible with Python 2.
Note that the intention is to be a Python 3 project, but if simple changes
can make it compatible with Python 2, they will be incorporated.
- changed name of set_save_file_name to get_save_file_name
- changed name of yes_no_question to get_yes_or_no
- added get_list_of_choices
- added demo launcher

0.2.1
-----

- Moved the demos directory to a more sensible location
- added get_directory_name
- added get_file_names
- added set_save_file_name
- attempt to fix bug for Python 3.2 where inspect.signature was not defined

0.2.0
------

The API has been changed since the initial release
and the following widgets have been documented, with images inserted
in the documentation.

- get_choice
- get_float
- get_int
- get_integer
- get_string
- set_font_size
- set_default_font
- select_language
- set_locale
- show_message
- yes_no_question

0.1.0
---------------------

* First release on PyPI.