Project Title: PySoy’s interactive widgets

Student: Amaury Bartolomeu Carneiro de Medeiros

Organization: Python Software Foundation

Assigned mentor: David Czech


The widgets in PySoy live on soy.widgets module. Mostly of the work of this project will be done in that module. Basically, the project consists in building a set of themeable interactive widgets for PySoy.

The main goal is to build some widgets like containers, collapsable branches, text input and display and scrollable panels to make possible to build a buddy list and chat windows in PySoy, which users will use to comunicate in and out PySoy’s based games.

Also, a new module (soy.themes) is intended to be made. That module will be responsible for the themes properties. Themes will be set for widgets and will be inherited for their eventual children.

Buddy List

Buddy lists, also known as roster widgets are used to show and manage contacts. It’s very important for network gaming. In Pysoy, roster widgets will be shown like the prototype illustrated in Figure 1.

Figure 1 - Buddy List

The contacts can be divided by groups. Each group is a collapsable branch. When those branches are expanded, they show the contact list, one by one, in a vertical display. Each contact has some personal information, like display name, status and an icon representing which game he/she is playing.

If the number of contacts is so big that the list can’t fit the viewport, the widget will need a scroll bar. Currently, PySoy doesn’t have scroll support, so a scrollable widget will be implemented too.

As we can see, roster widgets need a few more widgets to be implemented. This projects aims to implement those widgets in the most reusable way. After implemented, they will be used to build the buddy list. This proposal taks a little about each widget and how they’re planned to be done.


Containers, as the name itself, are widgets that contains widgets inside. There’s a container already implemented in PySoy – Window. This project aims to write at least two more types of containers: HBox and VBox. Both of them would put widgets side by side. The difference is HBox would distribute them horizontally, while VBox would do it vertically.

Figure 2 - VBox use in Roster Widgets

As illustrated in Figure 2, VBox are extensively used in buddy list. They’re used to contain other containers and also to contain some structures, like the collapsable branches. The red delimiters in the pictures were made just to give a notion of what each container contains.

There’s also two HBox’s in that figure. If we take a look at each contact, we can easily see that each one is a HBox. Lets take the Mark contact example, as we can see in Figure 3. That HBox has three elements. The first one contains a contact picture. The second one contains the contact’s display name and his/her status. Finally, the last one has the icon of the game the contact is currently playing, if there’s one.

Figure 3 - HBox use in Roster Widgets

Scrollable Widgets

The scrollable widgets are widgets with on-demand scroll bars. They could be used in too many parts of PySoy. For example, when selecting a saved file from a loadlist, in your buddy list while displaying contacts, in a widget that shows a lot of information (like game instructions) and in any widgets that seems like a table view and its area of contents doesn’t fit the viewport.

The example in buddy list is displayed in Figures 4 and 5. In both examples, the widget have the same content, but it doesn’t fit the viewport. For that reason, the scroll bar is needed and each picture show different parts of the content on the viewport.

Figure 4 - Scrollable Widget

The API generated would be used in something like:

>>> scrollBar1 = soy.widgets.ScrollBar()
>>> scrollBar2 = soy.widgets.ScrollBar()
>>> scrollable = soy.widgets.Scrollable(window, alwaysOn=True)
>>> scrollable.horizontalScrollBar = scrollBar1
>>> scrollable.verticalScrollBar = scrollBar2

Figure 5 - Scrollable Widget


Collapsable branches, or just branches, are nodes used in a tree model. They can be expanded or collapsed. A good abstraction can be found if we compare the branches to directories in a filesystem and compare their children with files. Each directory can be expanded, so we can see its files and its subdirectories. Each subdirectory can be expanded and so on.

In the buddy list, branches are used to group the contacts. Each group is a branch. When we collapse each group, just its name is displayed. When we expand it, each contact of the group is displayed in a VBox.

The branches are going to be used like the code below and a prototype can be viewd in Figure 6:

>>> branchFamily = Branch(vBox)
>>> contactWJ = Contact('Walter Junior')
>>> contactWJ.picture = '../img/default.png'
>>> branchFamily['Walter Junior'] = contactWJ

Figure 6 - Collapsable Branches

Chat Widgets

Chat Widgets are also very important for network gaming. They make possible the communication between players. A chat widget consists basically in a text input widget, to write text you want to send and a text display widget, to view the conversation that has already been sent.

Figure 7 shows a chat widget prototype.

Figure 7 - Chat Widget

Text Input Widgets

A text input widget is basically a widget where the user can write text on. It can be used in a large number of scenarios. For example, to answer NPC’s questions during a game, to set line command actions during a game and to write text in a chat conversation.

An example use of text input widgets can be seen below:

>>> sentBox = soy.widgets.TextInput(window)
>>> sentBox.size = soy.atoms.Size((300, 100, 0))
>>> sentBox.lineWrap = True

Text Display Widgets

A text display widget is used to display any kind of text in games. In a chat environment, it can be used to display the messages sent in a conversation on the screen. In a game environment, it can be used to display characters speeches and any text labels the game needs.

Since most of texts to be displayed are not plain texts (games deserves richer texts), a solution to text layout is proposed. PySoy already use Pango[1] for it, so that’s the library chosen to this project.

Themeable Widgets

The idea here is create a set of themes to widgets. Instead of the user customize each widget, colour by colour, we intend to offer some pre-customized choices, made by us. Something that should be said, the user won’t be restricted to use our themes, but can customize their widgets colours by himself too. As we know, game developers like to make their own game styles and we strongly encourage that. Themes properties are made to help.

The intention is to create a themes module (soy.themes) and then create a Theme type. In theme type, we can set style properties, like background image, background color, gradients, font colors and borders. After that, we could set the theme for a widget/container and all it children would be customized with the same theme.

For example:

>>> w = soy.widgets.Window()
>>> theme = soy.themes.Theme()
>>> theme.backgroundColour = soy.atoms.Color(‘blue’)
>>> #theme.backgroundImage = ‘../img/background1.png’
>>> theme.border = soy.atoms.border(5, 0)
>>> widget1 = soy.widgets.Widget(w)
>>> w.theme = theme


1st Milestone – April 26th to May 23rd

Get in touch with the code. Discuss with my mentor at #PySoy channel on IRC. Start to search and read important files and tutorials. Try to figure out how the API will look like after the changes would be made.

2nd Milestone – May 24th to July 15th

Implement HBox and VBox. The libsoy part of those widgets already have something implemented and I did some contributions to VBox one myself. Implement text input widget and text display widget. Implement scrollable widget. Implement collapsable branches. The idea is to have all widgets implemented before mid term evaluation.

Final Milestone – July 26th to August 22nd

Discuss the themes idea with the mentor and some other community developers. Implement themes module. Integrate the network module ( to play well with the widgets. Write some unit tests to the changes made. The time remaining will be dedicated to write a XMPP client written entirely in PySoy.


Progress of the project will be reported regularly at a blog[2]. Currently, I’ve already contribute to PySoy. Also did something related with widgets. I’m still active in the project and intend to keep working on it after GsoC. Some of my contributions can be found in my ohloh’s profile[3].  

Who Am I?

I’m an undergraduate student at Computer Science at Universidade Federal de Campina Grande, 2 semesters left. In 2009, I joined an OpenSource? project called TabletSuite?[4], for maemo devices. Also participated, in 2010, of another OS project, this time as a co-owner, called ChessTools?[5] – a touchscreen chess clock, that also saves games results and keeps a ranking.