olpcgames.pangofont
index
/home/mcfletch/olpc/code/games-misc/olpcgames-src/doc/pydoc/olpcgames/pangofont.py

Implement Pygame's font interface using Pango for international support
 
Depends on:
 
    pygtk (to get the pango context)
    pycairo (for the pango rendering context)
    python-pango (obviously)
    numpy
    (pygame)
 
As soon as you import this module you have loaded *all* of the above.
You can still use pygame.font until you decide to call install(), which 
will replace pygame.font with this module.
 
Notes:
 
    * no ability to load TTF files, PangoFont uses the font files registered 
        with GTK/X to render graphics, it cannot load an arbitrary TTF file.  
        Most non-Sugar Pygame games use bundled TTF files, which means 
        that you will likely need at least some changes to your font handling.
        
        Note, however, that the Pygame Font class is available to load the TTF 
        files, so if you don't want to take advantage of PangoFont for already 
        written code, but want to use it for "system font" operations, you can 
        mix the two.
        
    * metrics are missing, Pango can provide the information, but the more 
        involved metrics system means that translating to the simplified model 
        in Pygame has as of yet not been accomplished.
        
    * better support for "exotic" languages and scripts (which is why we use it)
 
The main problem with SDL_ttf is that it doesn't handle internationalization 
nearly as well as Pango (in fact, pretty much nothing does). However, it is 
fairly fast and it has a rich interface. You should avoid fonts where possible, 
prerender using Pango for internationalizable text, and use Pango or SDL_ttf 
for text that really needs to be rerendered each frame. (Use SDL_ttf if profiling 
demonstrates that performance is poor with Pango.)
 
Note:
    Font -- is the original Pygame Font class, which allows you to load 
        fonts from TTF files/filenames
    PangoFont -- is the Pango-specific rendering engine which allows 
        for the more involved cross-lingual rendering operations.

 
Modules
       
olpcgames._cairoimage
gtk
logging
pango
pangocairo
pygame
struct
pygame.surface

 
Classes
       
object
PangoFont
SysFont

 
class PangoFont(object)
    Base class for a pygame.font.Font-like object drawn by Pango
 
Attributes of note:
 
    fd -- instances Pango FontDescription object 
    WEIGHT_* -- parameters for use with set_weight
    STYLE_* -- parameters for use with set_style
 
  Methods defined here:
__init__(self, family=None, size=None, bold=False, italic=False, underline=False, fd=None)
If you know what pango.FontDescription (fd) you want, pass it in as
'fd'.  Otherwise, specify any number of family, size, bold, or italic,
and we will try to match something up for you.
get_bold(self)
Return whether our font's weight is bold (or above)
get_italic(self)
Return whether we are currently italicised
get_style(self)
Get our font description's pango-style
get_underline(self)
Retrieve our current underline setting
get_weight(self)
Explicitly get our pango-style weight value
render(self, text, antialias=True, color=(255, 255, 255), background=None)
Render the font onto a new Surface and return it.
We ignore 'antialias' and use system settings.
 
text -- (unicode) string with the text to render
antialias -- attempt to antialias the text or not
color -- three or four-tuple of 0-255 values specifying rendering 
    colour for the text 
background -- three or four-tuple of 0-255 values specifying rendering 
    colour for the background, or None for trasparent background
 
returns a pygame image instance
set_bold(self, bold=True)
Set our font description's weight to "bold" or "normal"
 
bold -- boolean, whether to set the value to "bold" weight or not
set_italic(self, italic=True)
Set our "italic" value (style)
set_style(self, style)
Set our font description's pango-style
set_underline(self, underline=True)
Set our current underlining properly
set_weight(self, weight)
Explicitly set our pango-style weight value
size(self, text)
Determine space required to render given text
 
returns tuple of (width,height)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
STYLE_ITALIC = <enum PANGO_STYLE_ITALIC of type PangoStyle>
STYLE_NORMAL = <enum PANGO_STYLE_NORMAL of type PangoStyle>
STYLE_OBLIQUE = <enum PANGO_STYLE_OBLIQUE of type PangoStyle>
WEIGHT_BOLD = <enum PANGO_WEIGHT_BOLD of type PangoWeight>
WEIGHT_HEAVY = <enum PANGO_WEIGHT_HEAVY of type PangoWeight>
WEIGHT_LIGHT = <enum PANGO_WEIGHT_LIGHT of type PangoWeight>
WEIGHT_NORMAL = <enum PANGO_WEIGHT_NORMAL of type PangoWeight>
WEIGHT_SEMIBOLD = <enum PANGO_WEIGHT_SEMIBOLD of type PangoWeight>
WEIGHT_ULTRABOLD = <enum PANGO_WEIGHT_ULTRABOLD of type PangoWeight>
WEIGHT_ULTRALIGHT = <enum PANGO_WEIGHT_ULTRALIGHT of type PangoWeight>

 
class SysFont(PangoFont)
    Construct a PangoFont from a font description (name), size in pixels,
bold, and italic designation. Similar to SysFont from Pygame.
 
 
Method resolution order:
SysFont
PangoFont
object

Methods defined here:
__init__(self, name, size, bold=False, italic=False)

Methods inherited from PangoFont:
get_bold(self)
Return whether our font's weight is bold (or above)
get_italic(self)
Return whether we are currently italicised
get_style(self)
Get our font description's pango-style
get_underline(self)
Retrieve our current underline setting
get_weight(self)
Explicitly get our pango-style weight value
render(self, text, antialias=True, color=(255, 255, 255), background=None)
Render the font onto a new Surface and return it.
We ignore 'antialias' and use system settings.
 
text -- (unicode) string with the text to render
antialias -- attempt to antialias the text or not
color -- three or four-tuple of 0-255 values specifying rendering 
    colour for the text 
background -- three or four-tuple of 0-255 values specifying rendering 
    colour for the background, or None for trasparent background
 
returns a pygame image instance
set_bold(self, bold=True)
Set our font description's weight to "bold" or "normal"
 
bold -- boolean, whether to set the value to "bold" weight or not
set_italic(self, italic=True)
Set our "italic" value (style)
set_style(self, style)
Set our font description's pango-style
set_underline(self, underline=True)
Set our current underlining properly
set_weight(self, weight)
Explicitly set our pango-style weight value
size(self, text)
Determine space required to render given text
 
returns tuple of (width,height)

Data descriptors inherited from PangoFont:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes inherited from PangoFont:
STYLE_ITALIC = <enum PANGO_STYLE_ITALIC of type PangoStyle>
STYLE_NORMAL = <enum PANGO_STYLE_NORMAL of type PangoStyle>
STYLE_OBLIQUE = <enum PANGO_STYLE_OBLIQUE of type PangoStyle>
WEIGHT_BOLD = <enum PANGO_WEIGHT_BOLD of type PangoWeight>
WEIGHT_HEAVY = <enum PANGO_WEIGHT_HEAVY of type PangoWeight>
WEIGHT_LIGHT = <enum PANGO_WEIGHT_LIGHT of type PangoWeight>
WEIGHT_NORMAL = <enum PANGO_WEIGHT_NORMAL of type PangoWeight>
WEIGHT_SEMIBOLD = <enum PANGO_WEIGHT_SEMIBOLD of type PangoWeight>
WEIGHT_ULTRABOLD = <enum PANGO_WEIGHT_ULTRABOLD of type PangoWeight>
WEIGHT_ULTRALIGHT = <enum PANGO_WEIGHT_ULTRALIGHT of type PangoWeight>

 
Functions
       
_fixColorBase(v)
Return a properly clamped colour in floating-point space
fontByDesc(desc='', bold=False, italic=False)
Constructs a FontDescription from the given string representation.
    
The format of the fontByDesc string representation is passed directly 
to the pango.FontDescription constructor and documented at:
 
    http://www.pygtk.org/docs/pygtk/class-pangofontdescription.html#constructor-pangofontdescription
 
Bold and italic are provided as a convenience.
 
The format of the string representation is:
 
  "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]"
 
where FAMILY-LIST is a comma separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace separated list of words where each WORD describes one of style, variant, weight, or stretch, and SIZE is an decimal number (size in points). For example the following are all valid string representations:
 
  "sans bold 12"
  "serif,monospace bold italic condensed 16"
  "normal 10"
 
The commonly available font families are: Normal, Sans, Serif and Monospace. The available styles are:
Normal  the font is upright.
Oblique the font is slanted, but in a roman style.
Italic  the font is slanted in an italic style.
 
The available weights are:
Ultra-Light     the ultralight weight (= 200)
Light   the light weight (=300)
Normal  the default weight (= 400)
Bold    the bold weight (= 700)
Ultra-Bold      the ultra-bold weight (= 800)
Heavy   the heavy weight (= 900)
 
The available variants are:
Normal  
Small-Caps      
 
The available stretch styles are:
Ultra-Condensed the smallest width
Extra-Condensed 
Condensed       
Semi-Condensed  
Normal  the normal width
Semi-Expanded   
Expanded        
Extra-Expanded  
Ultra-Expanded  the widest width
get_default_font()
Return default-font specification to be passed to e.g. fontByDesc
get_fonts()
Return the set of all fonts available (currently just 3 generic types)
get_init()
Return boolean indicating whether we are initialised
 
Always returns True
init()
Initialise the module (null operation)
install()
Replace Pygame's font module with this module
match_font(name, bold=False, italic=False)
Stub, does not work, use fontByDesc instead
quit()
De-initialise the module (null operation)
stdcolor(color)
Produce a 4-element 0.0-1.0 color value from input