AtFontFamily(3X)

NAME
AtFontFamily -- Font convenience routines

SYNOPSIS

#include <X11/At/FontFamily.h>

AtFontFamily *AtFontFamilyGet(display, name);
void AtFontFamilyRelease(family);
XFontStruct *AtFontFetch(family, face, size);
char *AtFontFamilyGetName(family);
Display *AtFontFamilyGetDisplay(family);
int AtFontBigger(size);
int AtFontSmaller(size);
int AtFontPointSize(family, size);
int AtFontPixelSize(family, size);
int AtFontEmphasize(face);
int AtFontDeemphasize(face);
int AtFontItalicize(face);
int AtFontDeitalicize(face);
int AtFontStringToSize(string);
	Display *display;
	char *name;
	AtFontFamily *family;
	int face,size;
	char *string;

void AtRegisterFontStyleConverter();
void AtRegisterFontSizeConverter();

DESCRIPTION
These functions provide a convenient interface for handling X fonts in environments that want to use multiple fonts, typefaces or sizes. An AtFontFamily is a shared resource which encapsulates all necessary information about the fonts of a single family. Querying an AtFontFamily with a font face and size returns a pointer to an XFontStruct. The table below lists currently supported font families. Both font faces and sizes are described by integers. The table below lists symbolic names for legal faces and sizes.
Supported Font Families, Faces, and Sizes
Families | Faces | Sizes
"helvetica" | AtFontPLAIN | AtFontSMALLEST
"times" | AtFontBOLD | AtFontSMALL
"new century schoolbook" | AtFontITALIC | AtFontMEDIUM
"charter" | AtFontBOLDITALIC | AtFontNORMAL
"courier" | AtFontBIG
"symbol" | AtFontBIGGEST

AtFontFamilyGet()
    This function returns an AtFontFamily for the family name on the display display. An AtFontFamily is an immutable resource, and as such is sharable. AtFontFamilyGet() implements a cache -- only one instance of an AtFontFamily is created for each display, name pair. Because of the caching, creating a font family should be treated as an inexpensive function. It is appropriate, for example, to call AtFontFamilyGet() for each instantiation of a widget.

AtFontFamilyRelease()
    This function releases family. If this is the last reference to that AtFontFamily, then all the resources associated with it are freed up. No further references should be made to family.

AtFontFetch()
    This function gets a font of the specified family, face, and size. This is an efficient operation -- fonts are not loaded and queried until first requested, and once requested, the XFontStruct is cached in the AtFontFamily structure. If no font in the specified face or size is available in the font family, AtFontFetch() returns a font that is as close as possible.

AtFontFamilyGetName()
    This function returns the name (a character string) of the family.

AtFontFamilyGetDisplay()
    This function returns the display on which family is defined.

AtFontBigger()
    This function returns the font size one bigger than size. If size is the biggest supported then, it returns size unmodified.

AtFontSmaller()
    This function returns the font size one smaller than size. If size is the smallest supported then, it returns size unmodified.

AtFontPointSize()
    This function returns the size in points of a font of size size in font family.

AtFontPixelSize()
    This function returns the size in pixels of a font of size size in font family.

AtFontEmpahsize(), AtFontDeemphasize()
    These functions add and remove the bold font attribute from face.

AtFontItalicize() , AtFontDeitalicize()
    These functions add and remove the bold font attribute from face.

AtFontStringToSize()
    This function will convert any of the strings "smallest", "small", "medium", "normal", "big" and "biggest" to the corresponding font size. In addition, if the string is an integer, it will be converted into the font size which is closest to that number of points. If the string doesn't match any size, or the integer is out of range, it returns -1. This function is useful when parsing font sizes from the X resource database.

AtRegisterFontSizeConverter()

AtRegisterFontStyleConverter()
    These two functions register converters with the Xt Intrinsics necessary for converting Strings to the relevant types.

USAGE
These routines are designed so that font families and sizes can easily be specified from X resource files. The intended use is that the user of the application should specify the font family for the application (as a general rule, most applications should not mix fonts from different families) as well as the base font size for the application. The application is free to change typefaces where appropriate (with the understanding that italic fonts do not render well on most displays) and, where appropriate, may use bigger or smaller font sizes than that specified as the base. The font size must be adjusted up or down relative to the user-supplied base -- it should not be specified absolutely. When the user does not specify a base font size, AtFontNORMAL is an appropriate default.

Widgets that use these font routines should have a AtNfontFamily resource of resource type String. They should call AtFontFamilyGet() in their Initialize methods to create the font family and AtFontFamilyRelease() in their Destroy method. Both of these procedures may also have to be called from the XtSetValues method. Font families should be thought of as analogous to GCs, which are (as used in widgets) also shared resources. Widgets that use these font routines should also call AtRegisterFontSizeConverter() and AtRegisterFontStyleConverter() in their class initialize routines so the relevant conversions can be made as widgets are created.

EXAMPLE
Display *dpy;
AtFontFamily *ff;
XFontStruct *f;
ff = AtFontFamilyGet(dpy, "new century schoolbook");
f = AtFontFetch(ff,AtFontITALIC, AtFontNORMAL);

AUTHOR
David Flanagan (MIT Project Athena) wrote the code for version V4. No changes for versions V5-beta and V6.0.

COPYRIGHT
Copyright 1990,1991 by the Massachusetts Institute of Technology All rights reserved. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of the firms, institutes or employers of the authors not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. THE AUTHORS AND THEIR FIRMS, INSTITUTES OR EMPLOYERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE AUTHORS AND THEIR FIRMS, INSTITUTES OR EMPLOYERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.