Contents

• Introduction
• User's Guide (Linux)
• User's Guide (Windows)
• Attribute Reference (Linux)
• Attribute Reference (Windows)
• The listFonts Command
• Making Portable MEL Scripts
• Support & Copyright Information
• Downloads

Introduction

The font node lets you specify the characteristics of a desired font. It then loads the closest matching font available in the system and presents a handle to that font on its handle attribute. This in turn can be used by other nodes, such as Gooroos Software's annotation node, as the font in which they display their text.

Because font handling varies considerably between different operating systems, the font node makes available different attributes on Windows than on Linux. The functionality of the listFonts command is also different between the two operating systems.

For this reason, this documentation provides separate User's Guides and Attribute References for Linux and Windows.

The differences between the two platforms also means that you must take extra care if you are writing MEL scripts which must run on both. For tips on doing that, refer to the section on Making Portable MEL Scripts.

User's Guide (Linux)

A font node is created like any other node in Maya, using the createNode command. For example:

    createNode font;
    // Result: font1

When initially created, the font node is set to provide the system's "fixed" font. Specifically, it uses the following X Logical Font Descriptor (XLFD):

    -*-fixed-*-r-*-*-*-120-*-*-*-*-*-*

    setAttr -type "string" font1.family "times";
    setAttr -type "string" font1.weight "bold";
    setAttr -type "string" font1.slant "i";
    setAttr font1.pointSize 240;

    -*-times-bold-i-*-*-*-240-*-*-*-*-*-*

    annotation -fontNode font1 "Italicized Times Font";

When setting string values, "any" is an alias for "*", and "none" is an alias for an empty string. Thus, the following two blocks of MEL script will both generate the same XLFD:

    // These two statements...
    setAttr -type "string" font1.slant "any";
    setAttr -type "string" font1.additionalStyle "none";

    // Are the same as these two...
    setAttr -type "string" font1.slant "*";
    setAttr -type "string" font1.additionalStyle "";

    // They both generate the following XLFD:
    -*-times-bold-*-*--*-240-*-*-*-*-*-*

Each attribute will take any value you give it, regardless of whether that produces a meaningful font descriptor. The reason for this is that the list of valid values is dependent upon the set of fonts currently installed in your system. To help narrow down the range of choices, the Attribute Editor provides a 'Browse' button for each attribute which lists the valid values for the fonts currently installed on your system. However, it should be noted that the various size attributes -- pixelSize, pointSize, xResolution, yResolution and width -- only pertain to non-scalable fonts: for scalable fonts, such as TrueType fonts, you can specify any positive integer value for these sizing attributes.

You can also use the listFonts command to view all the valid values for any XFLD attribute, from all of the fonts installed on your system. Alternatively, the X Windowing System provides a standard utility called xfontsel which you can run from the Linux shell to interactively select different font characteristics to see how they work together.

If the X Windowing System cannot provide a font exactly matching the characteristics which you have specified then it will supply the closest matching font. If no font at all can be found, then the font node will fall back to using the system's "fixed" font.

In addition to the individual attributes used to define the XFLD, the font node has an another string attribute called predefinedFont. If this attribute is set to anything other than "none" or empty, the font node will ignore all of its other attributes and just use whatever font name you supply. This provides a method for using predefined font aliases which are not in XFLD form. For example:

    setAttr -type "string" font1.predefinedFont "8x16";

User's Guide (Windows)

A font node is created like any other node in Maya, using the createNode command. For example:

    createNode font;
    // Result: font1

When initially created, the font node is set to select Windows' "GUI Default" font. This is one of the seven predefined fonts which are available on all Windows systems. The diagram below shows what these predefined fonts look like:

A font node can be made to select any one of these predefined fonts by setting its stockFont attribute to the appropriate value, from 1 to 7. For example, the following MEL command would set a font node to use Windows' predefined ANSI Fixed-pitch font:

    setAttr font1.stockFont 2;

Instead of using a predefined font, you can set the font node's stockFont attribute to zero, then use its remaining attributes to specify the precise characteristics of the font you would like. The node will then search for the available font which most closely matches those characteristics.

    setAttr font1.stockFont 0;
    setAttr -type "string" font1.typeface
        "Times New Roman";
    setAttr font1.width 10;
    setAttr font1.height 20;
    setAttr font1.italic yes;

    createNode -name "sample" annotation;
    setAttr -type "string" sample.text
        "Italicized Times New Roman font";

    connectAttr font1.handle sample.font;

Attribute Reference (Linux)

A font node's special attributes are found in the Attribute Editor under the Font heading. Beneath this is a sub-section entitled Explicit Font Attributes. The explicit attributes are only enabled when you set the Predefined Font field to None or empty.

Beside each input attribute the Attribue Editor will display a 'Browse' button. If you click on the button a list of valid values for that attribute will be displayed. Double-clicking on a value, or selecting one and clicking the "OK" button, will copy that value into the attribute.

Long (Short) Name	Type	Default Value	Description
predefinedFont (pf)	string	none	Selects an explicit font name which overrides all of the other attribute settings. This can be used to specify predefined font aliases such as "8x16" which are not in X Logical Font Descriptor (XLFD) format. To use the individual attributes to build an XLFD, set this attribute to empty or to the string "none".
family (f)	string	fixed	Font family (e.g. "courier").
weight (wt)	string	any	Weight (e.g. "bold", "medium").
slant (sl)	string	r	Slope of the font (e.g. "r" for roman, meaning no slant, "i" for italics).
widthStyle (ws)	string	any	Some fonts allow "condensed" versions in which the width is compressed. This attribute lets you specify the style of compression (e.g. "condensed", "semicondensed")
additionalStyle (as)	string	any	Any additional, special styles which a specific font might provide.
pixelSize (px)	integer	-1	Height of the font, in screen pixels. Specify -1 to accept any size.
pointSize (pt)	integer	120	Height of the font, in tenths of a printer's point. Specify -1 to accept any size.
xResolution (xr)	integer	-1	The number of horizontal dots-per-inch the font should provide. Most X Windowing System installations provide 75 and/or 100. Specify -1 to accept any resolution.
yResolution (yr)	integer	-1	The number of vertical dots-per-inch the font should provide. Most X Windowing System installations provide 75 and/or 100. Specify -1 to accept any resolution.
spacing (sp)	string	any	Style of spacing between characters (e.g. "p" for proportional, "m" for monospaced or fixed).
width (w)	integer	-1	The average width of the characters in the font, specified in tenths of a pixel. Specify -1 to accept any width.
characterSet (cs)	string	any	The character set to be used with the font (e.g. "iso8859").
encoding (en)	string	any	Some character sets provide multiple encodings (e.g. "1", "2", "fontspecific"). This attribute lets you select which encoding to use.
handle (hdl)	string	n/a	This is the font node's only output attribute. It contains the X Logical Font Descriptor for the font which most closely matches the specification given, either as a predefined font, or using the explicit font attributes.

Attribute Reference (Windows)

A font node's special attributes are found in the Attribute Editor under the Font heading. Beneath this is a sub-section entitled Explicit Font Attributes. The explicit attributes are only enabled when you set the Predefined Font field to None (which is equivalent to setting the node's stockFont attribute to zero).

Long (Short) Name	Type	Default Value	Description
stockFont (sf)	enum	7	Selects one of the seven predefined fonts which are available on all Windows systems. Valid values are: 0 None 1 OEM fixed pitch 2 ANSI fixed pitch 3 ANSI proportional spaced 4 System fixed pitch 5 System propotional spaced 6 Device default 7 GUI default If zero (None) is selected, then no predefined font used. Instead, the remaining attributes are used to specify the desired font.
typeface (tf)	string	(empty)	Specifies the typeface (e.g. "Times New Roman"). The typefaces available vary depending upon what has been installed on your system. The Browse button in the Attribute Editor can be used to select from a list of currently installed typefaces. Alternatively, the listFonts command can be used to return an array of the installed typeface names.
width (w)	short	0	Average width of the characters in the font. Width is measured in points, where each point is 1/72 of an inch. If width is set to 0 then the font node will choose the width most suitable for your display device and the other specified font characteristics.
height (h)	short	0	Height of the font, which is taken from the baseline of the font to the top of its tallest character (i.e the height does not include descenders). Height is measured in points, where each point is 1/72 of an inch. If height is set to 0 then the font node will choose the height most suitable for your display device and the other specified font characteristics.
heightIsCellHeight (ch)	bool	false	If true, then the value given for the height attribute applies to the entire character cell, including descenders and interline spacing.
weight (wt)	short	400	Specifies the weight or thickness of the lines making up the characters. Valid values range from 0 to 1000. If 0 is specified, then the system default value will be used.
italic (i)	bool	false	If true, text drawn in the font will be italicized.
underline (u)	bool	false	If true, text drawn in the font will be underlined.
strikeout (so)	bool	false	If true, text drawn in the font will be struck out, meaning that it will have a horizontal line running through the middle of it.
characterSet (cs)	enum	1	Specifies the character set to be used. Valid values are: 0 ANSI 1 Default 2 Symbol 77 MacIntosh 128 Shift JIS 129 Hangul 130 Johab 134 GB2312 136 Chinese Big 5 161 Greek 162 Turkish 163 Vietnamese 177 Hebrew 178 Arabic 186 Baltic 204 Russian 222 Thai 238 East European 255 OEM The Default (1) character set is special: it selects the default character set for the selected typeface. Not all character sets are available with all typefaces. In fact, most typefaces only support one or two character sets. If you specify a character set which is not supported by any matching typeface, then the default character set for the best matching typeface will be used.
outputPrecision (op)	enum	0	Specifies a preference for either a device, outline, raster, or TrueType font. Valid values are: 0 Default 1 Device font preferred 2 Outline font preferred 3 Raster font preferred 4 TrueType font preferred 5 TrueType font required
quality (q)	enum	0	Specifies the print quality. This doesn't seem to have any effect on displayed fonts, but it is part of the Windows font specification, so it is included for completeness. Valid values are: 0 Default 1 Draft 2 Proof
pitch (p)	enum	0	Specifies the preferred type of pitch for the font: fixed or variable (proportional). Valid values are: 0 Default 1 Fixed 2 Variable
family (f)	enum	0	Specifies a preference for a specific family of fonts. This doesn't seem to have any effect on displayed fonts, but it is part of the Windows font specification, so it is included for completeness. Valid values are: 0 Any 1 Decorative 2 Modern 3 Roman 4 Script 5 Swiss
handle (hdl)	long (HFONT)	0	This is the font node's only output attribute. It contains the Windows font handle for the font which most closely matches the specification given, either as a predefined font, or using the explicit font attributes.

The listFonts Command

The font node plugin also contains the listFonts MEL command. When executed with no arguments, this returns an array of strings where each element is the name of an installed font family (which are referred to as "typefaces" on Windows). For example:

    string $fonts[] = listFonts();
    print("The result is " + $fonts[5] + "\n");

    The result is Courier New

On Linux, the listFonts command also supports a number of flags which can be used to list the valid values for each component of an X Logical Font Descriptor. The flag names match the names of the corresponding attributes on the font node. Thus, if you wanted to list the pixelSizes available across all currently installed fonts, you would use the -px or -pixelSize flag. For example:

    int $pixelSizes[] = `listFonts -px`;

Only one flag may be specified per command invocation. If you specify more than one then the command will pick just one of them and return the values for it.

Making Portable MEL Scripts

At the MEL scripting level, the syntax for connecting a font node to an annotation node is consistent. Thus, all of the following will work on both Linux and Windows:

    // Create a font node and annotation
    // node and connect them by hand.
    createNode -n f font;
    createNode -n a annotation;
    connectAttr f.handle a.font;

    // Have the annotation command create and
    // connect the font node for us.
    annotation -createFontNode yes "Some text";

    createNode -n myFont font;

    // Have the annotation command connect
    // to the existing font node.
    annotation -fontNode myFont "Some more text";

Furthermore, the listFonts command, with no arguments, will behave similarly on both operating systems, returning an array of font family names on Linux and an array of typeface names on Windows.

However, pretty much anything else that you do with the font node or the listFonts command will require that you provide different MEL commands for Linux and Windows. To do this, you can use the MEL command about to determine which operating system the script is being run under. For example:

    //
    // Change the font size.
    //
    if (`about -windows`)
    {
        // Windows-specific code
        setAttr f.width 20;
        setAttr f.height 40;
    }
    else
    {
        // Linux-specific code
        setAttr f.pointSize 200;
    }

Support & Copyright Information

The font node and its associated materials, which are collectively referred to as "this product", are copyright Gooroos Software, 1999-2004.

Gooroos Software provides this product as-is and assumes no liability for its use. You may freely redistribute it, but only in complete and unmodified form.

If you have any questions or problems with this product, please send email to support@gooroos.com. Because this product is made freely available, we cannot guarantee you a response, but we will try to get back to you as time permits.

For more information on Gooroos Software and our other products, please visit our web-site at www.gooroos.com.

Downloads