xlibconf
--------

So I've started playing with pygame, and immediately ran into a couple of
annoyances. There appears to be no standard way to say "give me color 'white'"
or "color 'FF00FF'". It also wants font files to be specified exactly. This
is a portability nightmare, unless you're shipping TTF files around all the
time with your application. Bugger that for a game of soldiers, I say!

xlibconf exposes the standard rgb.txt file, as well as an interface to
the X11 font directory/ies.

Note that I'll be changing this soon to support the Xft style names -
see http://keithp.com/~keithp/talks/xtc2001/paper/xft.html#sec-xft-name

Sample Usage
============

Here's a small sample::

    >>> import xlibconf
    >>> xlibconf.init(x11lib='/usr/lib/X11')
    # I only want iso8859-1 fonts.
    >>> xlibconf.setFontDefaults(registry='iso8859', encoding='1')
    # give me bold italic arial.
    >>> print xlibconf.getFont(family='arial',weight='bold',slant='i')
    ImmutableSet([('-monotype-Arial-bold-i-normal--0-0-0-0-p-0-iso8859-1',
    '/usr/lib/X11/fonts/TTF/Arialbi.TTF')])
    >>> print xlibconf.getColor("red")
    (255, 0, 0)
    >>> print xlibconf.getColor("#eeddbb")
    (238, 221, 187)


Simple API
==========

    xlibconf.init(x11lib='/usr/lib/X11', fontsdotdir='/path/to/ttf/fonts.dir', rgbdottxt='/path/to/rgb.txt')
        load the databases. By default, it loads x11lib/rgb.txt for colors, and x11lib/fonts/TrueType/fonts.dir for fonts. Other locations known to work::

            /usr/share/fonts/default/TrueType/fonts.dir
            /usr/share/fonts/ja/TrueType/fonts.dir

    xlibconf.loadFonts(fontsdotdir)
        load a different fonts.dir file into the global font registry.  This can be called multiple times with different fonts.dir files, it will merge them together.

    xlibconf.loadColors(rgbdottxt)
        load a different rgb.txt file into the global color registry
    
    xlibconf.getColor(color)
        return an RGB triple for the specified color, which is either a color name as in rgb.txt, #rrggbb, or #rgb (where r,g,b are hex digits).

    xlibconf.getFont(key=value,...)
        return a list of (fontname, fontfile) for fonts that match the specified keywords. See the later section on Font selectors for more. The fontname is a full -dash-seperated--fontname-

    xlibconf.listFontAttribute(keyword, key=value,...)
        return a list of valid values of 'keyword' for the given font spec. Can be used to see what values are valid. For instance::

              >>> xlibconf.listFontAttribute('weight', family='arial')
              Set(['medium', 'bold'])

    xlibconf.PyGameFont(selectors)
        returns a (wrapped) pygame.font.Font object matching the supplied selectors. You must also supply an additional keyword argument 'size'. This object supports all the `usual font methods`_, plus one additional method: getFont(). This method takes one or more selectors and returns the current font, modified by the selectors. So, for instance::

            >>> normal = xlibfont.PyGameFont(family='arial', weight='medium', slant='r', size=12)
            >>> bold = normal.getFont(weight='bold')
            >>> italic = normal.getFont(slant='i')
            >>> bolditalic = normal.getFont(weight='bold', slant='i')

Note that fonts retrieved with PyGameFont.getFont() are likely to produce
much higher quality output than using the font.set_bold()/set_italic() &c
methods. See `this font screenshot`_ - it shows the difference between, say,
arial-bold, and the arial font, with the 'set_bold()' method called.

.. _this font screenshot: font-samples.png

.. _usual font methods: http://www.pygame.org/docs/ref/Font.html

For more examples of the API, read the source, or install the package and
run::

     pydoc xlibconf


Font selectors
==============

Font selection keywords are lifted from the X Logical Font Description
format, see either this `XLFD info page`_ or this `XLFD PDF file`_  for
full details. The short and simple list that's supported by default are:

    foundry
        The font foundry, e.g. 'adobe', 'b&h'

    family
        The font family, e.g. 'arial', 'helvetica', 

    weight
        The font weight, e.g. 'medium', 'bold', 'semibold'

    slant
        The posture of the font, e.g 'i' (italic), 'o' (oblique), 'r' (roman)

    swidth
        The width of the font, e.g 'normal', 'semicondensed', 'wide'

    adstyle
        Additional style name - e.g 'decorated', 'sans', ...

    registry
        The character set registry - e.g. 'iso8859', 'ascii'

    encoding
        The character set encoding - e.g. '1', '15', 

The registry and encoding are normally specified together - e.g.
'registry="iso8859", encoding="1"' will give a Western European 
font. 

Values for these keywords can either be a string, or a sequence of strings.
If the latter, the resulting set contains all fonts that match any of
the values in the sequence.

Since these are true-type fonts, the various size options are not supported.

Note that there's a lot of options, true, but you can set the common
ones using the xlibconf.setFontDefaults(...) function.

.. _XLFD info page: http://wwwinfo.cern.ch/umtf/working-groups/X11/fonts/xlfd.html

.. _XLFD PDF file: http://www.x-docs.org/XLFD/xlfd.pdf



Availability
============

Version 0.2 released 18th Feb, 2003

- added PyGameFont class.

- font lookup can now pass a sequence of strings as a value. Any that match are returned.



Older versions
++++++++++++++

Version 0.1.1 released 17th Feb, 2003 available here: `xlibconf-0.1.1.tar.gz`_.
This version corrects an extremely last minute stupid error in 0.1.

Version 0.1 released 17th Feb, 2003 available here: `xlibconf-0.1.tar.gz`_

.. _xlibconf-0.2.tar.gz: xlibconf-0.2.tar.gz

.. _xlibconf-0.1.1.tar.gz: xlibconf-0.1.1.tar.gz

.. _xlibconf-0.1.tar.gz: xlibconf-0.1.tar.gz

Feedback
========

Feedback to me at anthony@interlink.com.au

License
=======

This code is released under a Python-style license, and is
(c) 2003 Anthony Baxter and ekit.com, Inc.