###############################################################################
# STplayer (aka STconverter 2) allows you to execute Python scripts written for 
# SimpleGUI on a machine configured with Tkinter GUI instead. 
# 
# STplayer is the successor of STconverter, and is different in such ways that 
# it has been entirely rewritten to handle with a totally different approach 
# the "conversion". 
# While STconverter was converting (by this, meaning rewriting) each SimpleGUI 
# operation in the user code before the program is executed with Tkinter, 
# STplayer is an API between SimpleGUI operations and Tkinter. 
# 
# "Tkinter is Python's de-facto standard GUI (Graphical User Interface) package"
# (http://wiki.python.org/moin/TkInter)
# "SimpleGUI is a custom Python graphical user interface (GUI) module implemented 
# directly in CodeSkulptor that provides an easy to learn interface for building 
# interactive programs in Python" (http://www.codeskulptor.org) used for the 
# online Coursera course "An Introduction to Interactive Programming in Python" 
# by Joe Warren, Scott Rixner, John Greiner, and Stephen Wong (Rice University) 
# 
# I want to thank Amín Guzmán for his valuable comments and suggestions on how 
# to improve STconverter, which lead to the development of STplayer
# 
# For the latest version of STplayer visit the repository on Github: 
# https://github.com/jem-gh/STplayer
# 
# STplayer is developed by Jean-Etienne Morlighem (https://github.com/jem-gh)
###############################################################################



1. LICENSE
STplayer (aka STconverter 2) is under the MIT License
Copyright (c) 2012 Jean-Etienne Morlighem <jem.nvnt@gmail.com>
https://github.com/jem-gh/STplayer



2. REQUIREMENTS

2.1. To run STplayer

- Python & Tkinter: STplayer will need Python installed on your machine with 
the Tkinter module (generally installed by default with Python).
http://www.python.org/download/


2.2. Minimum requirements to run your program on your machine

A simple rule of thumb is:
                        Additional module     Works with Python
NO music and NO image   none                  2.7 or 3
WITH music              pygame                2.7 or 3
WITH image              PIL                   2.7 only

- Music: if your SimpleGUI program plays music, you will need in addition to have 
pygame installed on your machine to run your program (but is not required for the 
conversion)
http://www.pygame.org/download.shtml

- Image: if your SimpleGUI program displays images, you will need in addition to 
have the Python Imaging Library (PIL) with the ImageTk module installed on your 
machine to run your program (but are not required for the conversion).
Unfortunately, so far, PIL is not available for Python 3 and works only for 
Python 2.2 to 2.7.
http://www.pythonware.com/products/pil/index.htm



3. HOW TO USE


There are three ways of using STplayer

>> command line only:
$ python /path/to/STplayer.py /path/to/your/SimpleGUI_file.py


>> with a Graphical User Interface
- by double clicking on STplayer.py

- or by typing in terminal
$ python /path/to/STplayer.py


>> API only
If you want to use only the API without the program, you can do so by copying the 
"simplegui2tkinter_API" folder in your Python working directory, and then update 
your "PYTHONPATH" or change in your SimpleGUI the following line the import of 
the "simplegui" module by:
	from path.to.simplegui2tkinter_API import simplegui2tkinter as simplegui



4. MAJOR KNOWN ISSUES

> frame.start() 
frame.start() has to be your last line of code. If a timer.start() is written 
afterwards, it won't start.

> GLOBAL VARIABLES
SimpleGUI handles very well global variables which were assigned "locally" 
in a function. This is generally not the case of a Python interpreter. 

> DIVISIONS
Division on Python 2.7 returns the floor of the quotient, whereas on Python 3 
and SimpleGUI it returns the true division result. This could result on a 
different behavior of your program depending on which Python you have installed. 

> MUSIC/SOUND
MP3 musics and sounds are not fully supported yet. 



5. TESTED ON...

So far, it has been tested on:
- Linux with Python 2.7.3, pygame 1.9.1, and PIL 1.1.7



6. ACKNOWLEDGEMENT

I want to thank Amín Guzmán for his valuable comments and suggestions on how to 
improve STconverter, which lead to the development of STplayer.