pygame is
Simple DirectMedia Layer is
Site Swing
simple game gui

simple game gui - 0.9.2

Canio Massimo Tristano (keebus)




This project is not under development anymore. Version 2 is in experimental phase and uses as a sharing and development platform for its making. Please feel free to join as you wish to the project (which is much more advanced than this old version).
You can find the official page at Hope to see you there!

After evaluating different pygame gui systems, I finally decided that none was exactly the one I needed for my games, an easy-to-setup and to-use, fast, lightweight and well-integrated gui system.

The goal of this gui is to be extremely easy to use, and setup especially, and to be quickly and well integrated in any pygame game.

It's all contained in a py module: just import it and go!

Features implemented so far:
- No initialization needed. Just import and go.
- Style based GUI, to avoid to pass paremeters like font and font color everywhere, keeping your code compact and reusable
- Functions to create styles quickly (and not by hand).
- Optimizations to refresh your widget only when strictly needed.
- Desktop widget to contain all kinds of widgets, keeping them ordered correctly: if you add a button and a window to a desktop, the button will always be drawn UNDER the window.
- Label widget with autosizing and wordwrapping.
- Skinnable button widget with all kinds of statuses (normal, mouse-over, pressed and disabled).
- Skinnable (or vector) window widget with fast z-ordering. Just add it to your desktop widget, and it will do the rest. - Full-featured textbox widget, with flat or 3D appearence, automatic scrolling (singleline text so far but going to upgrade it soon).
- Skinnable ImageButton to create your personal button based on images (one for each status).
- Skinnable CheckBox and Optionbox.
- Customizable ListBox with mouse-wheel/keyboard scrolling.

Thanks for reading ;)

For any explanation/need, just send me an email, I'll be glad to help you. :)


* Desktop callbacks
* Possibility to pass an integer to the position parameter in the widget creation, that will be transformed
using parent.nextPosition(theIntegerPassed)
* Images on buttons instead of text supported * Other minor improvements


Home Page:


click to view original size


simple game gui - 0.9.2 - Jun 11, 2008
simple game gui - 0.9.1 - Jun 10, 2008
simple game gui - 0.8.1 - Jun 3, 2008 account Comments

If you wish to leave a comment with your account, please sign in first.

September 17, 2009 9:22pm - Jack - nickname: (spira) - 4/5
I have found this incredibly fun to use. However it seems to hang whenever it uses any form of timers such as sleep or wait. Makes it very limiting, but it does have its uses.
April 12, 2009 8:27am - matthew smith - nickname: (durandal) - 4/5
Just wanted to say that this runs smoothly on OS X and great job. Looking forward to SPG2.
September 8, 2008 10:22am - Canio Massimo Tristano - nickname: (keebus)
Actually your issue is pretty wierd. SPG 0.x has been coded on both Ubuntu/Windows XP platforms and it works fine on my system. I can tell you in that version, Windows have their own Surface with the but SRCALPHA enabled. So I fill the Surface with the set background color then I blit the surface to parent's one. Hope this helps.
September 8, 2008 8:30am - Mohit Taneja - nickname: (mohitgenii)
keebus: I am using pygame 1.8.1, the alpha values are working in Ubuntu or for that matter any other linux distribution but i am unable to have alpha values in pixels in Windows XP, i just want to ask that is there any platform specific code that has been used in SPG 0.9.2. I am using alpha values of colours in the background color of the windows.
September 6, 2008 5:48pm - Canio Massimo Tristano - nickname: (keebus)
mohitgenii: SPG2 is under development and no source is avaible yet, sorry. For your issue, which version of pygame are you using? I think alpha works with pygame >= 1.8.
September 6, 2008 3:51pm - Mohit Taneja - nickname: (mohitgenii)
Well Even I am using SPG 0.9.2 and there are some issues with alpha values of the colors of windows, I am not able to display translucent windows in XP, any solution....
Or should i wait for SPG2...
September 6, 2008 3:42pm - Mohit Taneja - nickname: (mohitgenii) - 4/5
Massimo can you just let us know the link to the repository of spg2
September 5, 2008 8:21pm - Canio Massimo Tristano - nickname: (keebus)
The right URL is THIS:

Sorry for the mistake.
September 5, 2008 8:20pm - Canio Massimo Tristano - nickname: (keebus)
mmh html is disabled :\
September 5, 2008 8:20pm - Canio Massimo Tristano - nickname: (keebus)
The Development of the new version SPG2 is going fast and powerful :)

Here's a video-preview about windows: <a href="">click here</a>

Thank you, and please leave crits and suggestions. ;)
August 3, 2008 11:47pm - Mark Pitcock - nickname: (mpitcock)
Massimo, thanks for your good work. I'm trying to use your gui in a program I am developing but I am hung up on needing the TAB key to move to the next TextBox. I realize that you are working on that but I am in a crunch and was wondering if you could give me a pointer as to how to force the focus onto a widget. I tried moving the mouse and then posting mouse movements and mouse down and mouse up events but while they do move the mouse to the TextBox they don't set the focus to the TextBox unless you click on the box manually. Am I missing something obvious?
August 1, 2008 11:04am - Canio Massimo Tristano - nickname: (keebus)
Hey guys. I wanted to notice a big news to you. I stopped working on Simple-Pygame-GUI to begin a new project called "Definitive-Pygame-GUI" which takes it bases from SPG bringing them to a full library.

It will be slightly different from SPG (it's a package now and not just a module anymore because the bigger number of features supported than SPG), but will include all widgets already present in SPG plus all missing ones, such as scrollbars, comboboxes, skinnable windows, and so on. Other features are a built-in module to handle GUI widgets animations, helpers to better and quicker create your layouts and others.

The project is in early development and it will take a while until I manage to complete all the tasks I prefixed. I will create a new page when I think the most is done to keep you updated about it better.

Thanks for everything,
July 26, 2008 9:03am - Karol Nowak - nickname: (grzywacz)
Hm... I'm looking for a lightweight and unobtrusive pygame/gui lib for a small prototype project of mine. I'll give it a try. :-)
July 21, 2008 4:08am - Canio Massimo Tristano - nickname: (keebus)
Quick news: in some time i'll release the 0.9.3 version with lots of new features like: Dialog windows (windows that must be closed to proceed), SKINNABLE WINDOWS (they look pretty good), move focus with TAB key, default windows button (if you press RETURN while you're writing in a textbox, that window's default button will raise onClick callback), 2 new functions to create windows styles (Vector or Skinned), a new and updated documentation and some more.

I've made an improvement to the windows system, so now you can set two tuples indicating the "ClientRectangle", which is the area where widgets will be put and never out of this rectangle. So if you give to a widget the position (0,0), this will be the top-left corner of this rectangle and not the top-left corner of the window itself. After this, I think you'll need to update a little your code, but you'll see it's quite useful.

Thanks and stay tuned.

July 10, 2008 2:06pm - Jordan Trudgett - nickname: (tgfcoder) - 4/5
Impressive pygame gui; a working version for Python 2.4 can be found here:

(with fixed AND
June 26, 2008 1:26pm - orcun avsar - nickname: (floodlight) - 4/5
it's really easy and plugable
June 26, 2008 1:09pm - orcun avsar - nickname: (floodlight) - 4/5
it's really easy and plugable
June 20, 2008 8:02pm - patrick mullen - nickname: (saluk)
I still have no transparency in, but I need to test it further to see why. It's not actually a problem with transparency, but in the setting of transparency for the windows. If I add this line to button3_onClick in, after initializing win:

Then the window is transparent, as it should be.
June 18, 2008 12:30am - Astan - nickname: (traltixx)
Doesnt work with OPENGL, this is how I set the pygame window mode:


This is the error that is displayed:

Traceback (most recent call last):
File "C:/stanc_home/etc/rigs/suns of
sol/example/spg-src-0.9.2/spg-src-0.9.2/", line 43, in <module>
File "C:/stanc_home/etc/rigs/suns of
sol/example/spg-src-0.9.2/spg-src-0.9.2\", line 590, in draw
File "C:/stanc_home/etc/rigs/suns of
sol/example/spg-src-0.9.2/spg-src-0.9.2\", line 481, in draw
surf.blit(, self.position)
error: Cannot blit to OPENGL Surfaces (OPENGLBLIT is ok)

Im using these things:
Pygame 1.8, latest spg, windows xp, python 2.5
June 14, 2008 2:03pm - Canio Massimo Tristano - nickname: (keebus)
Yes guys, i'm sorry but that's a bug in the file. To solve simply remove the "pygame.event.get()" parameter because the gui.setEvents function accepts no parameters.

The screenshot is taken from window, that's just my window decorator in the ubuntu style =)

Thanks for you congrats!! I'll remember, the project is on the page . May everyone feel free to join the project!
June 14, 2008 10:26am - Luca Fabbri - nickname: (keul)
Yeah! This fix the problem for me too!
June 14, 2008 6:06am - Elias - nickname: (biodome) - 4/5

To Luca :
line 139: for e in gui.setEvents(pygame.event.get()):
i fixed the same problem for me removing pygame.event.get() ...

line 139:for e in gui.setEvents():

*i am very new in python so if i have wrong please correct me :)
June 13, 2008 6:43pm - Luca Fabbri - nickname: (keul)
Running your now give me an error:

File "", line 139, in <module>
for e in gui.setEvents(pygame.event.get()):
TypeError: setEvents() takes no arguments (1 given)

Maybe that the problem is my pygame 1.7.1 version (I hope that kubuntu will update to 1.8 someday... :-| )
June 13, 2008 5:32pm - Emmanuel Dempuré - nickname: (altefcat) - 4/5
You need pygame 1.8 to have transparency; see

Anyway, great Gui, very promising !

One question: is it FPS that are displayed on the title bar ? If so, it seems to me that it's really faster under Windows than Ubuntu, do you second that ?
June 11, 2008 12:29pm - RB[0] - nickname: (roebros)
If I may - sometimes transparency in gui's is strange in pygame - varying on systems.
I have tried it on my gui and it is rather strange.
Make sure you are using convert alpha all the time, and also some other things.
Saluk - do other pp-alpha pygame surfaces work for you?
June 6, 2008 8:00pm - Canio Massimo Tristano - nickname: (keebus)
Well... it is transparent to me :) I didn't retouched the screenshot... It works fine to me. By design, focus will be lost if user clicks on a widget which isn't focused widget's parent (try to focus the textbox then click on the desktop, outside the window)

Thanks for the rest =)
June 6, 2008 6:13pm - patrick mullen - nickname: (saluk) - 4/5
Some things I saw from the test:

*Windows aren't transparent like in the screenshot.
*Clicking outside textbox doesn't stop focusing it
*ran pretty fast (130 fps avg)
*your theme is pretty

It's a good start but needs some work I think. Good luck with it.
June 1, 2008 6:35pm - Canio Massimo Tristano - nickname: (keebus)
I'm going to release it under the MIT license. I'm a strong promoter of open-source philosophy...

I'm lookin for people who wants to collaborate to complete it, or for people who want to give an help to write a full documentation. Unfortunately i'm very busy with my university, so i've got not much time to spend on it.
June 1, 2008 6:25pm - Canio Massimo Tristano - nickname: (keebus)
This library is focused on simplicity, but that doesn't mean low performance. I've tried to obtain the highest simplicity with the highest performance.

There are some attributes like the "text" attribute of a label which should force the widget to refresh. But instead of making the user to explicitly call a kind of "refresh" method, there it checks if the attribute you're changing is in "Changing Methods List", and if so, signals the widget it will need to refresh on next update.

Widgets refresh theirselves only when strictly needed. That's a must for any good gui system.
June 1, 2008 11:04am - Carlos Gabriel Hasbun Comandari - nickname: (gasto)
Why did you put?:

if attr in self.dynamicAttributes:
#Must refresh then
self.needsRefresh = True

in 's:

def __setattr__(self, attr, value):
object.__setattr__(self, attr, value)

if attr in self.dynamicAttributes:
#Must refresh then
self.needsRefresh = True

I find it unrelated.
June 1, 2008 9:47am - Carlos Gabriel Hasbun Comandari - nickname: (gasto) - 5/5
I like the library, simple code and excellent design.
Congratulations. Intelligent people create complexity, but only genius create simpleness.
June 1, 2008 3:45am - Claudio Canepa - nickname: (claxo)
I will be glad to collaborate. Its very late here, I mail you later some things I can work.
Maybe you can spell under what licence you release the code? Some people hate GPL, but will work if LPGL or MIT.
May 31, 2008 5:05pm - Canio Massimo Tristano - nickname: (keebus)
Happy to see many people interested on it =)

Well, I'll work on it more, until every programmed part is complete. I'm working on scrollbars now, then I'll add them to listboxes and I'll create the combobox witget. In the end I'll put the possibility to skin windows, then it will be truly finished (for the features I decided for it).

If someone likes the idea to give an hand on its development, i'll create a googlecode page for it :)

Just let me know.
May 31, 2008 2:29pm - Ian Mallett - nickname: (geometrian)
On quitting, it crashes, which does the actual closing of the program.
May 31, 2008 10:14am - pymike - nickname: (pymike)
I like the one file approach too. It's easier to distribute ;-)
May 30, 2008 10:26pm - Claudio Canepa - nickname: (claxo)
Looks pretty good.
As a matter of opinion, I like the one file aproach.
May 30, 2008 7:08pm - Luca Fabbri - nickname: (keul) - 4/5
This is a 5/5 project, but you really need to give some documentation (event a README file).

My personal tought about the "only a source file" rule you are following: is BAD. Is better a complete module like keebus.gui splitted in many files (and a install script... but the lack of using a install procedure is very common on pygame projects).

But after all this is a very interesting idea! Keep working on it, I will use this for sure in my cheeseboys game!
May 30, 2008 4:23pm - Francesco Mastellone - nickname: (effeemme) - 5/5
Man, that's a good one =)
I'd be using it right now if I wasn't messing with pyglet currently.
May 30, 2008 2:08pm - pymike - nickname: (pymike) - 5/5
Wow. Nice GUI. I like the transparent windows :) This looks a bit similar to the GUI I'm working on :)
May 30, 2008 12:35pm - Canio Massimo Tristano - nickname: (keebus)
Now it is :) For any need/explanation dont wait to send me an email to [email protected]

Thank you.
May 27, 2008 5:17pm - Jeffrey Aylesworth - nickname: (jeffayle)
ummmm.....being able to download would be nice...

our projects welcomes all python game, art, music, sound, video and multimedia projects. If they use pygame or not.
recent releases
Feb 21, 2017

Jan 31, 2017

Jan 24, 2017

Jan 18, 2017

Jan 7, 2017

Dec 30, 2016

Dec 8, 2016

Nov 28, 2016

Nov 27, 2016

... more!
for pygame related questions, comments, and suggestions, please see help (lists, irc)