NAME
Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj,
Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont - maintain
database of fonts
SYNOPSIS
#include <tk.h>
Tk_Font |
Tk_AllocFontFromObj(interp, tkwin, objPtr) |
Tk_Font |
Tk_GetFont(interp, tkwin, string) |
Tk_Font |
Tk_GetFontFromObj(tkwin, objPtr) |
char *
Tk_NameOfFont(tkfont)
Tk_Font |
Tk_FreeFontFromObj(tkwin, objPtr) |
void
Tk_FreeFont(tkfont)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter to use for
error reporting. If
NULL, then no error mes
sages are left after
errors.
Tk_Window tkwin (in) Token for window in which
font will be used.
Tcl_Obj *objPtr (in/out) ||
Gives name or description |
of font. See documenta |
tion for the font command |
for details on acceptable |
formats. Internal rep |
will be modified to cache |
corresponding Tk_Font. |
const |
char *string (in) ||
Same as objPtr except |
description of font is |
passed as a string and |
resulting Tk_Font isn't |
Tk_Font tkfont (in) Opaque font token.
_________________________________________________________________
DESCRIPTION
Tk_AllocFontFromObj finds the font indicated by objPtr and |
returns a token that represents the font. The return |
value can be used in subsequent calls to procedures such |
as Tk_GetFontMetrics, Tk_MeasureChars, and Tk_FreeFont. |
The Tk_Font token will remain valid until Tk_FreeFontFro |
mObj or Tk_FreeFont is called to release it. ObjPtr can |
contain either a symbolic name or a font description; see |
the documentation for the font command for a description |
of the valid formats. If Tk_AllocFontFromObj is unsuc |
cessful (because, for example, objPtr did not contain a |
valid font specification) then it returns NULL and leaves |
an error message in interp's result if interp isn't NULL. |
Tk_AllocFontFromObj caches information about the return |
value in objPtr, which speeds up future calls to proce |
dures such as Tk_AllocFontFromObj and Tk_GetFontFromObj. |
Tk_GetFont is identical to Tk_AllocFontFromObj except that |
the description of the font is specified with a string |
instead of an object. This prevents Tk_GetFont from |
caching the matching Tk_Font, so Tk_GetFont is less effi |
cient than Tk_AllocFontFromObj. |
Tk_GetFontFromObj returns the token for an existing font, |
given the window and description used to create the font. |
Tk_GetFontFromObj doesn't actually create the font; the |
font must already have been created with a previous call |
to Tk_AllocFontFromObj or Tk_GetFont. The return value is |
cached in objPtr, which speeds up future calls to Tk_Get |
FontFromObj with the same objPtr and tkwin.
Tk_AllocFontFromObj and Tk_GetFont maintain a database of
all fonts they have allocated. If the same font is
requested multiple times (e.g. by different windows or for
different purposes), then a single Tk_Font will be shared
for all uses. The underlying resources will be freed
automatically when no-one is using the font anymore.
The procedure Tk_NameOfFont is roughly the inverse of
Tk_GetFont. Given a tkfont that was created by Tk_GetFont
(or Tk_AllocFontFromObj), 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 is no longer needed, Tk_FreeFontFromObj or |
Tk_FreeFont should be called to release it. For Tk_Free |
FontFromObj the font to release is specified with the same |
release is specified with its Tk_Font token. There should |
be exactly one call to Tk_FreeFontFromObj or Tk_FreeFont |
for each call to Tk_AllocFontFromObj or Tk_GetFont.
SEE ALSO
Tk_FontId(3)
KEYWORDS
font
Man(1) output converted with
man2html