Tk_GetFont(3)

NAME
Tk_GetFont, Tk_NameOfFont, Tk_FreeFont - maintain database of fonts

SYNOPSIS
#include <tk.h>

Tk_Font
Tk_GetFont(interp, tkwin, string)

char *
Tk_NameOfFont(tkfont)

void
Tk_FreeFont(tkfont)

ARGUMENTS
Interpreter to use for error reporting. Token for window on the display in which font will be used. Name or description of desired font. See documentation for the font command for details on acceptable formats. Opaque font token.

DESCRIPTION

Tk_GetFont finds the font indicated by string and returns a token that represents the font. The return value can be used in subsequent calls to procedures such as Tk_FontMetrics, Tk_MeasureChars, and Tk_FreeFont. The token returned by Tk_GetFont will remain valid until Tk_FreeFont is called to release it. String can be either a symbolic name or a font description; see the documentation for the font command for a description of the valid formats. If Tk_GetFont is unsuccessful (because, for example, string was not a valid font specification) then it returns NULL and stores an error message in interp->result.

Tk_GetFont maintains a database of all fonts it has allocated. If the same string is requested multiple times (e.g. by different windows or for different purposes), then additional calls for the same string will be handled without involving the platform-specific graphics server.

The procedure Tk_NameOfFont is roughly the inverse of Tk_GetFont. Given a tkfont that was created by Tk_GetFont, the return value is the string argument that was passed to Tk_GetFont to create the font. The string returned by Tk_NameOfFont is only guaranteed to persist until the tkfont is deleted. The caller must not modify this string.

When a font returned by Tk_GetFont is no longer needed, Tk_FreeFont should be called to release it. There should be exactly one call to Tk_FreeFont for each call to Tk_GetFont. When a font is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) Tk_FreeFont will release any platform-specific storage and delete it from the database.

KEYWORDS
font