GUI Basics

Here is a simple program that puts a score in the corner of the window:

function onSceneStart()
    currentScore = 235
    GuiManager.call("paintScore", paintScore, 1)
end

function paintScore()
    local scorebox = Rect.new("",0,0,200,25)
    scorebox:drawText(nil, {}, "Score: " .. currentScore .. " points")
end

Every frame, the GUI is erased and rebuilt from scratch. The way this works is that you must write a function like 'paintScore' above whose job is to repaint the GUI from scratch. You then use GuiManager.call to tell the GUI subsystem to call your paint-function. Every frame, the this function will get called to rebuild the GUI.

The actual process of drawing the GUI consists of two steps: construct objects of class 'Rect' (rectangle) to lay out the positions of the gui elements. The coordinates are in pixels: (0,0) is the upper-left corner. After constructing the rectangles, you fill those rectangles with pictures and text. In the code above, we start by constructing a rectangle that will hold the score. Then, using the method 'Rect.drawText', we paint the desired string.

Because the GUI is rebuilt from scratch every frame, it tends to update itself naturally. For example, if some other part of the program were to change the contents of the variable 'currentScore', the GUI would immediately reflect that.

Drawing Pictures with Rect.drawPict

The method 'Rect.drawPict' is used to fill a rectangle with a picture. The simplest cases are these:

rect:drawPict(nil, {background="user/zebra.jpg", stretch = false})
rect:drawPict(nil, {background="user/zebra.jpg", stretch = true})

In the first case, the picture of a zebra is tiled across the rectangle. In the second case, the picture of the zebra is stretched to fill the rectangle exactly once.

The first parameter to drawPict is a clipping rectangle. These aren't used that often, so the parameter is usually nil. If you supply a clipping rectangle, then this acts like a cropping tool outside of which nothing is drawn.

If you wish, you can also put something that looks like a picture frame around the zebra. To do so, create a PNG image that looks like a picture frame with an alpha-transparent center. Then, use the foreground keyword to supply the frame:

rect:drawPict(nil, {background="user/zebra.jpg", stretch=true, foreground="user/picframe.png"})

This will draw a picture of a zebra with a frame.

The 'foreground' and 'background' keywords are somewhat badly named - background is really "the image that fills the rectangle", and foreground is really "the picture frame that decorates the edges of the rectangle." This is an important distinction: many people make the mistake of trying to use 'foreground' to draw a picture. But foreground can't do that - foreground is to decorate the edges, not to fill the rectangle. To draw a simple picture, use 'background,' not 'foreground.'

The foreground (picture frame) image must have some alpha transparent areas. Before rendering, the alpha-transparent portions of the frame are analyzed. Some of the alpha-transparent areas may be judged to be on the "inside" of the frame, and others may be judged to be on the "outside" of the frame. (This analysis uses a flood-fill which starts at the outside edge and stops when it gets to an opaque pixel). Alpha transparent areas on the inside of the frame will show the zebra. Alpha transparent areas on the outside of the frame will show whatever was on the screen before the pict was rendered.

If the picture frame does not fit the rectangle exactly, it is expanded using a quadrant-based algorithm. The PNG is chopped into four quadrants: upper-left, upper-right, lower-left, and lower right. The four corners of the PNG are placed into the four corners of the screen Rect. This may leave gaps in the middle. The gaps are filled by stretching the middle pixels of the PNG. This quadrant-based algorithm is ideal for picture frames. It really is not very useful for anything else. The "foreground" keyword is solely intended to enable you to put a picture frame around an image. Note that the 'stretch' keyword only affects the background image. The foreground image is always processed using the quadrant-based algorithm.

To get more complex effects, you can use multiple 'drawPict' calls to layer images on top of each other.

The table which is passed to drawPict may contain a number of other options in addition to 'foreground', 'background', and 'stretch'. See the API reference for a full list.

Drawing Text with Rect.drawText

To display text, build a rectangle, then call drawText. Here is a common case:

rect:drawText(nil, {}, "Now is the time for all good men")

The first parameter to drawText is a clipping rectangle. These aren't used that often, so the parameter is usually nil. If you supply a clipping rectangle, then this acts like a cropping tool outside of which nothing is drawn.

The table can contain a large variety of options. Here is an example of passing options:

rect:drawText(nil, { font="josh/verdana", size = 12, wrap = false }, "Now is the time for all good men")

The font must name a truetype font-file that has been uploaded to the Wild Pockets server. The font-file can be uploaded using a menu item in the development environment, in the file menu.

There are a large number of options to drawText. These can be found in the API reference in the plugin.