#
#		Python GUI - Fonts - Generic
#

import sys
from Properties import overridable_property

class Font(object):
    """A Font object represents a set of characters of a particular 
    typeface, style and size. Font objects are immutable.
    
    Constructors:
        Font(family, size, style)
            family = family name
            size	 = size in points
            style	 = a list of 'bold', 'italic'
    
    Properties:
        family	-->	 string
        size		-->	 number
        style		-->	 ['bold', 'italic']
        ascent	-->	 number
        descent -->	 number
        height	-->	 number
    """
    
    family = overridable_property('family', "Family name ('Times', 'Helvetica', etc.)")
    size = overridable_property('size', "Size in points")
    style = overridable_property('style', "A list of 'bold', 'italic'")
    ascent = overridable_property('ascent', "Distance from baseline to top of highest character")
    descent = overridable_property('descent', "Distance from baseline to bottom of lowest character")
    height = overridable_property('height', "Sum of ascent and descent")
    line_height = overridable_property('line_height', "Recommended distance between baselines")
    
    def width(self, s, start = 0, end = sys.maxint):
        """width(s [,start [,end ]])
        The width of the specified part of the given string in this font."""
        raise NotImplementedError

    def x_to_pos(self, s, x):
        """Given a number of pixels measured from the left of
        the given string, returns the nearest inter-character position. 
        Returns 0 if x is negative, and len(string) if x is beyond the 
        right end of the string."""
        raise NotImplementedError

    def __str__(self):
        return "Font(%r,%g,%s)" % (self.family, self.size, self.style)
