Pygame: GUI toolkit
Short description: I would like to reach a stable version of this GUI toolkit, meaning that it will be ready for general use and will be in a good, maintainable state.
Additional info: http://sambull.org/downloads/spec.odt
Plenty of time. Working on some weekends. Unfortunately, my course doesn't finish till June, so I may be a little busy for the first few weeks, though I'm confident I can keep up.
I am fluent with Python, having used it for a few years. I also have a reasonable understanding of C.
I have used pygame for a couple of years. I have been working on a game in that time, which started out as a 2D project and was later moved to 3D using pyopengl. I have also been occassionally working on the toolkit which I would like to expand for this GSoC.
I have good written English and have begun documenting the existing toolkit. I'll leave judgement of whether I have good documentation skills or not, to you. program.sambull.org/sgc
This toolkit will fill the need for a good quality, easy to use toolkit. The previously existing toolkits available for Pygame are either lacking attention to detail or are too complicated to setup and use, or both. My toolkit is simple to use, but also has a good attention to detail, things such as mouse selection of text in an input box and being able to TAB through widgets.
For full details of the project proposal check the additional info link.
Feedback and Design
I discussed developing this for GSoC on the mailing list last year (unfortunately Pygame wasn't part of GSoC last year), and received some positive feedback from users having the same frustrations with the existing toolkits available. You can see some of these discussions here: http://firstname.lastname@example.org/msg14880.html
As one user, who had also searched through all the pygame toolkits available, told me: The only toolkit that still seems to be maintained is Pgu. One problem with this toolkit is a lack of detail in the features of individual widgets.
Another problem is that it's API is designed like a typical GUI toolkit, and thus is great for creating full applications. But, due to this design and the way it takes over the event loop, it is a rather large and complex system to utilise in a game.
That user also specified 3 things he would like in a GUI toolkit, stating that other toolkits were not doing things "the pygame way":
- Not taking over the event loop, such as PGU, this is something my toolkit has never done.
- Subclassing from pygame sprites. I added this about the time this was mentioned to me.
- Using regular pygame events for widget events. This exists in my toolkit, but needs some work completed as part of GSoC.
At the time, the toolkit was a little more fiddly to set up and had no documentation. The newest release has begun to alleviate these issues, it is a lot more simple to setup and use, and I have made a good start to documenting the toolkit.
I feel that my toolkit is nearly ready to replace the other toolkits available. With the development effort put into this project through GSoC, I believe we will have the first stable release at the end of GSoC, and it will be in a place where it can replace those other toolkits. Completing the tasks outlined in the timeline and spec is what will be required to reach this state.
I have had one developer produce a couple of widgets in the last month. They needed only a little help from me and produced each widget in around a day. With the developer documentation completed I'm convinced that any developer could create new widgets.
In designing the toolkit, I have looked at how some other toolkits function. I have noticed some similarities with the API used for Tkinter, and have made some small changes in the past to match some method names or arguments.
I also tend to look at the widgets from GTK+ from the outside, to see how they behave. When I am unsure exactly how some detail of a widget should behave, I look at GTK+ and see how the widget behaves there. This helps to create a consistent GUI experience, where the GUI in a game closely mimics a desktop GUI, meaning the user is never frustrated by functionality missing or behaving differently to what they would expect.
I have been working on this project where I can spare the time for nearly two years now. I am currently using the toolkit with two game projects, my own game in OpenGL and a plain Pygame game I'm working on with a couple of other people.
I have been motivated to keep working on this when it was just me and one game. I'm only more motivated now I am working on a second game with other people.
I also believe that after GSoC, the code will be in a state that it would be easy for somebody else to take over maintaining if it ever came to that.
As Pygame has little OpenGL support, I am having to implement surface and drawing functions for OpenGL as part of this project. I am imitating Pygame's API so that it is can be used and will behave in the same way as vanilla Pygame.
This code may be useful to integrate into Pygame in the future to improve Pygame's OpenGL support. I have asked on the mailing list about extending OpenGL support, and it appears there are some users who are enthusiastic about using OpenGL in Pygame, so this may prove to be an interesting addition to the project someday.
Here is a rough timeline:
Decouple labels (so as not to be included in sizes)
Update certain widgets that use labels.
At the moment widgets such as the input box and toggle button have a label argument that adds a label to the left of the widget. Because this toolkit has less emphasis on packing, this is a handy feature to keep a label associated with a widget without messing around with packing widgets.
The problem is that the labels take a portion of the widgets actual space, and the widget must then be resized to fit into the remaining space. This results in the image of the widget being inconsistent sizes and making the widget coding a little more complicated.
The label should be created as a new widget and added independently of the widget it is associated with. The label should then have it's position linked with the other widget so it always remains next to the widget. There should also be a new config argument that specifies which side the label should be attached to.
Currently, events are not well tested. More events should be added to widgets, such as when selecting a radio button. This will allow for a more event driven game design. It should also be tested that these work with callback as well as events.
Widgets have some support for using custom images, but this has not been well tested or documented. Passing an image as the first argument when creating a widget should set the widget's image to that image, and a dictionary can be used to specify different images for different states.
This will also require that widget drawing is split into two functions, one which draws the base image when no image is given. The other function draws anything else that should still be drawn, for example the text on a button.
OpenGL setup tutorial
OpenGL support is currently a mess, and barely functions on my machine with some hacks. I would like this toolkit to run on either plain Pygame or OpenGL as the user requires.
This should work identically to the end user, so the user only needs to add or remove the OPENGL flag when creating the screen. There should be no other required code changes.
Widgets are currently positioned and sized using pixel coordinates. To accommodate differing screen resolutions, positioning and sizing should be possible to specify through a percentage value.
Currently there is little error handling. Things may fail silently, or crash without a meaningful error message.
Exceptions should be created for the toolkit so they can be targeted with an except statement. Invalid configuration options and other settings should have assert statements to ease debugging.
Adding developer documentation will allow users to create custom widgets for their own purpose. It will also make it easier for developers to contribute to the toolkit by adding new widgets or new features to existing widgets.
This was recommended to move to an earlier point in the process. So, I intend to do it at this point, as all the details of widget development will be completed by this point.
Currently there is a problem with transparency when using plain Pygame. This is an issue with differing types of surface. The main issue can be seen with anti-aliased fonts showing black pixels around them, this is caused by them being blitted onto a surface using set_colorkey().
If a mentor can give me tips on how to fix this without losing the fading effects from set_alpha(), then I will be able to fix this problem which has been plaguing me since I began this project.
Adding the small features still missing from the checklist for individual widgets.
The checklist in the spec file still has some uncompleted features. The rest of these small features should all be implemented to provide the most consistent usable experience to the player.
During the development period, I will make regular releases to make it easy for people to test the project throughout GSoC. This will help find any problems with the documentation, so that it can be expanded on or written more clearly.
With some time left over, I will look into optimising the code with dirty sprites, as suggested by René.
There is currently a small quick-start tutorial as part of the documentation. To make the documentation really useful for developers some more tutorials need to be added to cover specific features such as events, theming and OpenGL. These will be completed as each relevant feature is completed, to allow more time to receive feedback on the implementation.