Displaying Graphics

Python doesn't include any native capability to display or manipulate graphics, or react to user input via keyboard or mouse in a "real time" manner. Instead, Python supports the ability to import external Python code that makes this possible. For this course, we will use a graphics library called ggame that is provided by the Github ggame repository.

In this tutorial, we will show you how to use ggame to write your own graphical programs.

Create Your Own Repository

In Github (where you are reading this now), click the + in the upper-right corner of the page and select "new repository". You can name the repository whatever you want, but I recommend "tutorials" or something similar. Check the box for "Initialize this repository with a README". Press the green Create Repository button.

Now press the New File button to create a new file in your tutorials repository. Name it tutorial1.py and give it some initial contents like this:

from ggame import App
myapp = App()
myapp.run()

Commit the changes, then copy the contents of your browser's URL window (it should look something like https://github.com/yourusername/tutorials/blob/master/tutorial1.py).

Switch to runpython.org, LOGIN with Github (if you haven't already), then paste the URL into the window at the top, LOAD it, then GO! it.

This should create a simple, blank window within your runpython tab.

What Does the Program Do?

The first line, from ggame import App, tells Python to run an external Python module called ggame and bring the resulting App name in to our name space. In other words, the external module called ggame defines a new type of Python object called App and this line of code imports it and allows us to use it. Note that ggame is not available in the official Python distributions that you would use directly on a Windows or Mac computer. ggame is a graphics module that is tightly integrated with the runpython.org environment and is only available on runpython.org.

The second line, myapp = App(), runs the imported App() function to create a new App object in the computer's memory. The object is assigned to the myapp name. Note that the myapp name could be any legal Python name. The App object will create a new graphics tab in your browser, display graphical objects for you and handle keyboard and mouse input.

The second line, myapp.run() executes the run() function (technically called a "method") that is attached to the App object. Notice that you have to run this method by referring first to the name of the object (myapp), then use the period character, then the name of the method with a pair of parenthesis following. The App object doesn't start doing anything until you execute its run() method.

Fill With Graphics

Modify your program (tutorial1.py) to look like the following (make changes in runpython.org, then press COMMIT to save them):

from ggame import App, Color, LineStyle, Sprite
from ggame import RectangleAsset, CircleAsset, EllipseAsset, PolygonAsset

# Three primary colors with no transparency (alpha = 1.0)
red = Color(0xff0000, 1.0)
green = Color(0x00ff00, 1.0)
blue = Color(0x0000ff, 1.0)
black = Color(0x000000, 1.0)

# Define a line style that is a thin (1 pixel) wide black line
thinline = LineStyle(1, black)
# A graphics asset that represents a rectangle
rectangle = RectangleAsset(50, 20, thinline, blue)

# Now display a rectangle
Sprite(rectangle)

myapp = App()
myapp.run()

What do all these new functions do?

Color

First of all, the import lines at the start of the file (which is where all of your imports should appear, by the way) allow us to use many more functions from ggame.

Next, there are several lines like this: red = Color(0xff0000, 1.0)

Each of these creates a Color object and then assigns it to a name. The code that you find inside the parentheses is called arguments to the function. Arguments are separated by commas and the number of arguments depends on what the function is. If we look at the definition of Color, we see that there is a short example given, and that the two arguments are known as color and alpha. The color argument is a number in hexadecimal (like 0xff0000) that has three parts corresponding to the red, green and blue components of the color. If you want to see examples of hexadecimal color codes, you can find these on the Internet (Google is your friend here).

The second argument, alpha, is a floating point number between 0.0 and 1.0 that says how transparent you want the color to be. 1.0 is opaque and 0.0 is transparent.

LineStyle

Next, there is thinline = LineStyle(1, black), which creates an object that represents the color and width of a line. This does not actually create any lines, but rather represents a template for future lines.

RectangleAsset

Next, we use the predefined colors and line style to create a graphical rectangle object: rectangle = RectangleAsset(50, 20, thinline, blue). Check out the documentation on the RectangleAsset.

The arguments to the RectangleAsset are width, height, line and fill. In our case, we used the line style and color that we already created, and typed in numbers for width (50 pixels) and height (20 pixels).

Like the line style before it, creating a RectangleAsset alone does not produce graphics on the screen. In order to do that, we have to create a Sprite.

Sprite

Compared to the previous objects, making a Sprite is pretty easy: Sprite(rectangle).

This will create a real displayable object, using the rectangle object as a template. By default, the sprite will be displayed at the origin of the screen coordinate system, which is the upper left corner of the screen. You can override this by adding a pair of x,y coordinates to the argument list.

Try adding the following line to see this:

Sprite(rectangle, (200, 50)) (add it below the other Sprite function reference)

Notice that the position of the new rectangle is given as a pair of numbers in parentheses.

Don't forget to check out the documentation on Sprite

Screen Coordinates

The numbers given for the coordinates are the horizontal location in pixels, followed by the vertical location in pixels. The horizontal positions are always positive numbers, measured from the left side of the screen. The vertical positions are always positive numbers, measured from the top of the screen.

Notice that the vertical position does not work exactly like the "y-coordinate" in mathematics. This is common in computer graphics and has origins in the early days of computer graphics and television technology. Get used to it!

More!

Visit the ggame documentation to see all of the asset types supported by ggame.

---

Questions

Add code to tutorial1.py while trying the following:

1. Modify tutorial1.py to display two overlapping squares.
2. Modify tutorial1.py to display a blue ellipse.
3. Modify tutorial1.py to display a red polygon that completely covers the blue ellipse.
4. Modify your answer to the previous question to make the polygon partially transparent.

---