X11FreeTypeFont (Ctalk)

X11FreeTypeFont

`X11FreeTypeFont` Class

This class contains the methods that handle FreeType fonts using the Xft and Fontconfig libraries. In classes and methods that use fonts, FreeType fonts take priority if they are available and the program has initialized the library with the initFontLib method, which is described in further detail below. Otherwise, applications use the X Window System’s builtin bitmap fonts.

Internally Ctalk uses the Fontconfig library to locate the system’s fonts.conf file. The fonts.conf file’s default location is configured when the library is built. Generally, the font.conf file’s path is /etc/fonts/fonts.conf or /usr/local/etc/fonts/fonts.conf.

However, an alternate fonts.conf pathname may be set in the environment with the ‘FONTCONFIG_FILE’ environment variable. If its value begins with a ‘~’, the path is relative to the user’s ‘HOME’ directory. If the name doesn’t start with a ‘/’, then the pathname is relative to the fontconfig libraries’ default installation directory. This directory can be changed by setting the ‘FONTCONFIG_PATH’ environment variable to an alternate directory.

Classes that use X Window System graphics (that is, X11Pane and its subclasses) can use either the X libraries’ built-in bitmap fonts (via the pane’s fontVar instance variable), or the scalable Freetype fonts (via the pane’s ftFontVar instance variable).

The default is to use X’s built in bitmap fonts. These fonts are initialized when the program connects to the display server.

However, to enable drawing with scalable fonts, programs need to call the initFontLib method during program initialization, with a line similar to this one.


myMainWindow ftFontVar initFontLib;

Fontconfig Font Selection

Fontconfig font descriptions have their own syntax. A Fontconfig pattern has the following elements.


<fontfamily>[-<fontsize>][:[[<name>=]<value>] ...]

Here are a few examples.


DejaVu Sans Mono
Nimbus Sans L-12
Ubuntu Mono-10.0:italic
FreeMono-10:slant=italic:weight=bold
Ubuntu Mono-10.0:italic
Roboto-12:style=bold

These font descriptors work with the selectFontFromFontConfig method. The receiver, of course, must be a X11FreetypeFont object, or the pane object’s ftFontVar instance variable. Here is an example


myWindow ftFontVar selectFontFromFontConfig "DejaVu Sans Mono-12"

The Fontconfig user guide describes the library’s font selection syntax. The documentation is available from many software package archives and also on the web at http://freedesktop.org/fontconfig.

Basic `fonts.conf` Files

Ctalk also uses a subset of the fonts.conf tag syntax and the older style of finding a system’s or users’ fonts.conf file:

1.: The file path named by the ‘$XFT_CONFIG’ environment variable.
2.: ‘$HOME/.fonts.conf’
3.: ‘$XDG_CONFIG_HOME/fontconfig/fonts.conf’
4.: /etc/fonts/fonts.conf
5.: The file /usr/X11R6/lib/X11/XftConfig

If you want to write your own font config file, the Ctalk libraries can use a subset of the fonts.conf markup.

In this case, the entries simply cause the libraries to add the fonts in the directories to the internal font database.


<fontconfig>
<dir>/usr/share/fonts/truetype/dejavu</dir>
<dir>/usr/share/fonts/truetype/freefont</dir>
<dir>/usr/share/fonts/type1/gsfonts</dir>
</fontconfig>

There is a sample ‘XftConfig’ file in the Ctalk source distribution, doc/XftConfig.sample. The fonts.conf (5) manual page and the Xft user and developer documentation provide even more information.

Further Information About Fontconfig and libXft

For further information about the the Fontconfig libraries, refer to: https://freedesktop.org/fontconfig. Information about Xft is available at http://freedesktop.org/wiki/Software/Xft.

Instance Variables

family: A String that contains the family of the currently selected font. See String.
fgRed
fgGreen
fgBlue
fgAlpha: The parameters of the font’s RGBA color. The variables are Integers and can have a range of 0 - 0xffff. See Integer.
rotation
scaleX
scaleY: Float instance variables that control the scaling and rotation of the rendered fonts.
slant
weight
dpi: Integers that contain the slant, weight, and dpi resolution of the receiver font. For a description of the Xft library’s constants, refer to the selectFont method entry, below. See Integer.
style: A String that contains the selected style parameter, if any.
pointSize: A Float that contains the font’s point size. See Float.
ascent: An Integer that contains the font’s height in pixels above the baseline.
descent: An Integer that contains the font’s height in pixels below the baseline.
handle: A Symbol that contains the value of the font’s handle. Normally this is set by X11FreeTypeFont : saveSelectedFont. The handle’s value is a cast from a XftFont * in a normal setup, like the Ctalk library’s default when the Xft libraries are enabled during installation.
height: An Integer that contains the dimensions in pixels of the font’s total height, both above and below the baseline, and any extra vertical spacing.
maxAdvance: An Integer that contains the maximum width in pixels of a font’s characters horizontal dimensions.

Instance Methods

alpha (Integer value)

Set the current Xft font’s foreground alpha channel. The argument value must be an unsigned short int; i.e., in the range 0 - 65535 (0xffff hex).

blue (Integer value)

Set the current Xft font’s foreground blue channel. The argument value must be an unsigned short int; i.e., in the range 0 - 65535 (0xffff hex).

currentDescStr (void)

Returns a String containing a font descriptor for the currently selected font. The descriptor contains the attributes that the Ctalk libraries use to select fonts: family, point size, slant, and weight.

For the complete descriptor that the Freetype library derives from the selected font’s pattern, refer to the X11FreeTypeFont : selectedFont method.

errors (void)

This is a shortcut for


myFont notifyLevel XFT_NOTIFY_ERRORS

Refer the the X11FreeTypeFont : notifyLevel method for more information.

green (Integer value)

Set the current Xft font’s foreground green channel. The argument value must be an unsigned short int; i.e., in the range 0 - 65535 (0xffff hex).

initFontLib (void)

Initializes the font library and sets the reciever’s instance variables to the default selected font. Apps need to use this method before most of the other other methods in this class.

Programs should call this method before any of the attachTo methods, so the methods can set their drawing parameters before the program starts to receive X events.

If the system is not configured to use outline fonts then the library prints a message and exits the program with a non-zero value. See ctalkXftInitLib. If the library is already initialized, then the method returns ‘0’.

isMonospace (void)

Returns a read-only Boolean value of true if the application’s selected font is monospace, false otherwise.

libIsInitialized (void)

Returns a non-zero Integer value if the Xft libraries are initialized and a font is selected.

listFonts (String pattern)

List the font descriptors in the FreeType library that contain pattern. If pattern is an empty string ‘""’ or a ‘*’, match every font descriptor.

loadNotify (void)

This is a shortcut for


myFont notifyLevel XFT_NOTIFY_LOAD

This causes methods like selectFont to display the family and size given to them, and a brief font descriptor that contains the font parameters that Ctalk uses to select fonts: family, point size, slant, and weight.

Refer to the X11FreeTypeFont : notifyLevel method for a description of information and error message levels. To return a string containing the font descriptor that the Freetype libraries derive from the selected font’s pattern, refer to the X11FreeTypeFont : selectedFont method.

namedX11Color (String colorName)

Sets the selected font’s red, green, and blue values from the X11 color name given as the argument.

Note: For a list of the colors that the X Window System recognizes, consult the file rgb.txt, which is often stored with the server’s configuration files when the GUI is installed.

notifyLevel (Integer level)

Set the Xft libraries’ notification level to level. Ctalk defines the following constants in /ctalk/ctalkdefs.h.


XFT_NOTIFY_NONE
XFT_NOTIFY_ERRORS
XFT_NOTIFY_LOAD
XFT_NOTIFY_VERBOSE

These definitions produce the following information and warning messages.

XFT_NOTIFY_NONE: The font libraries produce no output when the program is run.
XFT_NOTIFY_ERRORS: The font libraries display a warning if the library’s selected font does not match the user or appication defined font specification.
XFT_NOTIFY_LOAD: The font library displays a message containing information about the requested font, and a brief font descriptor that contains the attributes that the Ctalk libraries use to select fonts: family, point size, slant, and weight.
XFT_NOTIFY_VERBOSE: The font library displays a message that contains information about the requested font, and the complete font descriptor that the font libraries derive from the selected font’s patterm.

Note: programs should call this method before launching any processes. Generally this is before the X11Pane : openInputStream method. Otherwise, the program only displays font loads for the process it was called from.

qualifyName (String xftpattern)

Returns a fully qualified String containing a fully qualified Xft font descriptor that matches xftpattern.

quiet (void)

Sets the font libraries’ reporting level to XFT_NOTIFY_NONE. For a description of the libraries’ notification levels, refer to the notifyLevel method.

red (Integer value)

Set the current Xft font’s foreground red channel. The argument value must be an unsigned short int; i.e., in the range 0 - 65535 (0xffff hex).

saveSelectedFont (void)

This method does the work of setting the receiver’s instance variables to the values of the selected font.

selectedFont (void)

Returns the String with the descriptor of the selected font. Because a complete font descriptor contains a lot of information, this method can generate a lot of output.

RGBAColor (void)

RGBAColor (int red, int green, int blue, int alpha)

If given with no arguments, sets the current font’s color to the values of the receiver’s ‘ftRed, fgGreen, fgBlue,’ and ‘fgAlpha’ values. If the method is used with arguments, set’s the current font’s color to their values. The values are Integers and can have a range of 0-0xffff.

selectFont (void)

selectFont (String family, Integer slant, Integer weight, Integer dpi, Float pointSize)

If used without arguments, selects the font named by the receiver’s instance variables. If the statement provides arguments, only the family argument needs to describe an actual font family; that is, it has no default value. Defaults for the other arguments are described below. In this case, the method sets the receiver’s instance variables to the selected font.

For the slant and weight arguments, the Xft library defines the constants and their meanings as the following.

      SLANT
 0    Roman
 100  Italic
 110  Oblique

      WEIGHT
 0    Light
 100  Medium
 180  Demibold
 200  Bold
 210  Black

The dpi parameter should be set to the resolution of the display.

An easier way to describe a font may be to use the selectFontFromFontConfig method, which takes a FontConfig format font specification as its argument. See selectFontFromFontConfig.

selectFontFromXLFD (String xlfd)

Similar to selectFont, above, except that its argument is a string in XLFD format. That is, the method translates the XLFD argument into the Xft library’s font metrics. This makes possible font descriptions like the following.


-*-DejaVu Sans-medium-r-*-*-12-72-72-*-*-*-*-*

As with all of the selectFont* methods, refer to the X11FreeTypeFont : notifyLevel method for a description of information and error message levels. To return a string containing the font descriptor that the Freetype libraries derive from the selected font’s pattern, refer to the X11FreeTypeFont : selectedFont method.

selectFontFromFontConfig (String font_config_string)

Selects a font using the FontConfig specification given as its argument.

Refer to the beginning of the X11FreeTypeFont section for a description of Fontconfig descriptors.

Again, as with all of the selectFont* methods, refer to the X11FreeTypeFont : notifyLevel method for a description of information and error message levels. To return a string containing the font descriptor that the Freetype libraries derive from the selected font’s pattern, refer to the X11FreeTypeFont : selectedFont method.

textHeight (String text)

Return an Integer with the height in pixels of text in the currently selected FreeType font. If the Xft library is not available or not initialized, the method returns 0.

textRBearing (String text)

Return an Integer with the right bearing (the distance between the rightmost segment of a character glyph and the right edge of its character box) in pixels of text in the currently selected FreeType font. If the Xft library is not available or not initialized, or the application has not selected a font, the method returns 0.

textWidth (String text)

Return an Integer with the width in pixels of text in the currently selected FreeType font. If the Xft library is not available or not initialized, the method returns 0.

textHeight (Symbol displayPtr, Integer drawable, Integer GCPtr, String str)

textWidth (Symbol displayPtr, Integer drawable, Integer GCPtr, String str)

These methods return the width and height of str in the currently selected font. Unlike the textWidth and textHeight methods, which work within the client app’s process space, these methods direct the server process to perform the measurements.

verbose

Causes the Ctalk libraries to output verbose information about font selection and loading, like the complete font descriptor that the Freetype libraries derive from the currently selected font’s pattern. Refer to the X11FreeTypeFont : notifyLevel method for more information about this class’ notification levels..

verbosity (void)

Returns an Integer with the Xft libraries’ reporting level. The possible values, which are defined in ctalk/ctalkders.h, are:


XFT_NOTIFY_NONE
XFT_NOTIFY_ERRORS
XFT_NOTIFY_LOAD
XFT_NOTIFY_VERBOSE