Skip to main content

A GUI toolkit targeting browsers

Project description

What is this?
-------------
It's a GUI framework prioritizing portability, simplicity, and a Pythonic feel.

If you want to build a simple GUI for a simple task, I recommend this package whole-heartedly. I don't think this is just pride in my own work -- I'm pretty sure that this package *actually is* very easy to learn, and very good for simple things.

If you want to build a video game, or a nice, fluid 3D visualization, this is easily the worst GUI framework I have ever seen.

- [Why is it good?](#why-is-it-good)
- [Why is it bad?](#why-is-it-bad)
- [What are the alternatives?](#what-are-the-alternatives)
- [How do I install it?](#how-do-i-install-it)
- [How do I learn to use it?](#how-do-i-learn-to-use-it)


Why is it good?
---------------

This package prioritizes ease of use, portability, and good documentation above all else. The following statements will remain true as long as I have breath left in my body:

- **It feels like Python.** It uses HTML/CSS/JS under the hood, but that fact is carefully hidden under nice object-oriented abstractions. Contrast with [Tkinter][tkinter], which feels like Tk, because it is.
- **It has a shallow learning curve.** "Hello World" is `GUI(Text("Hello world!")).run()`. Minesweeper, including the game logic, is [less than 100 lines of code][minesweeper-code] and [looks like this][minesweeper-screenshot].
- **It's super-portable.** `pip install browsergui && python -m browsergui.examples` has worked, with no snags, on every system I've tried (OS X, Debian, and Ubuntu, with both Python 2.7 and a few Python 3.Xs). Seriously, you could run that right now and it would work, without a single abstruse error messages about your Qt/wx/PyObjC installation. At the risk of tooting my own horn, I've never seen another GUI library so easy to install.
- **It's well-documented.** There's a [wiki][wiki] to teach you how to use it. There are [examples](#how-do-I-learn-to-use-it). There's a [reference manual][docs]. There's a [runnable demo for every predefined kind of element][tour-screenshot]. I've spent more time documenting than I've spent writing actual code.

Why is it bad?
--------------

- **It's slow.** It does not even try to be high-performance. There's an HTTP request every time the user interacts with the GUI, and again every time the view is updated. Performance is off the table. (It's not *frustratingly* slow -- you can drag a slider and see the value update with no perceptible delay -- but it's not good for fancy stuff.)
- **It's not super-easy to make super-pretty things.** I just haven't prioritized styling: any styling you want to do, you have to do through CSS. I'm not sure `element.css['color'] = 'red'` is so much worse than `widget.config(foreground="#f00")`, but it *does* feel like a thin wrapper over CSS (because it is), which is gross.

How do I install it?
--------------------

If you use pip, `pip install browsergui`.

If you use easy_install, `easy_install browsergui`.

If you don't like package managers, just unzip [this][download-zip] and put the `browsergui` folder anywhere on your Python path.

Once it's installed, I recommend running `python -m browsergui.examples` to see a catalog of all the kinds of building blocks available to you, or checking out [the wiki][wiki] for tutorial-type stuff.


How do I learn to use it?
-------------------------

[The wiki][wiki] has several tutorial-type pages. Or you could just extrapolate from these examples:

- Hello world:

from browsergui import GUI, Text
GUI(Text("Hello world!")).run()

- A number that increments every time you press a button:

from browsergui import GUI, Text, Button

button = Button('0')
@button.def_callback
def increment():
button.text = str(int(button.text)+1)

GUI(button).run()

- A clock:

import time
import threading
from browsergui import Text, GUI

now = Text("")

def update_now_forever():
while True:
now.text = time.strftime("%Y-%m-%d %H:%M:%S")
time.sleep(1)

t = threading.Thread(target=update_now_forever)
t.daemon = True
t.start()

GUI(Text("The time is: "), now).run()

(You can close/reopen the browser window at any time; Ctrl-C will stop the server.)

Each kind of element (`Text`, `Button`, `ColorField`, `Grid`...) also has a simple example showing you how to use it: `python -m browsergui.examples` will display all those examples to you.

What are the alternatives?
--------------------------

I am aware of some GUI toolkits for Python that fill a similar niche. You should consider using these instead:

- [tkinter][tkinter] (standard library)

Advantages: it's in the standard library. It has always worked out of the box for me. If you want maximal portability, this is probably your best bet.

Disadvantages: it feels like a wrapper around Tk, because it is. This gives good performance and detailed control, but writing it feels unintuitive (to me).

- [pyJS][pyjs], another Python package for making GUIs targeting browsers. It works by compiling your Python code into a slug of JavaScript which runs in the browser.

Advantages: pyJS applications are much faster and much easier to deploy (since it doesn't require the user to run Python).

Disadvantages: I had trouble installing it. And like `tkinter`, it's a wrapper, with the same dis/advantages.

There are, of course, many other GUI toolkits. [Here][official-alternatives] is a list of those popular enough to earn the notice of Official Python People. [Here][unofficial-alternatives] is a paralytically long listing of less-notable ones.

[minesweeper-code]: https://github.com/speezepearson/browsergui/blob/master/browsergui/examples/minesweeper.py
[minesweeper-screenshot]: http://i.imgur.com/8Ax04sZ.png
[tour-screenshot]: http://i.imgur.com/AvVVVFd.png
[download-zip]: https://github.com/speezepearson/browsergui/archive/master.zip
[wiki]: https://github.com/speezepearson/browsergui/wiki
[docs]: http://pythonhosted.org/browsergui
[download-zip]: https://github.com/speezepearson/browsergui/archive/master.zip
[tkinter]: https://docs.python.org/3/library/tkinter.html#module-tkinter
[pyjs]: http://pyjs.org
[official-alternatives]: http://docs.python.org/2/library/othergui.html
[unofficial-alternatives]: http://wiki.python.org/moin/GuiProgramming

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

browsergui-0.4.tar.gz (55.3 kB view hashes)

Uploaded Source

Built Distribution

browsergui-0.4-py2.py3-none-any.whl (59.5 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page