Menu
▾
▴
[r3311]: / trunk / htdocs / matplotlib.font_manager.html.template Maximize Restore History
295 lines (261 with data), 27.6 kB
@header@
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="heading">
<tr bgcolor="#7799ee">
<td valign=bottom> <br>
<font color="#ffffff" face="helvetica, arial"> <br><big><big><strong><a href="matplotlib.html"><font color="#ffffff">matplotlib</font></a>.font_manager</strong></big></big></font></td
><td align=right valign=bottom
><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:/home/jdhunter/dev/lib/python2.5/site-packages/matplotlib/font_manager.py">/home/jdhunter/dev/lib/python2.5/site-packages/matplotlib/font_manager.py</a></font></td></tr></table>
<p><tt>A module for finding, managing, and using fonts across-platforms.<br>
<br>
This module provides a single <a href="#FontManager">FontManager</a> that can be shared across<br>
backends and platforms. The findfont() method returns the best<br>
TrueType (TTF) font file in the local or system font path that matches<br>
the specified <a href="#FontProperties">FontProperties</a>. The <a href="#FontManager">FontManager</a> also handles Adobe Font<br>
Metrics (AFM) font files for use by the PostScript backend.<br>
<br>
The design is based on the W3C Cascading Style Sheet, Level 1 (CSS1)<br>
font specification (<a href="http://www.w3.org/TR/1998/REC-CSS2-19980512/">http://www.w3.org/TR/1998/REC-CSS2-19980512/</a> ).<br>
Future versions may implement the Level 2 or 2.1 specifications.<br>
<br>
<br>
KNOWN ISSUES<br>
<br>
- documentation<br>
- font variant is untested<br>
- font stretch is incomplete<br>
- font size is incomplete<br>
- font size_adjust is incomplete<br>
- default font algorithm needs improvement and testing<br>
- setWeights function needs improvement<br>
- 'light' is an invalid weight value, remove it.<br>
- update_fonts not implemented<br>
<br>
<br>
Authors : John Hunter <jdhunter@ace.bsd.uchicago.edu><br>
Paul Barrett <Barrett@STScI.Edu><br>
Copyright : John Hunter (2004,2005), Paul Barrett (2004,2005)<br>
License : matplotlib license (PSF compatible)<br>
The font directory code is from ttfquery,<br>
see license/LICENSE_TTFQUERY.</tt></p>
<p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#aa55cc">
<td colspan=3 valign=bottom> <br>
<font color="#fffff" face="helvetica, arial"><big><strong>Modules</strong></big></font></td></tr>
<tr><td bgcolor="#aa55cc"><tt> </tt></td><td> </td>
<td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="matplotlib.afm.html">matplotlib.afm</a><br>
<a href="matplotlib.ft2font.html">matplotlib.ft2font</a><br>
</td><td width="25%" valign=top><a href="glob.html">glob</a><br>
<a href="matplotlib.html">matplotlib</a><br>
</td><td width="25%" valign=top><a href="os.html">os</a><br>
<a href="cPickle.html">cPickle</a><br>
</td><td width="25%" valign=top><a href="shutil.html">shutil</a><br>
<a href="sys.html">sys</a><br>
</td></tr></table></td></tr></table><p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#ee77aa">
<td colspan=3 valign=bottom> <br>
<font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr>
<tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td>
<td width="100%"><dl>
<dt><font face="helvetica, arial"><a href="__builtin__.html#object">__builtin__.object</a>
</font></dt><dd>
<dl>
<dt><font face="helvetica, arial"><a href="matplotlib.font_manager.html#FontKey">FontKey</a>
</font></dt></dl>
</dd>
<dt><font face="helvetica, arial"><a href="matplotlib.font_manager.html#FontManager">FontManager</a>
</font></dt><dt><font face="helvetica, arial"><a href="matplotlib.font_manager.html#FontProperties">FontProperties</a>
</font></dt></dl>
<p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#ffc8d8">
<td colspan=3 valign=bottom> <br>
<font color="#000000" face="helvetica, arial"><a name="FontKey">class <strong>FontKey</strong></a>(<a href="__builtin__.html#object">__builtin__.object</a>)</font></td></tr>
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
<td colspan=2><tt>A class for storing Font properties. It is used when populating<br>
the font dictionary.<br> </tt></td></tr>
<tr><td> </td>
<td width="100%">Methods defined here:<br>
<dl><dt><a name="FontKey-__init__"><strong>__init__</strong></a>(self, name<font color="#909090">=''</font>, style<font color="#909090">='normal'</font>, variant<font color="#909090">='normal'</font>, weight<font color="#909090">='normal'</font>, stretch<font color="#909090">='normal'</font>, size<font color="#909090">='medium'</font>)</dt></dl>
<hr>
Data descriptors defined here:<br>
<dl><dt><strong>__dict__</strong></dt>
<dd><tt>dictionary for instance variables (if defined)</tt></dd>
</dl>
<dl><dt><strong>__weakref__</strong></dt>
<dd><tt>list of weak references to the object (if defined)</tt></dd>
</dl>
</td></tr></table> <p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#ffc8d8">
<td colspan=3 valign=bottom> <br>
<font color="#000000" face="helvetica, arial"><a name="FontManager">class <strong>FontManager</strong></a></font></td></tr>
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
<td colspan=2><tt>On import, the <a href="#FontManager">FontManager</a> creates a dictionary of TrueType<br>
fonts based on the font properties: name, style, variant, weight,<br>
stretch, and size. The <a href="#FontManager-findfont">findfont</a>() method searches this dictionary<br>
for a font file name that exactly matches the font properties of the<br>
specified text. If none is found, a default font is returned. By<br>
updating the dictionary with the properties of the found font, the<br>
font dictionary can act like a font cache.<br> </tt></td></tr>
<tr><td> </td>
<td width="100%">Methods defined here:<br>
<dl><dt><a name="FontManager-__init__"><strong>__init__</strong></a>(self, size<font color="#909090">=None</font>, weight<font color="#909090">='normal'</font>)</dt></dl>
<dl><dt><a name="FontManager-findfont"><strong>findfont</strong></a>(self, prop, fontext<font color="#909090">='ttf'</font>)</dt><dd><tt>Search the font dictionary for a font that exactly or closely<br>
matches the specified font properties. See the <a href="#FontProperties">FontProperties</a> class<br>
for a description.<br>
<br>
The properties are searched in the following order: name, style,<br>
variant, weight, stretch, and size. The font weight always matches<br>
returning the closest weight, and the font size always matches for<br>
scalable fonts. An oblique style font will be used inplace of a<br>
missing italic style font if present. See the W3C Cascading Style<br>
Sheet, Level 1 (CSS1; <a href="http://www.w3.org/TR/1998/REC-CSS2-19980512/">http://www.w3.org/TR/1998/REC-CSS2-19980512/</a>)<br>
documentation for a description of the font finding algorithm.</tt></dd></dl>
<dl><dt><a name="FontManager-get_default_size"><strong>get_default_size</strong></a>(self)</dt><dd><tt>Return the default font size.</tt></dd></dl>
<dl><dt><a name="FontManager-get_default_weight"><strong>get_default_weight</strong></a>(self)</dt><dd><tt>Return the default font weight.</tt></dd></dl>
<dl><dt><a name="FontManager-set_default_size"><strong>set_default_size</strong></a>(self, size)</dt><dd><tt>Set the default font size in points. The initial value is set by font.size in rc.</tt></dd></dl>
<dl><dt><a name="FontManager-set_default_weight"><strong>set_default_weight</strong></a>(self, weight)</dt><dd><tt>Set the default font weight. The initial value is 'normal'.</tt></dd></dl>
<dl><dt><a name="FontManager-update_fonts"><strong>update_fonts</strong></a>(self, filenames)</dt><dd><tt>Update the font dictionary with new font files.<br>
Currently not implemented.</tt></dd></dl>
</td></tr></table> <p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#ffc8d8">
<td colspan=3 valign=bottom> <br>
<font color="#000000" face="helvetica, arial"><a name="FontProperties">class <strong>FontProperties</strong></a></font></td></tr>
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
<td colspan=2><tt>A class for storing and manipulating font properties.<br>
<br>
The font properties are those described in the W3C Cascading Style<br>
Sheet, Level 1 (CSS1; <a href="http://www.w3.org/TR/1998/REC-CSS2-19980512/">http://www.w3.org/TR/1998/REC-CSS2-19980512/</a>)<br>
font specification. The six properties are:<br>
<br>
family - A list of font names in decreasing order of priority.<br>
The last item is the default font name and is given the<br>
name of the font family, either serif, sans-serif,<br>
cursive, fantasy, and monospace.<br>
style - Either normal, italic or oblique.<br>
variant - Either normal or small-caps.<br>
stretch - Either an absolute value of ultra-condensed, extra-<br>
condensed, condensed, semi-condensed, normal, semi-<br>
expanded, expanded, extra-expanded or ultra-expanded;<br>
or a relative value of narrower or wider.<br>
This property is currently not implemented and is set to<br>
normal.<br>
weight - A numeric value in the range 100, 200, 300, ..., 900.<br>
size - Either an absolute value of xx-small, x-small, small,<br>
medium, large, x-large, xx-large; or a relative value<br>
of smaller or larger; or an absolute font size, e.g. 12;<br>
or scalable.<br>
<br>
The default font property for TrueType fonts is: sans-serif, normal,<br>
normal, normal, 400, scalable.<br>
<br>
The preferred usage of font sizes is to use the absolute values, e.g.<br>
large, instead of absolute font sizes, e.g. 12. This approach allows<br>
all text sizes to be made larger or smaller based on the font manager's<br>
default font size, i.e. by using the set_default_size() method of the<br>
font manager.<br>
<br>
Examples:<br>
<br>
# Load default font properties<br>
>>> p = <a href="#FontProperties">FontProperties</a>()<br>
>>> p.<a href="#FontProperties-get_family">get_family</a>()<br>
['Bitstream Vera Sans', 'Lucida Grande', 'Verdana', 'Geneva', 'Lucida', 'Arial', 'Helvetica', 'sans-serif']<br>
<br>
# Change font family to 'fantasy'<br>
>>> p.<a href="#FontProperties-set_family">set_family</a>('fantasy')<br>
>>> p.<a href="#FontProperties-get_family">get_family</a>()<br>
['Comic Sans MS', 'Chicago', 'Charcoal', 'Impact', 'Western', 'fantasy']<br>
<br>
# Make these fonts highest priority in font family<br>
>>> p.<a href="#FontProperties-set_name">set_name</a>(['foo', 'fantasy', 'bar', 'baz'])<br>
Font name 'fantasy' is a font family. It is being deleted from the list.<br>
>>> p.<a href="#FontProperties-get_family">get_family</a>()<br>
['foo', 'bar', 'baz', 'Comic Sans MS', 'Chicago', 'Charcoal', 'Impact', 'Western', 'fantasy']<br> </tt></td></tr>
<tr><td> </td>
<td width="100%">Methods defined here:<br>
<dl><dt><a name="FontProperties-__hash__"><strong>__hash__</strong></a>(self)</dt></dl>
<dl><dt><a name="FontProperties-__init__"><strong>__init__</strong></a>(self, family<font color="#909090">=None</font>, style<font color="#909090">=None</font>, variant<font color="#909090">=None</font>, weight<font color="#909090">=None</font>, stretch<font color="#909090">=None</font>, size<font color="#909090">=None</font>, fname<font color="#909090">=None</font>)</dt></dl>
<dl><dt><a name="FontProperties-__str__"><strong>__str__</strong></a>(self)</dt></dl>
<dl><dt><a name="FontProperties-copy"><strong>copy</strong></a>(self)</dt><dd><tt>Return a deep copy of self</tt></dd></dl>
<dl><dt><a name="FontProperties-get_family"><strong>get_family</strong></a>(self)</dt><dd><tt>Return a list of font names that comprise the font family.</tt></dd></dl>
<dl><dt><a name="FontProperties-get_name"><strong>get_name</strong></a>(self)</dt><dd><tt>Return the name of the font that best matches the font properties.</tt></dd></dl>
<dl><dt><a name="FontProperties-get_size"><strong>get_size</strong></a>(self)</dt><dd><tt>Return the font size.</tt></dd></dl>
<dl><dt><a name="FontProperties-get_size_in_points"><strong>get_size_in_points</strong></a>(self, parent_size<font color="#909090">=None</font>)</dt><dd><tt>Return the size property as a numeric value. String values<br>
are converted to their corresponding numeric value.</tt></dd></dl>
<dl><dt><a name="FontProperties-get_stretch"><strong>get_stretch</strong></a>(self)</dt><dd><tt>Return the font stretch or width. Options are: normal,<br>
narrow, condensed, or wide.</tt></dd></dl>
<dl><dt><a name="FontProperties-get_style"><strong>get_style</strong></a>(self)</dt><dd><tt>Return the font style. Values are: normal, italic or oblique.</tt></dd></dl>
<dl><dt><a name="FontProperties-get_variant"><strong>get_variant</strong></a>(self)</dt><dd><tt>Return the font variant. Values are: normal or small-caps.</tt></dd></dl>
<dl><dt><a name="FontProperties-get_weight"><strong>get_weight</strong></a>(self)</dt><dd><tt>Return the font weight. See the <a href="#FontProperties">FontProperties</a> class for a<br>
a list of possible values.</tt></dd></dl>
<dl><dt><a name="FontProperties-set_family"><strong>set_family</strong></a>(self, family)</dt><dd><tt>Change the font family. Options are: serif, sans-serif, cursive,<br>
fantasy, or monospace.</tt></dd></dl>
<dl><dt><a name="FontProperties-set_name"><strong>set_name</strong></a>(self, names)</dt><dd><tt> Add one or more font names to the font family list. If the<br>
font name is already in the list, then the font is given a higher<br>
priority in the font family list. To change the font family, use the<br>
<a href="#FontProperties-set_family">set_family</a>() method.</tt></dd></dl>
<dl><dt><a name="FontProperties-set_size"><strong>set_size</strong></a>(self, size)</dt><dd><tt>Set the font size.</tt></dd></dl>
<dl><dt><a name="FontProperties-set_stretch"><strong>set_stretch</strong></a>(self, stretch)</dt><dd><tt>Set the font stretch or width. Options are: normal, narrow,<br>
condensed, or wide.</tt></dd></dl>
<dl><dt><a name="FontProperties-set_style"><strong>set_style</strong></a>(self, style)</dt><dd><tt>Set the font style. Values are: normal, italic or oblique.</tt></dd></dl>
<dl><dt><a name="FontProperties-set_variant"><strong>set_variant</strong></a>(self, variant)</dt><dd><tt>Set the font variant. Values are: normal or small-caps.</tt></dd></dl>
<dl><dt><a name="FontProperties-set_weight"><strong>set_weight</strong></a>(self, weight)</dt><dd><tt>Set the font weight. See the <a href="#FontProperties">FontProperties</a> class for a<br>
a list of possible values.</tt></dd></dl>
</td></tr></table></td></tr></table><p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#eeaa77">
<td colspan=3 valign=bottom> <br>
<font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr>
<tr><td bgcolor="#eeaa77"><tt> </tt></td><td> </td>
<td width="100%"><dl><dt><a name="-OSXFontDirectory"><strong>OSXFontDirectory</strong></a>()</dt><dd><tt>Return the system font directories for OS X.</tt></dd></dl>
<dl><dt><a name="-OSXInstalledFonts"><strong>OSXInstalledFonts</strong></a>(directory<font color="#909090">=None</font>, fontext<font color="#909090">=None</font>)</dt><dd><tt>Get list of font files on OS X - ignores font suffix by default</tt></dd></dl>
<dl><dt><a name="-add_filename"><strong>add_filename</strong></a>(fontdict, prop, fname)</dt><dd><tt>A function to add a font file name to the font dictionary using<br>
the <a href="#FontKey">FontKey</a> properties. If a font property has no dictionary, then<br>
create it.</tt></dd></dl>
<dl><dt><a name="-afmFontProperty"><strong>afmFontProperty</strong></a>(font)</dt><dd><tt>A function for populating the <a href="#FontKey">FontKey</a> by extracting information<br>
from the AFM font file.</tt></dd></dl>
<dl><dt><a name="-createFontDict"><strong>createFontDict</strong></a>(fontfiles, fontext<font color="#909090">='ttf'</font>)</dt><dd><tt>A function to create a dictionary of font file paths. The<br>
default is to create a dictionary for TrueType fonts. An AFM font<br>
dictionary can optionally be created.</tt></dd></dl>
<dl><dt><a name="-findSystemFonts"><strong>findSystemFonts</strong></a>(fontpaths<font color="#909090">=None</font>, fontext<font color="#909090">='ttf'</font>)</dt><dd><tt>Search for fonts in the specified font paths, or use the system<br>
paths if none given. A list of TrueType fonts are returned by default<br>
with AFM fonts as an option.</tt></dd></dl>
<dl><dt><a name="-pickle_dump"><strong>pickle_dump</strong></a>(data, filename)</dt><dd><tt>Equivalent to pickle.dump(data, open(filename, 'w'))<br>
but closes the file to prevent filehandle leakage.</tt></dd></dl>
<dl><dt><a name="-pickle_load"><strong>pickle_load</strong></a>(filename)</dt><dd><tt>Equivalent to pickle.load(open(filename, 'r'))<br>
but closes the file to prevent filehandle leakage.</tt></dd></dl>
<dl><dt><a name="-setWeights"><strong>setWeights</strong></a>(font)</dt><dd><tt>A function to populate missing values in a font weight<br>
dictionary. This proceedure is necessary since the font finding<br>
algorithm always matches on the weight property.</tt></dd></dl>
<dl><dt><a name="-ttfFontProperty"><strong>ttfFontProperty</strong></a>(font)</dt><dd><tt>A function for populating the <a href="#FontKey">FontKey</a> by extracting information<br>
from the TrueType font file.</tt></dd></dl>
<dl><dt><a name="-ttfdict_to_fnames"><strong>ttfdict_to_fnames</strong></a>(d)</dt><dd><tt>flatten a ttfdict to all the filenames it contains</tt></dd></dl>
<dl><dt><a name="-weight_as_number"><strong>weight_as_number</strong></a>(weight)</dt><dd><tt>Return the weight property as a numeric value. String values<br>
are converted to their corresponding numeric value.</tt></dd></dl>
<dl><dt><a name="-win32FontDirectory"><strong>win32FontDirectory</strong></a>()</dt><dd><tt>Return the user-specified font directory for Win32.</tt></dd></dl>
<dl><dt><a name="-win32InstalledFonts"><strong>win32InstalledFonts</strong></a>(directory<font color="#909090">=None</font>, fontext<font color="#909090">='ttf'</font>)</dt><dd><tt>Search for fonts in the specified font directory, or use the<br>
system directories if none given. A list of TrueType fonts are<br>
returned by default with AFM fonts as an option.</tt></dd></dl>
<dl><dt><a name="-x11FontDirectory"><strong>x11FontDirectory</strong></a>()</dt><dd><tt>Return the system font directories for X11.</tt></dd></dl>
</td></tr></table><p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#55aa55">
<td colspan=3 valign=bottom> <br>
<font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr>
<tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td>
<td width="100%"><strong>MSFolders</strong> = r'Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders'<br>
<strong>MSFontDirectories</strong> = [r'SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts', r'SOFTWARE\Microsoft\Windows\CurrentVersion\Fonts']<br>
<strong>OSXFontDirectories</strong> = ['/Library/Fonts/', '/Network/Library/Fonts/', '/System/Library/Fonts/', '/home/jdhunter/Library/Fonts']<br>
<strong>X11FontDirectories</strong> = ['/usr/X11R6/lib/X11/fonts/TTF/', '/usr/share/fonts/', '/usr/local/share/fonts/', '/usr/lib/openoffice/share/fonts/truetype/']<br>
<strong>fontManager</strong> = <matplotlib.font_manager.FontManager instance at 0x8279b8c><br>
<strong>font_scalings</strong> = {'large': 1.2, 'medium': 1.0, 'small': 0.83299999999999996, 'x-large': 1.4399999999999999, 'x-small': 0.69399999999999995, 'xx-large': 1.728, 'xx-small': 0.57899999999999996}<br>
<strong>home</strong> = '/home/jdhunter'<br>
<strong>path</strong> = '/home/jdhunter/Library/Fonts'<br>
<strong>rcParams</strong> = {'axes.axisbelow': False, 'axes.edgecolor': 'k', 'axes.facecolor': 'w', 'axes.formatter.limits': (-7, 7), 'axes.grid': False, 'axes.hold': True, 'axes.labelcolor': 'k', 'axes.labelsize': 12, 'axes.linewidth': 1.0, 'axes.titlesize': 14, ...}<br>
<strong>verbose</strong> = <matplotlib.Verbose instance at 0x8250fec><br>
<strong>weight_dict</strong> = {'black': 900, 'bold': 700, 'book': 400, 'demi': 600, 'demibold': 600, 'extra bold': 800, 'heavy': 800, 'light': 200, 'medium': 500, 'normal': 400, ...}</td></tr></table>
@footer@
