Words Nodes

The libavg WordsNode places formatted text on the screen. It supports UTF-8 encoded text, paragraph layout and internationalized text (including arabic and other right-to-left languages).

Uniform Strings

Single-line strings can be placed using nodes like this:

1node = avg.WordsNode(pos=(10,10), text="Apples and Oranges",
2        font="Arial", variant="Bold", fontsize=18,
3        color="CF8000")

This does pretty much what you would expect: The text is rendered in Arial Bold, 18 pixels size, using an orange color. Multi-line texts look like this:

1node = avg.WordsNode(pos=(10,10),
2        text="The quick brown fox jumped over the lazy dog.",
3        font="Arial", variant="Bold", fontsize=18,
4        color="CF8000", width=170, linespacing=10,
5        alignment="left", indent=10)

In this case, the text is rendered in a 170 pixel wide paragraph, with 10 pixels of space between the lines, left-aligned (you can also center or right-align text), and with an indentation of 10 pixels for the first line.

You can easily create several WordsNodes with identical or similar formatting by using the FontStyle class.

Finding and Installing Fonts

libavg looks for fonts in the standard directories that the operating system uses. In addition, it looks for fonts in a fonts/ subdirectory of the current directory and in any directories specified using WordsNode.addFontDir(). To check which fonts are installed and how they are rendered, you can use the avg_showfont.py utility. Called without parameters, it outputs the complete list of fonts available. Called with a font name as parameter, it displays all available variants of the font in an avg window. avg_showfont.py is installed during libavg installation.

Formatted Text

Paragraphs can change formatting in mid-sentence using an assortment of html-like tags:

1node = avg.WordsNode(pos=(10,10), font="Arial" size=18,
2         parawidth=300,
3         text="The quick brown fox <i>jumped</i> over the lazy dog"

It is not possible to use the text formatting tags when the text attribute is defined using an xml attribute because that would violate xml syntax.

The paragraph formatting tags include a full-featured <span/> tag that is described here:

http://developer.gnome.org/pango/stable/PangoMarkupFormat.html

Using this tag, you can change almost any text attribute (font, size, style, vertical displacement, underline,...) in mid-paragraph. Rudimentary multi-paragraph text is possible using <br/> tags. More complex multi-paragraph formatting should be done using more than one words node.

Antialiasing

Like any modern text rendering system, libavg uses antialiasing to make sure the text is smooth. The quality of antialiasing depends heavily on the gamma curve used to translate pixel coverage values into sRGB colors. Sadly, the optimal gamma value depends not only on monitor settings, but also on the combination of fore- and background colors used. For this reason, you can fine-tune the gamma setting yourself:

1node.aagamma = 1.5

Good values for aagamma are usually between 1.0 and 2.0. The image on the right shows the same text rendered with different gamma settings, and with black and white backgrounds.

The underlying cause for this effect is complex. The details are described in http://lists.w3.org/Archives/Public/public-html/2011Apr/0170.html and http://http.developer.nvidia.com/GPUGems3/gpugems3_ch24.html, among others.

Note that the default text rendering of libavg is more than sufficient for normal monitor resolutions. The aagamma attribute is only important if you're running low-DPI displays that users will be close to - like projector based multitouch tables.